Create PIX Transaction

To make a PIX charge, use this route to create a new transaction. Our API will return, among other data, the pix_copy_paste field, responsible for providing the PIX Copy and Paste that should be made available to the customer so they can make the payment.

Each PIX transaction has an expiration time, which can be defined at the time of transaction creation through the expired field. If not informed, the default expiration time is 24 hours (86,400 seconds). After this period, the PIX becomes invalid and it will no longer be possible to make the payment.

POSTv3/pix

Request Body Params

Attribute	Type	Description
amount	int32	Final amount to be charged from the end consumer. Must be passed in cents.
item_id	string	Transaction ID in your platform.
soft_descriptor	string	Description that will appear on your customer's invoice. Maximum of 13 characters, alphanumeric and spaces.
customer	object	Customer object.
customer[name]	string	Customer name.
customer[email]	string	Customer email.
customer[document_number]	string	Customer document number.
customer[phone]	object	Customer phone number object.
customer[phone][country_code]	string	Customer phone country code (DDI).
customer[phone][area_code]	string	Customer phone state code (DDD).
customer[phone][number]	string	Customer phone number.
expired	int32	Optional parameter. Expiration time in seconds. If not informed, we use the default of 86400 (24 h).
pix	object	Optional parameter. PIX key data object. If you include sub_seller_id, this field becomes dispensable.
pix[type]	string	PIX key type. Accepted values: cpf, cnpj, email or phone.
pix[key]	string	PIX key value. Must be informed according to the PIX key type.
sub_seller_id	string	Optional parameter. Partner ID for which the transfer will occur. If you include pix, this field becomes dispensable.
webhook_url	string	Optional parameter to pass the endpoint of your system that will receive information with each transaction update.
webhook_auth_token	string	Optional parameter to authenticate notifications sent to webhook_url. If the parameter is not informed, notifications will be sent without authentication.
simulate_status	string	Optional parameter that can be passed in test environment to simulate the PIX flow. Accepted values: paid, failed, expired.

Request Body Example

{
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expired": 86400,
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11", 
      "number": "999887766"
    }
  }
}

Important

Our API does not accept null, undefined or empty string values in any endpoint. If you pass a parameter with any of these 3 values, an error will be returned. If the parameter is not mandatory and you don't want it to be computed, simply remove it from the request.

Response Object

Property	Type	Description
status	string	Represents the current state of the transaction. Possible values: waiting_payment, failed.
date_created	dateTime	Transaction creation date in ISODateTime format.
date_updated	dateTime	Transaction status update date in ISODateTime format.
item_id	string	Transaction ID in your platform.
payment_method	string	Payment method used in the transaction. Possible values: pix.
transaction_id	string	Marlim transaction identifier number.
amount	int32	Amount in cents to be charged in the transaction.
payout_amount	int32	Amount in cents to be transferred.
paid_amount	int32	Amount in cents captured in the transaction.
refunded_amount	int32	Amount in cents refunded in the transaction.
pix_copy_paste	string | null	PIX Copy and Paste code that should be presented to the customer for payment. Returns null when the transaction fails or is rejected.

Response Example

{
  "status": "waiting_payment",
  "date_created": "2025-01-01T10:00:00.000Z",
  "date_updated": "2025-01-01T10:00:00.000Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "ABCeWbEfTwHtmkX3q123",
  "amount": 1000,
  "payout_amount": 950,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913Marlim Store6009Sao Paulo62070503***6304E2CA"
}

Examples

WARNING

The values used in the examples below are for illustration purposes only and should not be used to make requests to Marlim APIs. In development and testing environments, use data closer to a real transaction.

PIX Transaction Created

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "expired": 86400,
  "customer": {
    "name": "Luke Skywalker",
    "email": "luke@jedimaster.sw",
    "document_number": "00099988877",
    "phone": {
      "country_code": "+55",
      "area_code": "11",
      "number": "999887766"
    }
  }
}'

Response200

{
  "status": "waiting_payment",
  "date_created": "2025-07-29T11:38:57.850Z",
  "date_updated": "2025-07-29T11:38:57.850Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "ABCeWbEfTwHtmkX3q123",
  "amount": 1000,
  "payout_amount": 950,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126580014br.gov.bcb.pix0136123e4567-e12b-12d1-a456-426614174000520400005303986540510.005802BR5913Marlim Store6009Sao Paulo62070503***6304E2CA"
}

Missing Parameters

Request

curl -X POST "https://api.marlim.co/v3/pix" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "item_id": "ABC123456789",
  "soft_descriptor": "Marlim Store",
  "customer": {
    "name": "Luke Skywalker",
    "document_number": "00099988877"
  }
}'

Response400

{
  "api_reference": "https://docs.api.marlim.co/transactions/create/pix",
  "errors": [
    {
      "type": "customer.email",
      "message": "The parameter [ customer.email ] is missing."
    }
  ]
}