Payment Video Introduction

Integration Needed	Details
Mini App Frontend	Opens the redirection url provided by backend. SDK integration will be available in upcoming version.
Mini App Backend	Calls GoPay backend to obtain redirection url.

Sequence Diagram:

Mini app payments Flow diagram

1. User Initiate Order

• The user decides to place an order in the mini app front end process for order.

2.[Merchant owned]

• Merchant mini app frontend to call their own backend to initiate the payment

Step 3:[BI-SNAP Core API] Fetch Merchant Access Token

• In order to initiate order with Super App Backend Merchant access token is needed for verification purposes. This access token can be fetched by v1.0/access-token/b2b [BI-SNAP Core API]
• The Api returns the access token which can be used for all other payment oriented APIs.
• The contract of the API can be found here

Step 4:[Merchant owned]

• Merchant mini app frontend to call their backend to initiate the payment

Step 5:[BI-SNAP Core API] Payment Host to Host

• Using Merchant Access token from step 3, Payment Creation with Super App backend can be initiated by V1.0/debit/payment-host-to-host [BI-SNAP Core API]
• The contract of the API can be found here
• The merchant payment can be Guest Checkout Payment with Payer information unknown at the point.
• The merchant guest payment should have additionalInfo.pointOfPurchaseId which is shared by GoPay upfront.

Step 6: Super App Payment creation response

• Super App Backend returns response to the merchant backend with necessary info for payments
  • webRedirectUrl -> Payment deeplink
  • ReferenceNo -> GoPay Order Id

Step 7: Merchant payment creation response

• Merchant Backend returns response to Merchant Frontend with contract owned by Merchant team.

Step 8: FE Pay

• The Mini App front end can open the Super App Payment page using the launchPayment from step 5.
  SDK: MiniAppSDK version: 0.3.19
  Gopay App Version - 1.45.0
• Once the payment is completed, the Super App front end automatically redirects to the merchant page with payment status.

Step 9:[BI-SNAP Core API] Notify

• Once the payment is complete. Super App backend will notify the Mini App Backend by v1.0/debit/notify [BI-SNAP Core API]
• The contract for the api can be found here.

New GoPay Merchants:

If you have not integrated with GoPay or have integrated without following the BI-SNAP Core API convention, the following points apply :

• You must first onboard BI-SNAP Core API convention first using this section Onboard to BI-SNAP Core API.
• Once the BI-SNAP Core API onboarding is complete, you can follow Existing GoPay Merchant.

Existing GoPay Merchants:

If you have already integrated with GoPay and follow the BI-SNAP Core API convention, the following points apply :

• There is no change in the already integrated v1.0/access-token/b2b BI-SNAP Core API.
• For v1.0/debit/payment-host-to-host api, the new field in the existing contract needs to be added under additionalInfo.pointOfPurchaseId. The value for this is shared by the GoPay Team.
• There is no change in the already integrated v1.0/debit/notify BI-SNAP Core API.

1. Access Token B2B

Request Header

Content-type: application/json
X-TIMESTAMP: 2024-03-19T14:30:00+07:00
X-SIGNATURE: da1fa417c72d6b91c257e01e54fac824
X-CLIENT-KEY:962489e9-de5d-4eb7-92a4-b07d44d64bf4 

Request Body

{
   "grantType":"client_credentials"
}

Response Header

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

Response Body

{
   "responseCode":"2007400",
   "responseMessage":"Successful",
  "accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIyMTFlZThiMi1hN2FlLTRhZGUtYmJlYS1mNzI3MDk3ZmQ0NmEiLCJjbGllbnRJZCI6IjZhZTk1N2M0LTI4NjMtNDcxMy1hY2NlLWJhMTJkZTYzNmNmYyIsIm5iZiI6MTYxMTQ2ODk3OCwiZXhwIjoxNjExNDY5ODc4LCJpYXQiOjE2MTE0Njg5Nzh9.KM7yz9GvuUaDR1bXwei4iO0h4e3g4o1Hct5Ie9VoBdo",
   "tokenType":"Bearer",
   "expiresIn":"900"
}

Response Body Error Case

{
   "responseCode":"5007300",
   "responseMessage":"Timeout",
   "referenceNo":"19352694-0ef6-4439-8ad1-b1dfb8bbb85f"
}

List of Response code

2. Payment Host to Host

Note: This API allows you to create GoPay Payment Deeplink which when triggered correctly user's will be redirected to GoPay Payment Review Page.

GoPay deeplink - Direct Debit API

Request Header

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

References on X-Signature docs

Request Body

{
 "partnerReferenceNo": "merchant-order-id",
 "chargeToken": "accessToken",
 "merchantId": "G169749203",
 "urlParam": [{
   "url": "merchantapp://payments/callback/12345",
   "type": "PAY_RETURN",
   "isDeeplink": "Y"
 }],
 "validUpTo": "2023-09-24T20:34:15.452305Z",
 "payOptionDetails": [
   {
     "payMethod": "gopay",
     "payOption": "gopay",
     "transAmount": {
       "value": "12345678.00",
       "currency": "IDR"
     }
   }
 ],
 "additionalInfo": {
   "customerDetails": {
     "phone": "080123456789",
     "firstName": "john",
     "lastName": "doe",
     "email": "[email protected]",
     "billingAddress": {
       "firstName": "john",
       "lastName": "doe",
       "phone": "080123456789",
       "address": "jalan maju mundur",
       "city": "jakarta",
       "postalCode": "12345",
       "countryCode": "IDN"
     },
     "shippingAddress": {
       "firstName": "john",
       "lastName": "doe",
       "phone": "080123456789",
       "address": "jalan maju mundur",
       "city": "jakarta",
       "postalCode": "12345",
       "countryCode": "IDN"
     }
   },
   "items": [
     {
       "id": "ID012345",
       "price":  {
         "value": "12345678.00",
         "currency": "IDR"
       },
       "quantity":"1",
       "name": "someItemName",
       "brand": "someBrand",
       "category": "someCategory",
       "merchantName": "someMerchant",
       "url": "someItemUrl"
     }
   ],
   "metadata": {},
   "pointOfPurchaseId":"22cc3371-4bba-4ec6-8e0d-62163e130cdc"
 }
}

Response Header

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

Response Body

{
 "responseCode":"2005400",
 "responseMessage":"Successful",
 "referenceNo":"GOPAY012345678",
 "partnerReferenceNo":"merchant-order-id",
 "webRedirectUrl":"https://some-url.for/redirect-to-gopay-app",
 "appRedirectUrl":""
 "additionalInfo":{
   "paymentType": "GOPAY",
   "grossAmount":{
     "value": "12345678.00",
     "currency": "IDR"
   },
   "transactionTime":"2023-09-25T02:59:19.517854Z",
   "validUpTo":"2023-09-26T02:59:19Z"
 }

List of Response code

3. Launch Payment

Note: This is a Frontend SDK required to trigger the payment deeplink from payment host to host. This SDK allows redirection from MiniApp to GoPay Payment Review Page and redirection back to MiniApp

This is the Frontend Payment Response

Sample Request:

const webUrl = response.webRedirectUrl;

function convertToGoPayDeepLink(url) {
    const urlObj = new URL(url);
    const params = urlObj.search;
    return `gopay://merchanttransfer${params}`;
}
const deepLink = convertToGoPayDeepLink(webUrl);

// Assign to params object
var params = {
  deeplink: deepLink
};

window.gpContainer.call(  
  "GP",  
  "launchPayment",  
  params,  
  function(response) {  
    console.log('success:', response);  
  },  
  function(error) {  
    console.log('error:', error);  
  }  
);

Sample Response: (error codes)

{
    success: true,
    data: {
        status: "success"
    },
		"ret": "GP_SUCCESS"
}

{
    "success": false,
    "error_code": "300",
    "error_type": "JS_BRIDGE_ERROR",
    "error_message": "Permission denied",
    "ret": "GP_EXCEPTION"   
}

4. Notify

Note: This is the Backend API required to retrieve the payment response.

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

Additional APIs

1. Refund API
2. Cancel API
3. Get Transaction Status API
4. Payment Notification API