APIDOCS Registration SNAP BI

Buat API

Informasi API

Judul

API Registration SNAP BI

Versi

v1.0

URL Sandbox

https://sandbox.partner.api.bri.co.id

URL Production

  

Version Control

Versi Dok

Versi API

Tanggal

Tautan Dokumen

Deskripsi

v1.0

v1.0

2 Desember 2021

Halaman ini.

Baseline version

v2.0

v1.0

21 April 2022

Halaman ini

Update field format

v3.1

v1.0

26 Oct 2022

Halaman ini

Menambahkan RC 4030406 "Feature Not Allowed At This Time. [Reason]" pada endpoint Verify OTP

v3.2

 v1.0

07 Feb 2023

Halaman ini

Menambahkan catatan bahwa "OTP dan notif (Binding dan Payment) yang sebelumnya dikirimkan melalui SMS akan dikirimkan melalui Whatsapp" pada Deskripsi Produk dan Endpoint Verify OTP. 

v3.3

v1.0

23 Jun 2023

Halaman ini

Menambahkan 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

Halaman ini

Update mandatory untuk field expiryDate field from O menjadi M pada endpoint Card Registration

*Notes
 Perubahan ini berlaku mulai tanggal 14 Agustus 2023

Deskripsi Produk

Catatan: OTP dan Notifikasi (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.

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 : Token kartu yang didapatkan memiliki masa aktif mengikuti masa berlaku kartu.

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

Deskripsi

Contoh

phoneNo

String

Numeric

M

Note :

SNAP BI

(O)

15

Note :

Length

SNAP BI

(16)

Nomor telpon pengguna Format: 62xxxxxxxx xxxxx

6289912345678

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 : Length SNAP BI (19)

Nomor kartu

221843000100021

identificationNo

String

Numeric

O

64

Customer’s ID number

284923840902938402

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 :

Length

SNAP BI

(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

responseMessage

String

Alpha

M

150

Response deskripsi

successful

responseCode

String

Numeric

M

7

Response code

2000100

chargeToken

String

Alphanumeric

M

Note : SNAP BI (O)

45

Note : Length SNAP BI (40)

kode string untuk verifikasi OTP

abcd63617264746f6b656e

referenceNo

String

Numeric

M

Note:

SNAP BI (

C)

12

Note :

Length

SNAP BI

(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

Note :

Untuk melakukan enkripsi dapat merujuk ke link berikut https://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":"5221123456789101", 
       "identificationNo":"284923840902938402". 
       "identificationType":"02", 
       "email":"foo.bar@baz.com", 
       "expiryDate":"1010" 
}

Normal Response :

   {
        "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 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 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 Request  
504 01 00 Pending    
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/v1.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

64

Identifikasi transaksi pada sistem penyedia layanan

2020102977770000 000009

otp

String

Numeric

M

Note : SNAP BI (O)

6

Note : Length SNAP BI (8)

Kode OTP/Kode Sandi

12345678

chargeToken 

String

Alphanumeric

M

Note : SNAP BI (O)

50

Note: Length SNAP BI (40)

Kode string OTP yang akan diverifikasi dengan kode sandi yang diperoleh pengguna

TOK_TKN CPPPHUV L3IJVAXZ I5GG4WB EC77YZ6: :ADVQ

type

String

Alpha

M

Notes : SNAP BI (O)

20

Value "card" untuk card registration dan "payment" untuk direct debit payment

kartu/pembayaran

additionalInfo

Object

 

O

 

Informasi tambahan

 

>bankCardToken

String

Alphanumeric

M

for type payment

560

Note : Length SNAP BI (128)

Card token untuk pembayaran

6d7963617264746f6b656e

Response Structure & Sample

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

responseMessage

String

Alpha

M

150

Response deskripsi

Successful

responseCode

String

Numeric

M

7

Response code

2000000

bankCardToken

String

Alphanumeric

M

(Untuk respon tipe Card)

Note :

SNAP BI (O)

560

Note : Length SNAP BI (128)

Card token untuk pembayaran

6d7963617264746f6b656e

email

String

Alphanumeric

M

(Untuk respon tipe Card)

Note :

SNAP BI (O)

50

Note : Length SNAP BI (254)

RFC 3696 Length 254 after “<” and “>”

foo.bar@baz.com

phoneNo

String

Numeric

M

(Untuk

respon tipe

Card)

Note :

SNAP BI (O)

15

Note :

Length

SNAP BI (16)

Nomer telpon pelanggan Format: 62xxxxxxxx xxxxx

6289912345678

originalReferenceNo

String

Numeric

M

Note :

SNAP BI (C)

64

Identifikasi transaksi pada sistem penyedia layanan. Harus diisi setelah transaksi berhasil

2020102977770000000009

originalPartnerReferenceNo

String

Alphanumeric

M

(Untuk respon tipe Payment)

Note :

SNAP BI (O)

64

Identifikasi transaksi pada sistem layanan pelanggan

1233

additionalInfo

Object

 

O

 

Informasi tambahan

 

>amount

String (ISO421 7)

Numeric

M

(Untuk respon tipe Payment)

15,2

Note : Length SNAP BI (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

Alpha

M

(Untuk respon tipe Payment)

3

Mata uang

IDR

>lastFour

String

Numeric

M

(Untuk respon tipe Card)

4

4 digit terakhir kartu

5566

>debitCardType

String

Alpha

M

(Untuk respon tipe Card)

10

ada 6 tipe kartu: PVRGLR, PVGOLD, PVPLAT, RGLR, GOLD, PLAT

PVGOLD

>merchentTrxId

String

Alphanumeric

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 :

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

Respone 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

Sukses

Successful

  

400

04

01

Gagal

Invalid Field Format

Format tidak valid

400

04

02

Gagal

Invalid Mandatory Field 

Format field mandatory tidak valid atau hilang

401

04

02

Gagal

Invalid Customer Token

  

403

04

02

Gagal

Exceeds Transaction Amount Limit 

  

403

04

06

Gagal

Feature Not Allowed At This Time. [Reason]

 Feature Not Allowed At This Time. Send OTP Failed. (Gagal mengirimkan OTP)

403

04

12

Gagal

 OTP Lifetime Expired 

 

403

04

15

Gagal

 Transaction Not Permitted.[Reason] Transaction Not Permitted. originalReferenceNo does no match (reference No dan registrationToken tidak match)
404 04 15 Gagal Invalid OTP OTP Salah
409 04 00 Gagal Conflict  
500 04 00 Gagal General Erorr  
504 04 400 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/v1.0/registration-card-unbind

Tipe Format

JSON

Authentication

OAuth 2.0 with Access Token

Request Structure

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

token

String

Alphanumeric

M

560

Note : Length SNAP BI (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.

VGLzrr8wd ObHoYKbe lJRx7FVwez

Response Structure & Sample

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

responseMessage

String

Alpha

M

150

Respon deskripsi

successful

responseCode

String

Numeric

M

7

Respon Kode

2000500

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

Deskripsi

200

05

00

Sukses

Successful

  

400

05

01

Gagal

Invalid Field Format

  

400

05

02

Gagal

Invalid Mandatory Field

  

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