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

Attention

All string type fields must be informed with alphanumeric characters without accents or special characters.

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). Ex: +55.
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).
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-07-09T14:46:20.598Z",
  "date_updated": "2025-07-09T14:46:20.598Z",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "transaction_id": "mMaNRQqDAypdGatmyquR",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 0,
  "refunded_amount": 0,
  "pix_copy_paste": "00020126360014br.gov.bcb.pix...6304ABCD"
}

Webhook URL

The entire process of changing a transaction's status is asynchronous. Therefore, it's important that you pass a webhook_url during the transaction creation process so that your application receives all status changes.

If any value is passed in the webhook_auth_token parameter, Marlim will send the token to your application using the Authorization: Bearer standard in the request Header:

Authorization: Bearer {webhook_auth_token}

Below is the table with possible status values received at the webhook_url.

Status	Meaning
paid	Transaction paid and captured successfully.
failed	Transaction with failure in the capture process at the Acquirer.
refunded	Transaction refunded.
expired	Transaction expired by exceeding the payment time limit.

Attention

You must validate the webhook origin, that is, if it was really sent by Marlim's servers.
For this, we send two values in the HEADER of the POST:

• User-Agent: always with the value Marlim/1.0.0
• Marlim-Api-Signature: the end of your api_key removing the values mak_test_ and mak_live_

Example of WEBHOOK BODY from Marlim to your application

curl -X POST "https://yourapplication.com/orders/123456789/webhook" \
-H "Content-Type: application/json" \ 
-H "User-Agent: Marlim/1.0.0" \ 
-H "Marlim-Api-Signature: Star98765Wars43210ANewHope1977" \ 
-H "Authorization: Bearer 123456" \
-d '{
  "event": "transaction_status_changed",
  "current_status": "paid",
  "transaction_id": "HcDscltTIVK3VMAAOj7J",
  "item_id": "ABC123456789",
  "payment_method": "pix",
  "date_created": "2026-01-15T17:36:12.662Z",
  "date_updated": "2026-01-15T17:36:12.662Z",
  "amount": 1000,
  "payout_amount": 0,
  "paid_amount": 1000,
  "refunded_amount": 0
}'

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": "2026-01-15T17:36:12.662Z",
  "date_updated": "2026-01-15T17:36:12.662Z",
  "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."
    }
  ]
}