API Direct Debit
API Direct Debit
- Version Control
|
API Version |
Date |
Link to document |
Description |
|
v1 |
1 September 2018 |
this pages |
Baselin version. |
|
v1 |
1 Agustus 2020 |
this pages |
Added error code 0924 OTP requests have reached the maximum |
|
v1 |
1 September 2020 |
this pages |
Added optional callback notification specifications for charge and refund Added callback_url parameter on charge and refund (mandatory only for partner use callback notification) |
|
v1 |
8 Desember 2020 |
this pages |
Added error code 0112 Exceed limit binding |
|
v1 |
20 Januari 2021 |
this pages |
Added error code 0407 account is closed or frozen |
- Version Control
Enhancements
Added callback notification specifications for charge and refund
- Version Control
Introduction Part
The e Commerce payment feature that connects your e Commerce account with the BRI debit card as a Source of Fund (SoF) so that the transaction payment process takes place quickly with one registration process.
Flow API (actor interaction)
Sequence Diagram
-
- Binding Step
-
- Payment Step
-
- Refund Step
-
- Payment Step with Callback
-
- Refund Step with Callback
Standards (items that applicable for all endpoint)
- All field date time must be in ISO 8601 format.>
Additional Requirement
Partners who have a PCI-DSS license, card_number can be submitted in full format (16 digits), otherwise submitted only last 4 digits.
Endpoint
- Endpoint
Create Card Token (Binding) OTP
Endpoint explanation
The Bind API verifies that the information provided by the user matches the bank data. Card token which are obtained have an active period of one year or following the card expire date period. If the card token has expired, the user is required to bind again to get a new card token in order to make transactions.
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 |
aplication/json |
M |
- |
- |
Request Structure Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
card_pan |
varchar |
M |
16 |
last 4 digits of card number OR full 16 digits for partner with PCI-DSS license |
5221843000100021 or 0021 |
|
phone_number |
varchar |
M |
15 |
registered phone number on bank account. |
085736330909 |
|
|
varchar |
M |
50 |
User email |
|
|
exp_date |
varchar |
O |
4 |
expired date with format MMYY. |
0525 |
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
- |
|
location |
JSON |
O |
- |
The location when the token firstly binds |
{ "lat": "123", "lon": "-123" } |
|
metadata |
JSON |
O |
- |
Merchant metadata |
You can fill in this section with selected internal data |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
registration_token |
String |
M |
- |
String code for verification OTP |
TOK_CBF6XTIWO4HKQ3LJ2QPAGW445LORLPF5 |
|
status |
String |
M |
- |
Value will be "PENDING_USER_VERIFICATION" only |
PENDING_USER_VERIFICATION |
Request and Response Payload Sample
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"
}
}'
<?php
// PHP
?
// swift
// java
//ruby
// python
// c++
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 |
- |
success is identified by a non-empty registration token otp request and status = PENDING_USER_VERIFICATION |
|
400 |
0101 |
400 |
- |
card number not found |
Failed Binding Request |
|
400 |
0102 |
400 |
- |
the expired date is incorrect |
Failed Binding Request |
|
400 |
0103 |
400 |
- |
card was expired |
Failed Binding Request |
|
400 |
0104 |
400 |
- |
phone number not registered |
Failed Binding Request |
|
400 |
0105 |
400 |
- |
card status not activated |
Failed Binding Request |
|
400 |
0107 |
400 |
- |
Phone number is invalid |
Failed Binding Request |
|
400 |
0108 |
400 |
- |
National Id Number not matched |
Failed Binding Request |
|
400 |
0109 |
400 |
- |
Your card is blocked or disabled |
Failed Binding Request |
|
400 |
0110 |
400 |
- |
Your card is already registered |
Failed Binding Request |
|
400 |
0407 |
400 |
- |
account is closed or frozen |
Failed Binding Request |
|
400 |
0112 |
400 |
- |
Exceed limit binding |
Maximum trial binding is 5 times. More than that, will get this error. |
|
400 |
0924 |
400 |
- |
OTP requests have reached the maximum |
Maximum otp request. After 5 times the otp request will not verified or failed verification |
|
400 |
0921 |
400 |
- |
Send OTP Failed |
Failed Send OTP Service |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Create Card Token (Binding) OTP Verify
Create Card Token (Binding) OTP Verify
Endpoint explanation
Create Card Token (Binding) OTP Verify is the endpoint for verifying OTP binding requests.
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 |
OTP string code that is to be verified with the passcode obtained by the user |
TOK_TKNCPPPHUVL3IJVAXZI5GG4WBEC77YZ6::ADVQ |
|
passcode |
int |
M |
6 |
passcode that has been sent to the user |
545195 |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
4 |
identify that the binding process was successful |
“0000” |
|
phone_number |
varchar |
M |
15 |
registered phone number on bank account. |
6281225088578 |
|
last4 |
varchar |
M |
4 |
Last 4 digit cards |
5566 |
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
- |
|
card_token |
Text |
M |
- |
token for validating your transaction and binding status |
card_.xxxx |
|
|
varchar |
M |
50 |
User email |
|
|
location |
JSON |
O |
- |
The location when the token firstly binds |
- |
|
metadata |
JSON |
M |
- |
Merchant metadata |
{ } |
|
card_type |
varchar |
M |
10 |
There are 6 card_type status: PVRGLR, PVGOLD, PVPLAT, RGLR, GOLD, PLAT |
- |
Request and Response Payload Sample
|
Request: -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 |
Success binding, status will be 0000 |
|
400 |
0603 |
400 |
- |
Expired Card Token |
Binding Failed |
|
400 |
0918 |
400 |
- |
Invalid Passcode |
Binding Failed |
|
400 |
0919 |
400 |
- |
Error Validate OTP Passcode |
Binding Failed |
|
400 |
0920 |
400 |
- |
Expired OTP |
Binding Failed |
|
400 |
0922 |
400 |
- |
Invalid OTP Token |
Binding Failed |
|
400 |
0106 |
400 |
- |
binding failed |
Binding Failed |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Delete Card Token (Unbinding)
Delete Card Token (Unbinding)
Endpoint explanation
The unbinding API is used to delete user account that has been previously registered.
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 for validating your transaction and binding status |
card_.XXXXXX |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
4 |
identify that the unbinding process was successful |
“0000” |
Request and Response Payload Sample
|
Request: -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 was successful, status = 0000 |
|
400 |
0201 |
400 |
- |
unbinding was unsuccessful |
unbinding Failed |
|
400 |
0006 |
400 |
- |
Invalid card token |
card token not found or already unbinded |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Retrieve Payment Charges Refunds
Retrieve Payment Charges & Refunds
Endpoint explanation
This API request is used to display all payment statuses that have been made.
*NOTE: Normal case partner will get payment_id when charge and use it to retrieve the transaction, but if transaction is timeout, partner can make inquiry using Metadata or Remarks. Partners are expected to ensure that the value in Metadata or Remarks is unique since it will be used for transaction inquiry. If not, the inquiry result will return the last data.
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 from payment API response |
|
|
metadata |
JSON |
M |
- |
Metadata object to be queried |
|
|
remarks |
varchar |
O |
255 |
remarks as payment markers. |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
4 |
Code 0000 indicates that the inquiry was successfully processed |
0000 |
|
payment_id |
varchar |
M |
15 |
payment_id from payment API response |
|
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of the bill paid by the user. Example 20000.00 |
|
|
currency |
varchar |
M |
3 |
Three-letter currency ISO code |
IDR |
|
payment_status |
varchar |
M |
7 |
there are 3 payment status on inquiry : SUCCESS (for successful transaction), FAILED (for failed transaction), ""(empty for failed update status on database and can flag as failed transaction) |
|
|
remarks |
varchar |
M |
255 |
remarks as payment markers. Example "payment directlink" |
|
|
refund_history |
JSON |
M |
- |
array refund history |
|
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
|
|
location |
JSON |
O |
- |
The charge payment location is performed |
|
|
metadata |
JSON |
O |
- |
Merchant metadata |
*NOTE: Please use "payment_status" to identify whether the payment is SUCCESS or FAILED
Array Refund History
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
refund_id |
varchar |
M |
4 |
refund_id generated after transaction |
|
|
amount |
number (2 Decimal Points) |
M |
15 |
The amount of refund process. Example 20000.00 |
|
|
currency |
varchar |
M |
3 |
Three-letter ISO code for the currency. Currency used for payment |
|
|
reason |
varchar |
M |
255 |
reason refund |
|
|
refund_date |
date |
M |
- |
date refund process ISO-8601 format |
|
|
status |
varchar |
M |
7 |
there are 3 refund status on inquiry : SUCCESS (for successful refund), FAILED (for failed refund), ""(empty for failed update status on database and can flag as failed refund) |
|
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
|
|
location |
JSON |
O |
- |
The refund payment location is performed |
|
|
metadata |
JSON |
O |
- |
Merchant metadata |
*NOTE: Please use "status" to identify whether the payment is SUCCESS or FAILED
Request and Response Payload Sample
|
Request: -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: "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 |
Description |
|
200 |
- |
- |
0000 |
inquiry payment was success |
the inquiry process is success to return transaction data |
|
400 |
0301 |
400 |
- |
payment_id not found |
the inquiry process failed or transaction still on process |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Create Payment Charge OTP
Create Payment Charge OTP
Endpoint explanation
This API is used for payments from transactions with direct links based on the card number on card_token obtained from the binding process (card token creation).
Payment will be interrupted when: 1. The currency used for the transaction is not yet supported. 2. The payment amount exceeds the customer's credit limit or there is not enough funds in the account (determined by the bank). 3. The customer's account or card is no longer active. For each of the above cases, customer funds should not be debited.
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 |
- |
unique id request for preventing duplicate requests at the same time |
Request Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
card_token |
Text |
M |
token for validating your transaction and binding status |
||
|
amount |
number (2 Decimal Points) |
M |
The amount of the bill paid by the user. Example 20000.00 |
||
|
currency |
varchar(3) |
M |
Three-letter ISO code for the currency. Currency will be used for charge payment |
||
|
remarks |
varchar(255) |
O |
remarks as payment markers. Should contain unique value if it is used to inquiry payment. Example "ext123456" |
||
|
device_id |
varchar(55) |
O |
The device ID used by the user to make a payment |
||
|
location |
JSON |
O |
The charge payment location is performed |
||
|
metadata |
JSON |
O |
Merchant metadata. Should contain unique value if it is used to inquiry payment. |
||
|
otp_bri_status |
varchar(3) |
O |
otp bri status for flags that transaction uses OTP or not. If YES then will use OTP, if NO then do not use OTP. By default if the value is empty it will use OTP. |
||
|
callback_url |
string |
O |
Url to send notification callback. Mandatory only if partner uses callback feature. Otherwise, no needed. |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
40 |
Pending User Verification |
|
|
charge_token |
varchar |
M |
40 |
string code for verificaton OTP |
Request and Response Payload Sample
|
Request: -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: "body": { "charge_token": "CHARGE_M3AVZN3LQSX5Q3YZSUHDLT7UAUMANZAP", "status": "PENDING_USER_VERIFICATION" } }
|
|
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 |
- |
- |
PENDING_USER_VERIFICATION |
- |
success is identified by a non-empty charge token otp request |
|
400 |
0402 |
400 |
- |
payment currency not supported |
Failed |
|
400 |
0109 |
400 |
- |
Your card is blocked or disabled |
Failed |
|
400 |
0407 |
400 |
- |
account is closed or frozen |
Failed |
|
400 |
0111 |
400 |
- |
Duplicate Idempotency Key |
Failed |
|
400 |
0924 |
400 |
- |
OTP requests have reached the maximum |
Maximum otp request after 5 times the otp request is not verified or failed verification |
|
400 |
0921 |
400 |
- |
Send OTP Failed |
Failed Send OTP Service |
|
400 |
0006 |
400 |
- |
Invalid card token |
Failed |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Create Payment Charge OTP Verify
Create Payment Charge OTP Verify
Endpoint explanation
This API is used to verify OTP payments from transactions.
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 for validating your transaction and binding status |
card_token.xxxxx |
|
charge_token |
varchar |
M |
40 |
OTP string code that is to be verified with the passcode obtained by the user |
CHARGE_XXXXX |
|
passcode |
int |
M |
6 |
passcode that has been sent to the user |
999999 |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
4 |
status of process transaction |
0000 |
|
payment_id |
varchar |
M |
12 |
payment id generate after transaction |
|
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of the bill paid by the user. Example 20000.00 |
|
|
currency |
varchar |
M |
3 |
Three-letter ISO code for the currency. Currency will be used for charge payment |
|
|
payment_status |
varchar |
M |
7 |
The value will be SUCCESS for success payment. If payment is failed, payment_status will not be returned (the system will return error code and error message) |
|
|
remarks |
varchar |
M |
15 |
remarks as payment markers. |
|
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
|
|
location |
JSON |
O |
- |
The charge payment location is performed |
|
|
metadata |
JSON |
O |
- |
Merchant metadata. |
|
|
code |
varchar |
M |
4 |
Only applicable for payment failed. Error Code. |
|
|
message |
text |
M |
- |
Only applicable for payment failed. Error Description. |
|
|
status_code |
varchar |
M |
3 |
Only applicable for payment failed. Status Code. |
|
|
recorded_at |
datetime |
M |
- |
Only applicable for payment failed. Error Response Datetime. |
Request and Response Payload Sample
|
Request: -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: { |
List of Error/Response Code
|
Http Status |
Code |
Status Code |
Status |
Message |
Description |
|
200 |
- |
- |
0000 |
payment success |
transaction processed, success payment is indicated by the payment_status = SUCCESS |
|
400 |
0918 |
400 |
- |
Invalid Passcode |
failed |
|
400 |
0919 |
400 |
- |
Error Validate OTP Passcode |
failed |
|
400 |
0920 |
400 |
- |
Expired OTP |
failed |
|
400 |
0922 |
400 |
- |
Invalid OTP Token |
failed |
|
400 |
0401 |
400 |
- |
over limit |
failed |
|
400 |
0403 |
400 |
- |
charge payment failed |
failed |
|
400 |
0404 |
400 |
- |
insufficient balance |
failed |
|
400 |
0405 |
400 |
- |
account is frozen |
failed |
|
400 |
0406 |
400 |
- |
account is closed |
failed |
|
400 |
0407 |
400 |
- |
account is closed or frozen |
failed |
|
400 |
0408 |
400 |
- |
account not found |
failed |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Create Payment Refund
Create Payment Refund
Endpoint explanation
Refund API is used to make a refund request for a previous success payment. Refund can be done with full or partials amount.
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 for validating your transaction and binding status |
|
|
payment_id |
varchar |
M |
12 |
payment_id from payment API response |
|
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of refund process. Example 20000.00 |
|
|
currency |
varchar |
M |
3 |
currency used for payment |
|
|
reason |
text |
O |
- |
The reason users do refund. Should contain unique value if it is used to inquiry payment. |
|
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
|
|
location |
JSON |
O |
- |
The refund location is performed |
|
|
metadata |
JSON |
O |
- |
Merchant metadata. Should contain unique value if it is used to inquiry payment. |
|
|
callback_url |
string |
O |
url to send notification callback. Mandatory only if partner uses callback feature. Otherwise, no needed. |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
varchar |
M |
4 |
status of process transaction |
0000 |
|
refund_id |
varchar |
M |
12 |
refund_id generated after transaction |
|
|
payment_id |
varchar |
M |
12 |
payment_id from payment API response |
|
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of refund process. Example 20000.00 |
|
|
currency |
varchar |
M |
3 |
Three-letter ISO code for the currency. Currency used for user refund |
|
|
reason |
varchar |
O |
15 |
the reason users do refund |
|
|
refund_status |
varchar |
M |
6 |
The value will be SUCCESS for success refund. If refund is failed, refund_status will not be returned (the system will return error code and error message) |
|
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
|
|
location |
JSON |
O |
- |
The refund location is performed |
|
|
metadata |
JSON |
O |
- |
Merchant metadata |
Request and Response Payload Sample
|
Request: -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: "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 |
Description |
|
200 |
- |
- |
0000 |
transaction processed |
refund processed, success refund is indicated by the refund_status = SUCCESS |
|
400 |
0501 |
400 |
- |
refund currency not supported |
failed |
|
400 |
0502 |
400 |
- |
refund amount is greater than paid amount |
failed |
|
400 |
0503 |
400 |
- |
refund payment failed |
failed |
|
400 |
0405 |
400 |
- |
account is frozen |
failed |
|
400 |
0406 |
400 |
- |
account is closed |
failed |
|
400 |
0408 |
400 |
- |
account not found |
failed |
|
400 |
0404 |
400 |
- |
insufficient balance |
failed |
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Callback API Direct Debit Charges
Callback API Direct Debit Charges
Endpoint explanation
Callback API for send notification charges.
*NOTE: Transaction is successful if parameter status = 0000 and parameter payment_status = SUCCESS, while the transaction fails if parameter status = 0000 and 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 |
- |
- |
Example for signature payload:
path=/directdebit/notif/charges&verb=POST&token={{Merchant-Key}}×tamp=2019-01-02T13:14:15.678Z&body={{Body Payload}}
The payload data will be signed with SHA256-HMAC algorithm using your client_secret. The signature is formed by the specified payload. The signature value is then encoded with Base64 and filled into API requests header X-BRI-Signature.
Request Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
Text |
M |
- |
callback send status, if partner receives callback successfully the value will be always '0000' |
0000 |
|
payment_id |
varchar |
M |
12 |
payment_id from payment API response |
12345678901 |
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of refund process |
20000.00 |
|
currency |
varchar |
M |
3 |
currency used for payment |
IDR |
|
remarks |
text |
O |
- |
Remarks as payment markers |
trx_123456 |
|
device_id |
varchar |
O |
55 |
The device ID used by the user to make a payment |
1234567 |
|
location |
JSON |
O |
- |
The charge location is performed |
{ |
|
metadata |
JSON |
O |
- |
Merchant metadata |
{ |
|
payment_status |
string |
M |
Indicate the status of payment (FAILED / SUCCESS) |
SUCCESS |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
response_code |
varchar |
M |
4 |
code of process transaction |
refer to table below |
|
response_description |
varchar |
M |
40 |
description of code |
refer to table below |
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: "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: "response_code": "0000", "response_description": "success",
} |
|||||
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
Callback API Direct Debit Refunds
Callback API Direct Debit Refunds
Endpoint explanation
Callback API for send notification refunds
*NOTE: Refund is successful if parameter status = 0000 and parameter refund_status = SUCCESS, while refund fails if parameter status = 0000 and 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 |
use client_id from developers.bri.co.id |
|
BRI-Timestamp |
M |
- |
- |
|
|
X-BRI-Signature |
M |
64 |
- |
|
|
Content-Type |
application/json |
M |
- |
- |
Example for signature payload:
path=/directdebit/notif/refunds&verb=POST&token={{Merchant-Key}}×tamp=2019-01-02T13:14:15.678Z&body={{Body Payload}}
The payload data will be signed with SHA256-HMAC algorithm using your client_secret. The signature is formed by the specified payload. The signature value is then encoded with Base64 and filled into API requests header X-BRI-Signature.
Request Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
status |
Text |
M |
- |
callback send status, if partner receives callback successfully the value will be always '0000' |
'0000' |
|
payment_id |
varchar |
M |
12 |
Payment_id for related charge payment |
12345678901 |
|
refund_id |
varchar |
M |
12 |
Refund_id generate after refund transaction |
12345678901 |
|
amount |
number (2 Decimal Points) |
M |
- |
The amount of refund process |
20000.00 |
|
currency |
varchar |
M |
3 |
currency used for payment |
IDR |
|
reason |
text |
N |
- |
Reason as payment markers. |
trx_123456 |
|
device_id |
varchar |
N |
55 |
The device ID used by the user to make a payment |
123456 |
|
location |
JSON |
N |
- |
The refund location is performed |
{ |
|
metadata |
JSON |
N |
- |
Merchant metadata |
{ |
|
refund_status |
string |
M |
Indicate the status of refund (FAILED / SUCCESS) |
Response Structure & Sample
|
Field |
Data Type |
Mandatory |
Length |
Desc |
Example |
|
response_code |
varchar |
M |
4 |
code of process transaction |
refer to table below |
|
response_description |
varchar |
M |
40 |
description of code |
refer to table below |
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: "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 |
Description |
||
|
400 |
0001 |
Wrong message format |
format input invalid |
||
|
400 |
0003 |
Invalid BRI API Key |
there was a problem in the BRI system |
||
|
400 |
0006 |
Invalid card token |
|||
|
400 |
0009 |
Missing Card Pan |
|||
|
503 |
0503 |
- |
Failed |
Service Unavailable |
|
|
504 |
0504 |
- |
Failed |
Gateway Timeout |
|
