Direct Debit

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

Title

API Product Name

Version

v1

URL Sandbox

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

URL Production

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

 

Version History

API Version

Date

Link to document

Description

v1

1 September 2018

Halaman ini

Baseline version.

v1

1 Agustus 2020

Halaman ini

Menambahkan kode error 0924 Permintaan OTP telah mencapai maksimum

v1

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

8 Desember 2020

Halaman ini

Menambahkan kode error 0112 exceed limit binding

v1

20 Januari 2021

Halaman ini

Menambahkan kode error 0407 account is closed or frozen

Enhancements

Menambahkan spesifikasi callback notification untuk charge dan refund

 

API Flow

Actor Interaction

BRIAPI Flow API Direct Debit (Actor Interaction)

Binding Step

BRIAPI Flow API Direct Debit (Binding Step)

Payment Step

BRIAPI Flow API Direct Debit (Payment Step)

Refund Step

BRIAPI Flow API Direct Debit (Refund Step)

Payment Step with Callback

BRIAPI Flow API Direct Debit (Payment Step with Callback)

Refund Step with Callback

BRIAPI Flow API Direct Debit (Payment Step with Callback)

Ketentuan Tambahan

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

 

Create Card Token (Binding) OTP

Endpoint explanation

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.

General Information

HTTP Method

POST

Path

/v1/directdebit/tokens

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

Desc

Example

card_pan

varchar

M

16

4 digit terakhir nomor kartu atau 16 digit penuh untuk partner dengan lisensi PCI-DSS

5221843000100021 or 0021

phone_number

varchar

M

15

nomor telepon terdaftar di bank

085736330909

email

varchar

M

50

User email

test@email.com

exp_date

varchar

O

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

Desc

Example

registration_token

String

M

-

kode string untuk verifikasi OTP

TOK_CBF6XTIWO4HKQ3LJ2QPAGW445LORLPF5

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": "5221843000100021",
        "phone_number": "6285736330909",
        "email":"email"
    }
}'

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

Description

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

 

Create Card Token (Binding) OTP Verify

Endpoint explanation

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

General Information

HTTP Method

PATCH

Path

/v1/directdebit/tokens

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

Desc

Example

registration_token

varchar

M

40

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

TOK_TKNCPPPHUVL3IJVAXZI5GG4WBEC77YZ6::ADVQ

passcode

int

M

6

Passcode yang telah dikirim ke pengguna

545195

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Desc

Example

status

varchar

M

4

mengidentifikasi bahwa proses binding berhasil

“0000”

phone_number

varchar

M

15

nomor telepon terdaftar di bank

6281225088578

last4

varchar

M

4

4 digit terakhir kartu

5566

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

test@gmail.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

-

 

Contoh Request

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": "6285641403241",
        "device_id": "09864ADCASA",
        "card_token": "card_.eyJleHAiOjE2ODU0OTExOTksImlhdCI6MTU0MDE5NjUwMCwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiJhMGM2MjlhNS1hYWI5LTQ5OWMtODg5MS0yNzA1NDg3NGRmYWUiLCJuYmYiOjE1NDAxOTY1MDEsInBhcnRuZXJJZCI6Iu-_vSIsInNlcnZpY2VOYW1lIjoiRERfRVhURVJOQUxfU0VSVklDRSJ9.hceS_BQtzCIyMJCVMMvPWSfTvqIrW9TIL9arAUi95e-P6Kq9bvmQNuGLcfV6GLnQEc07fKF6IbaLLkUquEm2iDfsP1HMLv_crXiF9snwzqzTk5vJqYvLmRGDqhZk-tFw-MwX0NW-op2iyRUhwSTB7rCNVOyfeIGfif7dKpu2PdFT98VUimnsKRWqHjAR7uCVKXweDbfKVpLHpgcR914MvSthqt4a7eHzUxm6o6eqyjQjf_vkQi4Fl_iG98JOVuzVuXft5P50QKcKwAhnrIiGMC-Vd4DZWQ1rMVbx1iSLvGzBrR1xm3wIYYlmyR0pUVlDdGaE04N1Gz_dvcsgx15Ecw",
        "location": {
            "lat": "",
            "lon": ""
        },
        "last4": "1198",
        "email": "test@test.com",
        "metadata": {
            "example1": "example1"
        },
        "card_type": "PVRGLR",
        "limit_transaction": ""
    }
}

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

Description

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

 

Delete Card Token (Unbinding)

Endpoint explanation

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

General Information

HTTP Method

DELETE

Path

/v1/directdebit/tokens

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

Desc

Example

card_token

Text

M

40

token untuk memvalidasi transaksi dan binding status Anda

card_.XXXXXX

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Desc

Example

status

varchar

M

4

mengidentifikasi bahwa proses unbinding berhasil

“0000”

 

Request and Response Payload Sample

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

Description

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

 

Retrieve Payment Charges & Refunds

Endpoint explanation

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.

General Information

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

Description

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

Desc

Example

payment_id

varchar

M

15

payment_id dari API response payment

 

metadata

JSON

M

-

Metadata untuk inquiry

 

remarks

varchar

O

255

remarks sebagai penanda transaksi

 

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Desc

Example

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

remakrs 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

Desc

Example

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

remaks 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 Sample

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_pay": "0007654321"
                    }
            }
      }'

Normal Response Sample

{
    "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 Sample

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

Description

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

 

Create Payment Charge OTP

Endpoint explanation

API ini digunakan untuk pembayaran dari transaksi berdasarkan nomor kartu pada card_token yang diperoleh dari proses bidning (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.

General Information

HTTP Method

POST

Path

/v1/directdebit/charges

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

Description

Example

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

Desc

Example

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

Desc

Example

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

remakrs 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 Sample

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 Sample yang Memakai OTP

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

Normal Response Sample yang Tanpa 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 Sample (berlaku untuk memakai OTP atau tanpa 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

Description

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

Description

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

 

Create Payment Charge OTP Verify

Endpoint explanation

API ini digunakan untuk memverifikasi Request OTP charge dari transaksi.

General Information

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

Description

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

Desc

Example

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

Desc

Example

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

remakrs 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 Sample

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 Sample

{
    "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 Sample

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

Description

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

 

Create Payment Refund

Endpoint explanation

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

General Information

HTTP Method

POST

Path

/v1/directdebit/refunds

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

-

unique id request for preventing duplicate requests at the same time

 

Request Structure & Sample

Field

Data Type

Mandatory

Length

Desc

Example

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

Desc

Example

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 Sample

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": "DANAREFUND",
    "metadata": {
            "trx_id": "12345687"
        }
    "callback_url": "http://(url_partner)/directdebit/notif/refunds"
    }
}'

Normal Response Sample

{
    "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 Sample

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

Description

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

 

Callback API Direct Debit Charges

Endpoint explanation

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

General Information

HTTP Method

POST

Path

/directdebit/notif/charges

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

Merchant-Key

{client_id}

M

N/A

use client_id from developers.bri.co.id

BRI-Timestamp

 

M

-

-

X-BRI-Signature

 

M

64

-

Content-Type

application/json

M

-

-

 

Contoh payload signature:

path=/directdebit/notif/charges&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

Desc

Example

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

Desc

Example

response_code

varchar

M

4

code of process transaction

merujuk tabel di bawah ini

response_description

varchar

M

40

description of code

merujuk tabel di bawah ini

 

List of Error/Response Code

Http Status

Response Code

Response Description

200

0000

notification send

400

1010

notification failed

 

Request and Response Payload Sample

Request Sample

{
    "body": {
        "status": "0000",
        "payment_id": "950414364491",
        "amount": "1000.00",
        "currency": "IDR",
        "remarks": "TESTFEN",
        "device_id": "",
        "payment_status": "SUCCESS",
        "location": {
            "lat": "",
            "lon": ""
        },
        "metadata": {
            "trx_id": "12345687"
        },
        "limit_transaction": "-"
    }
}

Response Sample

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

 

 

Callback API Direct Debit Refunds 

Endpoint explanation

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

General Information

HTTP Method

POST

Path

/directdebit/notif/refunds

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

 

Header Structure & Sample

Key

Value

Mandatory

Length

Description

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

Desc

Example

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)

 

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Desc

Example

response_code

varchar

M

4

code of process transaction

merujuk tabel di bawah ini

response_description

varchar

M

40

description of code

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 Sample

Request Sample

{
    "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 Sample

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

 

 

Common Errors

Http Code

Response Code

Message

Description

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