Integrasi GoPay

GoPay adalah metode pembayaran e-Wallet dari Gojek. Pengguna akan membayar menggunakan aplikasi Gojek. Flow pengguna bervariasi ketika menggunakan web browser (komputer atau tablet) atau dengan SmartPhone:

  1. QR Code - Untuk pengguna yang menggunakan browser web (di komputer atau tablet), akan ditunjukkan kode QR dan diminta untuk scan kode QR menggunakan aplikasi Gojek.
  2. Deeplink - Untuk pengguna yang menggunakan SmartPhone, akan langsung diarahkan ke aplikasi Gojek untuk menyelesaikan pembayarannya.

Proses integrasi dasar untuk pembayaran GoPay akan dijelaskan di bawah.

Environment Sandbox

Semua langkah di bawah menggunakan Sandbox environment Midtrans, bukan Production, untuk memudahkan testing proses integrasi. Pastikan Anda sudah mengubah ke mode Sandbox pada dashboard akun Midtrans Anda saat mendapatkan Server Key dan Client Key. Dijelaskan pada Langkah Awal - Persiapan

Server Key dan Client Key bisa didapatkan pada menu Settings > Access Keys

Testing Pembayaran

Jika Anda menggunakan Deeplink, anda akan secara otomatis diarahkan ke Gopay Simulator.

Jika Anda menggunakan QR Code, salin URL Kode QR kemudian gunakan Gopay Simulator.

Diagram

QR Code Mode:
card transaction flow .
Deeplink Mode:
card transaction flow .

Langkah Integrasi

  1. Kirim data transaksi ke API Charge.
  2. Membuat flow transaksi sesuai pada perangkat yang digunakan:
    • Tampilkan gambar kode QR (komputer atau tab).
    • Buat link ke aplikasi Gojek (SmartPhone).
    • Mengimplementasi GoPay deeplink callback.
  3. Terima notifikasi transaksi.

1. Kirim Data Transaksi ke API Charge

Request API charge akan dilakukan melalui backend Merchant. Server Key (dari Dashboard dashboard Anda) akan dibutuhkan untuk meng-otentikasi request.

Request Charge API

Berikut contoh dari request API /charge dalam Curl, silahkan implementasikan sesuai bahasa pemrograman backend Anda (Anda juga bisa cek library-library pemrograman yang tersedia).

# contoh charge dalam CURL
curl -X POST \
  https://api.sandbox.midtrans.com/v2/charge \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic <SERVER KEY ANDA ENCODED dalam 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
  }
}'

Opsional: anda bisa kustomisasi data transaction_details. Untuk menyertakan data seperti customer_details, item_details, dsb. Disarankan untuk mengirim data sebanyak mungkin agar nantinya report/dashboard menampilkan informasi tersebut.

Response Charge API

Kita akan mendapat response API seperti ini.

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

Anda akan mendapatkan atribut actions yang berguna untuk melanjutkan transaksi ini.

2. Membuat flow transaksi sesuai pada perangkat yang digunakan

Flow transaksi akan berbeda ketika menggunakan web browser (komputer atau tab) atau SmartPhone.

Tampilkan kode QR (komputer atau tab)

Untuk menampilkan Kode QR, gunakan url dari generate-qr-code yang didapat dari respons API. Cara termudah adalah dengan "hotlink" url, jika frontend menggunakan HTML, masukkan url ke dalam tag img <img src="[URL KODE QR]">, atau tampilkan komponen yang serupa tanpa harus mendownload.

Jika frontend anda tidak mendukung hal tersebut, download Kode QR dari url tersebut, lalu tampilkan langsung di frontend.

Contoh instruksi untuk QR Code:

  1. Klik Pay using GoPay
  2. Kode QR akan tampil pada halaman berikutnya
  3. Buka aplikasi Gojek pada SmartPhone anda
  4. Klik Pay lalu scan kode QR
  5. Cek kembali rincian pembayaran anda dan klik PAY
  6. Masukan PIN anda
  7. Transaksi anda telah selesai

Instruksi kode QR GoPay

Untuk mengarahkan customer ke aplikasi Gojek, gunakan url dari deeplink-redirect yang didapat dari respons API.

Kemudian customer dapat diarahkan melalui server-side redirect, menggunakan javascript seperti window.location = [URL DEEPLINK], atau menggunakan link HTML <a href="[DEEPLINK URL]"> Bayar dengan GoPay </a>.

Contoh instruksi untuk Deeplink :

  1. Klik Pay using GoPay
  2. Anda akan langsung diarahkan menuju aplikasi Gojek
  3. Cek kembali rincian pembayaran anda dan klik Pay
  4. Masukan PIN anda
  5. Transaksi anda telah selesai

Instruksi GoPay Deeplink

Anda dapat mengimplementasikan deeplink callback untuk mengarahkan customer kembali ke aplikasi anda dari aplikasi Gojek.

Tambahkan parameter gopay di request API /charge

  "gopay": {
      "enable_callback": true,
      "callback_url": "someapps://callback" //anda juga dapat menggunakan url web seperti "https://myshop.com/finish"
  }
Atribut JSON Tipe Deskripsi
enable_callback Boolean Untuk menentukan, penambahan callback url pada deeplink. Nilai default: false.
callback_url String Untuk menentukan kemana aplikasi Gojek akan diarahkan setelah pembayaran berhasil. Dapat berupa HTTP atau url deeplink. Nilai default: callback_url pada dashboard settings.


Anda perlu menyiapkan callback_url yang dapat menerima dua parameter query.

Parameter Tipe Deskripsi
order_id String Order ID yang dikirimkan pada saat Charge Request.
result String Status transaksi untuk memutuskan halaman yang akan ditampilkan kepada customer. Nilai yang muncul: success atau failure



3. Terima HTTP Notification

HTTP notification dari Midtrans ke backend Merchant akan dikirimkan pada saat terjadi perubahan transaction_status, untuk memastikan Mercahant mendapat informasi secara aman. Termasuk pada saat status transaksi berubah jadi success atau expired (tidak dibayarkan). Jadi selain JSON pada callback di atas, Merchant juga akan menerima notifikasi dari Midtrans.

Request HTTP POST dengan body JSON akan dikirimkan ke notification url Merchant yang dikonfigurasi pada dashboard (Settings > Configuration > Notification URL), berikut contoh body JSON yang akan diterima 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"
}

Lihat disni untuk lebih lengkap dalam menangani HTTP Notification.

Mengubah Ke Production

Untuk menggunakan environment production (menerima pembayaran dari customer sesungguhnya), silahkan pastikan:

  1. Ubah domain API URL dari api.sandbox.midtrans.com menjadi api.midtrans.com
  2. Ubah Client Key dan Server Key dari Dashboard sandbox, dengan key dari Dashboard production.

Selesai

Integrasi pembayaran GoPay sekarang selesai. Berikut beberapa referensi tambahan.

Catatan Tambahan

Jika anda menggunakan GoPay deeplink pada aplikasi SmartPhone (Android / iOS), terdapat konfigurasi yang mungkin perlu ditambahkan untuk memastikan aplikasi anda dapat redirect langsung ke aplikasi Gojek.

Pada Android jika menggunakan Webview, pastikan bahwa Webview mengizinkan untuk membuka deeplink gojek://.

Anda perlu memodifikasi function shouldOverrideUrlLoading seperti berikut:

 @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;
        } 
 }

Pada iOS, anda perlu menambahkan LSApplicationQueriesSchemes key ke app's Info.plist.

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


Deskripsi

Nilai transaction_status dalam transaksi GoPay:

Status Transaksi Deskripsi
settlement Transaksi sukses, customer telah berhasil menyelesaikan/membayar transaksi.
pending Transaksi telah berhasil dibuat GoPay tetapi belum dibayarkan oleh customer.
expire Transaksi gagal karena customer tidak menyelesaikan pembayaran dalam waktu tertentu.
cancel Transaksi dibatalkan oleh Merchant.
deny GoPay menolak pembuatan transaksi.
refund Transaksi direfung oleh Merchant.


Link: Definisi lebih detail transaction_status

Untuk lebih detail: Dokumentasi lengkap Core API