Dokumentasi APIDOCS Registration SNAP BI

API Information

Title	API Registration SNAP BI
Version	v1.0
URL Sandbox	https://sandbox.partner.api.bri.co.id
URL Production

Version Control

Doc Version	API Version	Date	Document Link	Description
v1.0	v1.0	2 December 2021	this pages	Baseline version
v2.0	v1.0	21 April 2022	this pages	Update field format
v3.1	v1.0	26 Oct 2022	this pages	Added RC 4030406 "Feature Not Allowed At This Time. [Reason]" at Verify OTP endpoin
v3.2	v1.0	07 Feb 2023	this pages	Added a note that "OTP and Notifications (Binding and Payment) that were previously sent via SMS will be sent via Whatsapp" in the Product Description and Verify OTP Endpoint.
v3.3	v1.0	23 Jun 2023	This pages	Added a List of Error/Response Codes to the Card Registration Unbinding Endpoint : "HTTP status: 403, service code: 05, case code: 08, status: failed, response message: card expired."
v3.4	v1.0	03 Jul 2023	This pages	Update mandatory for the expiryDate field from O to M for Card Registration Endpoint *Notes This changes will apply on 14th August 2023

Product Description

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

Product Overview

API Registration is required so that Consumers can associate their data to perform payment transaction services or access their data. This data can vary depending on needs, such as debit card, credit card, or account data.

Header Structure

Key	Value	Format	Mandatory	Length	Description
Authorization	Authorization	Alphanumeric	M		Bearer {Token}
X-TIMESTAMP	BRI - Timestamp	Datetime	M		Format Timestamp ISO8601
X-SIGNATURE	BRI - Signature	Alphanumeric	M		HMAC_SHA512
Content-type	application/json	Alpha	M		application/json
X-PARTNER-ID		Alphanumeric	M	36
CHANNEL-ID		Alpha	M	5
X-EXTERNAL-ID		Numeric	M	36

Endpoint

A. Card Registration

This endpoint is used to create consumer card data

Note : Card tokens that are obtained have an active period following the card's expiration date.

General Information

HTTP Method	POST
Path	snap/v1.0/registration-card-bind
Tipe Format	JSON
Authentication	OAuth 2.0 with Access Token

Request Structure

Field	Data Type	Format	Mandatory	Length	Description	Example
phoneNo	String	Numeric	M Note : SNAP BI (O)	15 Note : SNAP BI Length (16)	Customer’s phone number Format: 62xxxxxxxx xxxxx	62812345678
custIdMerchant	String	Alphanumeric	M	18	Merchant’s customer ID	0012345679504
cardData	Encrypted Object				Refer to Standard Symmetric Encryption on Security Standard Document section 2.1.9
bankCardType	String	Alpha	M	2	Type of the card (D – Debit, C –Credit, UE – Uang Electronik).	D
bankCardNo	String	Numeric	M	16 Note : SNAP BI Length (19)	Card number	221843000100021
identificationNo	String	Numeric	O	64	Customer’s ID number	2849238f02938402
identificationType	String	Numeric	O	2	Type of ID (01 - passport, 02 – eKTP&KTP, 03-TKTP, 04- SIM (Driver License), 99 – Others)	02
email	String	Alphanumeric	M Note : SNAP BI (O)	50 Note : SNAP BI Length (254)	RFC 3696 Length 254 after “<” and “>”	john.doe@email.com
expiryDate	String	Numeric	M	4	Card expiry date. Format: MMYY	1022

Response Structure & Sample

Field	Data Type	Format	Mandatory	Length	Description	Example
responseCode	String	Numeric	M	7	Response code	2000100
responseMessage	String	Alpha	M	150	Response description	Successful
chargeToken	String	Alphanumeric	M Note : SNAP BI (O)	45 Note : SNAP BI Length (40)	string code for verification OTP	abcd63617264746f6b656e
referenceNo	String	Numeric	M Note: SNAP BI (C)	12 Note : SNAP BI Length (64	Transaction identifier on service provider system. Must be filled upon successful transaction	2020102977770000000009

Request & Response Payload Sample

To encrypt the card data, use the Symmetric Encryption Standard (AES-256-cbc) with the Client Secret as the encryption key which has been encrypted with MD5.

AES-256-cbc requires an initialization vector which contains the client secret without an MD5 hash. The output of this encryption (AES-256-cbc) is in hex encoded format. The components in (AES-256-cbc) are as shown in the following table:

No.	Component	Example
1.	Plain text	{ "bankCardType":"D", "bankCardNo":"5221843000100021", "identificationNo": "1234567", "identificationType":"02", "email":"crisevan@gmail.com", "expiryDate":"1010" }
2.	Initialization Vector	rQpLmMkB4p2zYUQG
3.	Encryption key	00099531c1839c0a0d48fd2d93b271f1

No.

Component

Example

1.

Plain text

{

"bankCardType":"D",

"bankCardNo":"5221843000100021",

"identificationNo": "1234567",

"identificationType":"02",

"email":"crisevan@gmail.com",

"expiryDate":"1010"

}

2.

Initialization Vector

rQpLmMkB4p2zYUQG

3.

Encryption key

00099531c1839c0a0d48fd2d93b271f1

To perform encryption, please refer to the following linkhttps://www.javainuse.com/aesgenerator

Request :

{
"cardData": " a7ccf48471c041948b0efa921492fa0bcfe58dade682bf6251cb9ab77a52003bc7520
c3311ce67090a6d7112cae89756dbbde307a8de7f06 2bb05c4b2368c43e4afad09256fbde63c3335b6
3ee16a2b7d1b1bdde8c34768528f79c23d88571e998931ece556c34bb023a7a1cfc79613d 688cae558183
29ab7dbb6d61c2f69d57f2e37326ef8609dac4775b3b42014926756d35a4c2a527713e5d2996b2806464 ",
 "custIdMerchant": "0012345679504",
    "phoneNo": "6289912345678"
}
       Request untuk filed cardData yang dienkripsi :
{
      "bankCardType": "D",
      "bankCardNo": "5221843000100021",
      "identificationNo": "284923840902938402".
      "identificationType":"02",
      "email": "crisevan@gmail.com",
      "expiryDate": "1010"
 }

Normal :

    {
        "responseCode": "2000100",
        "responseMessage": "Successful",
        "chargeToken": "TOK_5kkmIKoMGDzwt1VzZssywSzDu2FIbALNwe5Z",
        "referenceNo": "757548930887"
    }

Error Response :

    {
        "responseCode": "4040111",
        "responseMessage": "Card Information Invalid"
    }

List of Error/Response Code

HTTP Status	Service Code	Case Code	Status	Response Message	Description
200	01	00	Success	Successful
400	01	01	Failed	Invalid Field Format [field request]	Invalid format
400	01	02	Failed	Invalid Mandatory Field [field request]	Missing or invalid format on mandatory field
403	01	03	Failed	Suspected Fraud
403	01	07	Failed	Card Blocked
403	01	08	Failed	Card Expired
403	01	09	Failed	Dormant Account
403	01	18	Failed	Inactive Card/Account/Customer
404	01	11	Failed	Card Information Invalid	Card information may be invalid, or the card account may be blacklisted.
409	01	01	Failed	Conflict
429	01	00	Failed	Too Many Requests
504	01	00	Pending	Timeout

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

B. Verify OTP

This endpoint is used to verify at the time of creation or deletion of consumer card data

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

General Information

HTTP Method	POST
Path	snap/v1.0/otp-verification
Tipe Format	JSON
Authentication	OAuth 2.0 with Access Token

Request Structure

Field	Data Type	Format	Mandatory	Length	Description	Example
originalReferenceNo	String	Numeric	M	64	Transaction identifier on service provider system	2020102977770000000009
otp	String	Numeric	M Note : SNAP BI (O)	6 Note : SNAP BI Length (8)	OTP Code / Passcode	123456
chargeToken	String	Alphanumeric	M Note : SNAP BI (O)	50 Note : SNAP BI Length (40)	OTP string code that is to be verified with the passcode obtained by the user	TOK_TKN CPPPHUV L3IJVAXZ I5GG4WB EC77YZ6: :ADVQ
type	String	Alpha	M Note : SNAP BI (O)	20	value "card" for card registration and "payment" for direct debit payment	card/payment
additionalInfo	Object		O		Additional information
>bankCardToken	String	Alphanumeric	M for type payment	560 Note : SNAP BI Length (128)	Card token for payment	6d7963617264746f6b656e

Response Structure & Sample

Field	Data Type	Mandatory	Length	Description	Example
responseCode	String	M	7	Response code	2000400
responseMessage	String	M	150	Response description	Successful
bankCardToken	String	M ( for card type response ) Note : SNAP BI (O)	560 Note : SNAP BI Length (128)	Card token for card binding	6d796361 7264746f6b656e
email	String	M ( for card type response ) Note : SNAP BI (O)	50 Note : SNAP BI Length (254)	RFC 3696 Length 254 after “<” and “>”	john.doe@email,com
phoneNo	String	M (for card type response) Note : SNAP BI (O)	15 Note : SNAP BI Length (16)	Customer’s phone number. Format: 62xxxxxxxx xxxxx	6289912345678
originalReferenceNo	String	M Note : SNAP BI (C)	64	Transaction identifier on service provider system. Must be filled upon successful transaction	2020102977770000 000009
originalPartnerReferenceNo	String	M ( for payment type response ) Note : SNAP BI (O)	64	Transaction identifier on service consumer system	1233
additionalInfo	Object	O		Additional information
>amount	String (ISO4217)	M ( Note: for payment type response )	15,2 Note : SNAP BI Length (16,2)	Transaction amount that will be paid using this payment method If it’s IDR then value includes 2 decimal digits. e.g. IDR 10.000,- will be placed with 10000.00	2000000.00
>currency	String	M ( Note: for payment type response )	3	currency	IDR
>lastFour	String	M ( Note: for card type response)	4	the last 4 digits of the card	5566
>debitCardType	String	M ( Note: for card type response )	10	There are 6 card_type statuses: PVRGLR, PVGOLD, PVPLAT, RGLR, GOLD, PLAT	PVGOLD
>merchantTrxId	String	O	64

Request & Response Payload Sample

Request type ( card ):

{
    "originalReferenceNo": "2020102977770000000009",
    "otp": "12345",
    "chargeToken": "TOK_m7aTkze5F3K9SizIwb72SEJfRVVrEWDS",
    "type": "card"
}

Request type ( payment ) :

"{
    "originalReferenceNo": "2020102977770000000009",
    "otp": "12345",
    "chargeToken": "TOK_m7aTkze5F3K9SizIwb72SEJfRVVrEWDS",
    "type": "payment",
    "additionalInfo": {
        "bankCardToken": "adswerR2QeqFREAATW4W4"
    }
}"

Normal Response ( card ):

{
    "responseCode": "2000400",
    "responseMessage": "Successful",
    "bankCardToken": "iyhTPdp9wznRHvGrKPAL5bwom",
    "email": "test@gmail.com",
    "phoneNo": "6289912345678",
    "originalReferenceNo": "2020102977770000000009",
    "additionalInfo": {
        "lastFour": "1234",
        "debitCardType": "PVGOLD"
    }
}

Response type ( payment ) :

 {
    "responseCode": "2000400",
    "responseMessage": "Successful",
    "originalReferenceNo": "2020102977770000000009",
    "originalPartnerReferenceNo": "1233",
    "additionalInfo": {
        "amount": "2000000.00",
        "currency": "IDR",
        "merchantTrxId": ""
   }
}

Error Response :

    {
        "responseCode": "5040400",
        "responseMessage": "Timeout"
    }

List of Error/Response Code

HTTP Status	Service Code	Case Code	Status	Response Message	Description
200	04	00	Success	Successful
400	04	01	Failed	Invalid Field Format	Invalid format
400	04	02	Failed	Invalid Mandatory Field	Missing or invalid format on mandatory field
401	04	02	Failed	Invalid Customer Token
403	04	02	Failed	Exceeds Transaction Amount Limit
403	04	06	Failed	Feature Not Allowed At This Time. [Reason]	Feature Not Allowed At This Time. Send OTP Failed. (Send OTP Failed)
403	04	12	Failed	OTP Lifetime Expired
403	04	15	Failed	Transaction Not Permitted [Reason]	Transaction Not Permitted. originalReferenceNo does not match (referenceNo and registrationToken does not Match)
404	04	15	Failed	Invalid OTP	OTP is incorrect
409	04	00	Failed	Conflict
500	04	00	Failed	General Erorr
504	04	00	Pending	Timeout

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

C. Card Registration Unbinding

This endpoint is used to delete consumer card data

General Information

HTTP Method	POST
Path	snap/v1.0/registration-card-unbind
Tipe Format	JSON
Authentication	OAuth 2.0 with Access Token

Request Structure

Field

Data Type

Mandatory

Length

Description

Example

token

String

M

560

Note :

SNAP BI

Length (128)

This is an alphanumeric field which contains the payment token used in a transaction.

This field is used during setting token daily limit, purchase, and delete token. This token represent token number of card or token.

VGLzrr8wdObHoYKbelJRx7FVwez

Response Structure & Sample

Field	Data Type	Mandatory	Length	Description	Example
responseCode	String	M	7	Response code	2000500
responseMessage	String	M	150	Response description	successful

Request & Response Payload Sample

Request type:


   '{
      "token": "VGLzrr8wdObHoYKbelJRx7FVwez"
    }'

Normal Response :

{
 "responseCode": "2000500",
 "responseMessage": "Successful"
}

Error Response :

{
    "responseCode": "4040511",
    "responseMessage": "Card Token Invalid"
}

List of Error/Response Code

HTTP Status	Service Code	Case Code	Status	Response Message
200	05	00	Success	Successful
400	05	01	Failed	Invalid Field Format [field request]
400	05	02	Failed	Invalid Mandatory Field [field request]
401	05	02	Failed	Invalid Customer Token
403	05	08	Failed	Card Expired
404	05	11	Failed	Card token invalid
409	05	00	Failed	Conflict
500	05	00	Failed	General Erorr
504	05	00	Pending	Timeout

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