Payment Notification API

In the SNAP-based Core API flow, Midtrans will call Payment Notification API on the merchant side to send payment notifications. Merchant should implement this Payment Notification API as stated in the contract below.

⚠️

Notes on Future Compatibility and Best Practices

To ensure your integration remains robust and scalable, please be aware that Midtrans may introduce additional parameters to the payment notification payload in the future, most likely under the additionalInfo section, but not limited to it. These enhancements are designed to provide greater flexibility and support for evolving business needs.

To prevent any issues caused by these future changes, we strongly recommend that merchants always perform signature verification on the entire payload, rather than validating fields individually. This practice ensures a seamless, secure, and simple implementation that can adapt to future updates without requiring significant changes on your side.

Receiving payment notifications for GoPay and GoPay Tokenization (non Pre-Auth) transaction

This section will describe how merchant should implement payment notification API for GoPay and GoPay Tokenization (non-Pre Auth) transactions for Midtrans to call.

Request Header

Content-type:application/json
X-TIMESTAMP:2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-PARTNER-ID: 
X-EXTERNAL-ID:12345678901234567890
CHANNEL-ID:12345

Request Body

{
    "createdTime": "2020-01-01T00:00:00+07:00",
    "latestTransactionStatus": "00",
    "originalReferenceNo": "gopayOrderId",
    "finishedTime": "2020-01-02T00:00:00+07:00",
    "originalPartnerReferenceNo": "merchant-order-id",
    "transactionStatusDesc": "desc",
   "originalExternalId":"merchant-order-id",
    "additionalInfo": { 
        "userPaymentDetails": [
         {
           "payMethod": "gopay",
           "payOption": "GOPAY_WALLET"
         }
        ],
         "refundHistory":[
  	{
     	     	"refundNo":"96194816941239812",
      			"refundStatus":"00",
     	     	"partnerReferenceNo":"239850918204981205970",
          		"refundAmount":{
          	   	     	"value":"12345678.00",
         	    	     	"currency":"IDR"
     	     	},
     	     	"refundDate":"2020-12-23T07:44:16+07:00",
          		"reason":"Customer Complain"
  	}
   ]
    }
}

Response Header

Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00

Response Body

{
   "responseCode":"2005600",
   "responseMessage":"Request has been processed successfully"
}

---

Receiving payment notifications for GoPay QRIS transaction

This section will describe how merchant should implement payment notification API for GoPay QRIS transactions for Midtrans to call.

Request Header

Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-PARTNER-ID: 
X-EXTERNAL-ID:12345678901234567890

Request Body

{
   "originalReferenceNo":"2020102977770000000009",
   "originalPartnerReferenceNo":"2020102900000000000001",
   "latestTransactionStatus":"00",
   "transactionStatusDesc":"success",
   "amount":{
      "value":"12345678.00",
      "currency":"IDR"
   },
   "externalStoreID":"124928924949487",
   "additionalInfo":{
     "qris" :{
       "issuerName":"gopay"
       "acquirerName":"gopay"
       "transactionType":"ON-US"
     }
   }
}

Response Header

Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00

Response Body

{
   "responseCode":"2005200",
   "responseMessage":"Request has been processed successfully"
}

List of response code

Receiving payment notifications for Bank Transfer (VA)

This section will describe how merchant should implement payment notification API for Bank Transfer (VA) transactions for Midtrans to call.

Request Header

Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00
X-SIGNATURE:da1fa417c72d6b91c257e01e54fac824
X-PARTNER-ID:G12345678
X-EXTERNAL-ID:12345678901234567890

Request Body

{
    "partnerServiceId":"  088899",
    "customerNo":"12345678901234567890",
    "virtualAccountNo":"  08889912345678901234567890",
    "virtualAccountName":"Jokul Doe",
    "virtualAccountEmail":"[email protected]",
    "virtualAccountPhone":"6281828384858",
    "trxId":"abcdefgh1234",
    "paymentRequestId":"abcdef-123456-abcdef",
    "paidAmount":{
       "value":"12345678.00",
       "currency":"IDR"
    },
    "referenceNo":"123456789012345",
    "additionalInfo":{
       "bank":"BCA",
       "paymentFlagStatus": "00",
       "merchantId":"G059876677",
       "paidTime":"2020-01-01T00:00:00+07:00",  
       "customField": {
          "1": "custom-field-1",
          "2": "custom-field-2",
          "3": "custom-field-3"
       }
    }
 }

Response Header

Content-type:application/json
X-TIMESTAMP:2020-01-01T00:00:00+07:00

Response Body

{
    "responseMessage": "Successful",
    "responseCode": "2002500",
    "virtualAccountData": {
        "partnerServiceId": "  088899",
        "customerNo": "12345678901234567890",
        "virtualAccountNo": "  08889912345678901234567890",
        "trxId": "midtrans-testing-001"
}

List of response code

Notification retry mechanism for Open API

In case we receive an error response when sending notifications to merchants (any non-success response), Midtrans will retry the notification delivery up to a maximum of 5 times with predefined retry intervals. For now, our retry mechanism is as follows:

• 1st retry delay time = 2 minutes
• 2nd retry delay time = 10 minutes
• 3rd retry delay time = 30 minutes
• 4th retry delay time = 90 minutes (1.5 hours)
• 5th retry delay time = 210 minutes (3.5 hours)

Notes:

1. These retry intervals may change at any time as part of continuous improvements. Any changes will be communicated and updated periodically in this documentation.
2. Midtrans will treat any other responses except HTTP status code 200 as an error