API References
Create AccountSubmit Feedback

Access Token API

📘

BI-SNAP Compliance

This page describes the Access Token API, which implements the BI-SNAP "Komponen Server Authorization dan Authentication Method." Midtrans acts as the authorization server implementing OAuth 2.0 (RFC 6749), issuing access tokens as Bearer tokens (RFC 6750).


Access Token API is an API call that can be used to acquire B2B access token from Midtrans. This access token will be used for client-level verification and subsequent Transactional API such as initiating payment, refund, and cancel.

OAuth 2.0 Authorization Model

The BI-SNAP Access Token API follows the OAuth 2.0 Client Credentials grant type (RFC 6749 §4.4):

  • Grant type: client_credentials — the merchant authenticates using its own credentials (Client ID + asymmetric signature) rather than on behalf of a resource owner
  • Token type: Bearer (RFC 6750) — the issued access token is included as a Bearer token in the Authorization header of all subsequent Transactional API calls
  • Token lifetime: 900 seconds (15 minutes) by default. After expiry, the merchant must request a new token.
  • Signature method: The merchant proves its identity by signing the request with its private key using SHA256withRSA. Midtrans verifies the signature using the merchant's registered public key.
Path/{version}/access-token/b2b
HTTP MethodPOST
Versionv1.0
SNAP service code73

Request Header

Field NameField TypeMandatoryField Description
Content-typeStringMMedia type of the resource, i.e. application/json
X-TIMESTAMPStringMClient’s current local time in ISO-8601 format
X-SIGNATUREStringMCreated using asymmetric signature SHA256withRSA algorithm
X-CLIENT-KEYStringMClient’s client_id (given at the completion registration process)
Content-type: application/json
X-TIMESTAMP: 2030-01-01T00:00:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-CLIENT-KEY: 962489e9-de5d-4eb7-92a4-b07d44d64bf4

Request Body

Field NameField TypeMandatoryField Description
grantTypeStringMclient_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 NameField TypeMandatoryField Description
Content-typeStringMMedia type of the resource, i.e. application/json
X-TIMESTAMPStringMClient’s current local time in ISO-8601 format
Content-type: application/json
X-TIMESTAMP: 2030-01-01T00:00:00+07:00

Response Body

Field NameField TypeMandatoryField Description
responseCodeString(7)MError code to specify the error returned.
responseMessageString (150)MDebug message to provide more information.
accessTokenString (2048)CA string representing an authorization issued to the client that used to access protected resources.

Will only be returned if API call is successful.
tokenTypeStringCThe access token type provides the client with the information required to successfully utilize the access token to make a protected resource request.

Will only be returned if API call is successful.
expiresInStringCTime duration when the accessToken will expire. (default = 900 second).

Will only be returned if API call is successful.
referenceNoStringCDebug ID to provide more information.

Will only be returned if API call is failure.
{
   "responseCode":"2007300",
   "responseMessage":"Successful",
  "accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMTFlZThiMi1hN2FlLTRhZGUtYmJlYS1mNzI3MDk3ZmQ0NmEiLCJjbGllbnRJZCI6IjZhZTk1N2M0LTI4NjMtNDcxMy1hY2NlLWJhMTJkZTYzNmNmYyIsIm5iZiI6MTYxMTQ2ODk3OCwiZXhwIjoxNjExNDY5ODc4LCJpYXQiOjE2MTE0Njg5Nzh9.KM7yz9GvuUaDR1bXwei4iO0h4e3g4o1Hct5Ie9VoBdo",
   "tokenType":"Bearer",
   "expiresIn":"900"
}
{
   "responseCode":"5007300",
   "responseMessage":"Internal Server Error",
   "referenceNo":"19352694-0ef6-4439-8ad1-b1dfb8bbb85f"
}

List of Response Code

Response CodeHTTP Status CodeResponse Message
2007300200Success
4017300401Unauthorized Signature
5007300500Internal Server Error


B2B Access Token Header Structure (ASPI Mapping)

The following table maps the Access Token API header fields to ASPI's "Komponen Struktur Format Header – Access Token (B2B)" specification:

Header FieldASPI ComponentFormat / ValueRequiredDescription
Content-TypeContent-Typeapplication/jsonMandatoryMedia type of the request body
X-TIMESTAMPTimestampISO-8601: YYYY-MM-DDTHH:MM:SS±HH:MMMandatoryMerchant's current local time. Used in signature generation and for request freshness validation.
X-CLIENT-KEYClient IDString (provided by Midtrans)MandatoryIdentifies the merchant. Corresponds to the clientId issued during credential exchange.
X-SIGNATUREDigital SignatureBase64-encoded SHA256withRSA signatureMandatoryStringToSign: X-CLIENT-KEY + "|" + X-TIMESTAMP
Algorithm: SHA256withRSA
Signing key: Merchant's private key

Request Body Fields (B2B)

FieldASPI ComponentValueRequiredDescription
grantTypeGrant Type"client_credentials"MandatoryOAuth 2.0 grant type per RFC 6749 §4.4

Sample Request (B2B)

POST /v1.0/access-token/b2b HTTP/1.1
Host: merchants.midtrans.com
Content-Type: application/json
X-TIMESTAMP: 2024-03-15T10:30:00+07:00
X-CLIENT-KEY: G1234325-SNAP
X-SIGNATURE: iv5YorKVVFOFS59l0HChDvPe+HeoE/jY5CfVgCg5i16nj5/DVnKg49ilkv8PyeU7...

{
  "grantType": "client_credentials"
}

Sample Successful Response

{
  "responseCode": "2007300",
  "responseMessage": "Successful",
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": "900"
}

📘

Compliance Note

This Access Token API implementation satisfies the BI-SNAP "Server Authorization dan Authentication Method" component. The asymmetric signature (SHA256withRSA) ensures non-repudiation — only the holder of the merchant's private key can generate a valid signature, and Midtrans verifies it using the merchant's registered public key.



Related Pages

Updated about 1 month ago

Updated about 1 month ago