Skip to main content
POST
/
api
/
v1
/
payments
/
pix
Process a PIX payment
curl --request POST \
  --url http://localhost:7701/api/v1/payments/pix \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "merchant_order_id": "ORD-2026-12345",
  "amount": 15000,
  "currency": "BRL",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "document": "12345678909"
  },
  "gateway_first_try": "pagarme",
  "expires_in": 3600,
  "splits": [
    {
      "subaccount_id": "sub_abc123",
      "amount": 5000
    }
  ]
}
'
{
  "status": "pending",
  "transaction_id": "01hvxyz...",
  "amount": 15000,
  "message": "PIX generated successfully.",
  "payment_method": "pix",
  "merchant_order_id": "ORD-2026-12345",
  "idempotency_key": "<string>",
  "plugtopay_request_time": "0.05s",
  "total_request_time": "0.8s",
  "gateways_request_time": "0.75s",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "transactions": [
    {}
  ],
  "customer": {},
  "webhook": {},
  "pix": {
    "qr_code": "<string>",
    "qr_code_url": "<string>",
    "expiration_at": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
X-API-Key
string
header
required

Company API key. Send in the X-API-Key header.

Body

application/json
​
merchant_order_id
string
required
Example:

"ORD-2026-12345"

​
amount
integer
required

Amount in cents

Example:

15000

​
currency
string
required
Example:

"BRL"

​
customer
object
required
​
gateway_first_try
string | null

Gateway slug to attempt first. Falls back to routing rules if not set.

Example:

"pagarme"

​
expires_in
integer | null

Seconds until PIX expires (min 60)

Example:

3600

​
splits
object[] | null

Optional split rules. Each entry directs a portion of the amount to a sub-account.

Response

PIX order created

​
status
string
Example:

"pending"

​
transaction_id
string
Example:

"01hvxyz..."

​
amount
integer
Example:

15000

​
message
string
Example:

"PIX generated successfully."

​
payment_method
string
Example:

"pix"

​
merchant_order_id
string | null
Example:

"ORD-2026-12345"

​
idempotency_key
string | null
​
plugtopay_request_time
string | null
Example:

"0.05s"

​
total_request_time
string | null
Example:

"0.8s"

​
gateways_request_time
string | null
Example:

"0.75s"

​
created_at
string<date-time> | null
​
updated_at
string<date-time> | null
​
transactions
object[]
​
customer
object
​
webhook
object
​
pix
object