Dokumentasi APIDOCS Registration SNAP BI

Informasi API

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

Version Control

Doc Version	API Version	Tanggal	Link Dokumen	Deskripsi
v1.0	v1.0	07 Feb 2024	Disini	Baseline version
v1.1	v2.0	15 Feb 2024	Halaman ini	Update Details : Naik Version dari v1.0 menjadi v2.0 Endpoint Card Registration Response referenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O) Response bankCardToken : Penambahan Mandatory M Endpoint OTP Verify Request originalReferenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O) Response originalReferenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O) Update Request and Response Sample in endpoint Card Registration, OTP Verify dan Card Unbinding

Doc Version

API Version

Tanggal

Link Dokumen

Deskripsi

v1.0

07 Feb 2024

Disini

Baseline version

v1.1

v2.0

15 Feb 2024

Halaman ini

Update Details :

Naik Version dari v1.0 menjadi v2.0
Endpoint Card Registration
- Response referenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O)
- Response bankCardToken : Penambahan Mandatory M
Endpoint OTP Verify
- Request originalReferenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O)
- Response originalReferenceNo : Mandatory dari M menjadi M Notes : SNAP BI (O)
Update Request and Response Sample in endpoint Card Registration, OTP Verify dan Card Unbinding

Deskripsi Produk

Catatan : OTP dan Notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp

Gambaran Produk

API Registration (Registrasi) diperlukan agar Konsumen dapat melakukan pengaitan datanya untuk melakukan layanan transaksi pembayaran atau mengakses data miliknya. Data-data yang dikaitkan ini dapat beragam tergantung kebutuhan, seperti data kartu debit, kartu kredit, atau rekening.

Header Structure

Key	Value	Format	Mandatory	Length	Deskripsi
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

Endpoint ini digunakan untuk melakukan pembuatan data kartu nasabah/konsumen.

Catatan : Card token yang diperoleh memiliki masa aktif sesuai dengan masa aktif kartu yang akan di binding

General Information

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

Request Structure

Field	Data Type	Format	Mandatory	Length	Deskripsi	Contoh
phoneNo	String	Numeric	M Note : SNAP BI (O)	15 Note : SNAP BI Length (16)	Nomor telpon pengguna Format: 62xxxxxxxxxxxxx	62812345678
custIdMerchant	String	Alphanumeric	M	18	Merchant’s ID pengguna	0012345679504
cardData	Encrypted Object				Merujuk pada standar Enkripsi Simetris pada Dokumen Standar Keamanan bagian 2.1.9
bankCardType	String	Alpha	M	2	Tipe kartu (D – Debit, C –Credit, UE – Uang Electronik).	D
bankCardNo	String	Numeric	M	16 Note : SNAP BI Length (19)	Nomor kartu	221843000100021
identificationNo	String	Numeric	O	64	Customer’s ID number	2849238f02938402
identificationType	String	Numeric	O	2	Tipe ID (01 - passport, 02 – eKTP&KTP, 03-TKTP, 04- SIM (Lisensi Mengemudi), 99 – Others)	02
email	String	Alphanumeric	M Note : SNAP BI (O)	50 Note : SNAP BI Length (254)	RFC 3696 Length 254 after “<” and “>”	foo.bar@baz.com
expiryDate	String	Numeric	M	4	Tanggal Kadaluarsa kartu. Format : MMYY	1022

Response Structure & Sample

Field	Data Type	Format	Mandatory	Length	Deskripsi	Contoh
responseCode	String	Numeric	M	7	Respon Kode	2000100
responseMessage	String	Alpha	M	150	Respon Deskripsi	Successful
chargeToken	String	Alphanumeric	M Notes : SNAP BI (O)	45 Notes : SNAP BI Length (40)	kode string untuk verifikasi OTP	abcd63617264746f6b656e
bankCardToken	String	Alphanumeric	M (for card type response)	560 Notes : SNAP BI Length (128)	Card token untuk pembayaran	6d796361 7264746f 6b656e
referenceNo	String	Numeric	M Notes: SNAP BI (O)	12 Notes : SNAP BI Length (64)	Transaction identifier on service provider system. harus dilengkapi setelah transaksi berhasil	2020102977770000000009

Request & Response Payload Sample

Untuk melakukan enkripsi terhadap card data, gunakan Standar Symmetric Encryption (AES-256-cbc) dengan Client Secret sebagai encryption key yang sudah dienkripsi dengan MD5.

Pada AES-256-cbc membutuhkan inisialization vector yang mana berisi client secret tanpa dihash MD5. Output dari enkripsi (AES-256-cbc) ini berformat hex encoded. Komponen - komponen yang ada pada (AES-256-cbc) seperti pada tabel berikut :

No.	Komponen	Contoh
1.	Plain text	{ "bankCardType":"D", "bankCardNo":"5221843000100021", "identificationNo": "1234567", "identificationType":"02", "email":"foo.bar@baz.com", "expiryDate":"1010" }
2.	Initialization Vector	rQpLmMkB4p2zYUQG
3.	Encryption key	00099531c1839c0a0d48fd2d93b271f1

No.

Komponen

Contoh

1.

Plain text

{

"bankCardType":"D",

"bankCardNo":"5221843000100021",

"identificationNo": "1234567",

"identificationType":"02",

"email":"foo.bar@baz.com",

"expiryDate":"1010"

}

2.

Initialization Vector

rQpLmMkB4p2zYUQG

3.

Encryption key

00099531c1839c0a0d48fd2d93b271f1

Untuk melakukan enkripsi dapat merujuk ke link berikut https://www.javainuse.com/aesgenerator

Request :

{
   "cardData":"a7ccf48471c041948b0efa921492fa0bcfe58dade682bf6251cb9ab77a52003b0dc6acbac31124fefa8b911d2f57e48d7cefec12b8eefd33339295b506c9692b23f0a1dd17de24e0504085433b32bbd95454de7ef7abe00ac81a19d0a1341785a9063ddc92360ab926558c9c4fedb889",
   "custIdMerchant":"78678687613",
   "phoneNo":"6281234833767"
}

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_YIBK6F6OBBJBIQ5D6NS6WJZRYFGSNDGB::3767",
   "bankCardToken":"",
   "referenceNo":"286749703117"
}

Error Response :

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

List of Error/Response Code

HTTP Status	Service Code	Case Code	Status	Response Message	Deskripsi
200	01	00	Sukses	Successful
400	01	01	Gagal	Invalid Field Format [field request]	Format tidak valid
400	01	02	Gagal	Invalid Mandatory Field [field request]	Format field mandatory tidak valid atau hilang
403	01	03	Gagal	Suspected Fraud
403	01	07	Gagal	Card Blocked
403	01	08	Gagal	Card Expired
403	01	09	Gagal	Dormant Account
403	01	18	Gagal	Inactive Card/Account/Customer
404	01	11	Gagal	Card Information Invalid	informasi kartu tidak valid, atau rekening kartu masuk daftar hitam.
409	01	01	Gagal	Conflict
429	01	00	Gagal	Too Many Requests
504	01	00	Pending	Timeout

Seluruh response error yang tidak tercantum dalam list response BRIAPI memiliki status pending dan perlu dilakukan pengecekan.

B. Verify OTP

Endpoint ini digunakan untuk melakukan verifikasi pada saat pembuatan maupun penghapusan data kartu nasabah/konsumen

Catatan: OTP dan Notifikasi (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp

General Information

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

Request Structure

Field	Data Type	Format	Mandatory	Length	Deskripsi	Contoh
originalReferenceNo	String	Numeric	M Notes ; SNAP BI (O)	64	Identifikasi transaksi pada sistem penyedia layanan	2020102977770000000009
otp	String	Numeric	M Note : SNAP BI (O)	6 Note : SNAP BI Length (8)	Kode OTP / Kata Sandi	123456
chargeToken	String	Alphanumeric	M Note : SNAP BI (O)	50 Note : SNAP BI Length (40)	Kode string OTP yang akan diverifikasi dengan kode sandi yang diperoleh pengguna	TOK_TKN CPPPHUV L3IJVAXZ I5GG4WB EC77YZ6: :ADVQ
type	String	Alpha	M Note : SNAP BI (O)	20	value "card" untuk card registration dan "payment" untuk direct debit payment	card/payment
additionalInfo	Object		O		Informasi Tambahan
>bankCardToken	String	Alphanumeric	M for type payment	560 Note : SNAP BI Length (128)	Card token untuk pembayaran	6d7963617264746f6b656e

Response Structure & Sample

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
responseCode	String	M	7	Respon Kode	2000400
responseMessage	String	M	150	Respon Deskripsi	Successful
bankCardToken	String	M ( Untuk respon tipe Card ) Note : SNAP BI (O)	560 Note : SNAP BI Length (128)	Card token untuk pembayaran	6d796361 7264746f6b656e
email	String	M ( Untuk respon tipe Card ) Note : SNAP BI (O)	50 Note : SNAP BI Length (254)	RFC 3696 Length 254 after “<” and “>”	foo.bar@baz.com
phoneNo	String	M ( Untuk respon tipe Card ) Note : SNAP BI (O)	15 Note : SNAP BI Length (16)	Nomer telpon pelanggan Format: 62xxxxxxxx xxxxx	6289912345678
originalReferenceNo	String	M Note : SNAP BI (O)	64	Identifikasi transaksi pada sistem penyedia layanan. Harus diisi setelah transaksi berhasil	2020102977770000 000009
originalPartnerReferenceNo	String	M ( Untuk respon tipe Payment ) Note : SNAP BI (O)	64	Identifikasi transaksi pada sistem layanan pelanggan	1233
additionalInfo	Object	O		Informasi tambahan
>amount	String (ISO4217)	M ( Untuk respon tipe Payment )	15,2 Note : SNAP BI Length (16,2)	Jumlah transaksi yang akan dibayarkan menggunakan metode pembayaran ini apabila dalam rupiah maka nilainya termasuk 2 digit desimal. misalnya RP 10.000, akan ditempatkan dengan 10000.00	2000000.00
>currency	String	M ( Untuk respon tipe Payment )	3	Mata uang	IDR
>lastFour	String	M ( Untuk respon tipe Card )	4	4 digit terakhir kartu	5566
>debitCardType	String	M ( Untuk respon tipe Card )	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":"819826771321",
   "otp":"999999",
   "chargeToken":"TOK_RM5AW2RI3XJMYJHMCQGIS3RQTGN47JGK::2767",
   "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":"card_.eyJpYXQiOjE3MDc5NjYxNzUsImlzcyI6IkJhbmsgQlJJIC0gRENFIiwianRpIjoiMTIyNGZjMjAtMzg3Yy00NzQzLThkMmEtMzNmY2Q2N2NmODIxIiwicGFydG5lcklkIjoi77-9Iiwic2VydmljZU5hbWUiOiJERF9FWFRFUk5BTF9TRVJWSUNFIn0.JkGmWF9B1EQQpwuY5vmiCpO5Emh7_31k9kHVKpQkJNG5GFC1xXsGK7OGeWl3xJPWKZneKCGbRaFuM_-uO_MJMRf9pxU8gnAASlKeyMfgJ80HWoxyAj8SuqRHyHkWC6iVW7gGNKY9ZZKRkWh5Ba2ujqn_yCb9dSFeVqhBKp9WfY7KvFRpj8B1L-abeQCnsVaUg3yrxeXvq4nq1VflItKoFuzjImgRdz2i8cu39dUCsKTfmMv09P_HVoqPze5C3pmaN0QUdMcNQYFdZVDatRhBbLq3OjC0AbtP3_F-c8Of0CzRr0DtqvijG9KeqXchhUELgHbHIz4zSEJuIwX8_BUHRA",
   "email":"bebas@gmail.com",
   "phoneNo":"6281234832767",
   "originalReferenceNo":"819826771321",
   "additionalInfo":{
      "lastFour":"3691",
      "debitCardType":"PVRGLR"
   }
}

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	Deskripsi
200	04	00	Success	Successful
400	04	01	Failed	Invalid Field Format	Format tidak valid
400	04	02	Failed	Invalid Mandatory Field	Format field mandatory tidak valid atau hilang
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. (Gagal mengirimkan OTP)
403	04	12	Failed	OTP Lifetime Expired
403	04	15	Failed	Transaction Not Permitted [Reason]	Transaction Not Permitted. originalReferenceNo does not match (referenceNo dan registrationToken tidak match)
404	04	15	Failed	Invalid OTP	OTP Salah
409	04	00	Failed	Conflict
500	04	00	Failed	General Erorr
504	04	00	Pending	Timeout

Seluruh response error yang tidak tercantum dalam list response BRIAPI memiliki status pending dan perlu dilakukan pengecekan.

C. Card Registration Unbinding

Endpoint ini digunakan untuk melakukan penghapusan data kartu nasabah / konsumen

General Information

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

Request Structure

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

token

String

M

560

Note :

SNAP BI

Length (128)

Ini adalah bidang alphanumber IC yang berisi token pembayaran yang digunakan dalam transaksi. Kolom ini digunakan saat menetapkan batas harian token, pembelian, dan penghapusan token. Token ini mewakili nomor token dari kartu atau token.

VGLzrr8wdObHoYKbelJRx7FVwez

Response Structure & Sample

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
responseCode	String	M	7	Respon Kode	2000500
responseMessage	String	M	150	Respon Deskripsi	successful

Request & Response Payload Sample

Request type:

{
   "token":"card_.eyJpYXQiOjE3MDc5ODExMjcsImlzcyI6IkJhbmsgQlJJIC0gRENFIiwianRpIjoiNDQ1ZjUwN2MtNzdlOS00NTI5LWExZjUtYjgwYWEzNjRiNjI3IiwicGFydG5lcklkIjoi77-9Iiwic2VydmljZU5hbWUiOiJERF9FWFRFUk5BTF9TRVJWSUNFIn0.nqrdTeBmgDXUvA4B3OrAff4R2irCPB3TFimTh9brW-hHg-bY06opdncbcrtpChio4_b9ra5k1PzSxYUvGl8P76gtBOuaNqUMqMF8dUgwWLVyIuwCSUyMb8KED3wjP6gviEAwAv46rJE4ssK6LLPaTK44dbFvfnO3QDOeOveWdu_3GmsTW8sH5IPdvql_RrBFRhz6ynF0HfD3pdOr4KXmbSD-Y7S3BuzP0U7R9yYDcx4NT5yq_ynGkOt3uM1M1U-e1DyaXgLYh9aci9gGO3fXT-KNjmGUKUBip0TCwQNmrOCAgiNTGG_Z_RQeST0DGKjR_UMvDdZAb8WQCEWJEcqkBQ"
}

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	Gagal	Invalid Field Format [field request]
400	05	02	Gagal	Invalid Mandatory Field [field request]
401	05	02	Gagal	Invalid Customer Token
403	05	08	Gagal	Card Expired
404	05	11	Gagal	Card token invalid
409	05	00	Gagal	Conflict
500	05	00	Gagal	General Erorr
504	05	00	Pending	Timeout

Seluruh response error yang tidak tercantum dalam list response BRIAPI memiliki status pending dan perlu dilakukan pengecekan.