API PAY-IN TRANSACTION
About 6 min
Request
The Pay-In API enables merchants to initiate payment transactions from customers. This API supports various payment methods including PIX and other digital payment solutions for the Brazilian market.
Request Path:
sandbox:
https://sandbox-gateway.smilepayz.com/v2.0/transaction/pay-in
production:https://gateway.smilepayz.com/v2.0/transaction/pay-in
Header Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP content type specification Fixed value: application/json Required for proper request parsing |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 Note: Must be current server time within ±5 minutes |
| X-SIGNATURE | M | String | Digital signature for request authentication See Signature Generation |
| X-PARTNER-ID | M | String | Unique merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing Please enter merchantID |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String(32) | Unique transaction identifier Format: Alphanumeric string (numbers and letters only) Length: 6-32 characters Used for transaction tracking and reference |
| purpose | M | String(64) | Transaction purpose or description Format: UTF-8 encoded string Maximum length: 64 characters Used for transaction identification and reporting |
| merchant | M | Object | Merchant information container Contains merchant identification and business details See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | O | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| money | M | Object | Transaction amount details with currency specification Contains payment amount and currency information See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents BRL 200.00 Range: 100-999999999 |
| payer | M | Object | Payer information container Contains customer identification and payment details See Payer Model |
| pixAccount | M | String | PIX account identifier (CPF or CNPJ number) Format: 11 digits (CPF) or 14 digits (CNPJ) Example: "48982488880" Used for PIX payment processing |
| paymentMethod | M | String | Payment method specification Fixed value: PIX Determines payment processing channel and rules See Payment Method List |
| expiryPeriod | O | Number | Payment expiration time in seconds Format: Integer value Default: 3600 (1 hour) Range: 3600-86400 (60 minutes to 24 hours) |
| redirectUrl | O | String(256) | Customer redirect URL after payment completion Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Used for post-payment customer experience |
Example Body – Pay-In Transaction Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"merchant": {
"merchantId": "20011"
},
"payer": {
"pixAccount": "48982488880"
},
"money": {
"amount": 20000,
"currency": "BRL"
},
"orderNo": "200110edbb466abb04682968b40",
"paymentMethod": "PIX",
"purpose": "Purpose For Transaction from Java SDK",
"redirectUrl": "https://www.google.com/webhp"
}
Response
HTTP Response
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP response content type specification Fixed value: application/json Indicates JSON response format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00+07:00 |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| code | M | String | API response status code indicating operation result Format: Two-digit string Success: "00", Error: Other codes Used for programmatic response handling |
| message | M | String | Human-readable response status description Format: UTF-8 encoded string Provides detailed information about the operation result Localized based on request language |
| orderNo | M | String | Merchant transaction reference number Format: Alphanumeric string Same as the orderNo provided in the request Used for transaction tracking and reference |
| merchant | M | Object | Merchant information container Contains merchant identification and business details See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | O | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| accountNo | O | String | Merchant account number for transaction settlement Format: Alphanumeric string Used for fund allocation and settlement |
| money | M | Object | Transaction amount details with currency specification Contains confirmed transaction amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents BRL 200.00 Used for precise amount representation |
| transactionTime | M | String | Transaction creation timestamp Format: yyyy-MM-ddTHH:mm:ss-03:00 (Brazil timezone) Example: 2020-12-17T10:55:00-03:00 Used for transaction timing and audit |
| channel | M | Object | Payment channel information container Contains payment method details and processing information See Channel Model |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Fixed value: PIX Indicates the actual payment channel used |
| paymentUrl | M | String | Payment processing URL for customer access Format: Valid HTTP/HTTPS URL Used for customer payment completion and processing |
| qrString | O | String | PIX QR code string for mobile payment apps Format: PIX QR code format string Used for mobile payment processing and customer convenience |
| additionalInfo | O | Object | Additional channel-specific information Format: JSON object Contains supplementary payment channel details when available |
| tradeNo | O | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| status | O | String | Current transaction processing status Format: Predefined status codes Examples: PROCESSING, SUCCESS, FAILED, CANCELLED Indicates the current state of the transaction See Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
{
"channel": {
"additionalInfo": {},
"paymentMethod": "PIX",
"paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=131200112412130836186234",
"qrString": "00020101021226800014br.gov.bcb.pix2558pix.delbank.com.br/v2/cob/vcharge1f6aed0623644c24bbdc174ce5204000053039865802BR5907DELBANK6007ARACAJU62070503***6304BC39"
},
"code": "00",
"merchant": {
"accountNo": "11320011202402290943",
"merchantId": "20011",
"merchantName": "bradytest123www"
},
"message": "Successful",
"money": {
"amount": 2000,
"currency": "BRL"
},
"orderNo": "20011db2773a6fb2542dfa5cb34c",
"status": "PROCESSING",
"tradeNo": "131200112412130836186234",
"transactionTime": "2024-12-12T23:36:19-03:00"
}
{
"channel": {
"additionalInfo": {
"paymentUrl": "https://gateway.smilepayz.com/cashier/#/transfer"
},
"paymentMethod": "PIX",
"paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=131200112412130836186234",
"qrString": ""
},
"code": "00",
"merchant": {
"accountNo": "11320011202402290943",
"merchantId": "20011",
"merchantName": "bradytest123www"
},
"message": "Successful",
"money": {
"amount": 2000,
"currency": "BRL"
},
"orderNo": "20011db2773a6fb2542dfa5cb34c",
"status": "PROCESSING",
"tradeNo": "131200112412130836186234",
"transactionTime": "2024-12-12T23:36:19-03:00"
}
Notification
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP request content type specification Fixed value: application/json Indicates JSON request format |
| X-TIMESTAMP | M | String | ISO 8601 datetime format with timezone offset Format: yyyy-MM-ddTHH:mm:ss±HH:mm Example: 2020-12-17T10:55:00-03:00 |
| X-SIGNATURE | M | String | Digital signature for notification authentication See Callback Signature Verification |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String | Merchant transaction reference number Format: Alphanumeric string Same as the orderNo provided in the request Used for transaction tracking and reference |
| tradeNo | M | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for merchant authentication and transaction routing |
| merchantName | M | String | Merchant business name or display name Format: UTF-8 encoded string Used for transaction identification and reporting |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Used for sub-merchant transaction routing |
| subMerchantName | O | String | Sub-merchant business name or display name Format: UTF-8 encoded string Used for sub-merchant identification and reporting |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Fixed value: PIX Indicates the actual payment channel used |
| transactionTime | M | String | Transaction completion timestamp Format: yyyy-MM-ddTHH:mm:ss Example: 2020-12-17T10:55:00-03:00 Used for transaction timing and audit |
| money | M | Object | Transaction amount details with currency specification Contains confirmed transaction amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: BRL (Brazilian Real) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 100 represents BRL 100.00 Used for precise amount representation |
| status | M | String | Final transaction processing status Format: Predefined status codes Examples: SUCCESS, FAILED, CANCELLED Indicates the final state of the transaction See Status Model |
Return
Important
Notification please return only string SUCCESS
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 100000,
"currency": "BRL"
},
"orderNo": "2000102900000000000001",
"status": "SUCCESS",
"tradeNo": "101200012410241325417215",
"transactionTime": "2020-12-17T10:55:00-03:00"
}
SUCCESS