Integrasi Transfer Bank

Salah satu metode pembayaran yang ditawarkan Midtrans adalah Transfer Bank. Dengan menggunakan metode pembayaran ini, customer akan mempunyai pilihan untuk melakukan pembayaran melalui transfer bank dan Midtrans akan mengirimkan notifikasi pemberitahuan secara real time setelah customer menyelesaikan pembayarannya.

Saat ini, Midtrans telah terintegrasi dengan 4 metode pembayaran transfer bank yang berbeda:

  1. Permata Virtual Account
  2. BCA Virtual Account
  3. Mandiri Bill Payment
  4. BNI Virtual Account

Proses integrasi dasar untuk pembayaran Tranfer Bank 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

Berikut adalah daftar testing transaksi yang dapat digunakan di mode Sandbox, harap diperhatikan bahwa simulator ini tidak akan berfungsi pada mode Production.

Metode Pembayaran Deskripsi
Permata Virtual Account Midtrans akan membuat nomor dummy Permata Virtual Account. Untuk melakukan tes transaksi, gunakan simulator Permata Virtual Account.
BCA Virtual Account Midtrans akan membuat nomor dummy BCA Virtual Account. Untuk melakukan tes transaksi, gunakan simulator BCA Virtual Account.
Mandiri Bill Payment Midtrans akan membuat dummy Kode Pembayaran untuk pembayaran via Mandiri e-channel (Internet Banking, SMS Banking, Mandiri ATM). Untuk melakukan tes transaksi, gunakan simulator Mandiri Bill Payment.
BNI Virtual Account Midtrans akan membuat nomor dummy BNI Virtual Account. Untuk melakukan tes transaksi, gunakan simulator BNI Virtual Account.



Diagram

Gambaran dari flow transaksi dalam sequence diagram:
bank transfer transaction flow .

Langkah Integrasi

  1. Kirim data traksaksi ke API Charge.
  2. Tampilkan nomor virtual account dan waktu expire.
  3. 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": "bank_transfer",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
  "bank_transfer":{
      "bank": "bca"
  }
}'
# 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": "echannel",
  "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": "bank_transfer",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
  "bank_transfer":{
      "bank": "bni"
  }
}'
# 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": "permata",
  "transaction_details": {
      "order_id": "order-101",
      "gross_amount": 44000
  }
}'

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": "Success, Bank Transfer transaction is created",
    "transaction_id": "be03df7d-2f97-4c8c-a53c-8959f1b67295",
    "order_id": "1571823229",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "bank_transfer",
    "transaction_time": "2019-10-23 16:33:49",
    "transaction_status": "pending",
    "va_numbers": [
        {
            "bank": "bca",
            "va_number": "812785002530231"
        }
    ],
    "fraud_status": "accept"
}

Anda akan mendapatkan atribut va_numbers yang dapat digunakan untuk melakukan transaksi.

{
    "status_code": "201",
    "status_message": "OK, Mandiri Bill transaction is successful",
    "transaction_id": "abb2d93f-dae3-4183-936d-4145423ad72f",
    "order_id": "1571823332",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "echannel",
    "transaction_time": "2019-10-23 16:35:31",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "bill_key": "778347787706",
    "biller_code": "70012"
}

Anda akan mendapatkan atribut bill_key dan bill_code yang dapat digunakan untuk melakukan transaksi.

{
    "status_code": "201",
    "status_message": "Success, Bank Transfer transaction is created",
    "transaction_id": "2194a77c-a412-4fd8-8ec8-121ff64fbfee",
    "order_id": "1571823369",
    "merchant_id": "G812785002",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "bank_transfer",
    "transaction_time": "2019-10-23 16:36:08",
    "transaction_status": "pending",
    "va_numbers": [
        {
            "bank": "bni",
            "va_number": "9888500212345678"
        }
    ],
    "fraud_status": "accept"
}

Anda akan mendapatkan atribut va_numbers yang dapat digunakan untuk melakukan transaksi.

{
    "status_code": "201",
    "status_message": "Success, PERMATA VA transaction is successful",
    "transaction_id": "035ca76c-b814-4264-9e63-68142351df83",
    "order_id": "1571823410",
    "gross_amount": "44000.00",
    "currency": "IDR",
    "payment_type": "bank_transfer",
    "transaction_time": "2019-10-23 16:36:49",
    "transaction_status": "pending",
    "fraud_status": "accept",
    "permata_va_number": "850003072869607",
    "merchant_id": "G812785002"
}

Anda akan mendapatkan atribut permata_va_number yang dapat digunakan untuk melakukan transaksi.

2. Tampilkan Nomor Virtual Account dan Waktu Expire.

Anda bisa menggunakan va_number yang didapatkan dari respons API untuk menampilkan nomor virtual account.

Secara default expiry time untuk Transfer Bank / VA adalah 24jam, periksa halaman ini jika anda ingin mengkustomisasi expiry time sesuai kehendak anda.

3. Terima notifikasi transaksi

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:

{
  "va_numbers": [
    {
      "va_number": "812785002530231",
      "bank": "bca"
    }
  ],
  "transaction_time": "2019-10-23 16:33:49",
  "transaction_status": "pending",
  "transaction_id": "be03df7d-2f97-4c8c-a53c-8959f1b67295",
  "status_message": "midtrans payment notification",
  "status_code": "201",
  "signature_key": "b07e6b0c6e7786363f9d7c1502e1171143fefe38e1a2bb93bce87e0fb64dd2ddfbbc8c7d60c6dcd7d6d8edb22169fd46e2250a6a547aa9f3f6da206a63334360",
  "payment_type": "bank_transfer",
  "payment_amounts": [

  ],
  "order_id": "1571823229",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR"
}
{
  "transaction_time": "2019-10-23 16:35:31",
  "transaction_status": "pending",
  "transaction_id": "abb2d93f-dae3-4183-936d-4145423ad72f",
  "status_message": "midtrans payment notification",
  "status_code": "201",
  "signature_key": "ac6c542806820cd5abe218fadc4f2d150e6e6c9ea6cc24a56c78f3625c19ae0eb4bbf0e26059d2bc6879752e9a1f2b673c3158a34f7e96651d621a0be8258ca9",
  "payment_type": "echannel",
  "order_id": "1571823332",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR",
  "biller_code": "70012",
  "bill_key": "778347787706"
}
{
  "va_numbers": [
    {
      "va_number": "9888500212345678",
      "bank": "bni"
    }
  ],
  "transaction_time": "2019-10-23 16:36:08",
  "transaction_status": "pending",
  "transaction_id": "2194a77c-a412-4fd8-8ec8-121ff64fbfee",
  "status_message": "midtrans payment notification",
  "status_code": "201",
  "signature_key": "9eea61a37704a010c0665fbd738eade7bb08ecb8096ee4d3f08def1eb4f9e1f86f0717c3b79b3c41ff36c67c17bb0124e9f567589eba341aae1ad899fecf2ef3",
  "payment_type": "bank_transfer",
  "payment_amounts": [

  ],
  "order_id": "1571823369",
  "merchant_id": "G812785002",
  "gross_amount": "44000.00",
  "fraud_status": "accept",
  "currency": "IDR"
}
{
  "transaction_time": "2019-10-23 16:36:49",
  "transaction_status": "pending",
  "transaction_id": "035ca76c-b814-4264-9e63-68142351df83",
  "status_message": "midtrans payment notification",
  "status_code": "201",
  "signature_key": "386ef32b70e611a41062db75ce2d3770a3e9861df50b0f9e49e56f5d64d74fc4acdef5e16a12955bb232b08384eb43aea22400aa591f658197c69f8ffe8e04f3",
  "permata_va_number": "850003072869607",
  "payment_type": "bank_transfer",
  "order_id": "1571823410",https://open.spotify.com/track/7McZS9J6h0SKoZBR6cfcFe
  "merchant_id": "G812785002",
  "gross_amount": "44000.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 Transfer Bank / VA telah selesai. Berikut beberapa referensi tambahan.

Custom Virtual Account Number

Nomor virtual account berisi company code dan unique code. Hanya unique code yang bisa di kustomisasi untuk pembayaran bank BCA, BNI dan Permata (hanya untuk transaksi b2b).

Jika nomor VA yang direquest sudah digunakan untuk transaksi lain, maka akan ditampilkan unique code secara random.
Jika nomor VA yang direquest lebih panjang dari yang dibutuhkan, maka angka yang tidak perlu akan dipangkas.
Jika nomor VA yang direquest lebih pendek dari yang dibutuhkan, maka nomor tersebut akan diawali dengan nol.

Tambahkan parameter bank_transfer di request API /charge:

"bank_transfer":{
  "bank": "bca",
  "va_number": "12345678911" //Length should be within 1 to 11
}
"bank_transfer":{
  "bank": "bni",
  "va_number": "12345678" //Length should be within 1 to 8
}
"bank_transfer":{
  "bank": "permata",
  "va_number": "1234567890" //Length should be 10. Only supported for b2b transactions
}

Deskripsi

Nilai transaction_status dalam transaksi transfer bank:

Transaction Status Description
settlement Transaksi sukses, customer telah berhasil menyelesaikan/membayar transaksi.
pending Transaksi telah berhasil dibuat VAnya 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