Skip to main content

Pay-In · Brazil

TOPPAY TeamAbout 3 min

Overview

The Pay-In API initiates collection transactions from customers. This page covers Brazil (country code br) with two ordering modes:

ModePathDescription
Cashier mode/pay/prePayDefault. Returns cashierUrl for the platform H5 cashier
API mode/pay/transOrderRequires 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:

FieldRequiredTypeDescription
Content-TypeMStringFixed 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.

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/br/pay/prePay
Productionhttps://openapi.toppayment.com/br/pay/prePay

Request Body

FieldRequiredTypeDescription
mchNoMString(32)Merchant number
orderNumMString(64)Merchant order number
amountMNumber(32,8)Transaction amount
Positive, integer or at most 2 decimal places; not all zeros; no three or more decimal places
Example: 100.50
productDetailMString(100)Product detail
methodOString(16)Payment method (Brazil)
Optional; omit to let the user choose on the cashier. Currently PIX — Regional Payment Guide — Brazil
timestampMString(13)Timestamp in milliseconds
customerNameMString(64)Customer name
customerEmailMString(64)Customer email
customerPhoneMString(32)Customer phone
expiryPeriodONumber(1–9999)Validity in minutes
downNotifyUrlMString(255)Async callback URL
redirectUrlOString(512)Redirect after payment
signMStringSignature — see Signature

Request Body Example

Content-type: application/json

Response Body Parameters

FieldRequiredTypeDescription
successMBooleanSuccess flag
codeMString9999 = success
msgOStringMessage
timeStampMNumberServer time (ms)
dataMObjectPayload
orderNumMStringMerchant order number
platOrderNumMStringPlatform order number
amountMNumberTransaction amount
feeMNumberFee
methodMStringPayment method (Brazil) — Regional Payment Guide — Brazil
productDetailMStringProduct detail
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
validTimeMNumberExpiry timestamp (ms)
cashierUrlMStringCashier URL

Response note

Cashier mode does not return payData or payDataType. Those fields appear only in API mode responses.

Content-type: application/json

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

EnvironmentURL
Sandboxhttps://openapi.toppayment.com/sandbox/br/pay/transOrder
Productionhttps://openapi.toppayment.com/br/pay/transOrder

Request Body

Differences from cashier mode:

FieldRequiredTypeDescription
methodMString(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

Response Body Parameters

Common fields match cashier mode. API mode focuses on:

FieldRequiredTypeDescription
payDataMStringPayment payload — PIX QR content / copia e cola string, payment page URL, etc.; meaning depends on payDataType
payDataTypeMStringQR_CODE, QR_URL, CASHIER_URL, etc.

payDataType Reference

payDataTypeDescriptionTypical methods
QR_CODEPIX EMV payload (copia e cola) — render as QR code on your side, or show it for paste-and-pay in the bank appPIX
QR_URLQR image or scan-page URLPIX (some channels)
CASHIER_URLUpstream payment page URLPIX (some channels)

Usage

  • When payDataType is QR_CODE, payData is the complete PIX payload (contains br.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

Notification

Both ordering modes use the same async callback. Brazil uses v1 only — notifyVersion / v2 payer fields are not supported.

HTTP Request

FieldRequiredTypeDescription
Content-TypeMStringapplication/json

Notification Body

FieldRequiredTypeDescription
platOrderNumMStringPlatform order number
versionMStringFixed value: v1
orderNumMStringMerchant order number
amountMNumberAmount
feeMNumberFee
customerNameMStringCustomer name
customerEmailMStringCustomer email
customerPhoneMStringCustomer phone
statusMStringStatus — see Transaction Status Codes
signMStringCallback signature

Acknowledgment

Important

Return the string SUCCESS only 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": "…"
}