API - Generate Payment

This endpoint creates a PIX payment transaction for Brazilian instant payments. It generates a PIX code and QR image that the customer can use to complete the payment through their banking app.

POST {BASE_URL}/payment/pix

Headers

Header	Required	Description	Example
Authorization	Yes	Bearer token for authentication	Bearer...
x-api-key	Yes	API key for service access	xxxxxxxxxxxxxxxxxx
Content-Type	Yes	Must be application/json	application/json

Body Parameters

Parameter	Type	Required	Description	Validation
customerTaxId	string	Yes	Customer's CPF/CNPJ (Brazilian tax ID)	11-14 digits
customerEmail	string	Yes	Customer's email address	Valid email format
customerPhone	string	Yes	Customer's phone number	Minimum 6 digits
customerAddress	object	Yes	Customer's billing address	-
customerAddress.street	string	Yes	Street address	-
customerAddress.zipCode	string	Yes	Postal code	-
customerAddress.city	string	Yes	City name	-
customerAddress.state	string	Yes	State code	-
amount	number	Yes	Transaction amount	Positive decimal > 0
currency	string	Yes	Currency code (ISO 4217)	978 (EUR), 840 (USD), etc.
merchantOperationId	string	No	Merchant's internal reference	Optional

Example Request

{
  "customerTaxId": "123.456.789-09",
  "customerEmail": "[email protected]",
  "customerPhone": "5511999999999",
  "customerAddress": {
    "street": "Baker Street 123",
    "zipCode": "01234567",
    "city": "São Paulo",
    "state": "SP"
  },
  "amount": 2.00,
  "currency": "978",
  "merchantOperationId": "ORDER-0042"
}

Response

200

{
  "success": true,
  "result": {
    "id": "530780136-25-0-bgjXXuEtBtJXccqhMgILe65B",
    "pixCode": "00020101021226860014br.gov.bcb.pix2564qrpix.bradesco.com.br/qr/v2/274aca3b-a215-48a4-b7ba-55ab183a3843520400005303986540512.795802BR5925PAGBRASIL PAGAMENTOS LTDA6012PORTO ALEGRE620805043815630451D9",
    "pixImageUrl": "https://pagbrasil.com/x/img?MDAwMjAxMDEwMjEyMjY4NjAwMTRici5nb3YuYmNiLnBpeDI1NjRxcnBpeC5icmFkZXNjby5jb20uYnIvcXIvdjIvMjc0YWNhM2ItYTIxNS00OGE0LWI3YmEtNTVhYjE4M2EzODQzNTIwNDAwMDA1MzAzOTg2NTQwNTEyLjc5NTgwMkJSNTkyNVBBR0JSQVNJTCBQQUdBTUVOVE9TIExUREE2MDEyUE9SVE8gQUxFR1JFNjIwODA1MDQzODE1NjMwNDUxRDk=",
    "expiresAt": "2025-10-30T16:00:00Z",
    "amount": 2.00,
    "currency": "EUR",
    "amountBrl": 12.79,
    "fxRate": 6.3952
  }
}

400

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
result.id	string	Unique transaction identifier
result.pixCode	string	PIX code for copy/paste payment
result.pixImageUrl	string	URL to QR code image for scanning
result.expiresAt	string	Expiration datetime (ISO 8601 format)
result.amount	number	Original transaction amount
result.currency	string	Original currency code
result.amountBrl	number	Converted amount in Brazilian Reals
result.fxRate	number	Exchange rate used for conversion

QR Code Image

The pixImageUrl provides a direct link to a QR code that can be displayed to customers. The QR code contains the PIX payment information and can be scanned directly by Brazilian banking apps.

Important Notes

• Expiration: PIX codes typically expire in 30 minutes (as shown in expiresAt)

• Currency Conversion: Amount is automatically converted to BRL using the provided fxRate

• QR Code: The image URL returns a scannable QR code compatible with all Brazilian banking apps

• Payment Completion: Customer must use their banking app to scan QR or copy PIX code to complete payment

• Status Updates: Payment confirmation is handled asynchronously via webhooks