QRIS Merchant Presented Mode (MPM) Dynamic
What is QRIS Merchant Presented Mode (MPM) Dynamic ?
Quick Response Code Indonesian Standard or QRIS is a combined QR code from every kind of QR code Payment Service Provider. QRIS was developed by the payment service provider industry together with Bank Indonesia with the intention of having a QR code payment service that is easy, fast, and secure.
With QRIS, QR code payment from every kind of service provider application including bank or non-bank will be able to be used at every merchant with QRIS logo.
QRIS Merchant Presented Mode (MPM) Dynamic is a QR code that must be generated and presented to the customer every time the transaction is made. Merchant will need to input the payment amount and the customer will scan the QR code that was generated and printed.
Use Case of API QRIS Merchant Presented Mode (MPM) Dynamic
QRIS Merchant Presented Mode (MPM) Dynamic is suitable for middle and large business merchants with large volume of transactions. With this API merchant will need to input the payment amount and the customer will scan the QR code that was generated and printed.
API Information
Title |
QRIS Dynamic - MPM |
---|---|
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 |
this pages |
Baseline version. |
v1.1 | v1.0 | 31 Juli 2023 | Here | adding an issuerRrn Field to the Inquiry QR Endpoint |
Product Description
Product Overview
This document aims to explain the specifications of the QRIS Dynamic - MPM Outbound development API with the merchant scheme of the QRIS issuer, the customer uses the tool to scan the QRIS merchant. Then BRI sends notifications/callbacks according to predetermined specifications.
Endpoint
A. Get Token
Endpoint Description
This endpoint is used to get an access token that serves as authentication when you want to access other APIs. Test check that get token is not hit every time accessing 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 |
Description |
Example |
---|---|---|---|---|---|---|
X-SIGNATURE |
|
|
M |
|
With the asymmetric signature algorithm SHA256withRSA
(Private_Key, stringToSign). stringToSign = client_ID + “|” + X-TIMESTAMP |
|
X-CLIENT-KEY |
|
Alphanumeric |
M |
|
Client’s client_id (PJP Name) (given when the registration process is complete ) |
|
X-TIMESTAMP |
|
Datetime |
M |
|
Current client local time yyyy-MM- ddTHH:mm:ss.SSSTZD format |
|
Content-Type |
application /json |
|
M |
|
|
|
Request Structure
Field |
Data Type |
Format |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|---|
grantType |
String |
Alphabet |
M |
|
“client_credentials” : a client can request an access token using only its client credentials (or other supported authentication means) when a client requests access to a protected resource under its control (OAuth 2.0: RFC 6749 & 6750) |
client_crede ntials |
Response Structure
Field |
Type Data |
Format |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|---|
responseCode |
String |
Numeric |
C |
|
Response code |
|
responseMessage |
String |
Alphabet |
C |
|
Response description |
|
accessToken |
String |
Alphanumeric |
M |
|
Access token types provide clients with the information needed to successfully use access tokens to protect resource requests (along with type-specific attributes) Types of token types:
“Bearer”: includes a string access token on request “Mac”: issues a message authentication code key (MAC) along with the access token used to sign certain components of the HTTP request
Reference: OAuth2.0 RFC 6749 & 6750 |
|
tokenType |
String |
Alphabet |
M |
|
|
|
expiresIn |
String |
Alphanumeric |
M |
|
Session ends in seconds : 900 (15 minutes) |
|
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 |
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 |
|
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.
Signature
Signature ensures that the data sent is original and cannot be refuted. The signature is generated by the service user and verified by the service recipient. The signature is formed from a predefined payload, by implementing the algorithm HMAC_SHA512 with clientSecret as the key.
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
Example:
http://post/snap/v1.0/dummy:muhpwhwOkPRU9nNXYnyYHj8t54x3:8b4e9e83b5231cff4f84358ec8ca81951cfe9f999f635b1566452a501d5c23b2:2021-11-29T09:22:18.172+07:00
The details of each element in the payload are described below:
Path
Value in path i.e. URL after hostname and port without Query Parameter
Example:
https://sandbox.partner.api.bri.co.id/simulator/qr/qr-cpm-payment-url becomes /simulator/qr/qr-cpm-payment-ur
Verb
HTTP method using capital letters.
Example: GET, POST, PUT, PATCH, and DELETE.
Token
The token used in the Authorization header. Example: Bearer
R04XSUbnm1GXNmDiXx9ysWMpFWBr
Timestamp
Time when sending API request. The time format must follow the ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ). Must be in zero UTC offset
Example:
2021-11-02T13:14:15.678+07:00
Body
Body when sending API requests. Lowercase(HexEncode(SHA-256(minify(RequestBody))))
Example: {"hello":"world"}
Result SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749
If there is no request body, for example using the GET method, leave it blank. Example: &body=
Reference : https://developers.bri.co.id/en/snap-bi/apidocs-oauth-snap-bi
B. Generate QR
Endpoint Description
API Generate QR used to generate used to generate QR MPM Dynamic
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 |
Description |
---|---|---|---|---|---|
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 |
Description |
Example |
---|---|---|---|---|---|
partnerReferenceNo |
String |
M |
6 |
Identification of transactions in the customer service system |
1234567890133 |
amount |
Object |
M |
Details for the object amount are listed in the table below |
||
merchantId |
String |
M |
64 |
Unique ID owned by each merchant |
00007100010926 |
terminalId |
String |
M |
16 |
Terminal ID |
213141251124 |
Request Structure in Object "amount"
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
value |
Decimal |
M |
18 |
The net amount of the transaction. If it is IDR then the value includes 2 decimal places. for example IDR 10,000,- will be placed with 10000.00 |
123456.00 |
currency |
String |
M |
3 |
3 digit ISO Currency code |
IDR |
Response Structure
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
responseCode |
String |
M |
7 |
Response code HTTP status code + service code + case code |
2004700 |
responseMessage |
String |
M |
150 |
Response description |
Successfull |
partnerReferenceNo |
String |
M |
6 |
Transaction identification number on the customer service system |
1234567890133 |
qrContent |
String |
M |
512 |
QR String MPM |
0002xxxxxxxxxx |
referenceNo |
String |
M |
12 |
Transaction identification number on the service provider's system. |
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" }
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.
C. Inquiry Payment
Endpoint Description
Endpoint Inquiry Payment used to 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 |
Description |
---|---|---|---|---|---|
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 |
Description |
Example |
---|---|---|---|---|---|
originalReferenceNo |
String |
M |
64 |
Transaction identification number on service provider system |
000008526955 |
serviceCode |
String |
M |
2 |
Transaction type indicator (service code from the original request transaction) |
17 |
additionalInfo |
Object |
M |
The details for the additionalInfo object are listed in the table below |
Request Structure in Object "additionalInfo"
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
terminalId |
String |
M |
16 |
Terminal ID |
10049258 |
Response Structure
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
responseCode |
String |
M |
7 |
Response code HTTP status code + service code + case code |
2005100 |
responseMessage |
String |
M |
150 |
Response description |
Successful |
originalReferenceNo |
String |
C |
64 |
Transaction identification number on the service provider system |
000008526955 |
serviceCode |
String |
M |
2 |
Service code |
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 |
Description of transaction status |
Successfully |
amount |
Object |
M |
The details for the amount object are listed in the table below |
||
terminalId |
String |
O |
16 |
Terminal ID |
10049258 |
additionalInfo |
Object |
O |
The details for the additionalInfo object are listed in the table below |
Response Structure in Object "amount"
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
value |
Decimal |
M |
18 |
The net amount of the transaction. If it is IDR then the value includes 2 decimal places. for example IDR 10,000,- will be placed with 10000.00 |
1500100 |
currency |
String |
M |
3 |
3 digit ISO Currency code |
IDR |
Response Structure in Object "additionalInfo"
Field |
Data Type |
Mandatory |
Length |
Description |
Example |
---|---|---|---|---|---|
customerName |
String |
O |
Customer name |
I GEDE TONI DHARMAWAN |
|
customerNumber |
String |
O |
Customer nubmer |
9360015723456789 |
|
invoiceNumber |
String |
O |
Invoice number |
10009121031000912103 |
|
issuerName |
String |
O |
Issuer name |
Finnet 2 |
|
issuerRrn |
String |
O |
transaction id from issuer QR |
110002756582 |
|
mpan |
String |
O |
PAN merchant from original Payment QR |
9360000201102921379 |
Request & Response Payload Sample
Request :
{ "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 |
Description |
---|---|---|---|---|
200 |
00 |
Success |
Successfull |
Success |
202 |
00 |
Pending |
Transaction still on process |
Transaction is in progress |
202 |
00 |
Pending |
Request on progress |
Payment is being processed/failed |
400 |
01 |
Failed |
Invalid Field Format {field name} |
Invalid Format |
403 |
00 |
Failed |
Transaction Expired |
Refunds are no longer possible |
403 |
02 |
Failed |
Exceeds Transaction Amount Limit |
Nominal exceeds the limit |
403 |
15 |
Failed |
Transaction Not Permitted. Invalid Data. Abort Process |
Invalid Data. Abort Process |
403 |
15 |
Failed |
Transaction Not Permitted. QR Expired |
QR Expired |
403 |
23 |
Failed |
Account Limit Exceed |
Accumulated Nominal Exceeding Limit |
404 |
01 |
Failed |
Transaction Not Found |
Data not found |
404 |
08 |
Failed |
Invalid Merchant |
Invalid Merchant |
404 |
11 |
Failed |
Invalid Card/Account/Customer [info]/Virtual Account |
Invalid CPAN |
404 |
12 |
Failed |
Invalid Bill |
Invalid transaction / invalid number |
404 |
13 |
Failed |
Invalid Amount |
Invalid Amount |
404 |
14 |
Failed |
Paid Bill |
The transaction has been paid / the transaction has been refunded |
500 |
01 |
Failed |
Internal Server Error |
Retrieve Data Failed |
500 |
01 |
Failed |
Internal Server Error |
Database Error |
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.