NAV
Snap API

Langkah Awal

Gambaran Umum

  1. User melakukan pembayaran
  2. Server Merchant melakukan api request ke server Snap berisikan data transaksi
  3. Server Snap menyimpan data transaksi dan memberikan SNAP_TOKEN
  4. Server Merchant menampilkan halaman ringkasan pembelian dengan SNAP_TOKEN di browser
  5. User memverifikasi rincian pembelian dan mengklik tombol bayar. Merchant javascript mengeksekusi snap.pay (SNAP_TOKEN, opsi). Pengguna kemudian mengisi data pembayaran dan mengklik tombol konfirmasi.
  6. Snap JS mengirimkan data pembayaran ke server Snap
  7. Server Snap memproses data dan meresponse dengan status pembayaran. Snap JS kemudian mengeksekusi callback sesuai dengan status transaksi
  8. Server Snap akan memberikan notifikasi ke server Merchant tentang status pembayaran

payment flow

Browser yang didukung

Kami mencoba untuk mendukung versi terbaru dari semua browser utama. Berikut adalah versi minimum yang didukung untuk masing-masing browser di perangkat Mobile dan Desktop:

Mobile

Desktop

Persiapan Awal

Tujuan: Merchants melengkapi syarat yang diperlukan sebelum berintegrasi dengan midtrans

Ada beberapa syarat yang harus dilengkapi sebelum berintegrasi dengan midtrans:

1. Daftar ke akun Sandbox/Production Midtrans

Saat ini midtrans memiliki satu akun login untuk mengakses akun sandbox dan production. Akun sandbox digunakan pada periode development/testing sedangkan akun production digunakan ketika merchant sudah selesai melakukan integrasi dan siap untuk go live. Data dan transaksi yang dibuat di akun sandbox tidak akan memicu terjadinya pembelian sungguhan tetapi pada akun production akan mengakibatkan transaksi sebenarnya. Silakan melakukan pendaftaran akun midtrans di sini.

Setelah masuk, akan ada tombol kecil di bagian atas dari dasboard yang menampilkan anda sedang di dalam mode sandbox atau production. Warna pada menu navigasi samping juga dibedakan antara production (biru muda) dan sandbox (biru tua) untuk lebih memperjelas.

map production map sandbox

2. Lengkapi informasi yang diperlukan di Merchant Admin Portal (MAP)

Kolom yang perlu diisi bisa dilihat di Settings - General Settings.

general settings

3. Catat Access Keys akun Anda

Access Keys akun Anda dapat dilihat di Settings - Access Keys.

access keys

4. Konfigurasi Pengalihan URL

Customer akan dikembalikan ke website Anda setelah proses pembayaran selesai.

redirection url

Masuk ke Settings - Configuration menu untuk mengatur pengalihan URL.

map redirection url

Library dan Plugin

Kami berusaha membuat proses integrasi menjadi semudah mungkin untuk anda. Bagian ini berisi daftar plugin dan library midtrans, jika anda memiliki plugin atau library sendiri dan ingin terhubung dengan plugin dan library kami, hubungi support@midtrans.com.

Libraries

Platform Resources
PHP Github

Plugin

Platform Resources
Prestashop v1.6
Github
Magento v1.8, v1.9
Github
Opencart v2.0, v2.1, v2.2
Github
WHMCS WHMCS v5.3.12 ke atas
Github
Wordpress
Woocommerce
Wordpress v3.9.1 - v4.x
WooCommerce v2.1.11 - v2.5.x
Github

Integrasi Backend

Tujuan dari integrasi backend adalah memperoleh SNAP_TOKEN dengan mengirimkan informasi pembayaran. Kami menyediakan HTTP API untuk melakukan hal ini.

Endpoint

HTTP Method: POST

Production: https://app.midtrans.com/snap/v1/transactions

Sandbox: https://app.sandbox.midtrans.com/snap/v1/transactions

Request Headers

SERVER_KEY = "VT-server-Cpo03kYDOc0cNUKgt6hnLkKg"

AUTH_STRING = Base64("VT-server-Cpo03kYDOc0cNUKgt6hnLkKg:")

AUTH_STRING = "VlQtc2VydmVyLUNwbzAza1lET2MwY05VS2d0NmhuTGtLZzo="

Untuk melakukan HTTP request yang valid, merchant harus menambahkan 3 header:

Snap melakukan validasi HTTP request menggunakan Basic Authentication. Pada kasus ini, username Anda adalah SERVER_KEY dengan password kosong. Anda dapat mengetahui SERVER-KEY Anda dengan melihat di Settings - Access Keys.

Nilai dari header Authorization direpresentasikan sebagai AUTH_STRING. AUTH_STRING adalah base-64 dari username & password Anda.

AUTH_STRING = Base64(SERVER_KEY + :)

JSON Parameter (Request Body)

Request sederhana

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  }
}

Request lengkap

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  },
  "item_details": [{
    "id": "ITEM1",
    "price": 10000,
    "quantity": 1,
    "name": "Midtrans Bear",
    "brand": "Midtrans",
    "category": "Toys",
    "merchant_name": "Midtrans"
  }],
  "enabled_payments": ["credit_card", "mandiri_clickpay", "cimb_clicks",
    "bca_klikbca", "bca_klikpay", "bri_epay", "telkomsel_cash", "echannel",
    "xl_tunai", "indosat_dompetku", "mandiri_ecash", "permata_va", "bca_va",
    "bni_va", "other_va", "kioson", "indomaret", "gci", "danamon_online"],
  "credit_card": {
    "secure": true,
    "channel": "migs",
    "bank": "bca",
    "installment": {
      "required": false,
      "terms": {
        "bni": [3, 6, 12],
        "mandiri": [3, 6, 12],
        "cimb": [3],
        "bca": [3, 6, 12],
        "offline": [6, 12]
      }
    },
    "whitelist_bins": [
      "48111111",
      "41111111"
    ]
  },
  "customer_details": {
    "first_name": "TEST",
    "last_name": "MIDTRANSER",
    "email": "test@midtrans.com",
    "phone": "+628123456",
    "billing_address": {
      "first_name": "TEST",
      "last_name": "MIDTRANSER",
      "email": "test@midtrans.com",
      "phone": "081 2233 44-55",
      "address": "Sudirman",
      "city": "Jakarta",
      "postal_code": "12190",
      "country_code": "IDN"
    },
    "shipping_address": {
      "first_name": "TEST",
      "last_name": "MIDTRANSER",
      "email": "test@midtrans.com",
      "phone": "0 8128-75 7-9338",
      "address": "Sudirman",
      "city": "Jakarta",
      "postal_code": "12190",
      "country_code": "IDN"
    }
  },
  "expiry": {
    "start_time": "2018-12-13 18:11:08 +0700",
    "unit": "minutes",
    "duration": 1
  },
  "custom_field1": "custom field 1 content",
  "custom_field2": "custom field 2 content",
  "custom_field3": "custom field 3 content"
}
Parameter Deskripsi
transaction_details.order_id
String(50) (required)
ID Transaksi. Setiap merchant dapat menggunakan 1 order ID sekali
transaction_details.gross_amount
Integer (required)
Jumlah yang akan ditagih ke customer
item_details
Array Item Details (optional)
Rincian barang yang akan dibayar
enabled_payments
Array (optional)
Daftar tipe pembayaran yang dapat dipilih customer. Jika kosong, semua tipe pembayaran yang aktif akan digunakan.
Pilihan:
credit_card, mandiri_clickpay, cimb_clicks, bca_klikbca, bca_klikpay, bri_epay, telkomsel_cash, echannel, xl_tunai, indosat_dompetku, mandiri_ecash, permata_va, other_va, bca_va, bni_va, kioson, indomaret, gci, danamon_online.

Alias berelasi dengan beberapa tipe pembayaran. Menambahkan alias berarti menambahkan tipe pembayaran yang berelasi.
Daftar Alias:
bank_transfer => permata_va, bca_va
cstore => kioson, indomaret.

Jika Anda ingin mengaktifkan other_va, jangan lupa untuk turut mengaktifkan permata_va karena Midtrans menggunakan Permata untuk Bank Transfer lainnya
customer_details.first_name
String(255) (optional)
customer_details.last_name
String(255) (optional)
customer_details.email
String(255) (optional)
customer_details.phone
String(255) (optional)
customer_details.billing_address
Address (optional)
customer_details.shipping_address
Address (optional)
credit_card
CreditCard (optional)
Kustomisasi pembayaran kartu kredit
bca_va
BCA Virtual Account (optional)
Kustomisasi pembayaran BCA virtual account
permata_va
Permata Virtual Account (optional)
Kustomisasi pembayaran Permata virtual account
bni_va
BNI Virtual Account (optional)
Kustomisasi pembayaran BNI virtual account
callbacks.finish
String(255) (optional)
Redirect URL jika pembayaran berhasil diselesaikan (di-override oleh JS callback)
expiry
Expiry (optional)
kustomisasi umur transaksi
custom_field1
String(255) (optional)
Custom field 1 untuk kustom parameter dari merchant
custom_field2
String(255) (optional)
Custom field 2 untuk kustom parameter dari merchant
custom_field3
String(255) (optional)
Custom field 3 untuk kustom parameter dari merchant

JSON Object

Kumpulan objek JSON yang digunakan dalam parameter Create Snap Token.

Item Details

{
  "id": "ITEM1",
  "price": 10000,
  "quantity": 1,
  "name": "Midtrans Bear",
  "brand": "Midtrans",
  "category": "Toys",
  "merchant_name": "Midtrans"
}
Parameter Deskripsi
id
String(50) (optional)
ID barang
price
Integer (required)
Harga barang
NOTE: Jangan menggunakan desimal sebagai harga barang
quantity
Integer (required)
Jumlah barang yang dibeli
name
String(50) (required)
Nama barang
brand
String(50) (optional)
Merk barang
category
String(50) (optional)
Kategori barang
merchant_name
String(50) (optional)
Nama merchant yang menjual barang

Address

{
  "first_name": "TESTER",
  "last_name": "MIDTRANSER",
  "email": "test@midtrans.com",
  "phone": "081 2233 44-55",
  "address": "Sudirman",
  "city": "Jakarta",
  "postal_code": "12190",
  "country_code": "IDN"
}
Parameter Deskripsi
first_name
String(255) (optional)
last_name
String(255) (optional)
email
String(255) (optional)
phone
String(255) (optional)
address
String(200) (optional)
country_code
String(10) (optional)
postal_code
String(10) (optional)
city
String(100) (optional)

Credit Card

{
  "save_card": true,
  "secure": true,
  "channel": "migs",
  "bank": "maybank",
  "installment": {
    "required": false,
    "terms": {
      "bni": [3, 6, 12],
      "mandiri": [3, 6, 12],
      "cimb": [3],
      "bca": [3, 6, 12],
      "offline": [6, 12]
    }
  },
  "whitelist_bins": [
    "48111111",
    "41111111",
    "bni"
  ]
}
Parameter Deskripsi
secure
Boolean (optional)
Gunakan autentikasi 3D Secure. Default: false
bank
String (optional)
Acquiring bank. Pilihan: bca, bni, mandiri, cimb, bri, danamon, maybank, mega
channel
String (optional)
Acquiring channel. Pilihan: migs
type
String (opsional)
Tipe transaksi kartu kredit. Pilihan: authorize, authorize_capture. Default: “authorize_capture”
whitelist_bins
Array (optional)
Nomor BIN kartu kredit yang diperbolehkan. Nilainya dapat berupa 8 digit BIN ataupun nama bank (semua nomor kartu yang dikeluarkan oleh bank tersebut akan diperbolehkan). Nama bank yang didukung yaitu bni bca mandiri cimb bri and maybank. Default: perbolehkan semua nomor kartu
installment.required
Boolean (optional)
Transaksi harus menggunakan cicilan. Default: false
installment.terms
Object (optional)
Pilihan bank dan durasi cicilan

BCA Virtual Account

{
  "va_number": "12345678911",
  "free_text": {
    "inquiry": [
      {
        "en": "text in English",
        "id": "text in Bahasa Indonesia"
      }
    ],
    "payment": [
      {
        "en": "text in English",
        "id": "text in Bahasa Indonesia"
      }
    ]
  }
}
Parameter Deskripsi
va_number
String (optional)
Nomor virtual account kustom. Panjang antara 1-11 digit.
free_text
FreeText (optional)

Free Text

Parameter Deskripsi
inquiry
Array of FreeTextItem (optional)
Jumlah item tidak boleh lebih dari 10.
payment
Array of FreeTextItem (optional)
Jumlah item tidak boleh lebih dari 10.

Free Text Item

Parameter Deskripsi
en
String (required)
Panjang tidak boleh lebih dari 50 karakter.
id
String (required)
Panjang tidak boleh lebih dari 50 karakter.

Permata Virtual Account

{
  "va_number": "1234567890"
}
Parameter Deskripsi
va_number
String (optional)
Nomor virtual account kustom. Panjang 10 digit. Hanya untuk transaksi B2B.

BNI Virtual Account

{
  "va_number": "12345678"
}
Parameter Deskripsi
va_number
String (optional)
Nomor virtual account kustom. Panjang antara 1-8 digit.

Expiry

{
  "start_time": "2018-12-13 18:11:08 +0700",
  "unit": "minutes",
  "duration": 1
}
Parameter Deskripsi
start_time
String(255) (optional)
Timestamp dalam format yyyy-MM-dd HH:mm:ss Z. Jika tidak diset, waktu transaksi akan digunakan sebagai start_time (saat customer charge)
duration
Integer (optional)
Expiry duration
unit
String (optional)
Expiry unit. Pilihan: day, hour, minute (Bentuk plural dapat digunakan)

Response

Request Berhasil

{
  "token": "d379aa71-99eb-4dd1-b9bb-eefe813746e9"
}

HTTP status code: 201

Field Deskripsi
token
String(36)
Snap token untuk integrasi frontend

Request Gagal

Autentikasi Gagal

{
  "error_messages": [
    "Access denied, please check client or server key"
  ]
}

HTTP status code: 401

Field Deskripsi
error_messages
Array
Pesan error

Validasi Gagal

{
  "error_messages": [
    "transaction_details.gross_amount is not equal to the sum of item_details"
  ]
}

HTTP status code: 400

Field Deskripsi
error_messages
Array
Pesan error

Kesalahan Sistem

{
  "error_messages": [
    "Sorry, we encountered internal server error. We will fix this soon."
  ]
}

HTTP status code: 500

Field Deskripsi
error_messages
Array
Pesan error

Integrasi Frontend

Gambaran Umum

<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script type="text/javascript"
            src="https://app.sandbox.midtrans.com/snap/snap.js"
            data-client-key="<CLIENT-KEY>"></script>
  </head>
  <body>
    <button id="pay-button">Pay!</button>
    <script type="text/javascript">
      var payButton = document.getElementById('pay-button');
      payButton.addEventListener('click', function () {
        snap.pay('<SNAP_TOKEN>');
      });
    </script>
  </body>
</html>

Tujuan dari integrasi frontend adalah menampilkan pop up Snap di halaman Anda.

Tambahkan snap.js ke dalam halaman Anda sehingga modul snap siap digunakan. Jangan lupa untuk menaruh informasi CLIENT-KEY Anda sebagai nilai dari atribut data-client-key di tag script snap.js. Anda dapat mengetahui CLIENT-KEY Anda dengan melihat di Settings - Access Keys.

Anda dapat memulai proses pembayaran dengan memanggil fungsi snap.pay dan menggunakan SNAP_TOKEN yang didapat dari integrasi backend sebagai parameter.

Lokasi Snap.js

Production: https://app.midtrans.com/snap/snap.js

Sandbox: https://app.sandbox.midtrans.com/snap/snap.js

Viewport Meta Tag

Untuk memastikan popup modal Snap ditampilkan secara sesuai oleh browser mobile, jangan lupa untuk menaruh tag viewport meta tag di dalam element <head> Anda.

Pada umumnya, implementasi tag viewport meta dilakukan seperti berikut:

<meta name="viewport" content="width=device-width, initial-scale=1">

Snap JS

snap memiliki 3 fungsi utama: pay, show, & hide

pay(snapToken, options)

Mulai pembayaran di halaman Snap.

snap.pay('YOUR_SNAP_TOKEN', {
  onSuccess: function(result){console.log('success');console.log(result);},
  onPending: function(result){console.log('pending');console.log(result);},
  onError: function(result){console.log('error');console.log(result);},
  onClose: function(){console.log('customer closed the popup without finishing the payment');}
})

Parameter:

Nama Deskripsi
snapToken
String (required)
Snap token yang diperoleh saat integrasi backend
enabledPayments
Array (optional)
Daftar pilihan pembayaran yang akan ditampilkan. Akan memfilter daftar pilihan pembayaran dari integrasi backend.
options.onSuccess
Function (optional)
Callback pembayaran sukses (200 status_code)
options.onPending
Function (optional)
Callback pembayaran pending (201 status_code)
options.onError
Function (optional)
Callback pembayaran error (4xx or 5xx status_code)
options.onClose
Function (optional)
Callback saat customer menutup halaman pembayaran (transaksi belum dilakukan)
options.language
String (optional)
Pengaturan bahasa. Akan menimpa pengaturan bahasa di Merchant Administration Portal. Bahasa yang didukung yaitu en (Inggris) dan id (Bahasa). Default: id
options.skipOrderSummary
Boolean (optional)
Lewati halaman rangkuman jika di-set true. Default: false
options.skipCustomerDetails
Boolean (optional)
Membuat email dan no telefon opsional dalam form CC jika di-set to true. Default: false
options.autoCloseDelay
Integer (optional)
Tutup secara otomatis halaman pembayaran terakhir indomaret dan bank transfer setelah waktu yang ditentukan. Jeda waktu dinyatakan dalam satuan detik. Atur jeda waktu dengan nilai 0 untuk menonaktifkan fitur ini. Default: 0
options.showOrderId
Boolean (optional)
Menampilkan informasi order ID jika di-set true. Default: false

Fungsi onSuccess, onPending, & onError menerima satu parameter, yaitu: objek Transaction Result.

function ajaxGetToken(transactionData, callback){
    var snapToken;

    // Request SNAP_TOKEN melalui backend Anda & simpan hasilnya ke variabel snapToken

    if(snapToken){
      callback(null, snapToken);
    } else {
      callback(new Error('Failed to fetch snap token'),null);
    }
}

payButton.onclick(function(){
  snap.show();
  ajaxGetToken(transactionData, function(error, snapToken){
    if(error){
      snap.hide();
    } else {
      snap.pay(snapToken);
    }
  });
});

show()

Tampilkan halaman loading Snap. Fungsi ini berguna jika Anda ingin menampilkan animasi loading ketika request SNAP_TOKEN sedang berlangsung menggunakan AJAX.

Jika AJAX success, gunakan snap.pay untuk melanjutkan proses pembayaran. Anda juga dapat menggunakan snap.hide untuk menyembunyikan halaman loading.

hide()

Sembunyikan halaman Snap. Merupakan komplemen dari fungsi snap.show. Fungsi ini berguna jika anda ingin menyembunyikan halaman Snap yang sedang aktif.

JS Callback

Transaction Result

Kartu kredit - transaksi sukses

{
   "status_code":"200",
   "status_message":"Success, Credit Card transaction is successful",
   "transaction_id":"6d9677da-45a3-40d0-a0f0-8f0b2f860a64",
   "masked_card":"481111-1114",
   "order_id":"1459499971",
   "gross_amount":"10000.00",
   "payment_type":"credit_card",
   "transaction_time":"2016-04-01 15:39:58",
   "transaction_status":"capture",
   "fraud_status":"accept",
   "approval_code":"100057",
   "bank":"bni"
}

Echannel - transaksi pending

{
   "status_code":"201",
   "status_message":"Transaksi sedang diproses",
   "transaction_id":"0ae66c29-e4a6-4e7b-b223-a103564a8d29",
   "order_id":"1459500813",
   "gross_amount":"10000.00",
   "payment_type":"echannel",
   "transaction_time":"2016-04-01 15:54:07",
   "transaction_status":"pending",
   "fraud_status":"accept",
   "bill_key":"001689",
   "biller_code":"70012"
}

Transaksi error

{
  "status_code": "406",
  "status_message": ["transaction has been processed"]
}

Objek yang merepresentasikan hasil transaksi. Merupakan parameter dari Snap callback.

Nama Deskripsi
status_code
String
Kode status dari transaksi. Nilai: 200, 201, 202, 400, 404, 406, 500
status_message
String
Detail status
order_id
String
ID transaksi oleh merchant
gross_amount
String
Jumlah yang dibayar oleh customer
payment_type
String
Tipe pembayaran yang digunakan oleh customer. Nilai: credit_card, bca_klikpay, bca_klikbca, bri_epay, mandiri_clickpay, telkomsel_cash, xl_tunai, bank_transfer, echannel, indosat_dompetku, mandiri_ecash, cstore
transaction_time
String
Timestamp dalam format yyyy-MM-dd hh:mm:ss
transaction_status
String
Status transaksi. Nilai: capture, settlement, pending, cancel, expired
fraud_status
String
Status fraud. Nilai: accept, challenge, deny
approval_code
String
Kode approval dari bank
masked_card
String
6 digit depan & 4 digit belakang kartu (hanya di credit_card & mandiri_clickpay)
bank
String
Acquiring Bank (hanya di credit_card & mandiri_clickpay)
permata_va_number
String
Virtual account Permata (hanya di bank_transfer)
bill_key
String
Kode bill yang harus dibayar customer (hanya di echannel)
biller_code
String
Kode biller merchant (hanya di echannel)
redirect_url
String
URL yang harus dikunjungi customer (hanya di bca_klikbca, bri_epay, & cimb_clicks)
saved_token_id
String
TWO_CLICKS_TOKEN (hanya di credit_card)
saved_token_id_expired_at
String
Waktu kadaluarsa TWO_CLICKS_TOKEN

Fitur Lainnya

Two Clicks

1) Request /snap/v1/transactions dengan credit_card.save_card bernilai true

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  },
  "credit_card": {
    "secure": true,
    "save_card": true
  }
}

2) Simpan nilai saved_token_id yang tersedia di dalam callback OnSuccess atau Http Notification

snap.pay('YOUR_SNAP_TOKEN', {
  onSuccess: function(result) {
    if (result.saved_token_id) {
      // simpan TWO_CLICKS_TOKEN dari customer ke dalam database
    }
  }
})

3) Request /snap/v1/transactions dengan credit_card.card_token bernilai TWO_CLICKS_TOKEN yang telah Anda simpan pada transaksi pertama

{
  "transaction_details": {
    "order_id": "ORDER-102",
    "gross_amount": 10000
  },
  "credit_card": {
    "secure": true,
    "card_token": "TWO_CLICKS_TOKEN"
  }
}

Fitur two clicks memungkinkan Anda untuk menyimpan data nomor kartu kredit, tanggal kadaluarsa kartu kredit, email, dan ponsel customer dalam bentuk TWO_CLICKS_TOKEN. Pada pembayaran selanjutnya, TWO_CLICKS_TOKEN dapat digunakan untuk mengisi detail pembayaran secara otomatis. Customer hanya perlu melengkapi CVV kartu kredit untuk menyelesaikan pembayaran.

Ada 2 langkah yang perlu dilakukan untuk menggunakan fitur two clicks:

Transaksi Awal

Transaksi Selanjutnya

One Click

Request SNAP_TOKEN dengan user_id dan set credit_card.save_card ke true

{
  "transaction_details": {
    "order_id": "ORDER-101",
    "gross_amount": 10000
  },
  "credit_card": {
    "secure": true,
    "save_card": true
  },
  "user_id": "customer-nR6DCOzqGis"
}

Sebagai tambahan dari fitur two clicks, SNAP juga mendukung transaksi one click dimana informasi CVV juga akan disimpan. Dengan ini, customer dapat langsung melanjutkan proses pembayaran tanpa harus memasukkan informasi tambahan.

Untuk menyederhanakan alur penyimpanan data kartu oleh merchant, SNAP menyediakan fitur Card Token Storage. Jadi, merchant tidak perlu menyimpan dan mengatur Card Token sendiri. Merchant dapat dengan mudah mengintegrasikan fitur Card Token Storage ke SNAP dengan menambahkan parameter user_id yang berasosiasi dengan akun customer di sistem merchant, selain mengaktifkan flag credit_card.save_card, ketika mengirimkan request SNAP Token.

Kemudian, SNAP akan menentukan informasi kartu nantinya akan disimpan sebagai one click berdasarkan kriteria berikut:

  1. Merchant memiliki MID recurring yang aktif
  2. Transaksi awal adalah 3DS

Jika kedua kondisi di atas terpenuhi, Card Token akan disimpan sebagai one click. Selain itu, maka akan disimpan sebagai two clicks.

Mirip dengan alur two clicks, ada dua langkah yang diperlukan untuk menggunakan fitur Card Token Storage di SNAP:

Transaksi Awal

Transaksi Selanjutnya

Nomor Virtual Account Kustom

bca_va

{
  "bca_va": {
    "va_number": "55555555555"
  }
}

permata_va

{
  "permata_va": {
    "va_number": "1234567890"
  }
}

bni_va

{
  "bni_va": {
    "va_number": "12345678"
  }
}

Nomor virtual account terdiri dari dua bagian. Contohnya {91012}{12435678}, bagian pertama adalah kode perusahaan dan bagian kedua adalah kode unik. Bagian kedua dapat dikustomisasi untuk tipe pembayaran bca_va, permata_va dan bni_va.

Pre-Authorization

Request /snap/v1/transactions dengan credit_card.type di-set ke “authorize”

{
  "credit_card": {
    "type": "authorize"
  }
}

Fitur pre-authorization memungkinkan Anda untuk mem-blok limit kartu kredit customer. Untuk menggunakan fitur ini, dibutuhkan parameter tambahan di objek kartu kredit:

Parameter Deskripsi
credit_card.type
String (opsional)
Tipe transaksi kartu kredit. Pilihan: authorize, authorize_capture. Default: “authorize_capture”

Status Transaksi

midtrans menyediakan tiga sarana bagi merchant untuk memperoleh status transaksi.

Notifikasi email

Anda dapat mengkonfigurasi pengaturan notifikasi email di Settings - Email Notification di MAP.

email notification

Notifikasi HTTP(S) POST

Notifikasi melalui HTTP(S) POST akan dikirim ke merchant server bila pelanggan telah menyelesaikan proses pembayaran. Anda dapat memanfaatkan notifikasi HTTP(S) POST untuk memperbarui status pembayaran atau mengirim barang pembeli secara real time.

Mengaktifkan midtrans notifikasi HTTP(S) POST dengan menetapkan Payment Notification URL di Settings - Configuration.

http notification

Lihat disini untuk contoh json notifikasi setiap channels pembayaran.

Merchant Admin Portal (MAP) Status Transaksi

Merchant dapat memeriksa status transaksi dari payments menu di MAP.

Contoh status transaksi yang berhasil untuk kartu kredit:

map transaction

Menggunakan Notifikasi

Logika signature key

SHA512(order_id + status_code + gross_amount + serverkey)

Contoh kode menghasilkan signature key

<?php
$orderId = "1111";
$statusCode = "200";
$grossAmount = "100000.00";
$serverKey = "askvnoibnosifnboseofinbofinfgbiufglnbfg";
$input = $orderId.$statusCode.$grossAmount.$serverKey;
$signature = openssl_digest($input, 'sha512');
echo "INPUT: " , $input."<br/>";
echo "SIGNATURE: " , $signature;
?>

Dalam rangka meningkatkan aspek keamanan, ada beberapa cara untuk memastikan notifikasi yang diterima dari midtrans.

Membandingkan Response

Mekanisme tambahan yang kami sediakan untuk memverifikasi isi dan asal pengirim notifikasi adalah dengan membandingkan respon yg didapat dari get status API. Respon akan sama dengan status notifikasi.

challenge response

Signature Key

Kami menambahkan informasi signature key dalam notifikasi kami. Tujuan utama signature key ini adalah untuk memvalidasi apakah notifikasi tersebut berasal dari midtrans atau bukan. Jika notifikasi tidak asli, merchant dapat mengabaikan notifikasi. Silakan merujuk sisi kode di samping untuk melihat logika signature key dan contoh kode untuk menghasilkan signature key.

Best Practice Menggunakan Notifikasi

Berikut ini adalah jenis-jenis notifikasi. Catatan, notifikasi jenis baru dapat bertambah. Dan juga informasi baru dalam notifikasi yang telah ada dapat bertambah, silahkan konfirmasi dengan dokumentasi terbaru untuk informasi yang tepat.

Status Kode

Tujuan: Anda memahami kode status yang digunakan oleh midtrans. Apabila butuh bantuan, silahkan hubungi kami di support@midtrans.com atau kunjungi halaman support kami.

Status code di midtrans API terbagi menjadi beberapa bagian, yaitu 2xx, 3xx, 4xx dan 5xx.

Kode 2xx

Status Keterangan
200 Kartu Kredit: Sukses. Request dan transaksi berhasil (authorize, capture, cancel, get status, approve transaksi), telah diterima oleh midtrans dan bank.
Metode pembayaran lainnya: Sukses. Transaksi berhasil/settlement.
201 Kartu Kredit: Challenge. Transaksi berhasil namun belum selesai diproses, diperlukan tindakan manual merchant untuk menyelesaikan proses transaksi. Jika merchant tidak melakukan action apapun hingga waktu settlement (H+1 pkl 16.00 WIB), midtrans akan membatalkan transaksi tersebut.
Bank Transfer: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 24 jam.
Cimb Clicks: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
BRI ePay: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
Klik BCA: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
BCA Klikpay: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
Mandiri Bill Payment: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
XL Tunai: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
Indomaret: Pending. Transaksi berhasil namun proses pembayaran belum selesai dilakukan oleh customer. Secara default transaksi akan kadaluarsa dalam waktu 2 jam.
202 Kartu Kredit: Gagal. Request berhasil tapi transaksi ditolak oleh penyedia pembayaran atau Fraud Detection System midtrans.
Metode pembayaran lainnya: Gagal. Request berhasil tapi transaksi ditolak penyedia pembayaran.

Kode 3xx

Status Keterangan
300 Pindah permanen. Semua request, baik yang ada saat ini maupun yang akan datang, harus dialihkan ke URL baru.

Kode 4xx

Status Keterangan
400 Validasi error. Anda mengirim contoh request data yang salah; validasi error, kesalahan tipe transaksi, kesalahan format kartu kredit, dll.
401 Akses ditolak karena transaksi tidak sah, harap periksa client key atau server key.
402 Anda tidak memiliki akses untuk metode pembayaran ini.
403 Sumber yang diminta hanya mampu memberikan konten yang sesuai dengan accept header yang dikirim di HTTP request.
404 Sumber yang diminta tidak dapat ditemukan.
405 Metode HTTP tidak diizinkan.
406 Order ID sama. Order ID sudah digunakan sebelumnya.
407 Transaksi telah lewat dari masa berlaku.
408 Merchant mengirimkan tipe data yang salah.
409 Merchant sudah mengirimkan terlalu banyak transaksi dengan nomor kartu yang sama.
410 Akun Anda sudah dinonaktifkan. Silahkan hubungi midtrans Support.
411 Token ID tidak ada, salah, atau expired.
412 Merchant tidak bisa memodifikasi status transaksi.
413 Request tidak bisa diproses dikarenakan kesalahan syntax pada request body.

Kode 5xx

Status Keterangan
500 Server Internal Error.
501 Fitur akan segera tersedia.
502 Server Internal Error: Masalah Koneksi Bank
503 Server Internal Error
504 Server Internal Error: Deteksi Fraud tidak tersedia

Kredensial Testing Pembayaran

Berikut adalah daftar testing pembayaran yang dapat digunakan di Sandbox Environment.

Kartu Kredit

Kartu Umum

Transaksi Normal

VISA Description
Tidak ada Authentikasi
Merchant nonaktifkan 3DS
Transaksi Berhasil: 4011 1111 1111 1112
Transaksi Challenge oleh FDS: 4111 1111 1111 1111
Transaksi Gagal oleh FDS: 4211 1111 1111 1110
Transaksi Gagal oleh Bank: 4311 1111 1111 1119
MASTERCARD Description
Tidak ada Authentikasi
Merchant nonaktifkan 3DS
Transaksi Berhasil: 5481 1611 1111 1081
Transaksi Challenge oleh FDS: 5110 1111 1111 1119
Transaksi Gagal oleh FDS: 5210 1111 1111 1118
Transaksi Gagal oleh Bank: 5310 1111 1111 1117

Transaksi 3D Secure

VISA Description
Authentikasi Penuh
Pemegang kartu terdaftar 3DS
Transaksi Berhasil: 4811 1111 1111 1114
Transaksi Gagal oleh Bank: 4911 1111 1111 1113
Authentikasi Sebagian
Pemegang kartu tidak
terdaftar 3DS
Transaksi Berhasil: 4411 1111 1111 1118
Transaksi Challenge oleh FDS: 4511 1111 1111 1117
Transaksi Gagal oleh FDS: 4611 1111 1111 1116
Transaksi Gagal oleh Bank: 4711 1111 1111 1115
MASTERCARD Description
Authentikasi Penuh
Pemegang kartu terdaftar 3DS
Transaksi Berhasil: 5211 1111 1111 1117
Transaksi Gagal oleh Bank: 5111 1111 1111 1118
Authentikasi Sebagian
Pemegang kartu tidak
terdaftar 3DS
Transaksi Berhasil: 5410 1111 1111 1116
Transaksi Challenge oleh FDS: 5510 1111 1111 1115
Transaksi Gagal oleh FDS: 5411 1111 1111 1115
Transaksi Gagal oleh Bank: 5511 1111 1111 1114

Kartu Spesifik per Bank

Transaksi Berhasil

Bank Nomor Kartu
Mandiri 4617 0030 8177 8145 5573 3899 1384 3648
Mandiri Debit 4097 6658 2970 8136
CIMB 4599 2043 5516 9092 5481 1620 3830 7406
BNI 4105 0568 6475 0672 5264 2282 3919 2765
BNI Private Label 1946 4159 8148 7684
BCA 4773 7781 0290 6680 5229 9028 2076 4661
BRI 4365 0299 9362 0368 5520 0219 0920 3008
Maybank 4055 7796 2846 0474 5520 0883 1465 3770

Transaksi Berhasil dengan 3D Secure

Bank Nomor Kartu
Mandiri
Full Authentication

4617 0069 5974 6656

5573 3810 7219 6900
Attempted Authentication 4617 0017 4194 2101 5573 3819 9982 5417
CIMB
Full Authentication

4599 2078 8712 2414

5481 1698 1883 2479
Attempted Authentication 4599 2039 9705 2898 5481 1671 2103 2563
BNI
Full Authentication

4105 0586 8948 1467

5264 2210 3887 4659
Attempted Authentication 4105 0525 4151 2148 5264 2249 7176 1016
BCA
Full Authentication

4773 7760 5705 1650

5229 9031 3685 3172
Attempted Authentication 4773 7738 1098 1190 5229 9073 6430 3610
BRI
Full Authentication

4365 0263 3573 7199

5520 0298 7089 9100
Attempted Authentication 4365 0278 6723 2690 5520 0254 8646 8439
Maybank
Full Authentication

4055 7720 2603 6004

5520 0867 5210 2334
Attempted Authentication 4055 7713 3514 4012 5520 0867 7490 8452

Transaksi Gagal

Bank Nomor Kartu
Mandiri 4617 0085 6083 1760 5573 3840 4322 4447
Mandiri Debit 4097 6676 7217 8631
CIMB 4599 2060 0973 3090 5481 1691 9178 2739
BNI 4105 0541 4854 1363 5264 2235 3013 1711
BNI Private Label 1946 4102 7193 1269
BCA 4773 7752 0201 1809 5229 9034 0542 3830
BRI 4365 0286 6251 2583 5520 0219 0920 3008
Maybank 4055 7796 2846 0474 5520 0883 1465 3770

Expiry Date dan CVV

Input Nilai
Expiry Month 01
Expiry Year 2020
CVV 123

Bank Transfer

Metode Pembayaran Deskripsi
Permata Virtual Account Midtrans akan membuat 16 digit nomor testing Virtual Account Permata. Untuk melakukan tes transaksi, gunakan Permata Virtual Account Simulator
BCA Virtual Account Midtrans akan membuat 11 digit nomor testing Virtual Account BCA. Untuk melakukan tes transaksi, gunakan BCA Virtual Account Simulator
Mandiri Bill Payment Midtrans akan membuat 12 digit Kode Pembayaran untuk pembayaran via Mandiri e-channel (Internet Banking, SMS Banking, Mandiri ATM). Untuk melakukan tes transaksi, gunakan Mandiri Bill Payment Simulator

Direct Debit

Metode Pembayaran Deskripsi
Mandiri Clickpay Nomor kartu: 4111 1111 1111 1111
Token Berhasil: 000000
Token Gagal: 111111
CIMB Clicks midtrans akan mengalihkan tes transaksi CIMB Clicks ke simulasi pembayaran.
Transaksi Sukses: testuser00
Transaksi Gagal: testuser01
ePay BRI midtrans akan mengalihkan tes transaksi ePay BRI ke simulasi pembayaran.
Transaksi Sukses: testuser00
Transaksi Gagal: testuser03
BCA Klikpay midtrans akan mengalihkan tes transaksi BCA Klikpay ke simulasi pembayaran
KlikBCA midtrans akan mendaftarkan user id terisi di KlikBCA input. Untuk melakukan tes transaksi, gunakan KlikBca Simulator

e-Wallet

Metode Pembayaran Deskripsi
Telkomsel Cash Customer Berhasil: 0811111111
Customer Gagal: 0822222222
XL Tunai midtrans akan membuat Merchant Code dan Order ID testing untuk XL Tunai. Untuk melakukan tes transaksi, gunakan XL Tunai Simulator
Indosat Dompetku Nomor Berhasil: 08123456789
Nomor Gagal: other than 08123456789
Mandiri E-cash Nomor Berhasil: 0987654321
PIN: 12345
OTP: 12123434

Convenience Store

Metode Pembayaran Deskripsi
Indomaret midtrans akan membuat kode pembayaran Indomaret testing. Untuk melakukan tes transaksi, gunakan Indomaret Simulator
Kioson midtrans akan membuat kode pembayaran Kioson testing. Untuk melakukan tes transaksi, gunakan Kioson Simulator

Going Live

Tutorial berikut akan membantu anda melakukan perubahan konfigurasi dari Sandbox ke mode Production. Silahkan pilih metode integrasi yang digunakan. Apabila butuh bantuan, silahkan hubungi kami di support@midtrans.com atau kunjungi halaman support kami.

Jika Anda sudah selesai melakukan testing dan sudah siap untuk go live di Production Environment, ada beberapa hal yang perlu dipastikan:

Nilai Transaksi Minimum

Setiap transaksi memiliki nilai gross_amount minimum yaitu 10000.

PHP

<?php
include_once('Veritrans.php');

// Set our production server key
Veritrans_Config::$serverKey = '<your production server key>';

// Use production account
Veritrans_Config:$isProduction = true;
...

?>

Mengubah Veritrans-PHP library ke Production Environment. Ini dapat dilakukan dengan mengubah nilai Veritrans_Config::$serverKey dengan production server key dan Veritrans_Config::$isProduction menjadi true.

Magento

Mengubah pengaturan plugin magento dengan production client key dan server key dan mengubah environment menjadi production.

v1.9.x

magento set production

v2.x.x

magento set production

OpenCart

Ubah pengaturan plugin OpenCart dengan production client key dan server key dan ubah environment menjadi production.

magento set production

Prestashop

Ubah pengaturan plugin Prestashop Midtrans dengan production client key dan server key dan ubah environment menjadi production.

magento set production

Woocommerce

Ubah pengaturan plugin Woocomerce Midtrans dengan production client key dan server key dan ubah environment menjadi production.

magento set production