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

Environment	Legacy Core API	BI-SNAP-based Core API
Sandbox	api.sandbox.midtrans.com	- Get Auth Code API : merchants-app.sbx.midtrans.com - All other APIs: merchants.sbx.midtrans.com
Staging		- Get Auth Code API: merchants-app.stg.midtrans.com - All other APIs: merchants.stg.midtrans.com
Production	api.midtrans.com	- Get Auth Code API: merchants-app.midtrans.com - All other APIs: merchants.midtrans.com

Authorization

Merchant Credentials

Legacy Core API	Credentials	Definition
	Server key	Merchant’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 API	Credentials	Definition	Remarks
Both API scope	Merchant ID (MID)	Merchant’s unique ID generated by Midtrans	Existing
Access Token API scope	Merchant's public key	Created by merchant. Will be used by Midtrans to validate merchant’s signature	New
	Client ID	Provided by Midtrans. Will be used as X-CLIENT-KEY on request header	New
Transactional API scope	Client secret	Provided by Midtrans. Will be used for signature generation	New
	Partner ID	Provided by Midtrans. Will be used as X-PARTNER-ID on request header	New

Authorization Behavior

Legacy Core API	BI-SNAP-based Core API
Merchant will only need to use server key to initiate API calls	1. 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 API	BI-SNAP-based Core API
PENDING	03 (Pending)
AUTHORIZE	01 (Initiated)
SETTLEMENT	00 (Success)
REFUND & PARTIAL REFUND	04 (Refunded)
CANCEL	05 (Canceled)
FAILURE	06 (Failed)
EXPIRY	08 (Expiry)
DENY	09 (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 API	BI-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 astransaction_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_idin the legacy API,partnerReferenceNodoesn't have unique validation and is not recommended to be used as a value in subsequent APIs. Instead, we highly recommend merchant to useoriginalReferenceNo(referenceNo value that is generated by Midtrans) ororiginalExternalId (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.
accountid*(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&#xNAN;(only for GoPay Tokenization)* Same definition as account_idin legacy API. For account that has been linked using the legacy API, merchant need to exchange the account_id withAuthorization-Customer** token to initiate transaction in SNAP-based API.

Notification

Legacy Core API	BI-SNAP-based Core API
Merchant only required to share one notification URL for all payment type notification in Midtrans	There 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

Legacy Core API

BI-SNAP-based Core API

Merchant only required to share one notification URL for all payment type notification in Midtrans

There 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.

Environment	IPs
Staging	3.1.141.98/32 52.76.190.190/32 13.251.192.204/32
Production	13.228.166.126/32 52.220.80.5/32 3.1.123.95/32

Legacy Core API	BI-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 astransaction_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_idin the legacy API,partnerReferenceNodoesn't have unique validation and is not recommended to be used as a value in subsequent APIs. Instead, we highly recommend merchant to useoriginalReferenceNo(referenceNo value that is generated by Midtrans) ororiginalExternalId (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.
accountid*(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&#xNAN;(only for GoPay Tokenization)* Same definition as account_idin legacy API. For account that has been linked using the legacy API, merchant need to exchange the account_id withAuthorization-Customer** token to initiate transaction in SNAP-based API.