Pay-In · Brazil
Overview
The Pay-In API initiates collection transactions from customers. This page covers Brazil (country code br) with two ordering modes:
| Mode | Path | Description |
|---|---|---|
| Cashier mode | /pay/prePay | Default. Returns cashierUrl for the platform H5 cashier |
| API mode | /pay/transOrder | Requires method in the request; returns payData / payDataType (PIX QR payload / copia e cola, etc.) |
method (Brazil Pay-In codes) is listed in Regional Payment Guide — Brazil.
Integration note
Cashier mode is enabled by default. Contact support to whitelist your merchant account before integrating API mode.
Request Header
Shared by both modes:
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | Fixed value: application/json |
Cashier Mode (prePay)
Pre-order and redirect the customer to the platform cashier via cashierUrl.
Request URL
Domain: Prefer unified host
openapi.toppayment.com(path unchanged); legacy country domain (e.g.global-br-openapi.toppayment.com) remains available.
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/br/pay/prePay |
| Production | https://openapi.toppayment.com/br/pay/prePay |
Request Body
| Field | Required | Type | Description |
|---|---|---|---|
| mchNo | M | String(32) | Merchant number |
| orderNum | M | String(64) | Merchant order number |
| amount | M | Number(32,8) | Transaction amount Positive, integer or at most 2 decimal places; not all zeros; no three or more decimal places Example: 100.50 |
| productDetail | M | String(100) | Product detail |
| method | O | String(16) | Payment method (Brazil) Optional; omit to let the user choose on the cashier. Currently PIX — Regional Payment Guide — Brazil |
| timestamp | M | String(13) | Timestamp in milliseconds |
| customerName | M | String(64) | Customer name |
| customerEmail | M | String(64) | Customer email |
| customerPhone | M | String(32) | Customer phone |
| expiryPeriod | O | Number(1–9999) | Validity in minutes |
| downNotifyUrl | M | String(255) | Async callback URL |
| redirectUrl | O | String(512) | Redirect after payment |
| sign | M | String | Signature — see Signature |
Request Body Example
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "BR1234561",
"amount": 100.50,
"productDetail": "Product",
"method": "PIX",
"timestamp": "1749451858772",
"customerName": "Maria Silva",
"customerEmail": "[email protected]",
"customerPhone": "+5511999999999",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"redirectUrl": "https://example.com/return",
"sign": "Generate per signature rules and replace"
}
Response Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| success | M | Boolean | Success flag |
| code | M | String | 9999 = success |
| msg | O | String | Message |
| timeStamp | M | Number | Server time (ms) |
| data | M | Object | Payload |
| orderNum | M | String | Merchant order number |
| platOrderNum | M | String | Platform order number |
| amount | M | Number | Transaction amount |
| fee | M | Number | Fee |
| method | M | String | Payment method (Brazil) — Regional Payment Guide — Brazil |
| productDetail | M | String | Product detail |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| validTime | M | Number | Expiry timestamp (ms) |
| cashierUrl | M | String | Cashier URL |
Response note
Cashier mode does not return payData or payDataType. Those fields appear only in API mode responses.
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "BR1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100.50,
"fee": 2.0,
"method": "PIX",
"productDetail": "Product",
"customerName": "Maria Silva",
"customerEmail": "[email protected]",
"customerPhone": "+5511999999999",
"validTime": 1767926672819,
"cashierUrl": "https://example.cashier/pay"
}
}
API Mode (transOrder)
Specify the payment method in the request, place the order directly with the channel, and receive payData / payDataType (PIX QR payload, also usable as copia e cola) without the platform H5 cashier.
Request URL
| Environment | URL |
|---|---|
| Sandbox | https://openapi.toppayment.com/sandbox/br/pay/transOrder |
| Production | https://openapi.toppayment.com/br/pay/transOrder |
Request Body
Differences from cashier mode:
| Field | Required | Type | Description |
|---|---|---|---|
| method | M | String(16) | Payment method (Brazil) Required in API mode. Currently PIX — Regional Payment Guide — Brazil |
All other fields match cashier mode.
Request Body Example
Content-type: application/json
{
"mchNo": "{{mchNo}}",
"orderNum": "BRAPI1234561",
"amount": 100.50,
"productDetail": "Product",
"method": "PIX",
"timestamp": "1749451858772",
"customerName": "Maria Silva",
"customerEmail": "[email protected]",
"customerPhone": "+5511999999999",
"expiryPeriod": 1440,
"downNotifyUrl": "https://example.com/notify",
"sign": "Generate per signature rules and replace"
}
Response Body Parameters
Common fields match cashier mode. API mode focuses on:
| Field | Required | Type | Description |
|---|---|---|---|
| payData | M | String | Payment payload — PIX QR content / copia e cola string, payment page URL, etc.; meaning depends on payDataType |
| payDataType | M | String | QR_CODE, QR_URL, CASHIER_URL, etc. |
payDataType Reference
| payDataType | Description | Typical methods |
|---|---|---|
QR_CODE | PIX EMV payload (copia e cola) — render as QR code on your side, or show it for paste-and-pay in the bank app | PIX |
QR_URL | QR image or scan-page URL | PIX (some channels) |
CASHIER_URL | Upstream payment page URL | PIX (some channels) |
Usage
- When
payDataTypeisQR_CODE,payDatais the complete PIX payload (containsbr.gov.bcb.pix). Display or encode it as-is; do not truncate or rewrite it. - The customer must complete payment before
validTime; the order expires afterwards.
Content-type: application/json
{
"success": true,
"code": "9999",
"msg": null,
"timeStamp": 1767840272829,
"data": {
"orderNum": "BRAPI1234561",
"platOrderNum": "PRE2009093829059153920",
"amount": 100.50,
"fee": 2.0,
"method": "PIX",
"productDetail": "Product",
"customerName": "Maria Silva",
"customerEmail": "[email protected]",
"customerPhone": "+5511999999999",
"validTime": 1767926672819,
"payData": "00020101021226800014br.gov.bcb.pix2558pix.delbank.com.br/v2/cob/vcharge1f6aed0623644c24bbdc174ce5204000053039865802BR5907DELBANK6007ARACAJU62070503***6304BC39",
"payDataType": "QR_CODE"
}
}
Notification
Both ordering modes use the same async callback. Brazil uses v1 only — notifyVersion / v2 payer fields are not supported.
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | application/json |
Notification Body
| Field | Required | Type | Description |
|---|---|---|---|
| platOrderNum | M | String | Platform order number |
| version | M | String | Fixed value: v1 |
| orderNum | M | String | Merchant order number |
| amount | M | Number | Amount |
| fee | M | Number | Fee |
| customerName | M | String | Customer name |
| customerEmail | M | String | Customer email |
| customerPhone | M | String | Customer phone |
| status | M | String | Status — see Transaction Status Codes |
| sign | M | String | Callback signature |
Acknowledgment
Important
Return the string
SUCCESSonly to confirm receipt of the notification.
{
"platOrderNum": "PRE2009165141186183168",
"version": "v1",
"orderNum": "BR12345621",
"amount": 100.50,
"fee": 2,
"customerName": "Maria Silva",
"customerEmail": "[email protected]",
"customerPhone": "+5511999999999",
"status": "SUCCESS",
"sign": "…"
}
SUCCESS
