QRIS Dinamis - CPM Inbound

Buat API

Permudah Bisnis Anda dengan BRIAPI

Tonton videonya dan lihat bagaimana BRIAPI dapat membuat bisnis Anda menjadi lebih efisien dengan Transfer Interbank BRI.

Buat API Sekarang

 

API Information

Title

QRIS Dinamis - CPM Inbound

Version

v1.0

URL Sandbox

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

URL Production

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

Version Control

Doc Version

API Version

Date

Link to document

Description
v1.0

v1.0

11 Mei 2022

Halaman ini

Baseline version.
v1.1 v1.0 21 September 2022 Halaman ini Perubahan response description pada code 40315 endpoint payment
v1.2 v1.0 28 September 2022 Halaman ini Perubahan status dan description untuk response timeout endpoint payment dan cancel payment
v1.3 v1.0 04 Oktober 2022 Halaman ini Penambahan kondisi pada bagian sequence diagram dan notes pada endpoint payment
v1.4 v1.0 13 December 2022 Halaman ini Perubahan maksimal lenght parameter partnerReferenceNo
v1.5 v1.0 13 September 2023 Halaman ini Penambahan kolom service code pada list response code Payment dan Cancel Paymen

 

Product Description

Product Overview

Dokumen ini bertujuan untuk menjelaskan spesifikasi API dari pengembangan QRIS Dinamis - CPM Inbound dengan skema nasabah mengeluarkan QRIS, merchant menggunakan alat untuk memindai / scan QRIS nasabah.

Alur untuk decode QR adalah sebagai berikut :

Endpoint

A. Get Token

Endpoint Description

Endpoint ini digunakan untuk mendapatkan access token yang berfungsi sebagai otentikasi saat ingin mengakses API yang lain. Pilot test pengecekan bahwa get token tidak dihit setiap kali mengakses endpoint (integrator)

 

General Information

HTTP Method

POST

Path

/snap/v1.0/access-token/b2b

Format Type

JSON

Authentication

Digital Signature

Header Structure

Key

Value

Format

Mandatory

Length

Deskripsi

Contoh

X-SIGNATURE

 

 

M

 

Dengan algoritma asymmetric signature SHA256withRSA

 

(Private_Key, stringToSign). stringToSign = client_ID + “|” + X-TIMESTAMP

 

X-CLIENT-KEY

 

Alphanumeric

M

 

Client’s client_id (Nama PJP) (diberikan pada saat proses registrasi selesai )

 

X-TIMESTAMP

 

Datetime

M

 

Waktu lokal klien saat ini yyyy-MM- ddTHH:mm:ss.SSSTZD format

 

Content-Type

application

/json

 

M

 

 

 

Request Structure

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

grantType

String

Alphabet

M

 

“client_credentials” : klien dapat meminta token akses hanya menggunakan kredensial kliennya ( atau cara otentikasi lain yang didukung) ketika klien meminta akses ke sumber daya yang dilindungi di bawah kendalinya (OAuth 2.0: RFC 6749 & 6750)

client_credentials

Response Structure

Field

Type Data

Format

Mandatory

Length

Deskripsi

Contoh

responseCode

String

Numeric

C

 

Response code

 

responseMessage

String

Alphabet

C

 

Response description

 

accessToken

String

Alphanumeric

M

 

Jenis token akses menyediakan klien dengan informasi yang diperlukan untuk berhasil menggunakan token akses untuk melindungi resource request (bersama dengan atribut tipe- spesifik) Tipe jenis token:

 

“Bearer”: termasuk token akses string saat request

“Mac”: mengeluarkan pesan kunci kode otentikasi (MAC) bersama dengan token akses yang digunakan untuk menandatangani komponen tertentu dari permintaan HTTP

 

Reference: OAuth2.0 RFC 6749 & 6750

 

tokenType

String

Alphabet

M

 

 

 

expiresIn

String

Alphanum eric

M

 

Sesi berakhir dalam hitungan detik : 900 (15 menit)

 

 

Request & Response Payload Sample

Request :

{
  "grantType": "client_credentials"
}

Normal Response :

{
   "accessToken": "jwy7GgloLqfqbZ9OnxGxmYOuGu85",
   "tokenType": "BearerToken",
   "expiresIn": "899"
}

Error Response :

{
   "responseCode": "4007301",
   "responseMessage": "Invalid Field Format"
}

 

List of Error/Response Code

HTTP Status

Response Code

Status

Response Description

Deskripsi

200

-

Success

-

 

400

4007300

Failed

Bad Request

 

400

4007301

Failed

Invalid Field Format

 

401

4017300

Failed

Unauthorized Client

 

401

4017300

Failed

Unauthorized stringToSign

 

401

4017300

Failed

Unauthorized Signature

 

401

4017301

Failed

Invalid Token (B2B)

 

500

500000

Failed

General Error

 

Setiap respon kesalahan yang tidak tercantum dalam daftar respon BRIAPI dianggap sebagai "pending" dan memerlukan penyelidikan lebih lanjut.

Signature

Signature memastikan data yang dikirimkan adalah asli dan tidak bisa disanggah. Signature dihasilkan oleh pemakai layanan dan diverifikasi oleh penerima layanan

Signature dibentuk dari payload yang sudah ditentukan, dengan mengimplementasikan algoritma HMAC_SHA512 dengan clientSecret sebagai kuncinya.

 

Payload

Payload tergabung dari verb, path, token, timestamp, and body. Dengan format Symetric-Signature:

HMAC_SHA512(clientSecret, stringToSign) with formula stringToSign = HTTPMethod+”:“+ EndpointUrl +":"+ AccessToken+":“

+ Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ +TimeStamp

Contoh:

http://post/snap/v1.0/dummy:muhpwhwOkPRU9nNXYnyYHj8t54x3:8b4e9e83b5231cff4f84358ec8ca81951cfe9f999f635b1566452a501d5c23b2:2021-11-29T09:22:18.172+07:00

Detail setiap elemen di dalam payload dijelaskan di bawah ini:

 

Path

Value pada path yaitu URL setelah hostname dan port tanpa Query Parameter

Contoh:

https://sandbox.partner.api.bri.co.id/qr/qr-cpm-payment

 

Verb

Method HTTP dengan menggunakan huruf kapital.

Example: GET, POST, PUT, PATCH, and DELETE.

 

Token

Token yang dipakai di header Authorization.

Bearer R04XSUbnm1GXNmDiXx9ysWMpFWBr

 

Timestamp

Waktu saat mengirimkan request API. Format waktu harus mengikuti ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ). Harus dalam zero UTC offset.

Contoh:

2021-11-02T13:14:15.678+07:00

 

Body

Body saat mengirimkan request API. Lowercase(HexEncode(SHA-256(minify(RequestBody))))

Example: {"hello": "world"}

Result SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749

Jika tidak terdapat body request, contoh menggunakan metode GET, biarkan saja kosong.

Contoh:

&body=

Reference: https://developers.bri.co.id/id/snap-bi/apidocs-oauth-snap-bi

B. Payment QR CPM Dinamis

Endpoint Description

API Payment QR CPM Dinamis digunakan untuk melakukan transaksi QR CPM dinamis.

*Catatan: Apabila saat melakukan pembayaran QR mendapatkan response Timeout atau tidak mendapat response sama sekali dari BRI, kami sarankan untuk melakukan permintaan reversal melalui endpoint Cancel Payment pada point B

 

General Information

HTTP Method

POST

Path

/v1.0/qr-dynamic-cpm/qr-cpm-payment

Format Type

JSON

Authentication

OAuth 2.0

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-EXTRENAL-ID   Numeric M 36x  

Request Structure

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

partnerReferenceNo

String

(Numeric)

M

12

Nomor identifikasi transaksi pada sistem layanan konsumen

092783527859

qrContent

String

M

512

QR String CPM (base64)

8505XXXXXXX

amount

Object

M

 

Detail isian dari object amount terdapat pada tabel dibawah ini

 

 

Object

C

 

Detail isian dari object feeAmount terdapat pada tabel dibawah ini

 

merchantId

String

M

64

ID unik yang dimiliki setiap merchant

9360000200101145436

subMerchantId

String

O

32

ID unik yang dimiliki oleh submerchant

7612736352

externalStoreId

String

O

64

ID unik yang dimiliki oleh toko eksternal

asdasd

expiryTime

Numeric

M

25

Waktu kadaluwarsa QR CPM

(ISO-8601)

default value 5 minutes

merchantName

String

M

64

Nama merchant

TOKO IDOLA

merchantLocation

String

M

64

Lokasi merchant

BANYUWANGI
terminalId String M 32 ID Terminal asjkdhaskjdhaksjhd812836732 3623
additionalInfo Object     Detail isian dari object additionalInfo terdapat pada tabel dibawah ini  

Request Structure dalam Object "amount"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

value

Sting

M

18

Jumlah bersih dari transaksi. Jika itu IDR maka nilainya termasuk 2 angka desimal. misalnya Rp 10.000,- akan ditempatkan dengan 10000.00

1200.00

currency

String

M

3

3 digit kode ISO Currency

IDR

Request Structure dalam Object "feeAmount"

Field

Data Type

Mandatory

Length

Description

Example

value

String

M

18

Jumlah bersih dari transaksi. Jika itu IDR maka nilainya termasuk 2 angka desimal. misalnya Rp 10.000,- akan ditempatkan dengan 10000.00

 

currency

String

M

3

3-digit kode ISO Currency

 

Request Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

deviceId

String

O

64

ID unik perangkat

7162335125312

channel

String

O

 

Channel perangkat

mobilephone

processingCode

String

M

6

Kode untuk penanda source

266000
cpan String M   CPAN 5A0A9360000210000906432F
channelId String M   ID Channel 1231231
customerName String M   Nama konsumen PI04Q001CD30JOKOWI____ MC03UME
approvalCode String M   Kode approval 222334555

Response Structure

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

responseCode

String

M

7

Kode response 

HTTP Response + Service Code + Response Code

2006000

responseMessage

String

M

150

Deskripsi

Successful
referenceNo String C 64 Nomor identifikasi transaksi pada sistem penyedia layanan. Harus diisi setelah transaksi berhasil 828233404852
partnerReferenceNo String O 64 Nomor identifikasi transaksi pada sistem layanan konsumen 092783527859
transactionDate yyyyM MddH Hmmss O 255 Waktu transaksi ISO-8601 2022-05-13T14:58: 22+07:00
additionalInfo Object O   Isian dari Object additionalInfo ini dijelaskan pada tabel di bawah  

Request Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

deviceId

String

O

64

ID unik perangkat

7162335125312

channel

String

O

 

Channel perangkat 

mobilephone
invoiceNumber String O 20 Nomor invoice 10010173191001017319

Request & Response Payload Sample

Request :

{
 "partnerReferenceNo": "092783527859",
 "qrContent": "8505435056303161624F07A000000602202050075152495343504D5A0A9360000210000906432F5F200A534F455249
504E4F2E485F2D046964656E5F501B6D61696C746F3A72616E656D61696C343840676D61696C2E636F6D9F25020643630B9F740836343239
61623664",
 "amount": {
 "value": "1200.00",
 "currency": "IDR"
 },
 "feeAmount": {
 "value": "",
 "currency": ""
 },
 "merchantId": "9360000200101145436",
 "subMerchantId": "7612736352",
 "externalStoreId": "asdasd",
 "expiryTime": "60",
 "merchantName": "TOKO IDOLA",
 "merchantLocation": "BANYUWANGI",
 "terminalId": "asjkdhaskjdhaksjhd8128367323623",
 "additionalInfo": {
 "deviceId": "12345679237",
 "channel": "mobilephone",
 "proccesingCode": "266000",
 "cpan": "5A0A9360000210000906432F",
 "channelId": "1231231",
 "customerName": "PI04Q001CD30JOKOWI____MC03UME",
 "approvalCode": "222334555"
 }
}

Normal Response :

{
 "responseCode": "2006000",
 "responseMessage": "Successful",
 "referenceNo": "828233404852",
 "partnerReferenceNo": "092783527859",
 "transactionDateTime": "2022-05-13T14:58:22+07:00",
 "additionalInfo": {
 "deviceId": "7162335125312",
 "channel": "mobilephone",
 "invoiceNumber": "10010173191001017319"
 }
}

 

Error Response :

{
 "responseCode": "4096001",
 "responseMessage": "Duplicate partnerReferenceNo"
}

 

List of Error/Response Code

 

HTTP Status

Service Code

Code

Status

Response Description

Deskripsi

200

60

00

Success

Successful

Sukses melakukan transaksi QR CPM dinamis.

202

60

00

Gagal

Transaction still on process

Error karena payment belum di proses / gagal

400

60

01

Gagal

Invalid Field Format {field name}

Error karena format tidak sesuai

400

60

02

Gagal

Invalid Mandatory Field {field name}

Gagal karena terdapat parameter mandatory yang tidak sesuai

403

60

03

Gagal

Exceeds Transaction Amount Limit

Error karena nominal melebihi limit

403

60

14

Gagal

Insufficient Funds

Saldo tidak cukup
403 60 15 Gagal
  • Transaction Not Permitted. Invalid Transaction
  • Transaction Not Permitted. Transaction can't be specified.
  • Transaction Not Permitted. Transaction Already Exist or Not Found.

Error karena transaksi tidak ditemukan:

  • Transaksi tidak sesuai
  • Transaksi tidak dapat ditentukan
  • QR sudah dilakukan pembayaran, tidak ditemukan atau expired

404

60

01

Gagal

 Transaction not found Error karena transaksi tidak ditemukan
404 60 04 Gagal Transaction Cancelled Error karena transaksi dibatalkan oleh customer
404 60 08 Gagal Invalid Merchant Error karena merchant tidak sesuai
404 60 13 Gagal Invalid Amount Error karena jumlah tidak sesuai
404 60 14 Gagal Paid Bill Error karena transaksi sudah terbayarkan
500 60 01 Gagal Internal Server Error Internal Server Error
504 60 00 Pending Timeout Transaksi yang dilakukan bisa jadi sukses atau gagal, disarankan cek rekening koran/info mutasi dan melakukan cancel payment jika transaksi ingin digagalkan.

Setiap respon kesalahan yang tidak tercantum dalam daftar respon BRIAPI dianggap sebagai "pending" dan memerlukan penyelidikan lebih lanjut.

C. Cancel QR CPM Dinamis

Endpoint Description

API Cancel QR CPM Dinamis digunakan untuk melakukan cancel payment QR CPM dinamis.

 

General Information

HTTP Method

POST

Path

/v1.0/qr-dynamic-cpm/qr-cpm-cancel

Type Format

JSON

Authentication

OAuth 2.0

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-EXTRENAL-ID   Numeric M 36  

Request Structure

Field

Data Type

Mandatory

Length

Description

Example

originalPartnerReferen ceNo

String

(Numeric)

M

12

Nomor identifikasi transaksi asli pada sistem layanan konsumen

092783527859
originalReferenceNo String O 64 Nomor identifikasi transaksi asli pada sistem penyedia layanan 828233404852  
originalExternalId String O 32 ExternalID asli pada pesan header 3044378693072272646328009 7920913  
merchantId String M 64 ID unik yang dimiliki setiap merchant 9360000200101145436  
subMerchantId String O 32 ID Sub merchant 7612736352  
externalStoreId String O 64 D Toko eksterna asdasd  
amount Object M   Detail isian dari object amount terdapat pada tabel dibawah ini    
reason String M 512 Alasan melakukan cance Cancel reason  
additionalInfo Object O   Detail isian dari object additionalInfo terdapat pada tabel dibawah ini    

Request Structure dalam Object "amount"

Field

Type Data

Mandatory

Length

Description

Example

value

Decimal

M

18

Jumlah bersih dari transaksi. Jika itu IDR maka nilainya termasuk 2 angka desimal. misalnya Rp 10.000,- akan ditempatkan dengan 10000.00

1200.00

 

currency

String

M

3

3-digit code ISO Currency

IDR

 

Request Structure dalam Object "additionalInfo"

Field

Type Data

Mandatory

Length

Description

Example

deviceId

String

O

64

 ID unik perangkat

12345679237

 

channel

String

O

 

Channel perangkat

mobilephone

Response Structure

Field

Type Data

Mandatory

Length

Description

Example

responseCode

String

M

7

Kode response 

HTTP Response + Service Code + Response Code

2006200

 

responseMessage

String

M

150

Deskripsi response 

Successful
originalPartnerReferenceNo String O 64 Nomor identifikasi transaksi pada sistem layanan konsumen 092783527859
originalReferenceNo String O 64 Nomor identifikasi transaksi pada sistem penyedia layanan. Harus diisi setelah transaksi berhasil 828233404852
originalExternalId String O 32 ExternalID asli pada pesan header 30443786930722726463 280097920913
additionalInfo Object O   Detail isian dari object additionalInfo terdapat pada tabel dibawah ini  
cancelTime String M  

Waktu cancel dilakukan

ISO-8601 format

 2022-04-19T09:48:07+07: 00
transactionDate String O  

Waktu transaksi

ISO-8601 format

 2022-04-18T17:55:11+07: 00

Request Structure dalam Object "additionalInfo"

Field

Type Data

Mandatory

Length

Description

Example

deviceId

String

O

64

 ID unik perangkat

12345679237

 

channel

String

O

 

Channel perangkat

mobilephone

Request & Response Payload Sample

Request :

{
 "originalPartnerReferenceNo": "092783527859",
 "originalReferenceNo": "828233404852",
 "originalExternalId": "30443786930722726463280097920913",
 "merchantId": "9360000200101145436",
 "subMerchantId": "7612736352",
 "externalStoreId": "asdasd",
 "amount": {
 "value": "1200.00",
 "currency": "IDR"
 },
 "reason": "cancel reason",
 "additionalInfo": {
 "deviceId": "12345679237",
 "channel": "mobilephone"
 }
}

Normal Response :

{
 "responseCode": "2006200",
 "responseMessage": "Successful",
 "originalReferenceNo": "092783527859",
 "originalPartnerReferenceNo": "828233404852",
 "originalExternalId": "30443786930722726463280097920913",
 "additionalInfo": {
 "deviceId": "12345679237",
 "channel": "mobilephone"
 },
 "cancelTime": "2022-04-19T09:48:07+07:00",
 "transactionDate": "2022-04-18T17:55:11+07:00"
}

Error Response :

{
 "responseCode": "4046201",
 "responseMessage": "Transaction Not Found"
}

 

List of Error/Response Code

HTTP Status

Service Code

Code

Status

Response Description

Description

200

62

00

 Success

Successful

 Sukses melakukan cancel payment QR CPM dinamis

202

62

00

Failed

Transaction still on process

 Error karena payment belum di proses / gagal

400

62

01

Failed

Invalid Field Format {field name}

 Error karena format tidak sesuai

400

62

02

Failed

Invalid Mandatory Field {field name}

 Gagal karena terdapat parameter mandatory yang tidak sesua

403

62

02

Failed

Exceeds Transaction Amount Limit

 Error karena nominal melebihi limi

403

62

15

Failed
  • Transaction Not Permitted. Invalid Transaction
  • Transaction Not Permitted. Transaction can't be specified.
  • TransactionNot Permitted. QR Expired
  • Transaction Not Permitted. Transaction already exist.

Error karena transaksi tidak diizinkan, ketika :

  • Transaksi tidak sesuai
  • Transaksi tidak dapat ditentukan
  • QR has expired.
  • Transaksi sudah ada

404

62

01

Failed

Transaction not found

 Error karena transaksi tidak ditemukan

404

62

04

Failed

Transaction Cancalled

 Error karena transaksi di batalkan oleh customer
404 62 08 Failed Invalid Merchant Error karena merchant tidak sesuai
404 62 13 Failed Invalid Amount

Error karena jumlah tidak sesuai

Note: Amount reversal harus sesuai dengan amount payment sebelumnya
404 62 14 Failed Paid Bill Error karena transaksi sudah terbayarkan
500 62 01 Failed Internal Server Error Internal Server Error
504 62 00 Pending Timeout Cancel payment bisa sukses atau gagal dimana transaksi tetap terbuku, disarankan untuk melakukan pengecekan lebih lanjut melalui rekening koran/info mutasi

List Processing Code

Value Description
260000  Payment Credit from Unspecified Acct
261000 Payment Credit from Savings Acct
262000 Payment Credit from Current Acct
263000 Payment Credit from Credit Acct
266000 Payment Credit from e-Purse Acct
200000 Refund from Unspecified Acct
200010 Refund from Savings Acc
200020 Refund from Current Acct
200030 Refund from Credit Acct
200060 Refund from e-Purse Acct
000000 Payment Debit from Unspecified Acct
001000 Payment Debit from Savings Acct
002000 Payment Debit from Current Acct
003000 Payment Debit from Credit Acct
006000 Payment Debit from e-Purse Acct

Setiap respon kesalahan yang tidak tercantum dalam daftar respon BRIAPI dianggap sebagai "pending" dan memerlukan penyelidikan lebih lanjut.