Create Payment
- Endpoint:
POST /v1.0/debit/payment-host-to-host - Tags: Indonesia SNAP/Collection
Parameters
| Field | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
Content-Type | header | string | Yes | Content type, value always application/json | |
X-TIMESTAMP | header | string | Yes | Transaction date time, in format yyyy-MM-dd'T'HH:mm:ss.SSSXXX | |
X-SIGNATURE | header | string | Yes | Signature need to be generated with symmetricSignature or asymmetricSignature method | |
ORIGIN | header | string | No | Origin domain | |
X-PARTNER-ID | header | string | Yes | Unique identifier for partner was generated by payermax, or known as clientId | |
X-EXTERNAL-ID | header | string | Yes | Unique messaging reference identifier generated by merchant and should be unique within the same day | |
CHANNEL-ID | header | string | Yes | Device identification on which the API services is currently being accessed by the end user (customer) | |
Authorization | header | string | Yes | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token |
Parameter Examples
Content-Type:"application/json"X-TIMESTAMP:""X-SIGNATURE:""ORIGIN:""X-PARTNER-ID:""X-EXTERNAL-ID:""CHANNEL-ID:""Authorization:""
Request Body
Content-Type: application/json
| Field | Type | Required | Constraints | Description | Enum |
|---|---|---|---|---|---|
merchantId | string | No | maxLength: 32 | Merchant identifier that is unique per each merchant | |
subMerchantId | string | No | maxLength: 64 | Sub-merchant identifier. Required for platform merchants. | |
partnerReferenceNo | string | Yes | maxLength: 64 | Unique transaction identifier on partner system which assigned to each transaction | |
amount | object | Yes | Transaction amount | ||
amount.value | string | Yes | The order amount is passed in by the merchant. The decimal point supported by the currency of each country. | ||
amount.currency | string | Yes | maxLength: 3 | Currency code, capital letter. | |
externalStoreId | string | No | maxLength: 64 | Store identifier to indicate to which store this payment belongs to | |
validUpTo | string | No | maxLength: 29 | The time when the payment will be automatically expired, in format yyyy-MM-dd'T'HH:mm:ss.SSSXXX | |
urlParams | array[object] | No | Notify URL that merchant must send the payment notification to | ||
urlParams[].url | string | Yes | maxLength: 512 | The URL | |
urlParams[].type | string | Yes | maxLength: 32 | URL Type:PAY_RETURN or PAY_NOTIFY | |
urlParams[].isDeeplink | string | Yes | maxLength: 1 | Whther the URL is a deeplink URL or not:Y or N | |
payOptionDetails | array[object] | No | Payment option that will be used for this payment, this filed only supports passing one item currently | ||
payOptionDetails[].payMethod | string | No | maxLength: 64 | Payment Method. e.g. CREDIT_CARD | |
payOptionDetails[].payOption | string | No | maxLength: 64 | Payment option which shows the provider of this payment e.g. CREDIT_CARD_VISA | |
payOptionDetails[].additionalInfo | object | No | |||
payOptionDetails[].additionalInfo.payAccountInfo | array[object] | No | Payment account info.Support collect payer’s account info on merchant side when specifying the payment method and target organization | ||
payOptionDetails[].additionalInfo.payAccountInfo[].accountNoType | string | No | maxLength: 32 | account type:EMAIL,PHONE,ACCOUNT. | |
payOptionDetails[].additionalInfo.payAccountInfo[].accountNo | string | No | maxLength: 32 | The payment account registered by the user in the target institution under this payment method. | |
payOptionDetails[].additionalInfo.cardInfo | object | No | Card information | ||
payOptionDetails[].additionalInfo.cardInfo.cardExpirationMonth | string | No | maxLength: 2 | Card Expiration Date - month, two digits. | |
payOptionDetails[].additionalInfo.cardInfo.cardExpirationYear | string | No | maxLength: 2 | Card Expiration Date - year, only the last two years are taken. | |
payOptionDetails[].additionalInfo.cardInfo.cardHolderFullName | string | No | maxLength: 64 | Cardholder’s Name. | |
payOptionDetails[].additionalInfo.cardInfo.cardIdentifierNo | string | No | maxLength: 19 | card ID, card number. | |
payOptionDetails[].additionalInfo.cardInfo.cvv | string | No | maxLength: 4 | Card cvv, three digits for Visa and Master, four digits for AMEX. | |
payOptionDetails[].additionalInfo.cardInfo.dynamic3DS | string | No | maxLength: 64 | ynamic 3ds (case insensitive) do3DS: Perform 3D Secure for this order. no3DS: Do not perform 3D Secure for this order. ext3DS: Use external 3DS results, suitable for merchants who have integrated 3DS services. The info3DSecure object is required when using this value. If no value is passed or other values are passed in, PayerMax will determine whether to initiate 3ds | |
payOptionDetails[].additionalInfo.paymentTokenID | string | No | maxLength: 64 | When paying with card token | |
payOptionDetails[].additionalInfo.buyerInfo | object | No | buyer information. when additionalInfo.integrate is Direct_Payment, this filed is Mandatory | ||
payOptionDetails[].additionalInfo.buyerInfo.firstName | string | No | maxLength: 64 | first name of the user. | |
payOptionDetails[].additionalInfo.buyerInfo.middleName | string | No | maxLength: 64 | Middle name of the buyer. | |
payOptionDetails[].additionalInfo.buyerInfo.address | string | No | maxLength: 1024 | user’s address. | |
payOptionDetails[].additionalInfo.buyerInfo.city | string | No | maxLength: 64 | user’s city. | |
payOptionDetails[].additionalInfo.buyerInfo.idNo | string | No | maxLength: 64 | Id NO. | |
payOptionDetails[].additionalInfo.buyerInfo.idType | string | No | maxLength: 32 | Id type. | |
payOptionDetails[].additionalInfo.buyerInfo.region | string | No | maxLength: 64 | user’s region. | |
payOptionDetails[].additionalInfo.buyerInfo.taxNo | string | No | For tax number, please refer to 【Personal Identification】 Note:This field is required for the country of Brazil, which is the Brazilian ID number. | ||
payOptionDetails[].additionalInfo.buyerInfo.taxType | string | No | For tax types, please refer to 【Personal Identification】 Note:This field of Brazil country must be passed into CPF | ||
payOptionDetails[].additionalInfo.buyerInfo.zipCode | string | No | maxLength: 32 | post code. | |
payOptionDetails[].additionalInfo.buyerInfo.lastName | string | No | maxLength: 64 | last name of the user. | |
payOptionDetails[].additionalInfo.buyerInfo.phoneNo | string | No | maxLength: 32 | phone number of the user. | |
payOptionDetails[].additionalInfo.buyerInfo.clientIp | string | No | user’s IP address. Required when additionalInfo.integrate is Direct_Payment | ||
payOptionDetails[].additionalInfo.buyerInfo.userAgent | string | No | User browser information. Required when additionalInfo.integrate is Direct_Payment | ||
additionalInfo | object | Yes | Additional information | ||
additionalInfo.version | string | Yes | maxLength: 8 | API version. Current value: 1.4 | |
additionalInfo.keyVersion | string | Yes | maxLength: 8 | Signature Algorithm Version, Current value: 1 | |
additionalInfo.spMerchantNo | string | No | maxLength: 32 | ISV merchant identifier. Provide this field when using the ISV integration model. | |
additionalInfo.integrate | string | Yes | maxLength: 16 | Hosted_Checkout or Direct_Payment | |
additionalInfo.terminalType | string | No | maxLength: 3 | Device terminal, the values is WEB, WAP, APP; when integrate is Direct_Payment, this value is required | |
additionalInfo.subject | string | Yes | maxLength: 256 | Order title or product information, avoid using pure numbers, such as using PayerMax_Hosted_Payment_Page, it will be displayed on the user payment page Note: Brazil Pix cannot exceed 43 digits | |
additionalInfo.country | string | Yes | maxLength: 2 | Country code, in uppercase letters. | |
additionalInfo.userId | string | Yes | maxLength: 64 | The user ID by the merchant, needs to ensure the uniqueness of each user.After the payment method is saved, the payment method will be recommended according to the userId. | |
additionalInfo.referralCode | string | No | maxLength: 32 | According to the needs of merchants, add recommended payment method dimensions, such as device ID, device fingerprint, etc., before using, please contact the docking staff. | |
additionalInfo.language | string | No | maxLength: 8 | Cashier page language | |
additionalInfo.reference | string | No | maxLength: 512 | Customized data for merchant, will be returned in Callback Notification and Inquiry. | |
additionalInfo.goodsDetails | array[object] | No | The goods that the user buys. A list can be submitted. Note:E-commerce industy needs to send.If the object is passed in, the inner required fields must be passed in | ||
additionalInfo.goodsDetails[].goodsId | string | Yes | maxLength: 64 | Product identifier. Required when a goodsDetails item is provided. | |
additionalInfo.goodsDetails[].goodsName | string | Yes | maxLength: 128 | Product name. Required when a goodsDetails item is provided. | |
additionalInfo.goodsDetails[].quantity | string | Yes | maxLength: 16 | Number of units purchased. | |
additionalInfo.goodsDetails[].price | string | Yes | maxLength: 20 | Unit price set by the merchant. | |
additionalInfo.goodsDetails[].goodsCurrency | string | No | maxLength: 3 | Currency of the product price, in uppercase letters. | |
additionalInfo.goodsDetails[].showUrl | string | No | maxLength: 128 | Product URL. Required for e-commerce transactions. | |
additionalInfo.goodsDetails[].goodsCategory | string | No | Product category. Required for e-commerce transactions. | ||
additionalInfo.shippingInfo | object | No | shipping info. Note:E-commerce industy needs to send.If the object is passed in, the inner required fields must be passed in | ||
additionalInfo.shippingInfo.firstName | string | Yes | maxLength: 64 | First name of the shipping contact. | |
additionalInfo.shippingInfo.middleName | string | No | maxLength: 64 | Middle name of the shipping contact. | |
additionalInfo.shippingInfo.lastName | string | Yes | maxLength: 64 | Last name of the shipping contact. | |
additionalInfo.shippingInfo.phoneNo | string | Yes | maxLength: 32 | Phone number of the shipping contact. | |
additionalInfo.shippingInfo.email | string | Yes | maxLength: 255 | Email address of the shipping contact. Required when shippingInfo is provided. | |
additionalInfo.shippingInfo.address1 | string | Yes | maxLength: 1024 | First line of the shipping address. Required when shippingInfo is provided. | |
additionalInfo.shippingInfo.address2 | string | No | maxLength: 1024 | Second line of the shipping address. | |
additionalInfo.shippingInfo.city | string | Yes | maxLength: 64 | City of shipping address. Required when shippingInfo is provided. | |
additionalInfo.shippingInfo.region | string | No | maxLength: 64 | Region of the shipping address. | |
additionalInfo.shippingInfo.state | string | No | maxLength: 32 | State or province of the shipping address. Required for Canada, the United States, the United Kingdom, and Australia. | |
additionalInfo.shippingInfo.country | string | Yes | maxLength: 2 | Country of shipping address. Required when shippingInfo is provided. | |
additionalInfo.shippingInfo.zipCode | string | Yes | maxLength: 16 | Shipping address Zip code. Required when shippingInfo is provided. | |
additionalInfo.billingInfo | object | No | Billing Information.Note:If the object is passed in, the inner required fields must be passed in | ||
additionalInfo.billingInfo.firstName | string | No | maxLength: 64 | First name of the billing contact. | |
additionalInfo.billingInfo.middleName | string | No | maxLength: 64 | Middle name of the billing contact. | |
additionalInfo.billingInfo.lastName | string | No | maxLength: 64 | Last name of the billing contact. | |
additionalInfo.billingInfo.email | string | Yes | maxLength: 255 | Email address of the billing contact. | |
additionalInfo.billingInfo.phoneNo | string | No | maxLength: 32 | Phone number of the billing contact. | |
additionalInfo.billingInfo.address1 | string | Yes | maxLength: 255 | First line of the billing address. | |
additionalInfo.billingInfo.address2 | string | No | maxLength: 1024 | Second line of the billing address. | |
additionalInfo.billingInfo.city | string | Yes | maxLength: 64 | City of billing address. | |
additionalInfo.billingInfo.region | string | No | maxLength: 64 | Region of the billing address. | |
additionalInfo.billingInfo.state | string | No | maxLength: 32 | State or province of the billing address. Required for Canada, the United States, the United Kingdom, and Australia. | |
additionalInfo.billingInfo.country | string | Yes | maxLength: 2 | Country of billing address. | |
additionalInfo.billingInfo.zipCode | string | No | maxLength: 16 | Postal or ZIP code of the billing address. | |
additionalInfo.riskParams | object | No | Risk control business data,see:【Risk Information】. This part of information is usually used as supplementary information for customized risk control. If customized risk control is not enabled, it can be left blank. | ||
additionalInfo.envInfo | object | No | environmental information | ||
additionalInfo.envInfo.deviceId | string | No | Merchant device unique identifier | ||
additionalInfo.envInfo.deviceLanguage | string | No | Device default language | ||
additionalInfo.envInfo.screenHeight | string | No | device height | ||
additionalInfo.envInfo.screenWidth | string | No | device width |
Example
json
{
"merchantId": "{{newMerchantNo}}",
"partnerReferenceNo": "{{$uuid}}",
"subMerchantId": "{{subMerchantId}}",
"amount": {
"value": "100000.00",
"currency": "IDR"
},
"externalStoreId": "STORE001",
"validUpTo": "2026-11-16T23:59:59.000+07:00",
"urlParams": [
{
"url": "https://merchant.example.com/payment/return",
"type": "PAY_RETURN",
"isDeeplink": "N"
},
{
"url": "https://merchant.example.com/snap/notify",
"type": "PAY_NOTIFY",
"isDeeplink": "N"
}
],
"payOptionDetails": [
{
"payMethod": "CARD",
"payOption": "VISA",
"additionalInfo": {
"payAccountInfo": [
{
"accountNoType": "EMAIL",
"accountNo": "buyer@example.com"
},
{
"accountNoType": "PHONE",
"accountNo": "6281234567890"
}
],
"cardInfo": {
"cardExpirationMonth": "12",
"cardExpirationYear": "30",
"cardHolderFullName": "John Smith",
"cardIdentifierNo": "{{cardNumber}}",
"cvv": "{{cvv}}",
"dynamic3DS": "do3DS"
},
"paymentTokenID": "{{paymentTokenID}}",
"buyerInfo": {
"firstName": "John",
"middleName": "William",
"lastName": "Smith",
"address": "Example Street 1",
"city": "Jakarta",
"idNo": "{{buyerIdNo}}",
"idType": "{{buyerIdType}}",
"region": "Jakarta",
"taxNo": "{{buyerTaxNo}}",
"taxType": "{{buyerTaxType}}",
"zipCode": "10110",
"phoneNo": "6281234567890",
"clientIp": "192.0.2.10",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36"
}
}
}
],
"additionalInfo": {
"version": "1.4",
"keyVersion": "1",
"spMerchantNo": "{{spMerchantNo}}",
"integrate": "Hosted_Checkout",
"terminalType": "APP",
"subject": "40 Diamonds",
"country": "ID",
"userId": "USER001",
"referralCode": "DEVICE001",
"language": "en",
"reference": "merchant-reference-001",
"goodsDetails": [
{
"goodsId": "GOODS001",
"goodsName": "20 Diamonds",
"quantity": "1",
"price": "50000.00",
"goodsCurrency": "IDR",
"showUrl": "https://merchant.example.com/goods/GOODS001",
"goodsCategory": "Digital goods"
},
{
"goodsId": "GOODS002",
"goodsName": "20 Diamonds",
"quantity": "1",
"price": "50000.00",
"goodsCurrency": "IDR",
"showUrl": "https://merchant.example.com/goods/GOODS002",
"goodsCategory": "Digital goods"
}
],
"shippingInfo": {
"firstName": "John",
"middleName": "William",
"lastName": "Smith",
"phoneNo": "6281234567890",
"email": "buyer@example.com",
"address1": "Example Street 1",
"address2": "Unit 2",
"city": "Jakarta",
"region": "Jakarta",
"state": "Jakarta",
"country": "ID",
"zipCode": "10110"
},
"billingInfo": {
"firstName": "John",
"middleName": "William",
"lastName": "Smith",
"email": "buyer@example.com",
"phoneNo": "6281234567890",
"address1": "Example Street 1",
"address2": "Unit 2",
"city": "Jakarta",
"region": "Jakarta",
"state": "Jakarta",
"country": "ID",
"zipCode": "10110"
},
"riskParams": {
"isGuest": "N",
"isAgent": "N"
},
"envInfo": {
"deviceId": "DEVICE001",
"deviceLanguage": "en",
"screenHeight": "1080",
"screenWidth": "1920"
}
}
}Responses
200
| Field | Type | Required | Constraints | Description | Enum |
|---|---|---|---|---|---|
referenceNo | string | Yes | maxLength: 64 | Transaction identifier on payermax system | |
additionalInfo | object | Yes | Additional information | ||
additionalInfo.latestTransactionStatus | string | Yes | maxLength: 2 | Category code for the status of the transaction. The values include: 00 = Success, the order has been successfully in final state and paid 03 = Pending, the order is in process, not in final state, payment is success 05 = Cancelled, the order has been closed 06 = Failed, the order has been failed | |
additionalInfo.qrCode | string | No | maxLength: 512 | QR code information returned for payment methods that support QR code payments. | |
additionalInfo.vaCode | string | No | maxLength: 64 | Bank payment account information returned for applicable payment methods. | |
webRedirectUrl | string | Yes | maxLength: 1024 | payermax checkout URL | |
partnerReferenceNo | string | Yes | maxLength: 64 | Unique transaction identifier on partner system which assigned to each transaction | |
responseMessage | string | Yes | maxLength: 256 | response msg | |
responseCode | string | Yes | maxLength: 7 | response code |
Response Example
json
{
"referenceNo": "T2024030612031450000064",
"additionalInfo": {
"latestTransactionStatus": "PENDING",
"qrCode": "000201010212...6304ABCD",
"vaCode": "8808123456789012"
},
"webRedirectUrl": "https://cashier-n-ind-test.payermax.id/v2/index.html#/payments?merchantId=P05010114269706&merchantAppId=3d99d87a345c4c38aa23cfd7dde01592&country=ID&tradeToken=T2024030612031450000064&language=id&token=8673428cf610486a88c6720b191dc0a5&amount=100000¤cy=IDR&version=1.4&cashierId=T2024030612031450000064&frontCallbackUrl=https%3A%2F%2Fwww.payermax.com&pmaxLinkV=1",
"partnerReferenceNo": "9755fe22-aa4a-4bae-a064-c5b850156ef5",
"responseMessage": "Success.",
"responseCode": "2005400"
}