Integrasi Direct Debit

Dengan menggunakan metode pembayaran Direct Debit, customer akan mempunyai pilihan untuk melakukan pembayaran melalui website bank dan Midtrans akan mengirimkan notifikasi pemberitahuan secara real time setelah customer menyelesaikan pembayarannya.

Saat ini, Midtrans telah terintegrasi dengan 4 metode pembayaran Direct Debit yang berbeda:

  1. BCA Klikpay
  2. CIMB Clicks
  3. Danamon Online
  4. e-Pay BRI
  5. Akulaku

Proses integrasi dasar untuk pembayaran Direct Debit 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

Diagram

Gambaran dari flow transaksi dalam sequence diagram:
direct debit transaction flow .

Langkah Integrasi

  1. Kirim data traksaksi ke API Charge.
  2. Mengarahkan customer menuju website bank.
  3. Membuat landing page setelah customer menyelesaikan pembayaran.
  4. Terima notifikasi transaksi.

1. Kirim Data Traksaksi 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).

# 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": "bca_klikpay",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
  "bca_klikpay": {
    "description": "Pembelian Barang"
  }
}'
# 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": "cimb_clicks",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  },
  "cimb_clicks": {
      "description": "Purchase of a Food Delivery"
  }
}'
# 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": "danamon_online",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
}'
# 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": "bri_epay",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
}'
# 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": "akulaku",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 11000
  }
}'

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

Anda akan mendapat response API seperti berikut:

{
    "status_code": "201",
    "status_message": "OK, BCA KlikPay transaction is successful",
    "transaction_id": "d19a4bcd-ae30-49dc-bde7-57749aede090",
    "order_id": "order-101",
    "redirect_url": "https://api.sandbox.veritrans.co.id/v3/bca/klikpay/redirect/d19a4bcd-ae30-49dc-bde7-57749aede090",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "bca_klikpay",
    "transaction_time": "2019-12-12 11:03:55",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "redirect_data": {
        "url": "https://simulator.sandbox.midtrans.com/bca/klikpay/index",
        "method": "post",
        "params": {
            "klikPayCode": "03KHAN816197673",
            "transactionNo": "92396",
            "totalAmount": "44000",
            "currency": "IDR",
            "payType": "01",
            "callback": "https://example.com?id=d19a4bcd-ae30-49dc-bde7-57749aede090",
            "transactionDate": "11/11/2019 11:03:55",
            "descp": "Pembelian Barang",
            "miscFee": "0.00",
            "signature": "239297204"
        }
    }
}
{
    "status_code": "201",
    "status_message": "Success, CIMB Clicks transaction is successful",
    "redirect_url": "https://api.sandbox.veritrans.co.id/cimb-clicks/request?id=2e8f8ddd-c61a-4d5f-83ad-429432383057",
    "transaction_id": "2e8f8ddd-c61a-4d5f-83ad-429432383057",
    "order_id": "order-101i-1576124787",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "cimb_clicks",
    "transaction_time": "2019-11-11 11:26:27",
    "transaction_status": "pending",
    "merchant_id": "G812785002"
}
{
    "status_code": "201",
    "status_message": "Success, Danamon Online transaction is successful",
    "transaction_id": "9da1c095-81b2-40d3-8285-8d27c60ae56e",
    "order_id": "order-101p-1576124871",
    "redirect_url": "https://api.sandbox.veritrans.co.id/v2/danamon/online/redirect/9da1c095-81b2-40d3-8285-8d27c60ae56e",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "danamon_online",
    "transaction_time": "2019-11-11 11:27:50",
    "transaction_status": "pending",
    "fraud_status": "accept"
}
{
    "status_code": "201",
    "status_message": "Success, BRI E-Pay transaction is successful",
    "transaction_id": "01c03b08-5e77-40d3-b1df-972f20a92e09",
    "order_id": "order-101",
    "redirect_url": "https://api.sandbox.veritrans.co.id/v3/bri/epay/redirect/01c03b08-5e77-40d3-b1df-972f20a92e09",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "bri_epay",
    "transaction_time": "2019-11-11 15:09:35",
    "transaction_status": "pending",
    "fraud_status": "accept"
}
{
    "status_code": "201",
    "status_message": "Success, Akulaku transaction is created",
    "transaction_id": "f80b0974-46d6-480c-9278-8b0d473857e1",
    "order_id": "order-101s",
    "redirect_url": "https://api.sandbox.midtrans.com/v2/akulaku/redirect/f80b0974-46d6-480c-9278-8b0d473857e1",
    "merchant_id": "G812785002",
    "gross_amount": "11000.00",
    "currency": "IDR",
    "payment_type": "akulaku",
    "transaction_time": "2019-11-11 12:19:54",
    "transaction_status": "pending",
    "fraud_status": "accept"
}

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

2. Mengarahkan Customer Menuju Website Bank

Anda dapat menggunakan redirect_url yang didapatkan dari respons API untuk mengarahkan customer ke website bank.

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


3. Membuat Landing Page Setelah Customer Menyelesaikan Pembayaran

Setelah customer menyelesaikan pembayaran melalui website bank, customer akan diarahkan ke endpoint Finish Redirect URL yang dapat dikonfigurasi pada MAP (dashboard Midtrans).

Anda harus login ke MAP. Pilih menu Setting -> configuration, dan isi Finish Redirect URL dengan endpoint landing page Anda.

MAP settings

Midtrans akan mengirimkan response yang perlu didapatkan di script pada Finish Redirect URL. Pastikan endpoint Finish Redirect URL anda dapat menerima POST. Contoh code dibawah dibuat dalam PHP native. Silahkan sesuaikan dengan environment website anda.

<?php
$raw_response = $_POST['response']; //get the json response
$response = preg_replace('/\\\\/', '', $_POST['raw_response']); //clean up response from backslash
$decoded_response = json_decode($response);
$order_id = $decoded_response->order_id;//how to access
?>

Response akan dikirim dalam format JSON, dalam beberapa kasus terjadi adanya penambahakn backslash () dan tanda petik ("). Berikut contoh response yang mungkin diterima.

{
    \"status_code\" : \"200\",
    \"status_message\" : \"Success, transaction is found\",
    \"transaction_id\" : \"58b48d1c-3e51-46f8-a2fb-ad5fa668f534\",
    \"order_id\" : \"34\",
    \"gross_amount\" : \"19999998.00\",
    \"payment_type\" : \"cimb_clicks\",
    \"transaction_time\" : \"2018-01-26 08:57:45\",
    \"transaction_status\" : \"settlement\",
    \"approval_code\" : \"1516957074590\",
    \"signature_key\" : \"30b048ffff95e08c34cf265268224f0b6460d7716b3d70424a7203609a78b335280fe6137a9938cd3af24533fdafcfe8771203f6f30f21fd141a378bba1685fb\"
}

Jika response yang didapatkan seperti itu, maka perlu dibersihkan terlebih dahulu sehingga menjadi seperti ini.

{
    "status_code" : "200",
    "status_message" : "Success, transaction is found",
    "transaction_id" : "58b48d1c-3e51-46f8-a2fb-ad5fa668f534",
    "order_id" : "34",
    "gross_amount" : "19999998.00",
    "payment_type" : "cimb_clicks",
    "transaction_time" : "2018-01-26 08:57:45",
    "transaction_status" : "settlement",
    "approval_code" : "1516957074590",
    "signature_key" : "30b048ffff95e08c34cf265268224f0b6460d7716b3d70424a7203609a78b335280fe6137a9938cd3af24533fdafcfe8771203f6f30f21fd141a378bba1685fb"
}

Kemudian dilakukan decode dari json tersebut sehingga bisa di baca oleh PHP. Berikut hasil decode_response tersebut:

(
   [status_code] => 200
   [status_message] => Success, transaction is found
   [transaction_id] => 58b48d1c-3e51-46f8-a2fb-ad5fa668f534
   [order_id] => 34
   [gross_amount] => 19999998.00
   [payment_type] => cimb_clicks
   [transaction_time] => 2018-01-26 08:57:45
   [transaction_status] => settlement
   [approval_code] => 1516957074590
   [signature_key] => 30b048ffff95e08c34cf265268224f0b6460d7716b3d70424a7203609a78b335280fe6137a9938cd3af24533fdafcfe8771203f6f30f21fd141a378bba1685fb
)

Sekarang kira dapat menggunakan response tersebut untuk memberikan informasi kepada customer.


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:

{
  "transaction_time": "2019-12-11 16:20:48",
  "transaction_status": "settlement",
  "transaction_id": "34be81bd-1e4f-46b6-80f0-3e0f29776c63",
  "status_message": "midtrans payment notification",
  "status_code": "200",
  "signature_key": "f75192079b47bb2a55d8307d443388f418d139bd13b447b2521fd9fe7b33ffddf9435afaa212f4ef67452fb2f2f109c1852ddd7567bb2d74cefeb2f5aa995de6",
  "settlement_time": "2019-12-11 16:21:38",
  "payment_type": "bca_klikpay",
  "order_id": "order-101",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR",
  "approval_code": "112233"
}
{
  "transaction_time": "2019-12-11 16:23:18",
  "transaction_status": "settlement",
  "transaction_id": "89cb0bfd-675b-4d4a-942c-7e19ba66d442",
  "status_message": "midtrans payment notification",
  "status_code": "200",
  "signature_key": "65e02e423cca2618a8d9ec201768438684bbf7218b27ab6f05a2197ce5b3c44fc9f4a157dce5a42d49f3ed6b88ac7a163f7e6b532d876d57a4a9297c5802639c",
  "settlement_time": "2019-12-11 16:24:00",
  "payment_type": "cimb_clicks",
  "order_id": "order-101",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "currency": "IDR",
  "approval_code": "1576142640542"
}
{
  "transaction_time": "2019-12-11 16:25:34",
  "transaction_status": "settlement",
  "transaction_id": "e7eb187b-c54c-4960-8558-a995253d61ca",
  "status_message": "midtrans payment notification",
  "status_code": "200",
  "signature_key": "928775783adf67b0578340dc616a30d2c2b307350475fbfbcc5bc1a5ac94892bb6bb972b7fe2394509c32fd431fd3494a358f25e24456f7414b473989ab1e66f",
  "settlement_time": "2019-12-11 16:25:49",
  "payment_type": "danamon_online",
  "order_id": "order-101p-1576142735",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR",
  "approval_code": "uRaSu1XAnIm56i"
}
{
  "transaction_time": "2019-11-11 15:09:35",
  "transaction_status": "settlement",
  "transaction_id": "01c03b08-5e77-40d3-b1df-972f20a92e09",
  "status_message": "midtrans payment notification",
  "status_code": "200",
  "signature_key": "f0abe6507f42019839e028f9c5da723ff7c220c962af1f1f8fc25ac5a773c1123fd680602443e7cece83d059b9f9c13078d74cc4a79948214059394ec5d18c4b",
  "settlement_time": "2019-11-11 15:13:51",
  "payment_type": "bri_epay",
  "order_id": "order-101h-1576483775",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR",
  "approval_code": "1576483775235"
}
{
  "transaction_time": "2019-11-11 12:30:35",
  "transaction_status": "settlement",
  "transaction_id": "be30d5f1-3dfa-42a0-bc23-4d48207e71f0",
  "status_message": "midtrans payment notification",
  "status_code": "200",
  "signature_key": "1ab3eb28bc4833d193871ad911a0d96d45cc0d68cdfe30c6d5a61728593aa7129b6500090b95da1606956767473806102066d090eda72e4b2ee3f082df3ba731",
  "settlement_time": "2019-12-13 12:30:48",
  "payment_type": "akulaku",
  "order_id": "order-101",
  "merchant_id": "G812785002",
  "gross_amount": "11000.00",
  "fraud_status": "accept",
  "currency": "IDR"
}

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 Direct Debit sekarang selesai. Berikut beberapa referensi tambahan.

Deskripsi

Nilai transaction_status dalam transaksi direct debit:

Transaction Status Description
settlement Transaksi sukses, customer telah berhasil menyelesaikan/membayar transaksi.
pending Transaksi telah berhasil dibuat tetapi belum dibayarkan oleh customer.
expire Transaksi gagal karena customer tidak menyelesaikan pembayaran dalam waktu tertentu.
cancel Transaksi dibatalkan oleh Merchant.
deny Bank menolak transaksi tersebut.


Link: Definisi lebih detail transaction_status

Untuk lebih detail: Dokumentasi lengkap Core API