QRIS Dinamis - CPM Inbound

Create API

Simplify Your Business with BRIAPI

Watch the video and see how BRIAPI can make your business more efficient with BRI Interbank Transfer.

 

Create API Now

 

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

this pages

Baseline version.
v1.1 v1.0 21 September 2022 this pages Change in response description for code 40315 at the payment endpoint.
v1.2 v1.0 28 September 2022 this pages Change in status and description for the response timeout of the payment endpoint and cancel the payment.
v1.3 v1.0 04 Oktober 2022 this pages Adding conditions in the sequence diagram and notes on the payment endpoint.
v1.4 v1.0 13 December 2022 this pages Change in the maximum length parameter for partnerReferenceNo
v1.5 v1.0 13 September 2023 this pages Adding the service code column to the list of Payment and Cancel Payment response codes.

 

Product Description

Product Overview

This document is intended to explain the API specifications for the development of Dynamic QRIS - CPM Inbound with the customer issuing QRIS scheme, where merchants use tools to scan the customer's QRIS

The process to decode a QR code is as follows :

Endpoint

A. Get Token

Endpoint Description

This endpoint is used to obtain an access token, which serves as authentication when accessing other APIs. The pilot test verifies that the token is not counted each time the endpoint (integrator) is accessed.

 

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_credentials

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

 

The type of access token provides the client with the necessary information to successfully use the access token to protect a resource request (along with type-specific attributes). Token types include:

 

“Bearer”: includes the access token string during the request.

“Mac”: issues a message authentication code (MAC) key along with the access token used to sign specific components of the HTTP request.

 

Reference: OAuth2.0 RFC 6749 & 6750

 

tokenType

String

Alphabet

M

 

 

 

expiresIn

String

Alphanum eric

M

 

The session expires 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

-

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

The signature ensures that the transmitted data is genuine and cannot be repudiated. The signature is generated by the service user and verified by the service recipient.

The signature is formed from the predefined payload by implementing the HMAC_SHA512 algorithm with the clientSecret as the key

 

Payload

The payload consists of the verb, path, token, timestamp, and body. In the format of Symmetric-Signature:

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

The value in the path is the URL after the hostname and port without query parameters.

Example:

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

 

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

The time when sending an API request. The time format must follow ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ). It must be in a zero UTC offset.

Example

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

 

Body

The body when sending an API request. Lowercase(HexEncode(SHA-256(minify(RequestBody))))

Example: {"hello": "world"}

Result SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749

If there is no request body, for example when using the GET method, then leave it empty.

Example:

&body=

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

B. Payment QR CPM Dinamis

Endpoint Description

The Dynamic CPM QR Payment API is used to perform dynamic CPM QR transactions.

*Note : If you encounter a Timeout response or receive no response at all from BRI during QR payment, we recommend initiating a reversal request through the Cancel Payment endpoint in section 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

Description

Example

partnerReferenceNo

String

(Numeric)

M

12

The transaction identification number in the consumer service system.

092783527859

qrContent

String

M

512

QR String CPM (base64)

8505XXXXXXX

amount

Object

M

 

The filling details of the 'amount' object are found in the table below

 

 

Object

C

 

The filling details of the 'feeAmount' object are found in the table below

 

merchantId

String

M

64

The unique ID held by each merchant

9360000200101145436

subMerchantId

String

O

32

The unique ID held by the submerchant

7612736352

externalStoreId

String

O

64

The unique ID held by the external store

asdasd

expiryTime

Numeric

M

25

Expiration Time QR CPM

(ISO-8601)

default value 5 minutes

merchantName

String

M

64

Merchant Name

TOKO IDOLA

merchantLocation

String

M

64

Merchant Location

BANYUWANGI
terminalId String M 32 Terminal ID asjkdhaskjdhaksjhd812836732 3623
additionalInfo Object     The filling details of the 'additionalInfo' object are provided in the table below  

Request Structure in Object "amount"

Field

Data Type

Mandatory

Length

Description

Example

value

Sting

M

18

The net amount of the transaction. If it is in IDR, the value includes 2 decimal places. For example, Rp 10,000,- will be represented as 10000.00.

1200.00

currency

String

M

3

3 digit ISO Currency code

IDR

Request Structure within Object "feeAmount"

Field

Data Type

Mandatory

Length

Description

Example

value

String

M

18

The net amount of the transaction. If it's in IDR, the value includes 2 decimal places. For example, Rp 10,000,- will be represented as 10000.00

 

currency

String

M

3

3-digit code ISO Currency

 

Request Structure within Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

deviceId

String

O

64

Unique Device ID

7162335125312

channel

String

O

 

Device Channel

mobilephone

processingCode

String

M

6

Code for source identifier

266000
cpan String M   CPAN 5A0A9360000210000906432F
channelId String M   Channel ID 1231231
customerName String M   Customer's Name PI04Q001CD30JOKOWI____ MC03UME
approvalCode String M   Approval Code 222334555

Response Structure

Field

Data Type

Mandatory

Length

Description

Example

responseCode

String

M

7

Response Code

HTTP Response + Service Code + Response Code

2006000

responseMessage

String

M

150

Response Description

Successful
referenceNo String C 64 Transaction identification number in the service provider's system. Must be filled in after a successful transaction. 828233404852
partnerReferenceNo String O 64 The transaction identification number in the consumer service system 092783527859
transactionDate yyyyM MddH Hmmss O 255 Transaction Time ISO-8601 2022-05-13T14:58: 22+07:00
additionalInfo Object O   The details of the 'additionalInfo' object are explained in the table below  

Request Structure within Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

deviceId

String

O

64

 

7162335125312

channel

String

O

 

Device Channel

mobilephone
invoiceNumber String O 20 Invoice Number 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

Description

200

60

00

Success

Successful

Successful dynamic CPM QR transaction.

202

60

00

Failed

Transaction still on process

Error because payment has not been processed or failed.

400

60

01

Failed

Invalid Field Format {field name}

Error due to incorrect format

400

60

02

Failed

Invalid Mandatory Field {field name}

Failure due to incorrect mandatory parameters.

403

60

03

Failed

Exceeds Transaction Amount Limit

Error because the amount exceeds the limit.

403

60

14

Failed

Insufficient Funds

Insufficient balance
403 60 15 Failed
  • Transaction Not Permitted. Invalid Transaction
  • Transaction Not Permitted. Transaction can't be specified.
  • Transaction Not Permitted. Transaction Already Exist or Not Found.

Error because the transaction is not allowed when:

  • The transaction is incorrect
  • The transaction cannot be determined.
  • The QR has already been paid, not found, or expired.

404

60

01

Failed

 Transaction not found Error because the transaction was not found.
404 60 04 Failed Transaction Cancelled Error because the transaction was canceled by the customer
404 60 08 Failed Invalid Merchant Error because the merchant is incorrect.
404 60 13 Failed Invalid Amount Error because the amount is incorrect.
404 60 14 Failed Paid Bill Error because the transaction has already been paid.
500 60 01 Failed Internal Server Error Internal Server Error
504 60 00 Pending Timeout Transactions can be either successful or unsuccessful. It is recommended to check the bank statement/mutation information and perform a cancel payment if you wish to abort the transaction.
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.

C. Cancel QR CPM Dinamis

Endpoint Description

The Dynamic CPM QR Cancel API is used to perform the cancelation of a dynamic CPM QR payment.

 

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

The original transaction identification number in the consumer service system.

092783527859
originalReferenceNo String O 64 The original transaction identification number is in the service provider's system. 828233404852  
originalExternalId String O 32 The original ExternalID is in the header message. 3044378693072272646328009 7920913  
merchantId String M 64 The unique ID held by each merchant 9360000200101145436  
subMerchantId String O 32 Sub-merchant ID 7612736352  
externalStoreId String O 64 External store ID asdasd  
amount Object M   The details of the 'amount' object are provided in the table below.    
reason String M 512 The reason for cancelation Cancel reason  
additionalInfo Object O   The filling details of the 'additionalInfo' object are listed in the table below    

Request Structure within Object "amount"

Field

Type Data

Mandatory

Length

Description

Example

value

Decimal

M

18

The net amount of the transaction. If it is in IDR, the value includes 2 decimal places. For example, Rp 10,000,- will be represented as 10000.00.

1200.00

 

currency

String

M

3

3-digit code ISO Currency

IDR

 

Request Structure within Object "additionalInfo"

Field

Type Data

Mandatory

Length

Description

Example

deviceId

String

O

64

 Unique device ID

12345679237

 

channel

String

O

 

Device Channel

mobilephone

Response Structure

Field

Type Data

Mandatory

Length

Description

Example

responseCode

String

M

7

Response Code

HTTP Response + Service Code + Response Code

2006200

 

responseMessage

String

M

150

Response Description

Successful
originalPartnerReferenceNo String O 64 The transaction identification number in the consumer service system 092783527859
originalReferenceNo String O 64 The transaction identification number in the service provider's system. Must be filled in after a successful transaction 828233404852
originalExternalId String O 32 The original ExternalID in the header message 30443786930722726463 280097920913
additionalInfo Object O   The filling details of the 'additionalInfo' object are found in the table below  
cancelTime String M   The time when the cancelation is performed 2022-04-19T09:48:07+07: 00
transactionDate String O  

Transaction Time

ISO-8601 format

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

Request Structure within Object "additionalInfo"

Field

Type Data

Mandatory

Length

Description

Example

deviceId

String

O

64

 Unique device ID

12345679237

 

channel

String

O

 

Device Channel

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

 Successfully canceled dynamic CPM QR payment

202

62

00

Failed

Transaction still on process

 Error because payment has not been processed or failed

400

62

01

Failed

Invalid Field Format {field name}

 Error due to incorrect format

400

62

02

Failed

Invalid Mandatory Field {field name}

 Failure due to incorrect mandatory parameters

403

62

02

Failed

Exceeds Transaction Amount Limit

 Error because the amount exceeds the limit

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 because the transaction is not allowed when:

  • The transaction is incorrect
  • The transaction cannot be determined
  • QR has expired.
  • The transaction already exists."

404

62

01

Failed

Transaction not found

 Error because the transaction was not found

404

62

04

Failed

Transaction Cancalled

 Error because the transaction was canceled by the customer
404 62 08 Failed Invalid Merchant Error because the merchant is incorrect
404 62 13 Failed Invalid Amount

Error because the amount is incorrect

Note: The amount reversal must match the previous payment amount
404 62 14 Failed Paid Bill Error because the transaction has already been paid
500 62 01 Failed Internal Server Error Internal Server Error
504 62 00 Pending Timeout Cancel payment can be successful or unsuccessful, where the transaction remains booked. It is recommended to perform further checks through bank statements/mutation information

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
Any error response not listed in the BRIAPI response list is considered pending and requires further investigation.