Direct Debit

Buat API

Fitur pembayaran e-commerce yang menghubungkan akun e-commerce Anda dengan kartu debit BRI sebagai Source of Fund (SoF) sehingga proses pembayaran transaksi berlangsung cepat dengan satu proses registrasi.

Informasi API

Judul

Direct Debit

Version

v1.0

URL Sandbox

https://sandbox.partner.api.bri.co.id/v1/directdebit

URL Production

https://partner.api.bri.co.id/v1/rt-directdebit/

Kendali Versi

Versi Dok

API Version

Date

Tautan Dokumen

Deskripsi
v1.0

v1.0

1 September 2018

Halaman ini

Versi Dasar.
v1.1

v1.0

1 Agustus 2020

Halaman ini

Menambahkan kode error 0924 Permintaan OTP telah mencapai maksimum
v1.2

v1.0

1 September 2020

Halaman ini

Beberapa perubahan 

  • Menambahkan spesifikasi opsional untuk callback notification charge dan refund
  • Menambahkan parameter callback_url pada charge dan refund (mandatory hanya untuk partner yang menggunakan callback notification)
v1.3

v1.0

8 Desember 2020

Halaman ini

Menambahkan kode error 0112 Exceed limit binding
v1.4

v1.0

20 Januari 2021

Halaman ini

Menambahkan kode error 4047 account is closed or frozen
v1.2

v1.0

21 September 2022

Buka Docs

-
v1.5

v1.0

7 Februari 2023

Halaman ini

Menambahkan catatan bahwa "OTP dan Notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp"

v1.6

v1.0

27 April 2023

Halaman ini

Mengubah deskripsi jumlah maksimum permintaan OTP menjadi 3 kali dalam Kode Respons 0924 pada 2 titik akhir di bawah : 

  • Buat Kartu Token (Binding) OTP
  • Buat Biaya Pembayaran OTP

v1.7

v1.0

03 Juli 2023

Halaman ini

Update mandatory untuk field exp_date dari O menjadi M pada endpoint Create Card Token (Binding) OTP

*Notes
 Perubahan ini berlaku mulai tanggal 14 Agustus 2023

Pengenalan Gambaran Produk

a. Binding Step

b. Payment Step

c. Refund Step

d. Payment Step with Callback

e. Refund Step with Callback

Standar (item yang berlaku untuk semua titik akhir)

  • Semua bidang waktu tanggal harus dalam format ISO 8601.

Ketentuan Tambahan

Partner yang memiliki lisensi PCI-DSS, card_pan dapat dikirimkan dalam format penuh (16 digit), jika tidak hanya dikirimkan 4 digit terakhir. 

Catatan: OTP dan Notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp.

A. Create Card Token (Binding) OTP

Penjelasan Endpoint

Binding API memverifikasi bahwa informasi yang diberikan oleh pengguna cocok dengan data bank. card_token yang diperoleh memiliki masa aktif satu tahun atau setelah masa berlaku kartu habis. Jika card_token telah kedaluwarsa, pengguna diharuskan binding lagi untuk mendapatkan card_token baru untuk melakukan transaksi.

Informasi Umum

HTTP Method

POST

Path

/v1/directdebit/tokens

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

Header Structure & Sample

Key

Value

Mandatory

Length

Deskripsi

Authorization

Bearer {token}

M

N/A

Access Token

BRI-Timestamp

  

M

-

ISO 8601 format

X-BRI-Signature

  

M

64

-

Content-Type

application/json

M

-

-

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
card_pan varchar M 16 4 digit terakhir nomor kartu atau 16 digit penuh untuk partner dengan lisensi PCI-DSS 5221123456789101 atau 1234
phone_number varchar M 15 nomor telepon terdaftar di bank 6289912345678
email varchar M 50 User email foo.bar@baz.com
exp_date varchar M 4 expired date dengan format MMYY.  0525
device_id varchar O 55 Device ID yang digunakan oleh pengguna untuk melakukan binding -
location JSON O - Lokasi saat pertama kali dilakukan binding {    "lat": "123",    "lon": "-123"  }
metadata JSON O - Merchant metadata Anda dapat mengisi bagian ini dengan data internal yang dipilih

Response Structure & Sample

Field

Data Type

Mandatory

Length

Deskripsi

 Contoh

registration_token

String

M

-

kode string untuk verifikasi OTP

TOK_CBF6XTIW

O4HKQ3LJ2QPAGW44

5LORLPF5

status

String

M

-

Value will be "PENDING_USER_

VERIFICATION" only

PENDING_USER_

VERIFICATION

Contoh Request :

curl -X POST 'https://sandbox.partner.api.bri.co.id/v1/directdebit/tokens' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body": {
        "card_pan": "1234567890123456",
        "phone_number": "6281234567890",
        "email":"foo.bar@baz.com"
    }
}'

Normal Response :

{
    "body": {
        "status": "PENDING_USER_VERIFICATION",
        "token": "TOK_CBF6XTIWO4HKQ3LJ2QPAGW445LORLPF5"
	}
}

Error Response :

{
    "error": {
        "code": "0104",
        "message": "Phone number not registered"
    },
    "status_code": 400,
    "recorded_at": "2021-02-10T11:07:28Z"
}

List of Error/Response Code

Http Status Code Status Code Status Message Deskripsi
200 - -

PENDING_USER
_VERIFICATION

 - Proses permintaan otp sukses diidentifikasi oleh token permintaan otp yang tidak kosong dan status = PENDING_USER_VERIFICATION
400 0101 400 - card number not found Permintaan binding gagal
400 0102 400 - the expired date is incorrect Permintaan binding gagal
400 0103 400 - card was expired Permintaan binding gagal
400 0104 400 - phone number not registered Permintaan binding gagal
400 0105 400 - card status not activated Permintaan binding gagal
400 0107 400 - Phone number is invalid Permintaan binding gagal
400 0108 400 - National Id Number not matched Permintaan binding gagal
400 0109 400 - Your card is blocked or disabled Permintaan binding gagal
400 0110 400 - Your card is already registered Permintaan binding gagal
400 0407 400 - account is closed or frozen Permintaan binding gagal
400 0112 400 - Exceed limit binding Percobaan binding maksimum adalah 5 kali. Lebih dari itu, akan mendapatkan error ini.
400 0924 400 - OTP requests have reached the maximum Permintaan otp maksimum. Setelah 5 kali permintaan otp tidak akan diverifikasi atau verifikasi gagal
400 0921 400 - Send OTP Failed Pengiriiman OTP gagal

B. Create Card Token (Binding) OTP Verify

Penjelasan Endpoint

Create Card Token (Binding) OTP Verify adalah endpoint untuk memverifikasi permintaan Binding OTP.

Catatan: OTP dan Notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp.

Informasi Umum

HTTP Method PATCH
Path /v1/directdebit/tokens
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Request Structure & Sample

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

registration_token

varchar

M

40

Kode string token OTP yang akan diverifikasi dengan passcode yang diperoleh pengguna

TOK_TKNCPPPHUVL3IJVA
XZI5GG4WBEC77YZ6

::ADVQ

passcode

int

M

6

Passcode yang telah dikirim ke pengguna

545195

Response Structure & Sample

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

status

varchar

M

4

mengidentifikasi bahwa proses binding berhasil

“0000”

phone_number

varchar

M

15

nomor telepon terdaftar di bank

6289912345678

last4

varchar

M

4

4 digit terakhir kartu

1234

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan pembayaran

-

card_token

Text

M

-

token untuk memvalidasi transaksi dan status binding Anda

card_.xxxx

email

varchar 

M

50

User email

foo.bar@baz.com

location

JSON

O

-

Lokasi saat pertama kali dilakukan binding

-

metadata

JSON

M

-

Merchant metadata

{
“refnum”:”123”

}

card_type

varchar

M

10

Ada 6 status card_type: PVRGLR, PVGOLD, PVPLAT, RGLR, GOLD, PLAT

-

Request Example :

  
curl -X PATCH 'https://sandbox.partner.api.bri.co.id/v1/directdebit/tokens' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body":{
        "registration_token": "TOK_TKNCPPPHUVL3IJVAXZI5GG4WBEC77YZ6::ADVQ",
        "passcode": "545195"
    }
}'

Normal Response :

{
  "body": {
    "status": "0000",
    "phone_number": "6289912345678",
    "device_id": "09864ADCASA",
    "card_token": "card_.eyJleHAiOjE2ODU0OTExOTksImlhdCI6MTU0MDE5NjUwMCwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOi
    JhMGM2MjlhNS1hYWI5LTQ5OWMtODg5MS0yNzA1NDg3NGRmYWUiLCJuYmYiOjE1NDAxOTY1MDEsInBhcnRuZXJJZCI6Iu-_vSIsInNlcnZp
    Y2VOYW1lIjoiRERfRVhURVJOQUxfU0VSVklDRSJ9.hceS_BQtzCIyMJCVMMvPWSfTvqIrW9TIL9arAUi95e-P6Kq9bvmQNuGLcfV6GLnQE
    c07fKF6IaLLkUquEm2iDfsP1HMLv_crXiF9snwzqzTk5vJqYvLmRGDqhZk-tFw-MwX0NW-op2iyRUhwSTB7rCNVOyfeIGfif7dKpu2PdFT
    98VUimnsKRWqHjARuCVKXweDbfKVpLHpgcR914MvSthqt4a7eHzUxm6o6eqyjQjf_vkQi4Fl_iG98JOVuzVuXft5P50QKcKwAhnrIiGMC-
      Vd4DZWQ1rMVbx1iSLvGzBrR1xm3wIYYlmyR0pUVlDdGaE04N1Gz_dvcsgx15Ecw",
    "location": {
      "lat": "",
      "lon": ""
    },
    "last4": "1234",
    "email": " foo.bar@baz.com",
    "metadata": {
      "example1": "example1"
    },
    "card_type": "PVRGLR",
    "limit_transaction": ""
  }
}
"body": { 
"status": "PENDING_USER_VERIFICATION", 
"token": "TOK_CBF6XTIWO4HKQ3LJ2QPAGW445LORLPF5" 
  }
}

Error Response :

{
  "error": {
    "code": "0918",
    "message": "Invalid Passcode"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T11:09:43Z"
}

List of Error/Response Code

Http Status

Code

Status Code

Status

Message

Deskripsi

200

-

-

0000

binding success

Sukses binding, status akan berisi 0000

400

0603

400

-

Expired Card Token

Binding Gagal

400

0918

400

-

Invalid Passcode

Binding Gagal

400

0919

400

-

Error Validate OTP Passcode

Binding Gagal

400

0920

400

-

Expired OTP

Binding Gagal

400

0922

400

-

Invalid OTP Token

Binding Gagal

400

0106

400

-

binding failed

Binding Gagal

C. Delete Card Token (Unbinding)

Penjelasan Endpoint

API unbinding digunakan untuk menghapus akun pengguna yang telah terdaftar sebelumnya.

Informasi Umum

HTTP Method Delete
Path /v1/directdebit/tokens
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
card_token Text M 40 token untuk memvalidasi transaksi dan binding status Anda card_.XXXXXX

Response Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
status varchar M 4 mengidentifikasi bahwa proses unbinding berhasil “0000”

Request and Response Payload Sample

Request :


curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1/directdebit/tokens' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body":{
        "card_token": "card_.eyJleHAiOjE1ODkzNDk2ODgsImlhdCI6MTU1NzcyNzI4OCwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiJhNTcxZDA3OC0xYmMyLTQ4NGUtOTQ2NC0yOGMzZmE2MWFhNGQiLCJwYXJ0bmVySWQiOiLvv70iLCJzZXJ2aWNlTmFtZSI6IkREX0VYVEVSTkFMX1NFUlZJQ0UifQ.EUOaGaCI6giha7GmRsycxMBrVXQgeF9cHfonXYZcT_3R3ykXw6PFOS9r32fMVP8al2lf26_Q6VIZ3sm71e7Sbd1KoigtGdcTPeJseSMMP190Ful_2DA2cRqhvN1dzJx-6keaG_AzLzo6sWMzuonQuR9tk-o5YMkGzfHJ-ZOS0zWvmN9lWRmvKlZPOBH_8Q430Yu5CeSjIF9ocfQQ6oguk_bXVRCX-4_u8WYISHrsatIeptBAADpQZktLpjBj0gXELwDed0PXQ4TeArcsUvj7d66hG8KPCuhCWa41JWnDxycqlJK_fldsnY0ewofkudSnSJzg5Nh0FILxl83bBPj4Pw"
    }
}'

Normal Response :

{
  "body": {
  "status": "0000"
  }
}

Error Response :

 
{
  "error": {
    "code": "0006",
    "message": "Invalid card token"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T11:11:10Z"
}

List of Error/Response Code

Http Status Code Status Code status Message Deskripsi
200 - - 0000 - Unbinding berhasil, status = 0000
400 0201 400 - unbinding was unsuccessful Unbinding gagal
400 0006 400 - Invalid card token card_token tidak ditemukan atau sudah di-unbinding

D. Retrieve Payment Charges & Refunds

Penjelasan Endpoint

Permintaan API ini digunakan untuk menampilkan semua status pembayaran yang telah dibuat.

* NOTE: :Normal case partner akan mendapatkan payment_id saat charge dan menggunakannya untuk inquiry transaksi, namun jika transaksi sudah timeout, partner bisa melakukan inquiry menggunakan Metadata atau Remarks. Partner diharapkan untuk memastikan bahwa nilai dalam Metadata atau Remarks unik karena akan digunakan untuk inquiry transaksi. Jika tidak, hasil inquiry akan mengembalikan data terakhir.

Informasi Umum

HTTP Method POST
Path /v1/directdebit/charges/inquiry
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
payment_id varchar M 15 payment_id dari payment API response  
metadata JSON M - Metadata untuk inquiry  
remarks varchar O 255 remarks sebagai penanda transaksi.  

Response Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

status

varchar

M

4

Kode 0000 menunjukkan bahwa inquiry berhasil diproses

0000

payment_id

varchar

M

15

payment_id dari API response payment

  

amount

number (2 Decimal Points)

M

-

Jumlah amount yang dibayarkan oleh pengguna. Contoh 20000.00

  

currency

varchar

M

3

kode ISO mata uang tiga huruf

IDR

payment_status

varchar

M

7

ada 3 status pembayaran pada inquiry: SUCCESS (untuk transaksi sukses), FAILED (untuk transaksi gagal), "" (kosong untuk status update gagal di database dan dapat ditandai sebagai transaksi gagal)

  

remarks

varchar

M

255

remarks sebagai penanda pembayaran. Contoh "ext989898"

  

refund_history

JSON

M

-

list array riwayat refund

  

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan payment charge

  

location

JSON

O

-

Lokasi payment charge dilakukan

  

metadata

JSON

O

-

Merchant metadata

  
*CATATAN: Gunakan "payment_status" untuk mengidentifikasi apakah pembayaran SUCCESS atau FAILED

Array Refund History

Field Data Type Mandatory Length Deskripsi Contoh

refund_id

varchar

M

4

refund_id dibuat setelah transaksi

  

amount

number (2 Decimal Points)

M

15

jumlah proses refund dana. Contoh 20000.00

  

currency

varchar

M

3

kode ISO tiga huruf untuk mata uang. Mata uang yang digunakan untuk refund

  

reason

varchar

M

255

remarks untuk refund

  

date

date

M

-

tanggal proses refund dana dalam format ISO-8601

  

status

varchar

M

7

ada 3 status refund dana pada inquiry: SUCCESS (untuk pengembalian dana yang berhasil), FAILED (untuk pengembalian dana yang gagal), "" (kosong untuk status pembaruan yang gagal di database dan dapat ditandai sebagai pengembalian dana yang gagal)

  

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan refund

  

location

JSON

O

-

Lokasi refund dilakukan

  

metadata

JSON

O

-

Merchant metadata

  
* CATATAN: Gunakan "status" untuk mengidentifikasi apakah pembayaran SUCCESS atau FAILED

Request and Response Payload

Request :

 
curl -X POST 'https://sandbox.partner.api.bri.co.id/v1/directdebit/charges/inquiry' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body" : {
        "payment_id": "657314642873",
        "remarks":"payment directlink",
        "metadata": {
            "trx_id": "0007654321"
        }
    }
  }'

Normal Response :

{
  "body": {
    "status": "0000",
    "amount": "50000.00",
    "currency": "IDR",
    "payment_id": "657314642873",
    "remarks_merchant": "payment directlink",
    "payment_status": "SUCCESS",
    "refund_history": [
      {
        "refund_id": "447343838470",
        "amount": "10000.00",
        "currency": "IDR",
        "reason": "incorrect stuff",
        "date": "2019-08-28T02:28:30.246199Z",
        "status": "SUCCESS",
        "device_id": "lg-lllll",
        "location": {
          "lat": "",
          "lon": ""
        },
        "metadata": {
          "trx_id_ref": "000012345000"
        }
      }
    ],
    "device_id": "lg-lllll",
    "location": {
      "lat": "",
      "lon": ""
    },
    "metadata": {
      "trx_id_pay": "0007654321"
    }
  }
}

Error Response :

{
  "error": {
    "code": "0301",
    "message": "Payment id not found"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T11:15:43Z"
}

List of Error/Response Code

Http Status Code Status Code Status Message Deskripsi
200 - - 0000 inquiry payment was success Proses inquiry berhasil mengembalikan data transaksi
400 0301 400 - payment_id not found Proses inquiry gagal atau transaksi masih dalam proses

E. Create Payment Charge OTP

Penjelasan Endpoint

API ini digunakan untuk pembayaran dari transaksi berdasarkan nomor kartu pada card_token yang diperoleh dari proses binding (pembuatan token kartu).

Pembayaran akan terhenti jika: 1. Mata uang yang digunakan untuk transaksi belum didukung. 2. Jumlah pembayaran melebihi batas kredit nasabah atau dana di rekening tidak cukup (ditentukan oleh bank). 3. Rekening atau kartu nasabah tidak lagi aktif. Untuk setiap kasus di atas, dana nasabah tidak boleh didebet.

Informasi Umum

HTTP Method POST
Path /v1/directdebit/charges
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -
Idempotency-Key Unique ID M - request unique id untuk mencegah duplikasi data pada saat yang sama

Request Structure & Sample

Field Data

Type

Mandatory

Length

Deskripsi

 Contoh

card_token

text

M

 

Token untuk memvalidasi transaksi dan status binding Anda

 

amount

number (2 Decimal Points)

M

 

Jumlah amount yang dibayarkan oleh pengguna. Contoh 20000.00

 

currency

varchar(3)

M

 

Kode ISO tiga huruf untuk mata uang. Mata uang akan digunakan untuk payment charge

 

remarks

varchar(255)

O

 

Remarks sebagai penanda pembayaran. Harus mengandung nilai unik jika digunakan untuk inquiry payment charge dan refund.

"ext123456"

device_id

varchar(55)

O

 

Device ID yang digunakan oleh pengguna untuk melakukan payment charge.

 

location

JSON

O

 

Lokasi pembayaran dilakukan

 

metadata

JSON

O

 

Merchant metadata. Harus mengandung nilai unik jika digunakan untuk inquiry payment charge dan refund.

 

otp_bri_status

varchar(3)

O

 

otp bri status untuk menandakan bahwa transaksi menggunakan OTP atau tidak. Jika YES maka akan menggunakan OTP, jika NO maka tidak menggunakan OTP. Secara default jika nilainya kosong maka akan menggunakan OTP. *CATATAN: jika otp_bri_status = NO maka akan langsung diproses transaksinya dengan response sukses dan daftar error code yang berbeda. Silahkan melihat ke contoh response dan daftar error atau response code.

 

callback_url

string

O

 

URL untuk mengirim callback notification. Wajib hanya jika partner menggunakan fitur callback. Jika tidak, tidak perlu.

 

Response Structure & Sample untuk yang memakai OTP

Field Data Type Mandatory Length Deskripsi Contoh
status varchar M 40 Pending User Verification  
charge_token varchar M 40 kode string untuk verifikasi OTP  

Response Structure & Sample untuk tanpa OTP

Field Data Type Mandatory Length Deskripsi Contoh

status

varchar

M

4

status proses transaksi

0000

payment_id

varchar

M

12

payment_id menghasilkan setelah transaksi

 

amount

number (2 Decimal Points)

M

-

Jumlah amount yang dibayarkan oleh pengguna.

20000.00

currency

varchar

M

3

Kode ISO tiga huruf untuk mata uang. Mata uang akan digunakan untuk payment charge payment_

 

payment_status

varchar

M

7

Nilainya akan SUCCESS untuk pembayaran yang berhasil. Jika pembayaran gagal, payment_status tidak akan dikembalikan (sistem akan mengembalikan kode error dan pesan error)

 

remarks

varchar

M

15

remarks sebagai penanda payment charge device_id varchar O 55 device ID yang digunakan oleh pengguna untuk melakukan payment charge

 

location

JSON

O

-

Lokasi payment charge dilakukan

 

metadata

JSON

O

-

Merchant metadata

 

code

varchar

M

4

Hanya berlaku untuk pembayaran gagal.

Error Code.

message

text

M

-

Hanya berlaku untuk pembayaran gagal.

Error Description.

status_code

varchar

M

3

Hanya berlaku untuk pembayaran gagal.

Status Code.

recorded_at

datetime

M

-

Hanya berlaku untuk pembayaran gagal.

Error Response Datetime.

Request and Response Payload :

Request :


curl -X POST 'https://sandbox.partner.api.bri.co.id/v1/directdebit/charges' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0.6434517166433735' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body":{
        "card_token":   "card_.eyJleHAiOjE1ODkzNTA4NDEsImlhdCI6MTU1NzcyODQ0MSwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiJlM2YzNTQxNC00MTc4LTRlYzgtYmY2Ny03MjI2MzkyNjY3YTciLCJwYXJ0bmVySWQiOiLvv70iLCJzZXJ2aWNlTmFtZSI6IkREX0VYVEVSTkFMX1NFUlZJQ0UifQ.PMuH4Fq9TkacFSQE2nwr-Dr7icRPlOOxYv2_XeoOjzidTm8dRwD9xy1lpvc_JJiUUQ_WFsL-o267BkL4tpnUWNxjA0ggnfsIsJQzZUSKtQYPozi7ZSLgV4VHOMqDJxBAFb-TeuNhN6obQBpsWBc4g3e0iOvEWKvk56AviR9Hs-CIQvqoYUEds8PgOyWCdbCnT76LLBzBWjML6JVXSMbtR-J3nDvE4ykq_ajDkgVeHbgFiTPiBtnsXVskbDGZMma1kVijr5GS4cxdqAq7xzYRnFpbVNHyxUrzVKYrGGgYoHM6K3-zM8wlhfHqssjyO86DyvdmfTF1398ZT-B8uv9zog",
        "amount":"25099.00",
        "currency":"IDR",
        "remarks":"Remakrs Merchant",
        "otp_bri_status": "YES",
        "metadata":{
            "trx_id":"12345687"
        }
     "callback_url": "http://(url_partner)/directdebit/notif/charges"
    }
}'

Normal Response Using OTP :

{
  "body": {
    "charge_token": "CHARGE_M3AVZN3LQSX5Q3YZSUHDLT7UAUMANZAP",
    "status": "PENDING_USER_VERIFICATION"
  }
}

Normal Response without OTP :

{
  "body": {
    "status": "0000",
    "payment_id": "175226995569",
    "amount": "20000.00",
    "currency": "IDR",
    "remarks": "payment",
    "device_id": "",
    "payment_status": "SUCCESS",
    "location": {
      "lat": "-6.21462",
      "lon": "106.84513"
    },
    "metadata": {
      "payment_id": "0984645728"
    }
  }
}

Error Response (applies to using OTP or without OTP) :

{
  "error": {
    "code": "0006",
    "message": "Invalid card token"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T11:11:10Z"
}

List of Error/Response Code untuk yang memakai OTP

Http Status Code Status Code Status Message Deskripsi

200

-

-

PENDING_USER_VERIFICATION

-

sukses diidentifikasi oleh otp token yang tidak kosong

400

0402

400

-

payment currency not supported

Permintaan Charge OTP gagal

400

0109

400

-

Your card is blocked or disabled

Permintaan Charge OTP gagal

400

0407

400

-

account is closed or frozen

Permintaan Charge OTP gagal

400

0111

400

-

Duplicate Idempotency Key

Permintaan Charge OTP gagal

400

0924

400

-

OTP requests have reached the maximum

Permintaan otp maksimum setelah 5 kali permintaan otp tidak diverifikasi atau verifikasi gagal

400

0921

400

-

Send OTP Failed

Gagal Mengirim Layanan OTP

400

0006

400

-

Invalid card token

Permintaan Charge OTP gagal

List of Error/Response Code untuk yang tanpa OTP

Http Status Code Status Code Status Message Deskripsi

200

-

-

0000

Payment success

transaksi telah diproses, payment charge berhasil ditunjukkan dengan payment_status = SUCCESS

400

0401

400

-

Over limit

Charge Gagal

400

0403

400

-

Charge payment failed

Charge Gagal

400

0404

400

-

Insufficient balance

Charge Gagal

400

0405

400

-

Account is frozen

Charge Gagal

400

0406

400

-

Account is closed

Charge Gagal

400

0407

400

-

Account is closed or frozen

Charge Gagal

400

0408

400

-

Account not found

Charge Gagal

400

0402

400

-

Payment currency not supported

Permintaan Charge OTP gagal

400

0109

400

-

Your card is blocked or disabled

Permintaan Charge OTP gagal

400

0111

400

-

Duplicate Idempotency Key

Permintaan Charge OTP gagal

400

0006

400

-

Invalid card token

Permintaan Charge OTP gagal

F. Create Payment Charge OTP Verify

Penjelasan Endpoint

API ini digunakan untuk memverifikasi Request OTP charge dari transaksi.

Catatan: OTP dan Notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp.

Informasi Umum

HTTP Method POST
Path /v1/directdebit/charges/verify
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
card_token Text M - token untuk memvalidasi transaksi dan status binding Anda card_token.xxxxx
charge_token varchar M 40 Kode string OTP yang akan diverifikasi dengan passcode yang diperoleh pengguna CHARGE_XXXXX
passcode int M 6 passcode yang telah dikirim ke pengguna 999999

Response Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

status

varchar

M

4

status proses transaksi

0000

payment_id

varchar

M

12

payment_id menghasilkan setelah transaksi

  

amount

number (2 Decimal Points)

M

-

Jumlah amount yang dibayarkan oleh pengguna. Contoh 20000.00

  

currency

varchar

M

3

Kode ISO tiga huruf untuk mata uang. Mata uang akan digunakan untuk payment charge

  

payment_status

varchar

M

7

Nilainya akan SUCCESS untuk pembayaran yang berhasil. Jika pembayaran gagal, payment_status tidak akan dikembalikan (sistem akan mengembalikan kode error dan pesan error)

  

remarks

varchar

M

15

remarks sebagai penanda payment charge

  

device_id

varchar

O

55

device ID yang digunakan oleh pengguna untuk melakukan payment charge

  

location

JSON

O

-

Lokasi payment charge dilakukan

  

metadata

JSON

O

-

Merchant metadata

  

code

varchar

M

4

Hanya berlaku untuk pembayaran gagal. Error Code.

  

message

text

M

-

Hanya berlaku untuk pembayaran gagal. Error Description.

  

status_code

varchar

M

3

Hanya berlaku untuk pembayaran gagal. Status Code.

  

recorded_at

datetime

M

-

Hanya berlaku untuk pembayaran gagal. Error Response Datetime.

  

Request and Response Payload :

Request :

  
curl -X POST 'https://sandbox.partner.api.bri.co.id/v1/directdebit/charges/verify' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
    "body":{
        "card_token": "card_.eyJleHAiOjE1ODk0MjE0MzcsImlhdCI6MTU1Nzc5OTAzNywiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiIxMGI4M2U2Yy0zMmUxLTQxNDctYjI5My01OTg5YWU3Nzk5NTYiLCJwYXJ0bmVySWQiOiLvv70iLCJzZXJ2aWNlTmFtZSI6IkREX0VYVEVSTkFMX1NFUlZJQ0UifQ.MAdArs3zmCsehnWcwhA5m-fwCUory6oudxVtmMS9dC7bXCnRjq91AwRxBADjWLu2S6Ra_RxRAnHU03_H8QJclvLad9L6P-pqZX_pRKDPOI1Y_i0xVYOfc8ea6B2so1aEuvFoOQNFMbGSsaLz4JO-OuJ6EYfoApTFSMIKOh__jkcxcXqpM1sO3ZlkquXKGpx_zf87boVPNY58KbIPWgzCC-6V2Vxpm4DPGunKkEwVMz4z12vTTbv3Ph9rc1Gf0jRXw8b8wo3k2ZeVGoHwiKbyJ_8J7FTVxkm3funDpcQtPzFzgBMPRgWWtfT7IOZddrVwsFt9FKLUKLHTVyiu5R4ZYw",
        "charge_token":  "CHARGE_XEHK6S4SNTBRSTCFBDB65W3GHQXBEFI4::De5g",
        "passcode":"210074"
    }
}'

Normal Response :

{
  "body": {
    "status": "0000",
    "payment_id": "175226995569",
    "amount": "20000.00",
    "currency": "IDR",
    "remarks": "payment",
    "device_id": "",
    "payment_status": "SUCCESS",
    "location": {
      "lat": "-6.21462",
      "lon": "106.84513"
    },
    "metadata": {
      "payment_id": "0984645728"
    }
  }
}

Error Response :

{
  "error": {
    "code": "0403",
    "message": "charge payment failed"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T05:36:27Z"
}

List of Error/Response Code

Http Status Code Status Code Status Message Deskripsi

200

-

-

0000

payment success

transaksi telah diproses, payment charge berhasil ditunjukkan dengan payment_status = SUCCESS

400

0918

400

-

Invalid Passcode

Charge Gagal

400

0919

400

-

Error Validate OTP Passcode

Charge Gagal

400

0920

400

-

Expired OTP

Charge Gagal

400

0922

400

-

Invalid OTP Token

Charge Gagal

400

0401

400

-

over limit

Charge Gagal

400

0403

400

-

charge payment failed

Charge Gagal

400

0404

400

-

insufficient balance

Charge Gagal

400

0405

400

-

account is frozen

Charge Gagal

400

0406

400

-

account is closed

Charge Gagal

400

0407

400

-

account is closed or frozen

Charge Gagal

400

0408

400

-

account not found

Charge Gagal

G. Create Payment Refund

Penjelasan Endpoint

API Refund digunakan untuk membuat permintaan pengembalian dana untuk pembayaran yang berhasil sebelumnya. Pengembalian dana dapat dilakukan dengan jumlah penuh atau sebagian.

Informasi Umum

HTTP Method POST
Path /v1/directdebit/refunds
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Authorization Bearer {token} M N/A Access Token
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -
Idempotency-Key Unique ID M - request unique id untuk mencegah duplikasi data pada saat yang sama

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

card_token

Text

O

-

token untuk memvalidasi transaksi dan status binding Anda

  

payment_id

varchar

M

12

payment_id dari respons API charge

  

amount

number (2 Decimal Points)

M

-

Jumlah amount proses refund. Contoh 20000.00

  

currency

varchar

M

3

mata uang yang digunakan untuk refund

  

reason

text

O

-

Alasan pengguna melakukan refund yang dijadikan remark. Harus mengandung nilai unik jika digunakan untuk inquiry payment charge dan refund.

  

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan refund

  

location

JSON

O

-

Lokasi refund dilakukan

  

metadata

JSON

O

-

Merchant metadata. Harus mengandung nilai unik jika digunakan untuk inquiry payment charge dan refund.

  

callback_url

string

O

  

URL untuk mengirim callback notification. Wajib hanya jika partner menggunakan fitur callback. Jika tidak, tidak perlu.

  

Response Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

status

varchar

M

4

status proses transaksi refund

0000

refund_id

varchar

M

12

Refund_id dihasilkan setelah transaksi refund sukses

  

payment_id

varchar

M

12

Payment_id untuk transaksi charge terkait

  

amount

number (2 Decimal Points)

M

-

Jumlah amount yang diproses refund. Contoh 20000.00

  

currency

varchar

M

3

Kode ISO tiga huruf untuk mata uang. Mata uang yang digunakan untuk refund ke pengguna

  

reason

varchar

O

15

reason sebagai remark refund

  

refund_status

varchar

M

6

Nilainya akan SUCCESS untuk pengembalian dana yang berhasil. Jika pengembalian dana gagal, refund_status tidak akan dikembalikan (sistem akan mengembalikan kode kesalahan dan pesan kesalahan)

  

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan refund

  

location

JSON

O

-

Lokasi refund dilakukan

  

metadata

JSON

O

-

Merchant metadata

  

Request and Response Payload :

Request :


curl -X POST 'https://sandbox.partner.api.bri.co.id/v1/directdebit/refunds' \
  -H 'Authorization: Bearer {{TOKEN}}' \
  -H 'BRI-Timestamp: 2019-05-14T02:25:06.379Z' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 0.6434517166433735' \
  -H 'X-BRI-Signature: {{SIGNATURE}}' \
  -d '{
  "body": {
    "card_token": "card_.eyJleHAiOjE1ODMzOTM4OTIsImlhdCI6MTU1MTc3MTQ5MiwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiIyNWQ4MWZmNy04NmY3LTQ5NWItYWUwNi04MTQ1ZGRlMTI1MmMiLCJwYXJ0bmVySWQiOiLvv70iLCJzZXJ2aWNlTmFtZSI6IkREX0VYVEVSTkFMX1NFUlZJQ0UifQ.tVaYUv8VZSbAr6_wQCDCQuGiD_5malWPu33RCTM9l1N0cGHTLO5Czh6SYGxT4tfFLRAesfNB1qBKtPc0SA_bMHkJDsQ8E68KPDpoIEkh33BxHrStrordGy6-De9jDKleHmz1qos4h0ZeYT-vetBjWkhugOZgYQBRJDKT0z7GhRa5MtkK8X4yV2zXypZiDy_AZd7TJH9AvMt5zH6duyfLDtfqf5DmS6gnG5DwbwLPSYm7WlTJ8UTh94kZjdQW-t-UEVHfatNyitayQmZVwRkWwz-TyUABzZWgRluu4Hfsp_jTydYr_yEhv0TE-CFCgP7RmDNJEqpQ2q4DXFtD3i3oOg",
    "amount":"500.00",
    "payment_id": "989453118305",
    "currency": "IDR",
    "reason": "PARTNERREFUND",
    "metadata": {
            "trx_id": "12345687"
        }
    "callback_url": "http://(url_partner)/directdebit/notif/refunds"
    }
}'

Normal Response :

 
{
  "body": {
    "status": "0000",
    "refund_id": "6218763823",
    "payment_id": "89937492374",
    "amount": "20000.00",
    "currency": "IDR",
    "reason": "incorrect stuff",
    "refund_status": "SUCCESS",
    "device_id": "lg-lllll",
    "location": {
      "lat": "-6.21462",
      "lon": "106.84513"
    },
    "metadata": {
      "example1": "example1"
    }
  }
}

Error Response :

{
  "error": {
    "code": "0504",
    "message": "refund payment failed to get payment id"
  },
  "status_code": 400,
  "recorded_at": "2021-02-10T11:22:03Z"
}

List of Error/Response Code

Http Status Code Status Code Status Message Deskripsi

200

-

-

0000

transaction processed

refund telah diproses, refund berhasil ditunjukkan dengan refund_status = SUCCESS

400

0501

400

-

refund currency not supported

Refund gagal

400

0502

400

-

refund amount is greater than paid amount

Refund gagal

400

0503

400

-

refund payment failed

Refund gagal

400

0405

400

-

account is frozen

Refund gagal

400

0406

400

-

account is closed

Refund gagal

400

0408

400

-

account not found

Refund gagal

400

0404

400

-

insufficient balance

Refund gagal

H. Callback API Direct Debit Charges

Penjelasan Endpoint

Callback API untuk mengirim pemberitahuan dari charge.

*CATATAN: Transaksi berhasil jika parameter status = 0000 dan parameter payment_status = SUCCESS, sedangkan transaksi gagal jika parameter status = 0000 dan parameter payment_status = FAILED

Informasi Umum

HTTP Method POST
Path /directdebit/notif/charges
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Merchant-Key {client_id} M N/A Menggunakan client_id dari developers.bri.co.id
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Contoh payload signature:

path=/directdebit/notif/refunds&verb=POST&token={{Merchant-Key}}&timestamp=2019-01-02T13:14:15.678Z&body={{Body Payload}}

Data payload dienkripsi dengan algoritma SHA256-HMAC menggunakan client_secret Anda. Signature dibentuk oleh payload yang sudah ditentukan. Hasil signature kemudian di- encode dengan Base64 dan diisi ke dalam header permintaan API X-BRI-Signature.

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

status

Text

M

-

status pengiriman callback, jika partner berhasil menerima callback, nilainya akan selalu '0000'

0000

payment_id

varchar

M

12

payment_id dari respon API charge

12345678901

amount

number (2 Decimal Points)

M

-

Jumlah proses amount transaksi

20000.00

currency

varchar

M

3

mata uang yang digunakan untuk pembayaran

IDR

remarks

text

O

-

Remarks sebagai penanda pembayaran

trx_123456

device_id

varchar

O

55

Device ID yang digunakan oleh pengguna untuk melakukan pembayaran

1234567

location

JSON

O

-

Lokasi payment dilakukan

{
"lon":"",
"lat":""
}

metadata

JSON

O

-

Merchant metadata

{
"trx_id:"123456"
}

payment_status

string

M

  

Mengindikasikan status payment (FAILED / SUCCESS)

SUCCESS

Response Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh
response_code varchar M 4 kode proses transaksi merujuk tabel di bawah ini
response_description varchar M 40 deskripsi kode merujuk tabel di bawah ini

Request and Response Payload :

Request :


curl --location --request POST '{{url}}/directdebit/notif/charges' \
  --header 'X-BRI-Signature: PkP3lY+lCxxF4zoMwnKpPZs3Zn0kvl5HawRwzrFzBkQ=' \
  --header 'BRI-Timestamp: 2021-01-26T09:59:03.884Z' \
  --header 'Content-Type: application/json' \
  --header 'Merchant-Key: k8IkLp5ndDZz3zCgZpwdtQ' \
  --data-raw '{
    "body": {
      "status": "0000",
      "payment_id": "950414364491",
      "amount": "1000.00",
      "currency": "IDR",
      "remarks": "testing",
      "device_id": "",
      "payment_status": "SUCCESS",
      "location": {
        "lat": "",
        "lon": ""
      },
      "metadata": {
        "trx_id": "12345687"
      },
      "limit_transaction": "-"
    }
  }'

Response :

{
  "response_code": "0000",
  "response_description": "success",
}

List of Error/Response Code

Http Code Response Code Response Description
200 0000 notification send
400 1010 notification failed

I. Callback API Direct Debit Refunds

Penjelasan Endpoint

Callback API untuk mengirimkan pemberitahuan dari refund

*CATATAN: Refund berhasil jika parameter status = 0000 dan parameter refund_status = SUCCESS, sedangkan refund gagal jika parameter status = 0000 dan parameter refund_status = FAILED

Informasi Umum

HTTP Method POST
Path /directdebit/notif/refunds
Tipe Format JSON
Authentication OAuth 2.0 with Access Token

Header Structure & Sample

Key Value Mandatory Length Deskripsi
Merchant-Key {client_id} M N/A Menggunakan client_id dari developers.bri.co.id
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Contoh payload signature:

path=/directdebit/notif/refunds&verb=POST&token={{Merchant-Key}}&timestamp=2019-01-02T13:14:15.678Z&body={{Body Payload}}

Data payload dienkripsi dengan algoritma SHA256-HMAC menggunakan client_secret Anda. Signature dibentuk oleh payload yang sudah ditentukan. Hasil signature kemudian di- encode dengan Base64 dan diisi ke dalam header permintaan API X-BRI-Signature.

Request Structure & Sample

Field Data Type Mandatory Length Deskripsi Contoh

status

Text

M

-

status pengiriman callback, jika partner berhasil menerima panggilan balik, nilainya akan selalu '0000'

'0000'

payment_id

varchar

M

12

Payment_id untuk transaksi charge terkait

12345678901

refund_id

varchar

M

12

Refund_id dihasilkan setelah transaksi refund sukses

12345678901

amount

number (2 Decimal Points)

M

-

Jumlah amount yang diproses refund

20000.00

currency

varchar

M

3

mata uang yang digunakan untuk refund

IDR

reason

text

N

-

reason sebagai remark refund

trx_123456

device_id

varchar

N

55

Device ID yang digunakan oleh pengguna untuk melakukan pembayaran

123456

location

JSON

N

-

Lokasi refund dilakukan

{
"lon":"",
"lat":""
}

metadata

JSON

N

-

Merchant metadata

{
"trx_id:"123456"
}

refund_status

string

M

  

Mengindikasikan status refund (FAILED / SUCCESS)

  

Request and Response Payload :

Field Data Type Mandatory Length Deskripsi Contoh
response_code varchar M 4 kode proses transaksi merujuk tabel di bawah ini
response_description varchar M 40 deskripsi kode merujuk tabel di bawah ini

List of Error/Response Code

Http Code

Response Code

Response Description

200

0000

notification send

400

1010

notification failed

Request and Response Payload

Request :

 
curl --location -g --request POST '{{url}}/directdebit/notif/refunds' \
  --header 'X-BRI-Signature: PkP3lY+lCxxF4zoMwnKpPZs3Zn0kvl5HawRwzrFzBkQ=' \
  --header 'BRI-Timestamp: 2021-01-26T09:59:03.884Z' \
  --header 'Content-Type: application/json' \
  --header 'Merchant-Key: k8IkLp5ndDZz3zCgZpwdtQ' \
  --data-raw '{
    "body": {
      "status": "0000",
      "refund_id": "6218763823",
      "payment_id": "89937492374",
      "amount": "20000.00",
      "currency": "IDR",
      "reason": "incorrect stuff",
      "refund_status": "SUCCESS",
      "device_id": "lg-lllll",
      "location": {
        "lat": "-6.21462",
        "lon": "106.84513"
      },
      "metadata": {
        "example1": "example1"
      }
    }
  }'

Response :

{
  "response_code": "0000",
  "response_description": "success",      
}

Common Error

Http Code Response Code Message Deskripsi
400 0001 Wrong message format Invalid input format
400 0003 Invalid BRI API Key Ada masalah intermitent pada koneksi ke database dalam sistem BRI
400 0006 Invalid Card Token  
400 0009 Missing Card Pan  
401 0601 Invalid Token  
401 0602 Invalid Signature