GoPay Integration

GoPay is an e-Wallet payment method by Gojek. Users will pay using the Gojek apps. The user flow varies when using a web browser (on a computer or a tablet) compared to a SmartPhone:

  1. QR Code - This is the user flow on a web browser (on a computer or a tablet). User is shown a QR code and asked to scan using the Gojek apps.
  2. Deeplink - This is the user flow on a SmartPhone/mobile device. User gets redirected to the Gojek apps to finish payment.

Basic integration process of GoPay will be explained below.

Sandbox Environment

All the steps below are using Midtrans Sandbox environment, not Production, to easily test the integration process. Make sure you are switching to Sandbox mode on your Midtrans account dashboard while retrieving Server Key and Client Key. Explained in Getting Started - Preparation

Server Key and Client Key can be retrieved on menu Settings > Access Keys

Testing Payment

If you use Deeplink, you will be auto redirected to Gopay Simulator.

If you use QR Code, copy the QR Code image URL then use this Gopay Simulator.

Diagram

QR Code Mode:
qr transaction flow .
Deeplink Mode:
deeplink transaction flow .

Integration Step

  1. Send transaction data to API Charge.
  2. Alter payment flow depending on the device used:
    • Show QR code image (on a computer or a tablet).
    • Create redirect link to Gojek apps (on SmartPhone).
    • Implementing GoPay deeplink callback.
  3. Handle transaction notification.

1. Send Transaction Data to API Charge

Charge API request should be done from Merchant's backend. Server Key (from your account's Dashboard) will be needed to authenticate the request.

Charge API request

This is example of /charge API request in Curl, please implement according to your backend language (you can also check our available language libraries).

# sample charge in CURL
curl -X POST \
  https://api.sandbox.midtrans.com/v2/charge \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <YOUR SERVER KEY ENCODED in Base64>' \
  -H 'Content-Type: application/json' \
  -d '{
  "payment_type": "gopay",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
  "gopay": {
      "enable_callback": true,                //optional
      "callback_url": "someapps://callback"   //optional
  }
}'

Optional: you can customize transaction_details data. To include data like customer_details, item_details, etc. It's recommended to send as much detail so on report/dashboard those information will be included.

Charge API response

You will get the API response like the following.

{
  "status_code": "201",
  "status_message": "GO-PAY transaction is created",
  "transaction_id": "231c79c5-e39e-4993-86da-cadcaee56c1d",
  "order_id": "order-101h-1570513296",
  "gross_amount": "44000.00",
  "currency": "IDR",
  "payment_type": "gopay",
  "transaction_time": "2019-10-08 12:41:36",
  "transaction_status": "pending",
  "fraud_status": "accept",
  "actions": [
      {
        "name": "generate-qr-code",
        "method": "GET",
        "url": "https://api.sandbox.veritrans.co.id/v2/gopay/231c79c5-e39e-4993-86da-cadcaee56c1d/qr-code"
      },
      {
        "name": "deeplink-redirect",
        "method": "GET",
        "url": "https://simulator.sandbox.midtrans.com/gopay/ui/checkout?referenceid=Y0xwjoQ9uy&callback_url=someapps%3A%2F%2Fcallback%3Forder_id%3Dorder-101h-1570513296"
      },
      {
        "name": "get-status",
        "method": "GET",
        "url": "https://api.sandbox.veritrans.co.id/v2/231c79c5-e39e-4993-86da-cadcaee56c1d/status"
      },
      {
        "name": "cancel",
        "method": "POST",
        "url": "https://api.sandbox.veritrans.co.id/v2/231c79c5-e39e-4993-86da-cadcaee56c1d/cancel"
      }
  ]
}

You will get the actions attribute which can be performed this transaction.


2. Alter payment flow depending on the device used

The user flow varies when using a web browser (on a computer or a tablet) compared to a SmartPhone.

Show QR Code Image (on computer or tablet)

To display transaction QR Code image, use the url from generate-qr-code actions retrieved from API response. Simplest way is to "hotlink" the image url, if the frontend is HTML, put the url in image tag <img src="[QR CODE URL]">, or display it on a similar component without downloading.

If the frontend does not support such scenario, download the QR code image from that url, then display it on frontend.

Instruction Example for QR Code :

  1. Tap Pay using GoPay
  2. QR code will appear on the next page
  3. Open Gojek app on your mobile phone
  4. Tap Pay then scan the QR Code
  5. Check and verify your payment details then tap PAY
  6. Enter your security PIN
  7. Your transaction is finished

GoPay QR Instruction

To redirect customer to Gojek app, use the url from deeplink-redirect actions retrieved from API response.

Then customer can be redirected via server-side redirect, using javascript like window.location=[DEEPLINK URL], or using HTML link <a href="[DEEPLINK URL]">Pay with GoPay</a>.

Instruction Example for Deeplink :

  1. Tap Pay using GoPay
  2. You will be redirected to Gojek app
  3. Check and verify your payment details then tap Pay
  4. Enter your security PIN
  5. Your transaction is finished

GoPay Deeplink Instruction

In addition to the standard mobile apps flow, you may opt to implement a deeplink callback to redirect customer back from Gojek to their apps.

Please add gopay parameter in the /charge API request

  "gopay": {
      "enable_callback": true,
      "callback_url": "someapps://callback" //you can also use web url like https://myshop.com/finish
  }
JSON Attribute Type Description
enable_callback Boolean To determine appending callback url in the deeplink. Default value: false.
callback_url String To determine where Gojek apps will redirect after successful payment. Can be HTTP or deeplink url. Default value: callback_url in dashboard settings.


You needs to prepare a callback_url which accept two query parameters

Parameter Type Description
order_id String Order ID sent on the Charge Request.
result String Result of the transaction to decide what kind of page to show to customer. Possible values: success or failure.



3. Handle HTTP Notification

HTTP notification from Midtrans to Merchant backend will also be triggered on event of transaction_status getting updated, to ensure merchant is securely informed. Including if transaction success or expired (not paid). So apart of JSON result above, Merchant backend will be notified by Midtrans.

HTTP POST request with JSON body will be sent to Merchant's notification url configured on dashboard (Settings > Configuration > Notification URL), this is the sample JSON body that will be received by Merchant:

{
  "status_code": "200",
  "status_message": "midtrans payment notification",
  "transaction_id": "1c28dbbb-8596-48e4-85d7-9f1382db8a1f",
  "order_id": "order03",
  "gross_amount": "275000.00",
  "payment_type": "gopay",
  "transaction_time": "2016-06-19 15:54:42",
  "transaction_status": "settlement",
  "signature_key": "973d175e6368ad844b5817882489e6b22934d796a41a0573c066b1e64532dc0001087b87d877a3eac37cba20a733e1305f5e62739e65ff501d5d33c5ac62530f"
}

Refer here on more details of how to handle HTTP Notification.

Switching To Production

To use Midtrans production environment (accept real payment from real customer), please make sure to:

  1. Switch the API domain URL from api.sandbox.midtrans.com to api.midtrans.com
  2. Switch the Client Key and Server Key from sandbox Dashboard, with keys from production Dashboard.

Done

The GoPay payment integration guide is now complete. Below are some further references.

Additional Notes

If GoPay deeplink is being used on SmartPhone application (Android/iOS app), there are additional configurations you may need to add to ensure your app able to redirect customer to Gojek app.

On Android if using Webview, please make sure that the Webview allow opening gojek:// deeplink protocol.

You need to modify your web view shouldOverrideUrlLoading functions as follows:

 @Override
 public boolean shouldOverrideUrlLoading(WebView view, String url) {
        LogUtils.info(TAG, "shouldOverrideUrlLoading: " + url);
        Intent intent;

        if (url.contains("gojek://")) {
            intent = new Intent(Intent.ACTION_VIEW);
            intent.setData(Uri.parse(url));
            startActivity(intent);

            return true;
        } 
 }

On iOS, you will need to add LSApplicationQueriesSchemes key to your app's Info.plist.

<key>LSApplicationQueriesSchemes</key>
<array>
<string>gojek</string>
</array>


Description

transaction_status value description for GoPay transaction:

Transaction Status Description
settlement Transaction successful, customer has been completed the transaction.
pending The transaction has successfully created to GoPay but has not been completed by the customer.
expire Transaction failure because customer did not complete the payment within allowed time.
cancel Transaction is canceled by trigger from Merchant.
deny Payment provider rejected the payment code/id creation.
refund Transaction is refunded by trigger from Merchant.


Link: More detailed definition of transaction_status

For more detail: Complete Core API documentation