This section will explain how merchants can initiate GoPay deeplink transactions using SNAP-based CoreAPI specification.
1. Access Token B2B
| Path | /{version}/access-token/b2b |
|---|---|
| SNAP service code | 73 |
| HTTP Method | POST |
| Version | v1.0 |
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 asymmetric signature SHA256withRSA algorithm | |
| X-CLIENT-KEY | String | M | Client’s client_id (PJP Name) (given at completion registration process). | |
Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-CLIENT-KEY:962489e9-de5d-4eb7-92a4-b07d44d64bf4
Request Body
| Field Name | Field Type | Mandatory | Field Description | |
| grantType | String(64) | M | client_credentials: The client can request an access token using only its client credentials (or other supported means of authentication) when the client is requesting access to the protected resources under its control (OAuth 2.0: RFC 6749 & 6750) | |
{
"grantType":"client_credentials"
}
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:2024-03-19T14:30: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. | |
| accessToken | String(2048) | C | A string representing an authorization issued to the client that used to access protected resources | |
| tokenType | String | O | The access token type provides the client with the information required to successfully utilize the access token to make a protected resource request | |
| expiresIn | String | O | Time duration when the accessToken will be expired. (default in second). | |
{
"responseCode":"2007400",
"responseMessage":"Successful",
"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMTFlZThiMi1hN2FlLTRhZGUtYmJlYS1mNzI3MDk3ZmQ0NmEiLCJjbGllbnRJZCI6IjZhZTk1N2M0LTI4NjMtNDcxMy1hY2NlLWJhMTJkZTYzNmNmYyIsIm5iZiI6MTYxMTQ2ODk3OCwiZXhwIjoxNjExNDY5ODc4LCJpYXQiOjE2MTE0Njg5Nzh9.KM7yz9GvuUaDR1bXwei4iO0h4e3g4o1Hct5Ie9VoBdo",
"tokenType":"Bearer",
"expiresIn":"900"
}
Response Body Error Case
| 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 | C | Debug id to provide more information. | |
{
"responseCode":"5007300",
"responseMessage":"Timeout",
"referenceNo":"19352694-0ef6-4439-8ad1-b1dfb8bbb85f"
}
List of Response code
| Response Code | HTTP Status Code | Response Message |
| 2007300 | 200 | Success |
| 4017300 | 401 | Unauthorized. Signature |
| 5007300 | 500 | Internal Server Error |
2. Creating GoPay/ShopeePay/Dana deeplink transaction
GoPay/ShopeePay/Dana deeplink - Direct Debit 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 from Access Token B2B API response. | |
| X-PARTNER-ID | String | M | Unique identifier for partner | |
| X-EXTERNAL-ID | String | M | Alphanumeric string. Preferably UUID. Reference number that should be unique in the same day or 1 day idempotency key | |
| CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string | |
Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CupvIJbU1Mmu4a11MNDZ7Sg5u9a
X-PARTNER-ID: BMRI
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(40) | M | Authorization token. Same as the Authorization header. | |
| merchantId | String(64) | O | Merchant identifier that is unique per each merchant | |
| validUpTo | String(25) | O | The time when the payment will be automatically expired. The format is defined by ISO 8601.
(Minimum value : 20 second, default value : 15 min) Maximum value for gopay: 180 days from trx time, Maximum value for dana: 1 days from trx time |
|
| urlParam | Array of Object | O | Merchant redirect URL. After completing payment, user will be redirected back to this URL.
if it's not provided, the system will fallback to using the callback url from the dashboard configuration. In case the Midtrans dashboard configuration value is also unavailable, the system will return an error. |
|
| urlParam.url | String(512) | M | URL value | |
| urlParam.type | String(32) | M | URL type Possible value : PAY_RETURN | |
| urlParam.isDeeplink | String(1) | M | Whether the URL is a deeplink URL or not
Possible Value: Y, N |
|
| payOptionDetails | Array of Object | M | Payment option that will be used for this payment.
|
|
| payOptionDetails.payMethod | String(64) | M | Payment method for the transaction.
Possible value : GOPAY, SHOPEEPAY, DANA |
|
| payOptionDetails.payOption | String(64) | M | Payment option which shows the provider of this payment
Reserved for future use case. |
|
| payOptionDetails.transAmount | Object | M | Payment Transaction Amount | |
| payOptionDetails.transAmount.value | String(ISO 4217) | 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 | Transaction currency that will be paid using this payment method.
Possible Value: IDR |
|
| additionalInfo | Object | O | Additional information field which merchants need to pass to support current API contracts. | |
| 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 | Customer billing address | |
| 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 | |
| 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 | Customer shipping address | |
| 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 | |
| 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 | Item Details | |
| additionalInfo.items.id | String(32) | O | Item ID | |
| additionalInfo.items.price | Object | M | Price of the item in IDR. | |
| additionalInfo.items.price.value | String (ISO4217) | M | Item Price value | |
| additionalInfo.items.price.currency | String(3) | M | Item Price currency | |
| additionalInfo.items.quantity | String | M | Quantity of the item purchased by the customer. | |
| additionalInfo.items.name | String(64) | O | Name of the item. | |
| 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.items.url | String(64) | O | HTTP URL of the item in the merchant site | |
| additionalInfo.metadata | Object | O | Transaction metadata | |
{
"partnerReferenceNo": "merchant-order-id",
"chargeToken": "accessToken",
"merchantId": "G169749203",
"urlParam": [{
"url": "https://www.gojek.com",
"type": "PAY_RETURN",
"isDeeplink": "Y"
}],
"validUpTo": "2023-09-24T20:34:15.452305Z",
"payOptionDetails": [
{
"payMethod": "gopay",
"payOption": "gopay",
"transAmount": {
"value": "12345678.00",
"currency": "IDR"
}
}
],
"additionalInfo": {
"customerDetails": {
"phone": "080123456789",
"firstName": "john",
"lastName": "doe",
"email": "[email protected]",
"billingAddress": {
"firstName": "john",
"lastName": "doe",
"phone": "080123456789",
"address": "jalan maju mundur",
"city": "jakarta",
"postalCode": "12345",
"countryCode": "IDN"
},
"shippingAddress": {
"firstName": "john",
"lastName": "doe",
"phone": "080123456789",
"address": "jalan maju mundur",
"city": "jakarta",
"postalCode": "12345",
"countryCode": "IDN"
}
},
"items": [
{
"id": "ID012345",
"price": {
"value": "12345678.00",
"currency": "IDR"
},
"quantity":"1",
"name": "someItemName",
"brand": "someBrand",
"category": "someCategory",
"merchantName": "someMerchant",
"url": "someItemUrl"
}
],
"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:2024-03-19T14:30:00+07:00
Response Body
| Field Name | Field Type | Mandatory | Field Description | |
| responseCode | String(7) | M | Status code of transaction charge result. | |
| responseMessage | String(150) | M | Description of transaction charge result. | |
| referenceNo | String(256) | C | Transaction identifier on service provider system. The field is filled upon successful transaction | |
| partnerReferenceNo | String(64) | O | Transaction identifier on service consumer system | |
| appRedirectUrl | String(2048) | O | Reserved for future purposes. | |
| webRedirectUrl | String(2048) | M | Returns a universal link to the PJP AIS payment page. This link is recommended when the Client is unable to implement a check for whether the PJP AIS app is installed on the user's device before redirection. | |
| additionalInfo | Object | O | Additional information | |
| additionalInfo.gross_amount | Object | O | Transaction amount that will be paid using this payment method. The format defined by ISO 4217. | |
| additionalInfo.gross_amount.value | String (ISO4217) | M | Gross amount value | |
| additionalInfo.gross_amount.currency | String(3) | M | Gross amount currency | |
| additionalInfo.paymentType | String(64) | O | Transaction payment method | |
| additionalInfo.transactionTime | String(ISO 8601) | O | Timestamp of transaction in ISO 8601 format using GMT+7. | |
| additionalInfo.validUpTo | String(ISO 8601) | O | The time when the payment will be automatically expired. Using ISO 8601 format | |
{
"responseCode":"2005400",
"responseMessage":"Successful",
"referenceNo":"GOPAY012345678",
"partnerReferenceNo":"merchant-order-id",
"webRedirectUrl":"https://some-url.for/redirect-to-gopay-app",
"appRedirectUrl":""
"additionalInfo":{
"paymentType": "GOPAY",
"grossAmount":{
"value": "12345678.00",
"currency": "IDR"
},
"transactionTime":"2023-09-25T02:59:19.517854Z",
"validUpTo":"2023-09-26T02:59:19Z"
}
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 |