This section will explain how merchant can initiate GoPay Tokenization (non Pre-Auth) transactions using SNAP-based CoreAPI specification.
- In order to do GoPay Tokenization transaction, merchant should link the customer's GoPay account first by initiating the Account Linking API.
- Once linked, merchant can create a transaction by calling Direct Debit Payment API.
- Merchant can also do other subsequent actions such as Cancel, Refund, and Get Status.
- To receive payment notification from Midtrans, merchant will need to also implement Payment Notification API.
Creating GoPay Tokenization transaction
GoPay Tokenization - Direct Debit Payment API
| Path | /{version}/debit/payment-host-to-host |
|---|---|
| HTTP Method | POST |
| Version | v1.0 |
| SNAP service code | 54 |
Request Header
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| Content-type | String | M | Media type of the resource, i.e. application/json |
| X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
| X-SIGNATURE | String | M | Created using symmetric signature HMAC_SHA512 algorithm |
| Authorization | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token. Can get this token from Access Token B2B API response. |
| Authorization-Customer | String | M | Represents access_token of a request; string starts with keyword “Bearer ” followed by access_token from Binding API response |
| X-PARTNER-ID | String | M | Unique identifier for partner. Merchant can send any value. |
| X-EXTERNAL-ID | String | M | Numeric string. Preferably UUID. Reference number that should be unique in the same day or 1 day idempotency key. In case of timeout, merchant can do: 1. Use this value in get status API to get status transaction or 2. Retry this request with the same X-EXTERNAL-ID and request body to avoid creating duplicate transaction |
| CHANNEL-ID | String | M | Channel ID Device identification on which the API services are currently being accessed by the end user. Given by BI |
| X-DEVICE-ID | String | M | Device identification on which the API services are currently being accessed by the end user (customer). |
Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
Authorization-Customer: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: BMRI
X-DEVICE-ID: 0987ADCASA
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345
Request Body
| Field Name | Field Type | Mandatory | Field Description | |
| partnerReferenceNo | String (64) | M | Merchant order id
Only used for debugging purpose in server side |
|
| chargeToken | String | M | The account token used to represent the account binding between merchant and GoPay.
We are not sharing accountToken/accessToken with Merchants. Merchant needs to call the Binding Inquiry API to fetch the accountToken/accessToken. |
|
| urlParam | Array of Object | O | Merchant redirect URL.
After completing payment, user will be redirected back to this URL |
|
| urlParam.url | String(512) | M | URL value (need to be whitelisted as part of GoPay Tokenization onboarding process) | |
| urlParam.type | String(32) | M | Possible value : PAY_RETURN | |
| urlParam.isDeeplink | String(1) | M | Is Deeplink or not (Y/N) | |
| validUpTo | String(25) | O | The time when the payment will be automatically expired. Using ISO 8601 format
(Maximum value: 180 days from transaction time, minimum value: 20 seconds, default value: 15 minutes) |
|
| payOptionDetails | Array of Object | M | Payment option that will be used for this payment
Currently only accept 1 payOptions |
|
| payOptionDetails.payMethod | String (64) | M | Payment method. e.g. CREDIT_CARD, GOPAY | |
| payOptionDetails.payOption | String (64) | M | Payment option which shows the provider of this payment
e.g. GOPAY_WALLET, GOPAY_COINS, etc (Value can be acquired from additionalInfo.paymentOptions.name in Binding Inquiry API response) |
|
| payOptionDetails.transAmount | Object | O | Payment transaction amount | |
| payOptionDetails.transAmount.value | String (16,2) | M | Transaction amount that will be paid using this payment method. If it's IDR then value includes 2 decimal digits.
e.g. IDR 10.000 will be placed as 10000.00 Minimum value: 1.00 Maximum value : 99999999999.00 |
|
| payOptionDetails.transAmount.currency | String (3) | M | IDR | |
| payOptionDetails.additionalInfo | Object | M | Additional information field which merchants need to pass to support current API contracts. | |
| payOptionDetails.additionalInfo.recurring | String | O | Recurring flag
Possible value : Y/N If recurring: Y then we will treat this transaction as recurring transaction and bypass PIN challenge. Only applies if recurring feature has already been enabled, please talk to your Midtrans sales representative to have this feature enabled. |
|
| payOptionDetails.additionalInfo.promotionIds | Array of String | O | List of promotion ID
Promotion ID can be obtained from Get Promotion API. |
|
| payOptionDetails.additionalInfo.paymentoptiontoken | String | M | paymentOptionToken | |
| additionalInfo | Object | O | Additional Information | |
| additionalInfo.customerDetails | Object | O | Customer detail information | |
| additionalInfo.customerDetails.phone | String(15) | O | Customer phone number | |
| additionalInfo.customerDetails.email | String(255) | O | Customer email | |
| additionalInfo.customerDetails.firstName | String(255) | O | Customer first name | |
| additionalInfo.customerDetails.lastName | String(255) | O | Customer last name | |
| additionalInfo.customerDetails.billingAddress | Object | O | ||
| additionalInfo.customerDetails.billingAddress.firstName | String(255) | O | Billing address first name | |
| additionalInfo.customerDetails.billingAddress.lastName | String(255) | O | Billing address last name | |
| additionalInfo.customerDetails.billingAddress.phone | String(15) | O | Billing address phone number | |
| additionalInfo.customerDetails.billingAddress.address | String(255) | O | Billing address detail | |
| additionalInfo.customerDetails.billingAddress.city | String(255) | O | Billing address city | |
| additionalInfo.customerDetails.billingAddress.postalCode | String(255) | O | Billing address postal code | |
| additionalInfo.customerDetails.billingAddress.countryCode | String(15) | O | Billing address country code | |
| additionalInfo.customerDetails.shippingAddress | Object | O | ||
| additionalInfo.customerDetails.shippingAddress.firstName | String(255) | O | Shipping address first name | |
| additionalInfo.customerDetails.shippingAddress.lastName | String(255) | O | Shipping address last name | |
| additionalInfo.customerDetails.shippingAddress.phone | String(15) | O | Shipping address phone number | |
| additionalInfo.customerDetails.shippingAddress.address | String(255) | O | Shipping address detail | |
| additionalInfo.customerDetails.shippingAddress.city | String(255) | O | Shipping address city | |
| additionalInfo.customerDetails.shippingAddress.postalCode | String(255) | O | Shipping address postal code | |
| additionalInfo.customerDetails.shippingAddress.countryCode | String(15) | O | Shipping address country code | |
| additionalInfo.items | Array Of Object | O | ||
| additionalInfo.items.id | String(32) | O | Item ID
Shall merchant intent to apply SKU based promotion, merchant should pass the agreed item ID value for promotion. |
|
| additionalInfo.items.price | Object | M | ||
| additionalInfo.items.price.value | String (ISO4217) | M | Item price value | |
| additionalInfo.items.price.currency | String | M | Item price currency | |
| additionalInfo.items.quantity | String(16) | M | Item quantity | |
| additionalInfo.items.name | String(64) | M | Item name | |
| additionalInfo.items.merchantName | String(64) | O | Name of the merchant selling the item | |
| additionalInfo.items.brand | String(64) | O | Brand name of the item | |
| additionalInfo.items.category | String(64) | O | Category of the item | |
| additionalInfo.metadata | Object | O | Transaction metadata | |
{
"partnerReferenceNo": "merchant-order-id",
"chargeToken": “accessToken",
"validUpTo": “2023-07-03T10:36:17+07:00",
"payOptionDetails": [
{
"payMethod": "Gopay",
"payOption": "Coins",
"transAmount": {
"value": "12345678.00",
"currency": "IDR"
},
"additionalInfo": {
"paymentOptionToken": "aGoPayWalletToken / aPayLaterToken / aGoPayCoinsToken",
"challengeId": "aChallengeID",
"paymentToken": "aPaymentToken"
}
}
],
"urlParam":
{
"url": "www.merchant.com",
"type": "PAY_RETURN",
"isDeeplink": “Y/N”
},
"additionalInfo": {
"customerDetails": {
"phone": "81234532422",
"firstName": "farz",
"lastName": "zsasa",
"email": "[email protected]",
"billingAddress": {
"firstName": "billingFirstName",
"lastName": "billingLastName",
"phone": "billingPhone",
"address": "billingAddress",
"city": "billingCity",
"postalCode": "12790",
"countryCode": "CZH"
},
"shippingAddress": {
"firstName": "shippingFirstName",
"lastName": "shippingLastName",
"phone": "shippingPhone",
"address": "shippingAddress",
"city": "shippingCity",
"postalCode": "12790",
"countryCode": "CZH"
},
},
"items": [
{
"id": "8za1ieleavwusxn6u5re60ri",
"price": {
"value": "12345678.00",
"currency": "IDR"
},
"quantity": “1”,
"name": "subscription ",
"brand": "brand ",
"category": "Subsciption ",
"merchantName": "amazon prime"
}
],
"metadata": {}
}
}
Response Header
| Field Name | Field Type | Mandatory | Field Description |
|---|---|---|---|
| Content-type | String | M | Media type of the resource, i.e. application/json |
| X-TIMESTAMP | String | M | Client’s current local time in ISO-8601 format |
Content-type: application/json
X-TIMESTAMP: 2020-01-01T00:00:00+07:00
Response Body
| Field Name | Field Type | Mandatory | Field Description | |
| responseCode | String (7) | M | Error code to specify the error returned. | |
| responseMessage | String (150) | M | Debug message to provide more information. | |
| referenceNo | String (256) | M | Transaction unique identifier on service provider system. For e.g : GopayOrderId (Only filled if transaction created successfully) |
|
| partnerReferenceNo | String (32) | O | Transaction identifier on service consumer system (Merchant order ID) | |
| webRedirectUrl | String (2048) | M | Returns a universal link to GoPay PIN page. Use this link to redirect user to GoPay PIN page for them to complete payment. This can be open via webview / app redirection depending on which flow the merchant is onboarded. | |
| additionalInfo | Object | O | Additional information | |
| additionalInfo.gross_amount | Object | M | ||
| additionalInfo.gross_amount.value | String (ISO4217) | M | Gross amount value | |
| additionalInfo.gross_amount.currency | String | M | Gross amount currency | |
| additionalInfo.payOptionDetails | Array of Object | M | Payment option detail | |
| additionalInfo.payOptionDetails.payMethod | String | M | Gopay | |
| additionalInfo.payOptionDetails.payOptions | String | M | Gopay payment option used | |
| additionalInfo.transactionTime | String | O | Timestamp of transaction in ISO 8601 format. Time zone: GMT+7. | |
| additionalInfo.transactionStatus | String | O | Transaction status
Possible Values:
|
|
| additionalInfo.fraudStatus | String | O | Fraud status | |
| additionalInfo.validUpTo | String(25) | O | The time when the payment will be automatically expired. Using ISO 8601 format | |
{
"responseCode":"20054000",
"responseMessage":"Request has been processed successfully",
"referenceNo":"Gopay-order-id",
"partnerReferenceNo":"merchant-order-id",
"webRedirectUrl":"https://pjsp.com/universal?bizNo=REF993883&...",
"additionalInfo":{
"grossAmount":{
"value": "12345678.00",
"currency": "IDR"
},
"currency":"IDR",
“payOptionDetails” : [{
"payMethod":"Gopay",
"payOption": "Coins"
}],
"transactionTime":"",
"transactionStatus":"settlement",
"fraudStatus":"some-fraud-status" ,
"validUpTo":"2023-07-03T10:36:17+07:00"
}
}
{
"responseCode":"4001001",
"responseMessage":"There is some issue with the transaction request",
"originalExternalId": "merchant-order-id",
}
List of response code
| Response Code | HTTP Status Code | Response Message |
| 4005402 | 400 | Invalid Mandatory Field chargeToken , partnerReferenceNo |
| 4015400 | 401 | Unauthorized. Auth token required |
| 4015401 | 401 | Invalid Token (B2B) |
| 4015402 | 401 | Invalid Customer Token |
| 4035403 | 403 | Suspected Fraud |
| 4035414 | 403 | Insufficient Funds |
| 4035415 | 403 | Transaction Not Permitted. Url not whitelisted. |
| 5005401 | 500 | Internal Server Error |
| 5045400 | 504 | Timeout |