PIX
Brazilian Instant Payment System
Introduction
The Brazilian Instant Payment System (PIX) is a new payment method created by the Central Bank of Brazil. It is a fast, secure and convenient way to make payments and transfer money. PIX is available 24/7, including weekends and holidays, and it is free for individuals and small businesses. Currently is the most popular payment method in Brazil.
Getting Started
Generate Order
To generate a PIX order, you need to send a POST request to the following endpoint:
POST /api/v1/order
Host: latamgateway.com
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"
{
"customer": {
"name": "Customer’s full name",
"document": "111.222.333-44",
"email": "[email protected]",
"phone": "11999999999",
"birth": "1996-03-09"
},
"order": {
"code": "123",
"notification_url": "your_payback_notification_url.com",
"value": 50.00,
"additional_info": "Some description of your order as String",
"payment_method": "pix"
}
}
Params descriptions
Field | Description | Value Type | Requirement |
---|---|---|---|
customer.name |
Customer's full name | String | Required |
customer.document |
Customer's document | String | Required (see notes below) |
customer.email |
Customer's email address | String | Required |
customer.phone |
Customer's phone number | String | Required |
customer.birth |
Customer's date of birth | String | Required |
order.code |
Order reference in your system | String | Required |
order.notification_url |
URL to notify when status changes | String | Required |
order.value |
Total order value | Number (decimal) | Required |
order.additional_info |
Additional description of the order | String | Required |
order.payment_method |
Payment method | String | Required |
Note 1: The document can be a valid CPF or CNPJ. If CNPJ is used, the company name must be passed in the name parameter.
Note 2: CPF and CNPJ are the Brazilian individual and company identification numbers, respectively.
On a successful request HTTP 200 status code, the response will include the following parameters:
{
"latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
"code": "id_in_your_system",
"confirmation_url": "https://latamgateway.com/7c0b8129-f556-4357-bb6e-8189c2943024",
"qrcode_link": "https://latamgateway.com/qrcode/7c0b8129-f556-4357-bb6e-8189c2943024"
}
Business errors due to incorrect or missing parameters are returned with an HTTP 400 status code. The response will indicate which parameter is invalid or missing.
{
"message": "Invalid document"
}
KYC errors are returned with an HTTP 403 status code. The response will contain the following parameters:
{
"latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
"message": "kyc message table below",
"code": "kyc code table below"
}
KYC RESPONSE CODES DESCRIPTIONS
Code | Message |
---|---|
KYC110 | Invalid CPF, please verify your date of birth and CPF number. |
KYC110 | CPF document not found. |
KYC110 | CPF document belongs to a deceased holder. Year of death: 2024. |
KYC110 | CPF document is suspended. |
KYC111 | Invalid CNPJ, please verify your CNPJ number. |
KYC112 | Different name from the federal revenue register of natural persons. |
Get QR code and Image
To get QR Code info and image after generating the order:
GET /api/v1/qrcode/{latam_id}
Host: latamgateway.com
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"
The response will contain the following parameters:
{
"qrcode_data": "A string containing the complete Pix transaction information, ready to be copied and pasted into a banking application.",
"qrcode_image": "Base64 of the QR Code image"
}
Reverse Order
To reverse the order:
POST /api/v1/order/{order_id}/reverse
Host: latamgateway.com
Content-Type: "application/json"
ACCOUNT_TOKEN: "<token>"
If your request is successful, you will receive a response to the following
{
"message": "message": "Refund requested. Waiting for confirmation from the bank."
}