Deployment Notice

March 27, 2025

3DS Redirect Domain Change – Please Update Your Allowlist

As part of ongoing enhancements to ensure secure and seamless transactions. We have upcoming improvements to our 3DS (3D Secure) payment flow. We will gradually migrate the 3DS redirect domain from https://api.midtrans.com to https://card.midtrans.com.
Key Details:

• New 3DS Domain: https://card.midtrans.com
• Previous 3DS Redirect Domain: https://api.midtrans.com
• Implementation Timeline:
  • Start Date: April 24, 2025 (Gradual rollout).
  • Completion Target: End of June 2025 (Complete rollout).
    Action Required:
    If your system employs domain allowlisting, ensure that the new domain (https://card.midtrans.com) is added to your allowlist before April 24, 2025 to prevent disruptions. Failure to update the allowlist (if applicable) may result in transaction failures where customers cannot complete 3DS authentication and leading to declined payments.

Specifically, check all parts of your system that interact with 3DS Redirect URL, including:

• Web integrations: When performing a 3DS URL Redirect or embedding the URL in an iframe.
• Mobile apps: When handling the 3DS Webview.

What’s Changing?
The API paths will remain unchanged, only 3DS Redirect domain will be updated. Below are the revised URLs for reference:
This content is only supported in a Lark Docs
3DS Flow Overview:

1. Redirect URL: Returned in the charge response, which (on Frontend side) you will have to redirect your customer to open 3DS URL, for them to complete 3DS process.
2. Callback URL: Automatically triggered after the Redirect URL is opened (to gather browser information data).
3. Result Completion URL: Automatically triggered or displayed after the customer completes the 3DS authentication, whether by submitting an OTP or allowing the transaction (including frictionless flows and in-app 3DS authentication).
   For full details on the 3DS flow, refer to our documentation.

Frequently Asked Questions (FAQ)
Q1: When will this change take effect?
A: The migration will begin on April 24, 2025 and be fully completed by End of June 2025. We will notify you of any timeline adjustments.

Q2: Do merchants need to change their integration to use the new domain?
A: No, merchants should continue using the existing domain for Charge, Create Token, etc. This change only affects 3DS URL (which is used to redirect customers to the 3DS web page, on the Frontend side). No action is required unless you use domain allowlisting. If so, add https://card.midtrans.com to your allowlist.

Q3: Will this affect existing transactions?
A: No. The API paths remain identical, and the change will not disrupt current implementations.

Q4: Is there a deadline to update our allowlist?
A: Yes. Ensure the new domain is allowed before April 24, 2025 to avoid service interruptions.

Q5: What happens if we do not add the new domain to our allowlist?
A: If the new domain (https://card.midtrans.com) is not added to your allowlist, customers may experience failures when attempting to authenticate their transactions via 3DS. This can lead to increased transaction declines and potential revenue loss.

Q6: Why is the Result Completion Page URL unchanged?
A: Only 3DS Redirect and Callback URLs are migrating. The Result Completion URL will remain on api.midtrans.com. However, in the future, we will also migrate this to https://card.midtrans.com for 3DS URL consistency. This change will be announced separately and will take place after the migration of the 3DS Redirect and Callback URLs.

📢 Action Required: If your system enforces domain allowlisting, please ensure that https://card.midtrans.com is added before April 24, 2025 to prevent disruptions.

February 1, 2024

Card Channel Response Code Improvement

In order to enhance our services, we are standardizing the API Responses Code for Midtrans payment methods with cards, which will be implemented gradually on March 1, 2024. We urge you to promptly check the latest API, now available in Sandbox mode, and make necessary configuration changes according to your needs to ensure smooth transaction processes. Please review the changes in the API response codes provided.

For more details, please refer to Card Channel Response Code Improvement

December 14, 2023

Kredivo callback URL format update

Starting from January 8th, 2024, there will be an update on callback URL returned by Midtrans for Kredivo payment channel. Callback URL is the URL that Midtrans will return to merchant when user is redirected back to merchant's page after transaction completion in Kredivo page.

📘

Staring in January 8th, 2024 we will start appending additional information on Kredivo callback URL. We will gradually rollout the update, please make sure that your system can handle both the old and new format within the transition period.

The update mentioned above is as follows:

For more details please refer to this API documentation https://docs.midtrans.com/reference/kredivo-1.

GoPay static QRIS can only be refunded by passing Midtrans transaction ID

🚧

Starting from January 14th, 2024, refund on GoPay static QRIS transaction can only be initiated by passing Midtrans transaction ID.

Failure to do so may resulted in refund failures (we will return Midtrans status code 404) . We will gradually rollout the update, please make sure that your system can handle both the old and new format within the transition period.

The update mentioned above is as follows:

What is Midtrans transaction ID?

Midtrans transaction ID is a unique ID generated by Midtrans. This ID can be found as part of Midtrans charge API response as well as Midtrans HTTP post notification, also in Midtrans merchant portal as follows:

	Sample
Charge API response	{ "status_code":"201", "status_message":"Kredivo transaction is created", "transaction_id":"c1b4e32c-fd32-4ce3-98ed-130a6faf0fef", … }
HTTP Post Notification	{ "transaction_time": "2023-12-07 14:51:27", "transaction_status": "pending", "transaction_id": "c1b4e32c-fd32-4ce3-98ed-130a6faf0fef", … }
Merchant portal

For more details please refer to this API documentation https://docs.midtrans.com/reference/refund-transaction.

Midtrans status code update for GoPay blocked user scenario on GoPay Tokenization

📘

Starting January 14th, 2024, there will be an update on Midtrans status code for GoPay blocked user scenario on GoPay Tokenization linking and payment, from the previous status code 402 to status code 410.

We will gradually rollout the update, please make sure that your system can handle both the old and new format within the transition period.

The update mentioned above is as follows:

For more details please refer to this API documentation https://docs.midtrans.com/reference/code-4xx.

Update on order id format on B2B virtual account subsequent transactions

📘

Starting January 14th, 2024, we will update the format of B2B virtual account subsequent transactions format to become a random asymmetrical value.

We will gradually rollout the update, please make sure than your system can handle both the old and new format within the transition period.

The update mentioned above is as follows:

September 12, 2023

Related to internal optimization and improvement, we would like to announce changes related to the full PAN card payment Card Feature - Full PAN.

Change on Full PAN Card Payment Endpoint
Full PAN simplifies the process of recurring transactions on card payment by removing the tokenization step in a normal card payment transaction. This can be used only if the Merchant is already in accordance with PCI-DSS (Payment Card Industry Data Security Standard) compliance.

Before
Merchants use the same endpoint as a one-time card payment: https://api.midtrans.com (for sandbox https://api.sandbox.midtrans.com).

Now
Merchants need to use a different endpoint for full PAN card payment than a one-time card payment to https://panapi.midtrans.com (for sandbox https://panapi.sandbox.midtrans.com).

Purpose
Midtrans decided to provide a separate endpoint for full PAN card transactions to isolate PCI scope and mitigate any potential risks in the future related to PCI data in full PAN card transactions.

What merchant should do
Merchants need to change the endpoint to https://panapi.midtrans.com to be able to continue using the full PAN feature after the endpoint is ready in production. If there are any concerns about these changes please let us know at [email protected].

Timeline on Sandbox
We plan to expose the new endpoint for full PAN transactions around 18 to 22 September 2023

Timeline on Production
We plan to expose the new endpoint for full PAN transactions around 3 October to 3 November 2023. After 3 November, any full PAN transactions through the old endpoint (api.midtrans.com) will be denied/rejected.

{
  "status_code": "402",
  "status_message": "Please migrate to Full PAN new endpoint",
  "id": "5f907720-e9db-4aaf-8f11-8864ad5a021b"
}

August 7, 2023

In the event of our internal optimization and improvement, we would like to announce some changes regarding status_message of credit card payment type in the Status API.

July 14, 2023

Midtrans would like to announce changes in credit card payment type.

1. Addition of channel in charge and status response
Channel parameter in charge request is an optional field in credit card requests. If a merchant sends it on request, it helps Midtrans to create a payment to the specific channel.

Possible values of this field:

Before
Midtrans only sends the channel parameter in the charge response when the merchant has provided the channel parameter in the charge request. If merchants do not send any channel parameter on the charge request, then there will be no channel parameter mentioned in the charge response from Midtrans.

Now
Midtrans intends to gradually return the channel parameter in both of the charge and status response.
Final goal: The end goal is to achieve consistency so that all charge and status responses contain the channel parameter, ensuring accurate channel information is provided in both types of responses.

For more details regarding Channel

Benefit
The inclusion of the channel parameter in the charge and status response will be beneficial for merchants who utilize multiple channels. It will provide visibility into which specific channel is used for credit card transactions. This is important because the channel_response_code and channel_response_message may vary for each channel. Therefore, having the channel parameter in the response will help merchants accurately identify and handle transactions across different channels.

For more details regarding channel_response_code & channel_response_message

What merchant should do
As Midtrans will gradually send the channel parameter both in the charge and status response, it may pose challenges for the merchants. The merchants need to be ready to accept or disregard the channel parameter if it is returned by Midtrans in the charge and status response.
If this new field will break merchant implementation please let us know at [email protected].

Timeline on Sandbox
We plan to deploy for credit card transactions with one-time token on 14th July, 2023

Timeline on Production
We plan to deploy gradually on 20th July, 2023 until 20th August, 2023

2. Addition of settlement_time in API response
Before
There is no settlement_time parameter in the charge and status response of a captured credit card transaction.

Now
Midtrans will send settlement_time parameter in API response for any transaction_status state.
Final goal: The end goal is to achieve consistency so that all charge and status responses contain the settlement_time parameter.

For more details regarding settlement_time

What merchant should do
As Midtrans will gradually send the settlement_time parameter both in the charge and status response, it may pose challenges for the merchants. The merchants need to be ready to accept or disregard the channel parameter if it is returned by Midtrans in the charge and status response.
If this new field will break merchant implementation please let us know at [email protected].

Timeline on Sandbox
We plan to deploy for credit card transactions with one-time token on 14th July, 2023

Timeline on Production
We plan to deploy gradually on 20th July, 2023 until 20th August, 2023

3. Addition of expiry_time charge and status response
Before

• There is expiry_time in the status response of an authorized credit card transaction.
• The default expiry_time for 3DS & non-3DS authorized transactions is 8 days.
• The default expiry_time for 3DS pending transactions is 10 minutes.
• There is no expiry_time for non-3DS captured transactions.
• Merchants able to set custom expiry_time and receive the same on response.

Now

• Midtrans will keep the default expiry as 8 days for both 3DS and non-3DS authorized and captured transactions.
• Expiry_time for 3DS pending transaction still 10 minutes and the transaction will expire within 10 minutes if no further action to complete 3DS process.
• Merchants still able to set custom expiry_time and receive the same on response.
• Final goal: The end goal is to achieve consistency so that all charge and status responses contain the expiry_time parameter.

For more details regarding expiry_time

Disclaimer:
In the case where a merchant sends a custom expiry parameter in charge request then Midtrans will use the sent custom expiry time. (Note: please note that, for credit card transactions, the custom expiry feature is no longer supported. For more details on custom expiry, please refer to expiry_time)

What merchant should do
As Midtrans will gradually send the expiry_time parameter both in the charge and status response, it may pose challenges for the merchants. The merchants need to be ready to accept or disregard the channel parameter if it is returned by Midtrans in the charge and status response.
If this new field will break merchant implementation please let us know at [email protected].

Timeline on Sandbox
We plan to deploy for credit card transactions with one-time token on 14th July, 2023

Timeline on Production
We plan to deploy gradually on 20th July, 2023 until 20th August, 2023

Summary

• Merchants will be able to see channel in charge, capture, cancel, refund, and status responses.
• Merchants will be able to see settlement_time in charge, capture, cancel, refund, and status responses.
• Merchants will be able to see expiry_time in charge, capture, cancel, refund, and status responses.
• Please be noted these changes will be sent gradually for credit card payment that use a one-time token. For Full PAN and Recurring features readiness will be announced in separate announcements.
• Sandbox deployment for credit card transactions with one-time token on 14th July, 2023
• Production deployment for credit card transactions with one-time token will implement gradually on 20th July, 2023 until 20th August, 2023
• If these changes will break Merchant implementation please contact [email protected]

July 3, 2023

For Disbursement context, we would like to announce there will be a change on disbursement approval behavior. Before if merchant doesn't have enough balance to approve a disbursement, the approval will failed and disbursement will stay in queued status. The new behavior will be the approval still gone through but we will return you with a new error code and error message.

Before

During the approval, you will got this error.

400 / Bad Request
{"error_message"=>"An error occurred when approving payouts", "errors"=>["Partner does not have sufficient balance for the payout"]}

After

We're introducing new error code and error message:

• Error Code: 016
• Error Message: Merchant balance is not enough

Approval will still succeed, but the disbursement status will be failed with this new error detail.

For bulk disbursement approval, there will be a change of behavior as well where before if the total sum of disbursement amount and sum of disbursement fee is more than IRIS balance, the approval can't be done at all. Where after the changes is done, the approval process will still succeed and the disbursement can be partially completed and partially failed depends on how many disbursements can be approved using the current balance. The merchant shall top up their balance first to continue the disbursement process for those partial failed disbursements.

if you have any inquiry, please contact [email protected].

June 19, 2023

In the event of our internal optimization and improvement, we would like to announce several changes:

1. payment_type and bank_transfer value during Permata Virtual Account charge request
   Impacted payment channel: Permata Virtual Account

   BeforeAfter

   {
     "payment_type": "bank_transfer",
     "bank_transfer": null,
     "transaction_details": {
       "order_id": "H17550",
       "gross_amount": 145000
     }
   }
   
   OR
   
   {
     "payment_type": "bank_transfer",
     "bank_transfer": {
       "permata": {
         "recipient_name": "SUDARSONO"
       }
     },
     "transaction_details": {
       "order_id": "H17550",
       "gross_amount": 145000
     }
   }
   
   OR
   
   {
     "payment_type": "bank_transfer",
     "bank_transfer": {
       "bank": "permata",
       "permata": {
         "recipient_name": "SUDARSONO"
       }
     },
     "transaction_details": {
       "order_id": "H17550",
       "gross_amount": 145000
     }
   }
   

   {
     "payment_type": "permata",
     "bank_transfer": {
       "permata": {
         "recipient_name": "SUDARSONO"
       }
     },
     "transaction_details": {
       "order_id": "H17550",
       "gross_amount": 145000
     }
   }
   
   OR
   
   {
     "payment_type": "bank_transfer",
     "bank_transfer": {
       "bank": "permata"
       "permata": {
         "recipient_name": "SUDARSONO"
       }
     },
     "transaction_details": {
       "order_id": "H17550",
       "gross_amount": 145000
     }
   }
   

2. New id field in the error response
   Impacted payment channels: Permata Virtual Account, Mandiri Bill Payment and Indomaret

   BeforeAfter

   {
     "status_code": "402",
     "status_message": "Payment channel is not activated."
   }
   

   {
     "status_code": "402",
     "status_message": "Payment channel is not activated.",
     "id": "788e20d7-8fe7-4068-98a8-9bc4139bcd87"
   }
   
   

3. New expiry_time field in the charge api response
   Impacted payment channels: Permata Virtual Account, Mandiri Bill Payment and Indomaret

   BeforeAfter

   {
     "status_code": "201",
     "status_message": "Success, PERMATA VA transaction is successful",
     "transaction_id": "4f4da2ac-4779-4a03-9ca0-577909042ab4",
     "order_id": "order03",
     "merchant_id": "G00123",
     "gross_amount": "275000.00",
     "currency": "IDR",
     "payment_type": "bank_transfer",
     "transaction_time": "2022-04-21 17:15:30",
     "transaction_status": "pending",
     "fraud_status": "accept",
     "permata_va_number": "91019021579"
   }
   

   {
     "status_code": "201",
     "status_message": "Success, PERMATA VA transaction is successful",
     "transaction_id": "4f4da2ac-4779-4a03-9ca0-577909042ab4",
     "order_id": "order03",
     "merchant_id": "G00123",
     "gross_amount": "275000.00",
     "currency": "IDR",
     "payment_type": "bank_transfer",
     "transaction_time": "2022-04-21 17:15:30",
     "transaction_status": "pending",
     "fraud_status": "accept",
     "permata_va_number": "91019021579",
     "expiry_time": "2023-01-09 09:56:44"
   }
   

4. Status message changes when calling Expire API for cancelled/expired transaction
   Impacted payment channels: Permata Virtual Account and Indomaret

   BeforeAfter

   {
     "status_code": "412",
     "status_message": "Merchant cannot modify the status of the transaction"
   }
   

   {
     "status_code": "412",
     "status_message": "Transaction status cannot be updated.",
     "id": "353b3884-b1d8-4e05-a1d7-004a4e8fd183"
   }
   

February 9, 2023

Card transactions that are made using a card that is still using outdated 3DS version 1 will be denied immediately on Midtrans when merchants send /charge API request, to prevent from proceeding it to Card Principal’s network (Visa, MasterCard, JCB, Amex). Midtrans will only proceed normally if the card supports 3DS version 2. With main benefits of improving processing time & efficiency.

As compared to before: Midtrans would still proceed with 3DS version 1 card, even though Principal no longer supports 3DS version 1 (cards that do not support 3DS version 2 will be rejected). This would often result in rejection on the Principal side instead, which is less efficient.

{
  "status_code": "402",
  "status_message": "Cards with 3DS version 1 or lower are not supported. Please retry with another card that supports the minimum 3DS version 2.",
  "id": "dc948e9d-21c1-438d-9e4d-6ee5268b2ac7"
}

August 30, 2022

The allowed maximum time of expiry for GoPay is now adjusted to 7 days.

June 17, 2022

Starting on 22nd July, 2022, we are going to Implement 8 Digit bin.

📘

Note: 8 Digit Bin

With the oncoming mandates from Visa and other principals, Midtrans will start supporting 8-digit BIN's for card transaction processing flows.

The 8-digit bin changes on CoreAPI and will impact the length of token_id and format of saved_token_id.

Changes list:

1. Change on token_id length from 48 digit to 50 digit.

2. Change on saved_token_id format.

3. Change of masked_card in response body, event, and notification.

4. Support 8 digit bin in Midtrans Fraud Detection System/Aegis.
5. Support 8 digit bin in BIN API.

October 7, 2022

Starting on 7th Oct 2022, all MIGS MID has been migrated to MPGS MID.

❗️

Migrate MIGS to MPGS for BCA & BRI except Maybank

In relation to 3DS2.0 mandate from principal, we need to migrate all of existing BCA and BRI MID from MIGS to MPGS because MIGS BCA & BRI only support 3DS 1.0

The MID migration will affect channel_response_code and channel_response_message format.

For more MPGS response details, please refer to MPGS Response code

Affected Banks:

if you have any inquiry, please contact [email protected]

December 6, 2022

GoPay Deny Error

Starting in January 2023 there will be an update on Midtrans deny error for GoPay payment channel. The transition phase will start in January upto April 2023, Please ensure that merchant's system can accommodate both behavior (before and after) within this period.

🚧

Update on behavior of Midtrans deny errors for GoPay payment channel.

Midtrans will change the behavior of Midtrans deny error for GoPay payment channel - Some of GoPay error will be mapped to Midtrans error (4xx/5xx) - GoPay error that is mapped to 4xx error won’t have HTTP post notification.

{
"Status_code":"202",
"status_message":"GoPay transaction is denied",
"channel_response_code":"201",
"channel_response_message":"insufficient balance"
…
}

{
  "status_code":"400",
  "status_message":"One or more parameters in the payload is invalid.",
  "validation_messages":[
    "Gopay.account_id is required"
  ],
  "id":"1a3fef7b-c034-4cf2-98d6-e239594976f3"
}

{
  "status_code":"500",
  "status_message":"Sorry. Our system is recovering from unexpected issues. Please retry.",
  "Id":"6a782ad4-1e18-4df5-b5bd-dbf94ce15ddc"
}

Change List :

1. Update on behaviour for listed GoPay errors below :

2. GoPay error that is mapped to 4xx error won’t have HTTP post notification.

Expiry Threshold

Starting on January 16th 2023, we will apply minimum and maximum expiry time threshold.

🚧

New minimum and maximum expiry time threshold

Midtrans will apply minimum and maximum expiry time threshold on all payment channels. - Transaction with expiry time less than 20 seconds will be rejected. - Transaction with expiry time more than 180 days will be accepted, but expiry time will be trimmed to 180 days*

*except for GoPay transaction. GoPay have maximum expiry time of 7 days

Change list:

1. Added field expiry_time on charge response, get status response and notification. expiry_time field will be returned in API response (charge and status API) and also HTTP notification

{
   "transaction_time":"2023-01-16 10:00:00",
   "Transaction_status":"pending",
   "transaction_id":"ce0a3584-5a0c-4049-ad88-5590a96be4fe",
   …
   "expiry_time":"2023-07-16 10:00:00"
}

{
   "transaction_time": "2023-01-16 10:00:00",
   "transaction_status": "pending",
   "transaction_id": "ce0a3584-5a0c-4049-ad88-5590a96be4fe",
   "status_message": "midtrans payment notification",
   …
   "expiry_time":"2023-07-16 10:00:00"
}

2. Transaction with expiry time less than 20 seconds will be rejected

Sample scenario of Charge API with Custom Expiry object :

a. charge request without order time
If merchant send the sample request (seen on right side) without order_time at 10:00:30 GMT+7, then the calculated expiry time is 10 seconds, as follow:

• order_time: not specified hence will follow transaction time
• transaction_time: 10:00:30 GMT+7
• expiry_duration : 10 seconds
• Expiry timestamp: 10:00:40 GMT+7
• Expiry time: 10 seconds

Therefore the transaction will be rejected.

b. charge request with order time
If merchant send the sample request (seen on right side) with order_time at 10:00:30 GMT+7, then the calculated expiry time is 10 seconds, as follow:

• order_time: 10:00:00 GMT+7
• transaction_time: 10:00:30 GMT+7
• expiry_duration: 40 seconds
• Expiry timestamp: 10:00:40 GMT+7
• Expiry time: 10 seconds

Therefore the transaction will be rejected.

"custom_expiry": {
  "expiry_duration": 10,
  "unit": "second"
}

"custom_expiry": {
  "order_time": "2023-01-16 10:00:00 +0700",
  "expiry_duration": 40,
  "unit": "second"
}

{
   "status_code": "400",
   "status_message": "One or more parameters in the payload is invalid.",
   "id": "1a1a66f7-27a7-4844-ba1f-d86dcc16ab27",
   "validation_messages": 
       [
           "custom_expiry is below minimum threshold"
        ]
}

3. Transaction with expiry time more than 180 days will be accepted but expiry time will be trimmed to 180 days (except for GoPay transaction which is 7 days)

Sample scenario of Charge API with Custom Expiry object :

a. charge request without order time
If merchant send the sample request (seen on right side) request at 2023-01-16, then the calculated expiry time is 210 days, as follow:

• order_time: not specified hence will follow transaction time
• transaction_time: 2023-01-16 10:00:00 GMT+7
• expiry_duration : 210 days (approx 7 months)
• Expiry timestamp withouth trim should be: 2023-08-16 10:00:00 GMT+7

We will trim the expiry time to 180 days with new expiry timestamp: 2023-07:16 10:00:00 GMT+7.

b. charge request with order time

If merchant send the sample request (seen on right side) request at 2023-01-16, then the calculated expiry time is 209 days, as follow:

• order_time: 2023-01-15 10:00:00 GMT+7
• transaction_time: 2023-01-16 10:00:00 GMT+7
• expiry_duration: 210 days (approx 7 months)
• Expiry time: 209 days
• Expiry timestamp withouth trim should be: 2023-08-15 10:00:00 GMT+7

Therefore we will trim the expiry time to 180 days with new expiry timestamp: 2023-07:16 10:00:00 GMT+7.

"custom_expiry": {
  "expiry_duration": 210,
  "unit": "day"
}

"custom_expiry": {
  "order_time": "2023-01-15 10:00:00 +0700",
  "expiry_duration": 210,
  "unit": "day"
}

{
  "transaction_time":"2023-01-16 10:00:00",
  "transaction_status":"pending",
  "transaction_id":"ce0a3584-5a0c-4049-ad88-5590a96be4fe",
  ....
  "expiry_time":"2023-07-16 10:00:00" 
}