Direct Debit V1.2

Create API

What is BRI Direct Debit?

The need of digital payments has been growing rapidly and will keep evolving tremendously over the next few years. Conquer this opportunity by implementing Direct Debit feature as one of your app payment options.

Direct Debit is an electronic payment method that allows the bank to automatically withdraw funds from customers’ accounts for payments.

By implementing Direct Debit API by BRIAPI, your customers only need to register their debit card once, and enter the OTP (One-Time Password) code for further transactions. OTP codes will provide an extra layer of security in payment and convenience in customer transactions.

Use Case of BRI Direct Debit API?

Direct Debit is the most suitable payment method for digital businesses such as e-commerce, subscription services, e-wallet top up, insurance, or investment. By integrating this API to your digital business, you have created a seamless transaction journey for your customers within one click!

 

 

API Information

Title Direct Debit V1.2
Version v1.2
URL Sandbox https://sandbox.partner.api.bri.co.id/v1.2/directdebit
URL Production  

Versi Control

Version Doc

Version API

Date

Link Dokumen

Description

v1.0

v.1.2

6 Desember

2021

Open Docs

Baseline version.

v2.0

v1.2

14 Juni

2022

This Page

  • Remarks parameter takeout on request on all Endpoints

  • Sandbox URL Change, Playload Sample URL and Path Version

  • Changes in the Mandatory Field Metadata on the Create Payment Charge Multi Giro OTP endpoint

  • Adding the trx_id parameter to the Create Payment Charge Multi Giro OTP endpoint

  • Added structure and error response to all endpoints

v2.1

v1.2

12 September 2022

Halaman ini

Changes to the error list with the following details:

Existing RC

Existing Message

 

 

0107

Phone number is invalid

0113

Card Information Invalid

0101

Card Number Not Found

0113

Card Information Invalid

0104

Phone number not registered

0113

Card Information Invalid

v3.0

v1.2

26 September 2022

This Page
Added multiple endpoints:

  • Create Payment Charge OTP

  • Create Payment Charge OTP Verify

  • Create Payment Refund

  • Callback API Direct Debit Charges

  • Callback API Direct Debit Refunds

v4.0

v1.2

26 October 2022

This Page

  • Added rekening koran remark information at the product description

  • Added trx_id parameter to Create Payment Charge Multi Giro OTP and Create Payment Charge OTP endpoint requests and responses

  • Added trx_refund_id parameter to Create Payment Refund Multi Giro and Create Payment Refund endpoint requests and responses

  • Added response code 4000413 "Transaction Timeout" to Create Payment Charge OTP and Create Payment Charge Multi Giro OTP endpoint

  • Change metadata parameter on the Create Payment Charge Multi Giro OTP dan Create Payment Charge OTP endpoint are mandatory

  • Change metadata parameter on the Create Payment Refund Multi Giro dan Create Payment Refund endpoint are mandatory

v4.1

v1.2

7 Februari 2023

This Page

Added a note that "OTP and Notification (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp" in the Product Overview and on the 3 endpoints; 

  • Create Card Token (Binding) OTP Verify
  • Create Payment Charge Multi Giro OTP Verify
  • Create Payment Charge OTP Verify

v4.2

v1.2

27 April 2023

This pages

Changed the description of the maximum number of OTP requests to 3 times in Response Code 0924 on the 3 endpoints below : 

  • Create Card Token (Binding) OTP
  • Create Payment Charge Multi Giro OTP
  • Create Payment Charge OTP 

v4.3

v1.2

03 Juli 2023

This pages

Update mandatory for the exp_date field from O to M on the Create Card Token (Binding) OTP endpoint

*Notes
 This changes will apply on 14th August 2023

 

Product Overview

Introduction Part

 

The e-Commerce payment feature that connects your e-Commerce account with BRI Debit Card as Source of Fund (SoF), so the transaction payment process takes place quickly with one registration process.

 

Flow API (actor interaction)

 

Sequence Diagram

  1. Binding Step

     

  2. Payment Step

  3. Refund Step

 

Standards (items that applicable for all endpoint)

  • All date time fields must be in ISO 8601 format.

Additional Requirement

Partners who have PCI-DSS license, card_pan can be submitted in full format (16 digits), otherwise submitted only the last 4 digits.

Remark Rekening Koran

16 karaketer (DRDBT/DRRFN+5 digit kode partner+2 digit kode transaksi+4 digit terakhir kartu)+spasi+12 digit paymentid+spasi+10 karakter trx_id partner yang diambil dari (metadata>trx_id / metadata>trx_refund_id).

Note: OTP and Notifications (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp

Endpoint

1. Create card token (Binding) OTP

Endpoint Description

The Binding API verifies that the information provided by user matches the information (data) on bank. Card_token obtained has an active period of one year or following the card expire date period. If the card_token has expired, user is required to bind again to get a new card_token to make transactions.

General Information

HTTP Method

POST

Path

/v1.2/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

timestamp

M

-

ISO 8601 format

X-BRI-Signature

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

5221123456789101

phone_number

varchar

M

15

registered phone number on bank

6289912345678

email

varchar

M

50

User email

foo.bar@baz.com

exp_date

varchar

M

4

expired date with format MMYY.

0525

device_id

varchar

O

55

The device ID used by user for binding

-

location

JSON

O

-

Location when first binding

{

"lat": "123",

"lon": "-123"

}

metadata

JSON

O

-

Merchant metadata

You can fill this section with selected internal data

Normal Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Exam

registration_token

String

M

40

String code for OTP verification

TOK_CBF6XTIWO

W445LORLPF5

status

String

M

-

Value will be "PENDING_USER_VERIFICATION"

only

PENDING_USER_

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code": "0113",

"message": "Card information invalid"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-10T11:07:28Z

Request & Response Payload Sample

Request:

{   
        curl -X POST 'https://sandbox.partner.api.bri.co.id/v1.2/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": "5221123456789101",
        "phone_number": "6289912345678",
        "email":"foo.bar@baz.com"
        }
       }'

Normal Response :

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

Error Response :

{
   "error": {
      "code": "0113",
      "message": "Card Information Invalid"
  },
    "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

-

The successfull otp request process identified by a non-empty otp reque and status

= PENDING_USER_VERIFICATI

400

0102

400

-

the expired date is incorrect

Failed binding request

400

0103

400

-

card was expired

Failed binding request

400

0105

400

-

card status not activated

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

0113

400

-

Card Information Invalid

Failed binding request

400

0407

400

-

account is closed or frozen

Failed binding request

400

0112

400

-

Exceed limit binding

Maximum binding attempts is 5 tim More than that, will get this error.

400

0924

400

-

OTP

requests have reached the maximum

Maximum otp request. After 3 time otp request will not be verified or failed verification.

400

0921

400

-

Send OTP Failed

Failed send OTP
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

2. Create Card Token (Binding) OTP Verify

Endpoint Description

Create Card Token (Biding) OTP Verify is endpoint for verification OTP Binding requests.

Note: OTP and Notifications (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp

General Information

HTTP Method

PATCH

Path

/v1.2/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

timestamp

M

-

-

X-BRI-Signature

signature

M

64

-

Content-Type

application/json

M

-

-

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

registration_token

varchar

M

40

OTP token string code that will be verified with passcode obtained by user

TOK_TKNCPPPHUVL3IJVAXZI5GG4WB

passcode

int

M

6

Passcode that has been sent to user

545195

Normal Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

Identify that the binding process was successfull

“0000”

phone_number

varchar

M

15

registered phone number on bank

6281225088578

device_id

varchar

O

55

Device ID used by users for make payments

-

card_token

Text

M

-

Token to validate your transaction and binding status

card_.xxxx

last4

varchar

M

4

last 4 digits of card

1234

email

varchar

M

50

User email

foo.bar@baz.com

location

JSON

O

-

Location when first binding

-

metadata

JSON

M

-

Merchant metadata

{

“refnum”:”123”

}

card_type

varchar

M

10

There are 6 card_type status: PVRGLR, PVGOLD, PVPLAT, RGLR, GOLD, PLAT

  

limit_transaction

varchar

O

-

Limit transaksi

  

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code": "0918",

"message": "Invalid Passcode"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-10T11:09:43Z

Request & Response Payload Sample

Request:

            curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1.2/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": "5221123456789101",
            "phone_number": "6285736330909",
            "email":"foo.bar@baz.com"
            }
           }'

Normal Response :

{
 "body": {
 "status": "0000",
 "phone_number": "6289912345678",
 "device_id": "09864ADCASA",
 "card_token": 
"card_.eyJleHAiOjE2ODU0OTExOTksImlhdCI6MTU0MDE5NjUwMCwiaXNzIjoiQmFuayBCUkkgLSBEQ0UiLCJqdGkiOiJhMGM2MjlhNS1hYWI5LTQ5OWMtODg5MS0yNzA1NDg3NGRmYWUiLCJuYmYiOjE1NDAx
OTY1MDEsInBhcnRuZXJJZCI6Iu_vSIsInNlcnZpY2VOYW1lIjoiRERfRVhURVJOQUxfU0VSVklDRSJ9.hceS_BQtzCIyMJCVMMvPWSfTvqIrW9TIL9arAUi95e-
P6Kq9bvmQNuGLcfV6GLnQEc07fKF6IbaLLkUquEm2iDfsP1HMLv_crXiF9snwzqzTk5vJqYvLmRGDqhZk-tFw-
MwX0NWop2iyRUhwSTB7rCNVOyfeIGfif7dKpu2PdFT98VUimnsKRWqHjAR7uCVKXweDbfKVpLHpgcR914MvSthqt4a7eHzUxm6o6eqyjQjf_vkQi4Fl_iG98JOVuzVuXft5P50QKcKwAhnrIiGMCVd4DZWQ1rMVbx1iS
LvGzBrR1xm3wIYYlmyR0pUVlDdGaE04N1Gz_dvcsgx15Ecw",
 "location": {
 "lat": "",
 "lon": ""
 },
 "last4": "1234",
 "email": "foo.bar@baz.com",
 "metadata": {
 "example1": "example1"
 },
 "card_type": "PVRGLR",
 "limit_transaction": ""
 }
}

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

Error Response :

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

List of Error/Response Code

Http Status

Code

Status Code

Status

Message

Description

200

-

-

0000

binding success

Binding success, 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
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

3. Delete Card Token (Unbinding)

Endpoint Description

The unbinding API used for delete registered user accounts.

General Information

HTTP Method

DELETE

Path

/v1.2/directdebit-enterprise/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

timestamp

M

-

-

X-BRI-Signature

signature

M

64

-

Content-Type

application/json

M

-

-

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

card_token

Text

M

40

Token to validate your transaction and binding status

card_.XXXXXX

Normal Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

Identify that the unbinding process was successful

“0000”

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code":

"0006",

"message": "Invalid card token"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-

10T11:09:43Z

Request & Response Payload Sample

Request:

{
curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1.2/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.EUOaGaCI6giha7
GmRsycxMBrVXQgeF9cHfonXYZcT_3R3ykXw6PFOS9r32fMVP8al2lf26_Q6VIZ3sm71e7Sbd1KoigtGdcTPeJseSMMP190Ful_2DA2cRqhvN1dzJx-6keaG_AzLzo6sWMzuonQuR9tk-o5YMkGzfHJ-ZOS0zWvmN9lWRmvKlZPOBH_8Q430Yu5CeSjIF9ocfQQ6oguk_bXVRCX4_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 successful, status = 0000

400

0201

400

-

unbinding was unsuccessful

Unbinding failed

400

0006

400

-

Invalid card token

card_token not found or already unbinding
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

4. Retrieve Payment Charges & Refunds

Endpoint Description

This API request is used to display all payment status that have been made.

* NOTE: Normal case partners will get payment_id when charge and use it for transaction inquiry, but if the transaction has timed out, partners can make inquiries using Metadata or Remarks. Partners are expected to ensure that the values in Metadata or Remarks are unique as they will be used for transaction inquiries. Otherwise, the result of the inquiry will return the latest data.

General Information

HTTP Method

POST

Path

/v1.2/directdebit-enterprise/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

timestamp

M

-

-

X-BRI-Signature

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

  

remarks

varchar

O

 

Remarks as transasction

markers

  

metadata

JSON

M

-

Metadata for inquiry

{

"trx_id_pay": "0007654321"

}

>trx_id

varchar

M

64

Transaction partner ID

  

Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

Code 0000 indicates that the inquiry was successfully processed

0000

amount

number (2

Decimal Points)

M

-

The amount of the bill paid by user. Example 20000.00

  

currency

varchar

M

3

Three letter currency ISO code

IDR

payment_id

varchar

M

15

payment_id from payment API response

  

payment_status

varchar

M

7

There are 3 payment status on

inquiry: SUCCESS (for successfully transaction), FAILED (for failed transaction), "" (empty for failed update status on database and can mark as failed transaction)

  

remarks

varchar

M

255

remarks as payment markers.

Example "ext989898"

  

refund_history

JSON

M

-

list array refund history

  

device_id

varchar

O

55

Device ID used by users for make payments

  

location

JSON

O

-

The charge payment location is made

{

"lat": "",

"lon": ""

}

metadata

JSON

M

-

Merchant metadata

{

"trx_id_pay": "0007654321"

}
>trx_id varchar M 64 Transaction partner ID  

* NOTE: Use "payment_status" to identify whether the payment was SUCCESS or FAILED

Structure Array Refund History

Field

Data Type

Mandatory

Length

Description

Example

refund_id

varchar

M

4

refund_id created after transaction

  

amount

number (2

Decimal Points)

M

15

The amount of the refund process.

Example 20000.00

  

currency

varchar

M

3

Three letter ISO code for the currency.

Currency will be used for refund.

  

reason

varchar

M

255

remaks for refund

  

date

date

M

-

refund process date in ISO-8601 format

  

status

varchar

M

7

There are 3 refund status on inquiry

: SUCCESS

(for successfully refund), FAILED

(for failed refund), "" (empty for failed update status on database and can mark as failed refund)

  

device_id

varchar

O

55

Device ID used by users for refund

  

location

JSON

O

-

The refund location is made

  

metadata

JSON

O

-

Merchant metadata

  

* NOTE: Use "status" to identify whether the payment was SUCCESS or FAILED

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code":

"0301",

"message": "Payment id not found"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-

10T11:09:43Z

 

Request & Response Payload Sample

Request:

 curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1.2/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": "5221123456789101",
         "phone_number": "6285736330909",
          "email":"foo.bar@baz.com"
   }
  }'

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": "000012345000"
        }
      }
    ],
        "device_id": "lg-lllll",
        "location": {
           "lat": "",
           "lon": ""
      },
        "metadata": {
        "trx_id": "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 is failed or transaction still on process
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

5. Create Payment Charge Multi Giro OTP

Endpoint Description

This API is used for payments from transactions based on the card number in 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's funds should not be debited.

General Information

HTTP Method

POST

Path

/v1.2/directdebit-enterprise/charges/multiple

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

timestamp

M

-

-

X-BRI-

Signature

signature

M

64

-

Content-Type

application/json

M

-

-

Idempotency-Key

Unique ID

M

-

unique request for preventing duplicate requests at the same time

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

card_token

Text

M

  

token to validate your transaction or 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

  

giro_account_no

string

M

  

Giro Account Partner

  

device_id

varchar(55)

O

  

Device ID used by users for make payments

  

location

JSON

O

  

Location of payment is made

  

metadata

JSON

M

  

Merchant metadata. Should

contain unique value if it is used for inquiry charge payment and refund.

sample:

{ "trx_id":"1234566789"

}

  

trx_id

Varchar

M

 64

Partner Transaction ID

  

otp_bri_status

varchar(3)

O

  

otp bri status for marks 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.

*Note : if otp_bri_status = NO, then will be processed immediately with a successful response and a list of different error codes. Please look at the sample response and the list of errors or response codes.

  

Normal Response Structure & Sample for those who 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

  

Normal Response Structure & Sample for those without OTP

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

status of transcation process

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 successful payment. If payment is failed, payment_status will not be returned (system will return error code and error message)

  

remarks

varchar

M

15

remarks as charge payment markers.

  

device_id

varchar

O

55

Device ID used by users for make charge payments

  

location

JSON

O

-

Location of charge payment is made

  

metadata

JSON

M

-

Merchant metadata

  

trx_id

Varchar

M

 64

Partner Transaction ID

  

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code": "0006",

"message": "Invalid card token"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-10T11:09:43Z

Request & Response Payload Sample

Request:

{
    curl -X POST 'https://sandbox.partner.api.bri.co.id/v1.2/directdebit-enterprise/charges/multiple' \
 -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.PMuH4Fq9TkacFS
QE2nwr-Dr7icRPlOOxYv2_XeoOjzidTm8dRwD9xy1lpvc_JJiUUQ_WFsL-o267BkL4tpnUWNxjA0ggnfsIsJQzZUSKtQYPozi7ZSLgV4VHOMqDJxBAFb-TeuNhN6obQBpsWBc4g3e0iOvEWKvk56AviR9Hs-CIQvqoYUEds8PgOyWCdbCnT76LLBzBWjML6JVXSMbtRJ3nDvE4ykq_ajDkgVeHbgFiTPiBtnsXVskbDGZMma1kVijr5GS4cxdqAq7xzYRnFpbVNHyxUrzVKYrGGgYoHM6K3-zM8wlhfHqssjyO86DyvdmfTF1398ZT-B8uv9zog",
 "amount":"25099.00",
 "currency":"IDR",
"giro_account_no":"020601006205303",
 "otp_bri_status": "YES",
 "metadata":{
 "trx_id":"12345687"
 }
 }
}'

Normal response for using OTP:

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

Normal Response for without using 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",
"trx_id":"12345687"
 }
 }
}

Error Response :

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

List of Error/Response Code for those who use OTP

Http Status

Code

Status Code

Status

Message

Description

200

-

-

PENDING_USER_VERIFICATION

-

successfully identified by non-empty otp token

400

0402

400

-

payment currency not supported

Charge OTP

request failed

400

0109

400

-

Your card is blocked or disabled

Charge OTP

request failed

400

0407

400

-

account is closed or frozen

Charge OTP

request failed

400

0413

400

-

Transaction Timeout

Transaction Timeout

400

0111

400

-

Duplicate Idempotency Key

Charge OTP

request failed

400

0113

400

-

Giro Account Not Allowed

Giro Account not registered

400

0924

400

-

OTP

requests have reached the maximum

Maximum otp request after 5 times unverified otp request or failed verification

400

0921

400

-

Send OTP Failed

Failed send OTP

service

400

0006

400

-

Invalid card token

Charge OTP

request failed

List of Error/Response Code for those without OTP

Http Status

Code

Status Code

Status

Message

Description

200

-

-

0000

payment success

Transaction processed, the success payment charge is indicate by the payment_status

= SUCCESS

400

0113

400

-

Giro Account Not Allowed

Giro account not registered

400

0401

400

-

over limit

Charge Failed

400

0403

400

-

charge payment failed

Charge Failed

400

0404

400

-

insufficient balance

Charge Failed

400

0405

400

-

account is frozen

Charge Failed

400

0406

400

-

account is closed

Charge Failed

400

0407

400

-

account is closed or frozen

Charge Failed

400

0408

400

-

account not found

Charge Failed

400

0402

400

-

payment currency not supported

Charge OTP request failed

400

0413

400

-

Transaction Timeout

Transaction Timeout

400

0109

400

-

Your card is blocked or disabled

Charge OTP request failed

400

0111

400

-

Duplicate Idempotency Key

Charge OTP request failed

400

0006

400

-

Invalid card token

Charge OTP request failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

6. Create Payment Charge Multi Giro OTP Verify

Endpoint Description

This API used to verify charge OTP request from transaction.

Note: OTP and Notifications (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp

General Information

HTTP Method

POST

Path

/v1.2/directdebit/charges/multiple/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

timestamp

M

-

-

X-BRI-Signature

signature

M

64

-

Content-Type

application/json

M

-

-

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

card_token

Text

M

-

token to validate your transaction and binding status

card_token.xxxxx

charge_token

varchar

M

40

OTP string code to be verified with user-generated passcode

CHARGE_XXXXX

passcode

int

M

6

passcode that has been sent to user

999999

Normal Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

status of transaction process

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.

  

remarks

varchar

M

15

remarks as charge payment markers.

  

device_id

varchar

O

55

Device ID used by users for make charge payments

  

payment_status

varchar

M

7

The value will be SUCCESS

for successful payment. If payment is failed, payment_status will not be returned (system will return error code and error message)

  

location

JSON

O

-

Location of charge payment is made

  

metadata

JSON

O

-

Merchant metadata

  

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code": "0403",

"message": "charge payment failed"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-10T11:09:43Z

 

Request & Response Payload Sample

Request:


curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1.2/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": "5221123456789101",
    "phone_number": "6285736330909",
    "email":"foo.bar@baz.com"
      }
  }'

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 charge payment is indicated by the payment_status

= SUCCESS

400

0918

400

-

Invalid Passcode

Charge Failed

400

0919

400

-

Error Validate OTP

Passcode

Charge Failed

400

0920

400

-

Expired OTP

Charge Failed

400

0922

400

-

Invalid OTP

Token

Charge Failed

400

0401

400

-

over limit

Charge Failed

400

0403

400

-

charge payment failed

Charge Failed

400

0404

400

-

insufficient balance

Charge Failed

400

0405

400

-

account is frozen

Charge Failed

400

0406

400

-

account is closed

Charge Failed

400

0407

400

-

account is closed or frozen

Charge Failed

400

0408

400

-

account not found

Charge Failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

7. Create Payment Refund Multi Giro

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.2/directdebit/refunds/multiple

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

timestamp

M

-

-

X-BRI-

Signature

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 to validate your transaction and binding status

  

amount

number (2

Decimal Points)

M

-

The amount of refund process.

Example 20000.00

  

payment_id

varchar

M

12

payment_id from API charge response

  

giro_account_no

string

M

  

Giro Account Partner

  

currency

varchar

M

3

currency used for refund

  

device_id

varchar

O

55

Device ID used by users for make refund

  

location

JSON

O

-

Location of refund is made

  

metadata

JSON

M

-

Merchant metadata. Must contain a unique value if used for payment charge and refund inquiries.

sample:

{ "trx_id":"1234566789"

}

  

trx_refund_id

Varchar

M

 64

Refund ID Transaction Partner

  

Normal Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

status of process refund transaction

0000

refund_id

varchar

M

12

refund_id generated after refund transactions is success

  

payment_id

varchar

M

12

payment_id for related charge transaction

  

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 will be used for refund to user

  

reason

varchar

O

15

reason as remark refund

  

refund_status

varchar

M

6

The value will be SUCCESS for successful refund. If refund is failed, refund_status will not be returned (system will return error code and error message)

  

device_id

varchar

O

55

Device ID used by users for make refund

  

location

JSON

O

-

Location of refund is made

  

metadata

JSON

M

-

Merchant metadata

  

trx_refund_id

Varchar

M

 64

Refund ID Transaction Partner

  

Error Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

error

JSON

M

-

Detailed error information

{

"code": "0504",

"message": "refund payment failed to get payment id"

}

status_code

String

M

3

Error status code

400

recorded_at

String

M

-

Saved data timestamp

2021-02-10T11:09:43Z

Request & Response Payload Sample

Request:


            curl -X DELETE 'https://sandbox.partner.api.bri.co.id/v1.2/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": "5221123456789101",
                   "phone_number": "6285736330909",
                   "email":"foo.bar@baz.com"
                }
        }'

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": {
 "trx_refund_id":"12345687"
 }
 }
}

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

0113

400

-

Giro Account Not Allowed

Giro account not registered

400

0501

400

-

refund currency not supported

Refund failed

400

0502

400

-

refund amount is greater than paid amount

Refund failed

400

0503

400

-

refund payment failed

Refund failed

400

0405

400

-

account is frozen

Refund failed

400

0406

400

-

account is closed

Refund failed

400

0408

400

-

account not found

Refund failed

400

0404

400

-

insufficient balance

Refund failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

8. Create Payment Charge OTP

Endpoint Description

This API is used for payment of transactions based on the card number in the card_token obtained from the bidning process (card token creation). Payment will stop if

Payment will stop if:

1. The currency used for the transaction is not yet supported.

2. The payment amount exceeds the customer's credit limit or the funds in the account are not sufficient (determined by the bank)

3. The customer's account or card is no longer active. For each of the cases above, customer funds cannot be debited.

General Information

HTTP Method

POST

Path

/v1.2/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 to validate your transaction and binding status

  

amount

number (2 Decimal Points)

M

  

The amount paid by the user. Example 20000.00

  

currency

varchar

M

 3

Three letter ISO code for the currency. Currency will be used for refund to user

  

remarks

varchar

O

 255

remarks as a payment marker. Must contain unique values if used for payment charge and refund inquiries. Example "ext123456"

  

device_id

varchar

O

 55

Device ID used by users for make refund

  

location

JSON

O

  

Location of refund is made

  

metadata

JSON

M

  

Merchant metadata. Must contain a unique value if used for payment charge and refund inquiries

  

>trx_id

Varchar

M

 64

Partner Transaction ID

  

otp_bri_status

varchar

O

 3

otp bri status to indicate that the transaction uses OTP or not. If YES it will use OTP, if NO it will not use OTP. By default if the value is empty it will use OTP. *NOTE: if otp_bri_status = NO, the transaction will be processed immediately with a successful response and a different error code list. Please look at the sample response and the list of errors or response codes.

  

callback_url

string

O

  

Url to send notification callback. Required only if the partner uses the callback feature. If not, no need.

  

 

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 without use OTP

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

transaction processing status

0000

payment_id

varchar

M

12

payment_id for related charge transaction

  

amount

number (2 Decimal Points)

M

-

The amount paid by the user. Example 20000.00

  

currency

varchar

M

3

Three letter ISO code for the currency. Currency will be used for refund to user

  

payment_status

varchar

M

7

The value will be SUCCESS for successful payment. If payment is failed, payment_status will not be returned (system will return error code and error message)

  

remarks

varchar

M

15

remarks as charge payment markers

  

device_id

varchar

O

55

Device ID used by users for make charge payments

  

location

JSON

O

-

Location of charge payment is made

  

metadata

JSON

M

-

Merchant metadata

  

>trx_id

Varchar

M

 64

Partner Transaction ID

  
code varchar M 4 Only applicable for failed payment. Error Code.  
message text M - Only applicable for failed payment. Error Description.  
status_code varchar M 3 Only applicable for failed payment. Status Code.  
recorded_at datetime M - Only applicable for failed payment. Error Response Datetime.  

Request & Response Payload Sample

Request:

            curl -X POST ' https://sandbox.partner.api.bri.co.id/v1.2/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 for use OTP:

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

Normal Response for without use 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": {
                    "trx_id":"12345687"
                    }
                 }
              }

Response Error (only for 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 for those who use OTP

Http Status

Code

 Status Code Status

Message

Description

200

-

 - PENDING_USER_VERIFICATION

-

successfully identified by non-empty otp token

400

0402

 400 -

payment currency not supported

Charge OTP request failed

400

0109

 400 -

Your card is blocked or disabled

Charge OTP request failed

400

0407

 400 -

account is closed or frozen

 Charge OTP request failed

400

0413

 400 -

Transaction Timeout

Transaction Timeout

400

0111

 400 -

Duplicate Idempotency Key

Charge OTP request failed

400

0924

 400 -

OTP requests have reached the maximum

Maximum otp request after 5 times unverified otp request or failed verification

400

0921

 400 -

Send OTP Failed

Failed to Send OTP Service

400

0006

 400 -

Invalid card token

Charge OTP request failed

 

List of Error/Response Code for without use OTP

Http Status Code Status Code Status Message Description

200

-

 - 0000

payment success

Transaction processed, the success payment charge is indicate by the payment_status = SUCCESS

400

0401

 400 -

over limit

Charge Failed

400

0403

 400 -

charge payment failed

Charge Failed

400

0404

 400 -

insufficient balance

Charge Failed

400

0405

 400 -

account is frozen

Charge Failed

400

0406

 400 -

account is closed

Charge Failed

400

0407

 400 -

account is closed or frozen

Charge Failed
400 0408 400 - account not found Charge Failed

400

0402

 400 -

payment currency not supported

Charge OTP request failed

400

0413

 400 -

Transaction Timeout

Transaction Timeout

400

0109

 400 -

Your card is blocked or disabled

Charge OTP request failed

400

0111

 400 -

Duplicate Idempotency Key

Charge OTP request failed

400

0006

 400 -

Invalid card token

Charge OTP request failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

9. Create Payment Charge OTP Verify

Endpoint Description

This API is used to verify Request OTP charge from transactions.

Note: OTP and Notifications (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp

General Information

HTTP Method

POST

Path

/v1.2/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 to validate your transaction and binding status

card_token.xxxxx

charge_token

varchar

M

40

OTP string code to be verified with user-generated passcode

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

transaction processing status

0000

payment_id

varchar

M

12

payment_id for related charge transaction

  

amount

number (2 Decimal Points)

M

-

The amount 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 successful payment. If payment is failed, payment_status will

not be returned (system will return error code and error message

  

remarks

varchar

M

15

remarks as charge payment markers

  

device_id

varchar

O

55

Device ID used by users for make charge payments

  

location

JSON

O

-

Location of charge payment is made

  

metadata

JSON

O

-

Merchant metadata

  
code varchar M 4 Only applicable for failed payment. Error Code  
message text M - Only applicable for failed payment. Error Description.  
status_code varchar M 3 Only applicable for failed payment. Status Code.  
recorded_at datetime M - Only applicable for failed payment. Error Response Datetime.  

Request & Response Payload Sample

Request:

          curl -X POST 'https://sandbox.partner.api.bri.co.id/v1.2/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, the success payment charge is indicate by the payment_status

= SUCCESS

400

0918

 400 -

Invalid Passcode

Charge Failed

400

0919

 400 -

Error Validate OTP Passcode

Charge Failed

400

0920

 400 -

Expired OTP

 Charge Failed

400

0922

 400 -

Invalid OTP Token

Charge Failed

400

0401

 400 -

over limit

Charge Failed

400

0403

 400 -

charge payment failed

Charge Failed

400

0404

 400 -

insufficient balance

Charge Failed

400

0405

 400 -

account is frozen

Charge Failed

400

0406

 400 -

account is closed

Charge Failed

400

0407

 400 -

account is closed or frozen

Charge Failed
400 0408 400 - account not found Charge Failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

10. Create Payment Refund

Endpoint Description

The Refund API is used to make refund requests for previously successful payments. Refunds can be made in full or in part

General Information

HTTP Method

POST

Path

/v1.2/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 to validate your transaction and binding status

  

payment_id

varchar

M

12

payment_id from API charge response

  

amount

number (2 Decimal Points)

M

-

The amount of the refund process amount. Example 20000.00

  

currency

varchar

M

3

currency used for refund

  

reason

text

O

-

The reason for the user to make a refund is the remark. Must contain unique values if used for

payment charge and refund inquiries.

.

  

device_id

varchar

O

55

Device ID used by the user to make a refund

  

location

JSON

O

-

location the refund is made

  

metadata

JSON

M

-

Metadata Merchant. Must contain unique value if used for payment charge inquiry and refund.Url

to send callback notification. Required only if the partner uses the callback feature. If not, no need

  

trx_refund_id

Varchar

M

 64

Refund ID Transaction Partner

  

callback_url

string

O

  

Url to send notification callback. Required only if the partner uses the callback feature. If not, no

need.

.

  

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

varchar

M

4

status of the refund transaction process

0000

refund_id

varchar

M

12

Refund_id generated after a successful refund transaction

  

payment_id

varchar

M

12

Payment_id for related charge transactions

  

amount

number (2 Decimal Points)

M

-

The amount of the refund process amount. Example 20000.00

 

  

currency

varchar

M

3

Three-letter ISO code for currency. The currency used for refunds to users

  

reason

varchar

O

15

reason as remark refund

  
refund_status varchar M 6

The value will be SUCCESS for a successful refund. If the refund fails, refund_status will not be

returned (the system will return an error code and error message)

  

device_id

varchar

O

55

Device ID used by the user to make a refund

  

location

JSON

O

-

location the refund is made

  

metadata

JSON

M

-

Merchant metadata

  

>trx_refund_id

Varchar

M

 64

Refund ID Transaction Partner

  

 

Request & Response Payload Sample

Request:


    curl -X POST 'https://sandbox.partner.api.bri.co.id/v1.2/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_refund_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": {
        "trx_refund_id":"12345687"
        
        }
        }

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 has been processed, the refund has been successfully shown with refund

status = SUCCESS

400

0501

 400 -

refund currency not supported

Refund Failed

400

0502

 400 -

refund amount is greater than paid amount

Refund Failed

400

0503

 400 -

refund payment failed

Refund Failed

400

0405

 400 -

account is frozen

 Refund Failed

400

0406

 400 -

account is closed

Refund Failed
400 0408 400 - account not found Refund Failed

400

0404

 400 -

insufficient balance

Refund Failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

11. Callback API Direct Debit Charges

Endpoint Description

Callback API to send notification of charge

*NOTE: The transaction is successful if the status parameter = 0000 and the payment_status parameter = SUCCESS, while the transaction fails

if the status parameter = 0000 and the payment_status parameter = FAILED

 

General Information

HTTP Method

POST

Path

/v1.2/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

useclient_idfromdevelopers.bri.co.id

BRI-Timestamp

  

M

-

-

X-BRI-Signature

  

M

64

-

Content-Type

application/json

M

-

-

 

Example payload signature:

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

Payload data is encrypted with algorithmSHA256-HMAC using your client_secret. The signature is formed by a predefined payload. The signature result is

then encoded with Base64 and entered into X-BRI-Signature API request header

 

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

Text

M

-

callback delivery status, if partner successfully received the callback, the value will

always be '0000

 0000

payment_id

varchar

M

12

payment_id from API charge response

 12345678901

amount

number (2 Decimal Points)

M

-

Number of transaction amount 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

Device ID used by users to make payments

 1234567

location

JSON

O

-

Location payment made

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

metadata

JSON

O

-

Merchant metadata

 {
"trx_id:"123456"
}

payment_status

string

M

  

LIndicates payment status (FAILED / SUCCESS)

 SUCCESS

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

response_code

varchar

M

4

code of process transaction

 refer to the List of Error/Response Code table below

response_description

varchar

M

40

description of code

  refer to the List of Error/Response Code table below

 

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

List of Error/Response Code

Http Status

Response Code

Response Description

200

0000

notification send

400

1010

notification failed
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

12. Callback API Direct Debit Refunds

Endpoint Description

Callback API to send notification of 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

/v1.2/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

Using client_id fromdevelopers.bri.co.id

BRI-Timestamp

  

M

-

-

X-BRI-Signature

  

M

64

-

Content-Type

application/json

M

-

-

 

Example payload signature:

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

Payload data is encrypted with algorithm SHA256-HMAC using your client_secret. The signature is formed by a predefined payload. The signature result is

then encoded with Base64 and entered into X-BRI-Signature API request header.

 

Request Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

status

Text

M

-

callback delivery status, if partner successfully receive callback, the value will

always be '0000

 '0000'

payment_id

varchar

M

12

Payment_id for related charge transactions

 12345678901

refund_id

varchar

M

12

Refund_id is generated after a successful refund transaction

 12345678901

amount

number (2 Decimal Points)

M

-

The amount that is processed for the refund

20000.00

currency

varchar

M

3

currency used for refund

 IDR

reason

text

N

-

reason as remark refund

 trx_123456

device_id

varchar

N

55

Device ID used by users to make payments

 123456

location

JSON

N

-

Location refund made

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

metadata

JSON

N

-

Merchant metadata

 {
"trx_id:"123456"
}

refund_status

string

M

  

Indicates refund status (FAILED / SUCCESS)

  

 

Response Structure & Sample

Field

Data Type

Mandatory

Length

Description

Example

response_code

varchar

M

4

code of process transaction

  refer to the List of Error/Response Code table below

response_description

varchar

M

40

description of code

  refer to the List of Error/Response Code table below

 

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

List of Error/Response Code

Http Code

Response Code

Response Description

200

0000

notification send

400

1010

notification failed

Common Error

Http Code

Response Code

Message

Description

400

0001

Wrong message format

 invalid input format

400

0003

Invalid BRI API Key

there is an intermittent problem connecting to the database in the BRI system

400

0006

Invalid card token

  

400

0009

Missing Card Pan

  
400 0998 Gateway Timeout  
400 0999 General Error  
401 0601 Invalid Token  
401 0602 Invalid Signature  
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.