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