Moving to BI-SNAP based Core API

📘

For more details on merchant migration & backward compatibility, please refer to this page

As regulated by Bank Indonesia, merchants will need to integrate to BI-SNAP-based Core API. This section describes how Midtrans merchant can move to this new API, we will also explain in detail what are the differences between BI-SNAP-based Core API and Midtrans existing Core API.

API Domain

EnvironmentLegacy Core APIBI-SNAP-based Core API
Sandboxapi.sandbox.midtrans.com
Staging- Get Auth Code API: merchants-app.stg.midtrans.com
- All other APIs: merchants.stg.midtrans.com
Productionapi.midtrans.com- Get Auth Code API: merchants-app.midtrans.com
- All other APIs: merchants.midtrans.com


Authorization

Merchant Credentials

Legacy Core APICredentialsDefinition
Server keyMerchant’s key generated by Midtrans that is used for BASIC AUTH authentication for all Midtrans API
Merchant ID (MID)Merchant’s unique ID generated by Midtrans as part of the onboarding process


While in SNAP-based Core API, the credentials differ based on the API scope as follow:

BI-SNAP-based Core APICredentialsDefinitionRemarks
Both API scopeMerchant ID (MID)Merchant’s unique ID generated by MidtransExisting
Access Token API scopeMerchant's public keyCreated by merchant. Will be used by Midtrans to validate merchant’s signatureNew
Client IDProvided by Midtrans. Will be used as X-CLIENT-KEY on request headerNew
Transactional API scopeClient secretProvided by Midtrans. Will be used for signature generationNew
Partner IDProvided by Midtrans. Will be used as X-PARTNER-ID on request headerNew

Authorization Behavior

Legacy Core APIBI-SNAP-based Core API
Merchant will only need to use server key to initiate API calls1. Merchant need to call Access Token API first to generate a token that will be used for subsequent APIs, up until the token expired
2. Merchant need to create signature for all API calls. Please refer to Signature Generation section.

Transaction Status

Legacy Core APIBI-SNAP-based Core API
PENDING03 (Pending)
AUTHORIZE01 (Initiated)
SETTLEMENT00 (Success)
REFUND & PARTIAL REFUND04 (Refunded)
CANCEL05 (Canceled)
FAILURE06 (Failed)
EXPIRY08 (Expiry)
DENY09 (Rejected)

📘

  • Only transaction status on API response that will change. Transaction status on Midtrans dashboard and reporting will remain the same as Legacy API.
  • We will only return the transaction status numeric value in the actual API response. The text value (...) is only the status code description that won't be returned.

Transaction & Account Identification

Legacy Core APIBI-SNAP-based Core API
transaction_id
Midtrans generated transaction unique ID that is generated after transaction is successfully created. This ID can be used on all Midtrans APIs, such as in status API, cancel API, and refund API.
referenceNo
Same definition and usage as transaction_id in legacy API.
order_id
Merchant generated transaction ID that is unique per successful transaction. This ID can be used on all Midtrans APIs, such as in status API, cancel API, and refund API.
partnerReferenceNo
Same definition as order_id, this ID will be shown as merchant's order ID on the dashboard and reporting.

X-EXTERNAL-ID
Merchant generated ID that needs to be unique for all transactions. This ID can be passed in subsequent API calls (status, refund, cancel API) as an alternative value for originalExternalId. Please note we highly recommend merchant to use UUID format to avoid duplication. The TTL for this ID is 24 hours.

Note: Unlike order_id in the legacy API, partnerReferenceNo doesn't have unique validation and is not recommended to be used as a value in subsequent APIs. Instead, we highly recommend merchant to use originalReferenceNo (referenceNo value that is generated by Midtrans) or originalExternalId (X-EXTERNAL-ID value) in subsequent API calls.
Idempotency-Key
Key that is sent by merchant to ensure that transaction is only created once. If transaction already succeed and merchant re-send the same idempotency-key on request, Midtrans will response the same successful response as the first request.
X-EXTERNAL-ID
Has the same usage as idempotency-key in legacy API.
account_id (only for GoPay Tokenization)
Midtrans account unique ID that is generated as part of the account linking process. Will be used for initiating transaction.
Authorization-Customer (only for GoPay Tokenization)
Same definition as account_id in legacy API. For account that has been linked using the legacy API, merchant need to exchange the account_id with Authorization-Customer token to initiate transaction in SNAP-based API.

Notification

Legacy Core APIBI-SNAP-based Core API
Merchant only required to share one notification URL for all payment type notification in MidtransThere will be differences in notification’s relative path per payment type flow. Merchant required to share their notification URL domain, where Midtrans will append the dynamic relative path based on payment type as follow:
- Direct Debit API (GoPay Tokenization non pre-auth, GoPay deeplink): [merchant_url]/v1.0/debit/notify
- MPM (QRIS): [merchant_url]/v1.0/qr/qr-mpm-notify

Sample:
Merchant’s SNAP-based URL: https://www.merchant.open-api.com/

After appended by Midtrans, the URL will look like this:
- Direct Debit API: https://www.merchant.open-api.com/v1.0/debit/notify
- MPM API: https://www.merchant.open-api.com/1.0/qr/qr-mpm-notify

Notification for virtual account will follow the Midtrans legacy notification

To be able to receive notification from Midtrans, merchant will need to whitelist this set of IPs based on the environment.

EnvironmentIPs
Staging3.1.141.98/32
52.76.190.190/32
13.251.192.204/32
Production13.228.166.126/32
52.220.80.5/32
3.1.123.95/32