Direct Debit

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 is fast with one registration process.

API Information

Title

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/

Version Control

Doc Version

API Version

Date

Link to document

Description

v1.0

v1.0

1 September 2018

This page

Baseline version.

v1.0

v1.0

1 Agustus 2020

This page

Added error code 0924 OTP request has reached the maximum

v1.0

v1.0

1 September 2020

This page

Some changes 

  • Added optional specifications for callback notification charge and refund
  • Added callback_url parameter to charge and refund (mandatory only for partners using callback notifications)
v1.0

v1.0

8 Desember 2020

This page

Added error code 0112 exceed limit binding

v1.0

v1.0

20 Januari 2021

This page

Added error code 0407 account is closed or frozen

v1.2

v1.2

21 September 2022

Open Docs

-

Product Overview Introduction Part

a. Binding Step

b. Payment Step

c. Refund Step

d. Payment Step with Callback

e. 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_pan can be sent in full format (16 digits), otherwise only the last 4 digits are sent.

A. Create Card Token (Binding) OTP

Endpoint Description

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

application/json

M

-

-

Request Structure & Sample

Field Data Type Mandatory Length Description 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
email varchar M 50 User email test@email.com
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

Description

Example

registration_token

String

M

-

String code for verification OTP

TOK_CBF6XTIW
O4HKQ3LJ2

QPAGW445LORL
PF5

status

String

M

-

Value will be "PENDING_USER_
VERIFICATION" only

PENDING_USER_

VERIFICATION

Request Example :


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 - success is identified by a non-empty registration token otp request and status = PE NDING_USER_VERIFI CATION
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

B. Create Card Token (Binding) OTP Verify

Endpoint Description

Create Card Token (Binding) OTP Verify is an 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 Description Example
registration_token varchar M 40 OTP string code that is to be verified with the passcode obtained by the user

TOK_TKNCPPPHUVL3I

JVAXZI5GG4WBE

C77YZ6::ADVQ

passcode int M 6 Passcode that has been sent to the user 545195

Response Structure & Sample

Field Data Type Mandatory Length Description Example
status varchar M 4 identifies that the binding process was successful “0000”
phone_number varchar M 15 registered phone number on bank account. 6281225088578
last4 varchar M 4 The last 4 digits of the 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
email varchar  M 50 User email test@gmail.com
location JSON O - The location when the token firstly binds -
metadata JSON M - Merchant metadata {
“refnum”:”123” }
card_type varchar M 10 There are 6 card_type statuses: 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": "6285641403241",
	"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": "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

C. Delete Card Token (Unbinding)

Endpoint Description

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 Description Example
card_token Text M 40 token for validating your transaction and binding status card_.XXXXXX

Response Structure & Sample

Field Data Type Mandatory Length Description Example
status varchar M 4 identify that the unbinding process was successful “0000”

Request and Response Payload Sample

Request  Example:


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

D. Retrieve Payment Charges & Refunds

Endpoint Description

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 Description 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 Description 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: Use "payment_status" to identify whether the payment is SUCCESS or FAILED

Array Refund History

Field Data Type Mandatory Length Description 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: Use "status" to identify whether a payment is SUCCESS or FAILED

Request and Response Payload

Request Example :


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

E. Create Payment Charge OTP

Endpoint Description

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 Description 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.  "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 for use OTP

Field Data Type Mandatory Length Description Example
status varchar M 40 Pending User Verification  
charge_token varchar M 40 string code for OTP verification  

Response Structure & Sample for not use OTP

Field Data Type Mandatory Length Description 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 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)  
remark 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 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

Request Example:


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 with OTP

Http Status Code Status Code Status Message Description
200 - - PENDING_USER_VER IFICATION - 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

List of Error / Response Code for those without OTP

Http Status Code Status Code Status Message Description
200 - - 0000 payment success transaction processed, success payment is indicated by the payment_status = SUCCESS
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
400 0402 400 - payment currency not supported Request Charge OTP failed
400 0109 400 - Your card is blocked or disabled Request Charge OTP failed
400 0111 400 - Duplicate Idempotency Key Request Charge OTP failed
400 0006 400 - Invalid card token Request Charge OTP failed

F. Create Payment Charge OTP Verify

Endpoint Description

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 Description 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 Description 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

Request example:


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

G. Create Payment Refund

Endpoint Description

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 Description 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 Description 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

Request Example:


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

H. Callback API Direct Debit Charges

Endpoint Description

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 Using client_id from developers.bri.co.id
BRI-Timestamp   M - -
X-BRI-Signature   M 64 -
Content-Type application/json M - -

Example for payload signature:

path=/directdebit/notif/refunds&verb=POST&token={{Merchant-Key}}&timestamp=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 Description 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 payment 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 { "lon":"", "lat":"" }
metadata JSON O - Merchant metadata { "trx_id:"123456" }
payment_status string M   Indicate the status of payment (FAILED / SUCCESS) SUCCESS

Response Structure & Sample

Field Data Type Mandatory Length Description 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 

Request Example:


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",
}	

I. Callback API Direct Debit Refunds

Endpoint Description

Callback API for send notification refund

*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 payload signature:

path=/directdebit/notif/refunds&verb=POST&token={{Merchant-Key}}&timestamp=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 Description 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 { "lon":"", "lat":"" }
metadata JSON N - Merchant metadata { "trx_id:"123456" }
refund_status string M   Indicate the status of refund (FAILED / SUCCESS)  

Response Structure & Sample

Field Data Type Mandatory Length Description 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 

Request Example :


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 Description
400 0001 Wrong message format Invalid input format
400 0003 Invalid BRI API Key there was a problem in the BRI system
400 0006 Invalid Card Token  
400 0009 Missing Card Pan  
401 0601 Invalid Token  
401 0602 Invalid Signature