Dokumentasi QRIS Merchant Presented Mode (MPM) Dinamis

Informasi API Information

Title	QRIS Merchant Presented Mode (MPM) Dinamis
Version	v1.1
URL Sandbox	https://sandbox.partner.api.bri.co.id/
URL Production	https://partner.api.bri.co.id/

Kendali Versi

Doc Version	API Version	Date	Link to document	Deskripsi
v1.0	v1.0	11 Mei 2022	Halaman ini	Versi Dasar.
v1.1	v1.0	31 Juli 2023	Halaman ini	Penambahan Field issuerRrn pada Endpoint Inquiry QR

Deskripsi ProdukProduct Description

Product Overview

Dokumen ini bertujuan untuk menjelaskan spesifikasi API dari pengembangan QRIS Dinamis - MPM dengan skema merchant mengeluarkan QRIS, nasabah menggunakan alat untuk memindai / scan QRIS merchant. Kemudian dari BRI mengiriman notifikasi / callback sesuai dengan spesifikasi yang telah ditentukan.

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	Deskripsi
X-SIGNATURE			M	Dengan algoritma asymmetric signature SHA256withRSA (Private_Key, stringToSign). stringToSign = client_ID + “\|” + XTIMESTAMP
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_crede ntials

Response Structure

Field	Data Type	Format	Mandatory	Deskripsi
responseCode	String	Numeric	C	Response code
responseMessage	String	Alphabet	C	Respon deskripsi
accessToken	String	Alphanum eric	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 Referensi: OAuth2.0 RFC 6749 & 6750
tokenType	String	Alphabet	M
expiresIn	String	Alphanumeric	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
200	2005200	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

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

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 is consists of verb, path, token, timestamp, and body. In Symmetric-Signature format: HMAC_SHA512(clientSecret, stringToSign) with formula stringToSign = HTTPMethod+”:“+ EndpointUrl +":"+ AccessToken+":“ + Lowercase(HexEncode(SHA-256(minify(RequestBody))))+ ":“ +TimeStamp

Contoh:

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/simulator/qr/qr-cpm-payment-url becomes /simulator/qr/qr-cpm-payment-ur

Verb

Method HTTP dengan huruf kapital.

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

Token

Token yang dipakai di header Authorization

Contoh: Bearer R04XSUbnm1GXNmDiXx9ysWMpFWBr

Timestamp

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

Contoh:

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

Body

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

Contoh: {"hello":"world"}

Result SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749

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

contoh: &body=

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

B. Generate QR

Endpoint Description

API Notify Payment QR MPM Dinamis digunakan untuk mengirimkan notify payment QR MPM Dinamis ke partner.

General Information

HTTP Method	POST
Path	/v1.0/qr-dynamic-mpm/qr-mpm-generate-qr
Type Format	JSON
Authentication	OAuth 2.0

Header Structure

Key	Value	Format	Mandatory	Length	Deskripsi
Authorization	Authorization	Alphanumeric	M		Bearer {Token}
X-TIMESTAMP	BRI-timestamp	Datetime	M		Timestamp ISO8601 format
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	Deskripsi	Contoh
partnerReferenceNo	String	M	64	Nomor identifikasi transaksi pada sistem penyedia layanan	123456123456
amount	Object	M		Rincian untuk jumlah objek tercantum dalam tabel
merchantId	String	M	64	ID unik yang dimiliki oleh setiap pelanggan	00007100010926
terminalId	String	M	16	Terminal ID	213141251124

Request Structure dalam Object "amount"

Field	Data Type	Mandatory	Length	Deskripsi	contoh
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	123456.00
currency	String	M	3	3 digit kode ISO Currency	IDR

Response Structure

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
responseCode	String	M	7	Kode response HTTP status code + service code + case code	2004700
responseMessage	String	M	150	Deskripsi response	Successfull
partnerReferenceNo	String	M	64	Nomor identifikasi transaksi pada sistem layanan konsumen	1234567890133
qrContent	String	M	512	QR String MPM	0002xxxxxxxxxx
referenceNo	String	M	12	Nomor identifikasi transaksi pada sistem penyedia layanan.	409676201434

Request & Response Payload Sample

Request :

    {
        "partnerReferenceNo": "1234567890133",
        "amount": {
            "value": "123456.00",
            "currency": "IDR"
        },
        "merchantId": "00007100010926",
        "terminalId": "213141251124"
    }

Normal Response:

        {
            "responseCode": "2004700",
            "responseMessage": "Successful",
            "partnerReferenceNo": "1234567890133",
            "qrContent": "0002XXXXXXXXX",
            "referenceNo": "409676201434"
        }

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

C. Inquiry Payment

Endpoint Description

Endpoint untuk melakukan inquiry payment QR MPM Dinamis

General Information

HTTP Method	POST
Path	/v1.0/qr-dynamic-mpm/qr-mpm-query
Type Format	JSON
Authentication	OAuth 2.0

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

Request Structure

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
originalReferenceNo	String	M	64	Nomor identifikasi transaksi pada sistem penyedia layanan	000008526955
serviceCode	String	M	2	Indikator jenis transaksi (kode service dari transaksi request asli)	17
additionalInfo	Object	M		Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

Request Structure dalam Object "additionalInfo"

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
terminalId	String	M	16	ID Terminal	10049258

Response Structure

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
responseCode	String	M	7	Kode Response HTTP status code + service code + case code	2005100
responseMessage	String	M	150	Deskripsi Response	Successful
originalReferenceNo	String	C	64	Nomor Identifikasi transaksi pada sistem penyedia layanan	000008526955
serviceCode	String	M	2	Kode Service	17
latestTransactionStatus	String	M	2	00 - Success 01 - Initiated 02 - Paying 03 - Pending 04 - Refunded 05 - Canceled 06 - Failed 07 - Not found	00
transactionStatusDesc	String	O	50	Deskripsi dari status transaksi	Successfully
amount	Object	M		Detail isian dari object additionalInfo terdapat pada tabel dibawah ini
terminalId	String	O	16	Indentifikasi terminal	10049258
additionalInfo	Object	O		Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

Response Structure dalam Object "amount"

Field	Data Type	Mandatory	Length	Deskripsi	Contoh
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	1500100
currency	String	M	3	3 digit kode ISO Currency	IDR

Response Structure dalam Object "additionalInfo"

Field	Data Type	Mandatory	Deskripsi	Contoh
customerName	String	O	Nama konsumen	John Doe
customerNumber	String	O	Nomor konsumen	9360015723456789
invoiceNumber	String	O	Nomor invoice	10009121031000912103
issuerName	String	O	Nama issuer	Finnet 2
issuerRrn	String	O	transaksi id dari issuer QR	110002756582
mpan	String	O	Merchant PAN dari original Payment QR	9360000201102921379

Request & Response Payload Sample


    {
    "originalReferenceNo":"000008526955",
    "serviceCode":"17",
    "additionalInfo":{
    "terminalId": "10049258"
    }
   }

Normal Response:

   {
    "responseCode": "2005100",
    "responseMessage": "Successful",
        "originalReferenceNo": "290005165369",
    "serviceCode": "17",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "Successfully",
    "amount": {
        "value": "2000.00",
    "currency": "IDR"
    },
        "terminalId": "10049258",
    "additionalInfo": {
    "customerName": "John Doe",
    "customerNumber": "9360015723456789",
    "invoiceNumber": "10009121031000912103",
    "issuerName": "Finnet 2",
    "issuerRrn": "110002756528"
    "mpan": "9360000201102921379"
    }
   }

List of Error/Response Code

HTTP Status	Code	Status	Response Description	Deskripsi
200	00	Sukses	Successfull	Sukses
202	00	Pending	Transaction still on process	Transaksi sedang dalam proses
202	00	Pending	Request on progress	Payment sedang di proses / gagal
400	01	Gagal	Invalid Field Format {field name}	Invalid Format
403	00	Gagal	Transaction Expired	Refund sudah tidak bisa dilakukan
403	02	Gagal	Exceeds Transaction Amount Limit	Nominal melebihi limit
403	15	Gagal	Transaction Not Permitted. Invalid Data. Abort Process	Invalid Data. Abort Process
403	15	Gagal	Transaction Not Permitted. QR Expired	QR Expired
403	23	Gagal	Account Limit Exceed	Akumulasi Nominal Melebihi Limit
404	01	Gagal	Transaction Not Found	Data Tidak Ditemukan
404	08	Gagal	Invalid Merchant	Invalid Merchant
404	11	Gagal	Invalid Card/Account/Customer [info]/Virtual Account	Invalid CPAN
404	12	Gagal	Invalid Bill	Invalid transaction / invalid number
404	13	Gagal	Invalid Amount	Invalid Amount
404	14	Gagal	Paid Bill	Transaksi Sudah Terbayar / Transaksi sudah terefund
500	01	Gagal	Internal Server Error	Retrieve Data Failed
500	01	Gagal	Internal Server Error	Database Error

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