API PAYIN
About 5 min
Request
The Pay-In API enables merchants to initiate payment collection transactions from customers.
Supported payment methods include:
UPI (Unified Payments Interface)
Other digital payment channels
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+05:30 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 for merchant tracking Format: Alphanumeric characters only Length: 6-32 characters Must be unique within merchant scope |
| purpose | M | String(64) | Human-readable transaction description Format: UTF-8 encoded string Length: 1-64 characters Used for transaction history and reporting |
| merchant | M | Object | Merchant identification and business information container Contains primary and sub-merchant details Required for transaction routing and settlement |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in payment interface and transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in payment interface and transaction records |
| money | M | Object | Transaction amount and currency specification container Defines payment value and monetary unit Required for payment processing and settlement |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
| paymentMethod | M | String | Payment method specification for Indian market Format: Predefined payment method codes Fixed value: CASHIER_IN See Payment Method List |
| expiryPeriod | O | Number | Payment session timeout duration in seconds Format: Integer value Fixed value: 420 seconds (7 minutes) Cannot be modified for Indian market compliance |
| redirectUrl | O | String(256) | Post-payment redirect destination URL Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Customer is redirected here after payment completion |
| callbackUrl | O | String(256) | Webhook notification endpoint URL Format: Valid HTTP/HTTPS URL Maximum length: 256 characters Receives real-time transaction status updates |
Important Notes
1. Payment Method Requirement: The paymentMethod field is mandatory for Indian transactions and must be set to CASHIER_IN
2. Expiry Period: The payment session timeout is fixed at 7 minutes (420 seconds) for Indian market compliance and cannot be modified
3. Currency Specification: All transactions must use INR (Indian Rupee) as the currency
4. UPI Integration: The system supports UPI payments through the CASHIER_IN payment method
Example Body – Transaction Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+05:30
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"merchant": {
"merchantId": "20001"
},
"money": {
"amount": 200,
"currency": "INR"
},
"orderNo": "20001b0f6c612283d48d0",
"paymentMethod": "CASHIER_IN",
"purpose": "Purpose For Transaction from Java SDK"
}
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+05:30 |
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 | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction tracking and reconciliation |
| tradeNo | O | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| merchant | M | Object | Merchant information container with account details Contains merchant identification and account information See Merchant Model |
| merchantId | M | String | Primary merchant identifier assigned by the platform Format: Alphanumeric string Used for transaction routing and settlement processing |
| merchantName | O | String | Registered business name of the merchant Format: UTF-8 encoded string Displayed in payment interface and transaction records |
| subMerchantId | O | String | Sub-merchant identifier for multi-level merchant structures Format: Alphanumeric string Required for sub-merchant transaction processing |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Shown in payment interface and transaction records |
| money | M | Object | Transaction amount details with currency specification Contains confirmed payment amount and currency See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
| transactionTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss±HH:mm) Example: 2020-12-17T10:55:00+05:30 Timestamp when transaction was processed by the system |
| channel | M | Object | Payment processing channel details and instructions Contains payment method, URLs, and additional data See Channel Model |
| status | O | String | Current transaction processing status Format: Predefined status codes Examples: PROCESSING, SUCCESS, FAILED See Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+05:30
{
"channel": {
"paymentMethod": "CASHIER_IN",
"paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=121200012412131607559245"
},
"code": "00",
"merchant": {
"accountNo": "11220001202402271029",
"merchantId": "20001",
"merchantName": "20001"
},
"message": "Successful",
"money": {
"amount": 200,
"currency": "INR"
},
"orderNo": "20001b0f6c612-283d-48d0-b807-a51",
"status": "PROCESSING",
"tradeNo": "121200012412131607559245",
"transactionTime": "2024-12-13T14:37:56+05:30"
}
Notification/Callback
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | HTTP notification content type specification Fixed value: application/json Indicates JSON payload 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+05:30 |
| X-SIGNATURE | M | String | Digital signature for notification verification Format: Base64 encoded signature Used to verify notification authenticity See how to check this value |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String | Original merchant transaction identifier for reference Format: Same as request orderNo Used for transaction reconciliation and tracking |
| tradeNo | M | String | Internal transaction reference number for system tracking Format: System-generated alphanumeric string Used for internal transaction management and support |
| utr | C | String | Unique Transaction Reference number for Indian banking system Format: Alphanumeric string Provided by Indian banks for transaction tracking May not be available for all transaction types |
| merchantId | M | String | Primary merchant identifier for transaction routing Format: Alphanumeric string Used for merchant identification and settlement processing |
| merchantName | M | String | Registered merchant business name for display Format: UTF-8 encoded string Shown in transaction records and reports |
| subMerchantId | O | String | Sub-merchant identifier for multi-level structures Format: Alphanumeric string Included when sub-merchant is involved in transaction |
| subMerchantName | O | String | Sub-merchant business name for display purposes Format: UTF-8 encoded string Included when sub-merchant is involved in transaction |
| paymentMethod | M | String | Payment method used for transaction processing Format: Predefined payment method codes Examples: CASHIER_IN Indicates the actual payment channel used |
| transactionTime | M | String | ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss) Timestamp when transaction was completed by payment provider |
| money | M | Object | Final transaction amount details with currency Contains confirmed payment amount and currency May differ from request amount due to fees or adjustments See Money Model |
| currency | M | String | ISO 4217 currency code specification Fixed value: INR (Indian Rupee) Determines payment processing rules and settlement currency |
| amount | M | Number | Transaction amount in smallest currency unit Format: Integer value Example: 200 represents INR 200 Range: 100-999999999 |
| status | M | String | Final transaction processing status Format: Predefined status codes Examples: SUCCESS, FAILED Indicates the final outcome of the transaction See Status Model |
Return
Important
Notification please return only string SUCCESS
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 1000,
"currency": "INR"
},
"orderNo": "2000102900000000000001",
"utr": "09787676778",
"status": "SUCCESS",
"tradeNo": "101200012410241325417215",
"transactionTime": "2020-12-17T10:55:00"
}
SUCCESS