B2B Access Token Specification
B2B Access Token API header consists of the following fields:
| 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 ID |
Content-type: application/json
X-TIMESTAMP: 2023-01-01T00:00:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-CLIENT-KEY: 962489e9-de5d-4eb7-92a4-b07d44d64bf4Asymmetric Signature SHA256withRSA
Based on the specification above, merchant should use asymmetric signature SHA256withRSA for Access Token API.
Merchant should use this formula to create X-SIGNATURE for Access Token API:
Client ID + “|” + Timestamp encrypted with merchant’s private key by using SHA256withRSA algorithm
| SHA256withRSA algorithm reference |
|---|
| 8afe58a2b2955453854b9f65d070a10ef3def877a813f8d8e427d58028398b5ea78f9fc35672a0e3d8a592ff0fc9e53bcb7f1aa478603be714aef91f52ce418430faf722e7ef1a7c87337d45c474503cb9fa70ab4371860954b3649be511737e4c1d23e10ea932c8ebab8f98468c836b899396c8c94d4f5a1a32d1141620638332310e71d752722e7a05c1b4bc4c9e5efeae26528ceba78f55c877bb3904859c9370bcc485ac3c80231a0e2b4219408958dbd3da0c815c5a847e449018e361f616bca325c3e935f79eadc6e48fd8ec04b577c2610a88da0dea580514b9394227039c0010ccbe39b3dd8461e0aa0cdb934c93b275a25b52a128d5dfd93d5341b5 |
For a better understanding, please refer to this sample scenario for generating signature using the formula above on B2B Access Token API:
No. | Steps |
|---|---|
1 | Given merchant has private key |
2 | Given merchant wants to create a request with header: |
3 | X-SIGNATURE value for encryption will be: |
4 | By using merchant’s private key to encrypt the value with SHA256withRSA algorithm, merchant will generate |
5 | Final result of merchant's header will be: |
Transactional API Specification
Transactional API header consists of the following fields:
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, received from Access Token API response |
Authorization-Customer | String | C | User Access Token which GoPay will be sharing once linking is complete. |
X-PARTNER-ID | String | M | Merchant’s partner ID |
X-EXTERNAL-ID | String | M | Merchant’s unique ID per transaction request |
CHANNEL-ID | String | M | Mandatory field from Bank Indonesia that can take any value with correct format 5 digits numeric string |
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
X-EXTERNAL-ID behaviorCurrently we have 2 usage for X-EXTERNAL-ID:
Usage #1: For account linking related endpoint (ie. get-auth, binding, unbinding),
- If merchant sends the same request with same X-EXTERNAL-ID, then Midtrans will return an error conflict (the duration is 24 hour after the first request)
Usage #2: For payment related endpoint (ie. direct debit, auth payment, etc)
- If merchant sends the same request with same X-EXTERNAL-ID and the previous response is success, then GoPay will return an idempotency response
Things to note as well, in account linking flow, the external-id will need to be unique for each merchants, means different merchant can use the same X-EXTERNAL-ID to get different response from different request.
Symmetric Signature HMAC_SHA512
Based on the specification above, merchant should use symmetric signature HMAC_SHA512 for Transactional API.
Merchant should use this formula to create X-SIGNATURE for Transactional API:
HTTPMethod +”:“+ EndpointUrl +":"+ AccessToken +":“+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ + TimeStamp encrypted with merchant’s client secret by using HMAC_SHA512 algorithm.
| HMAC_SHA512 algorithm reference |
|---|
| 1529627511dee28c3daa9a4d89f19540d71dbfaee506380288fd011f2961f88297a387ecdab1da1ac14d518d0df2dd2b3e566ce2200700e0839259c271cc2e27 |
For a better understanding, please refer to this sample scenario for generating signature using the formula above on Transactional API:
No. | Steps |
|---|---|
1 | Given merchant has client secret |
2 | Given merchant wants to create a request with header for POST https://api.midtrans.com/v1.0/registration-account-binding |
3 | X-SIGNATURE value for encryption will be: |
4 | By using merchant’s client secret to encrypt the value with HMAC_SHA512 algorithm, merchant will generate |
5 | Final result of merchant's header will be: |