QRIS Merchant Presented Mode (MPM) Dynamic Notification

API Information

Title

QRIS Merchant Presented Mode(MPM) Dynamic Notification

Version

v1.0

URL Sandbox

provided by partner

URL Production

provided by partner

Version Control

API Version

Date

Link to document

Description

v1.0

13 April 2022

this pages

Baseline version.

Product Description

Product Overview

This document aims to explain the specifications of the QRIS Dynamic - MPM Notification 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

grantTy pe

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

response Code

String

Numeric

C

 

Response code

 

response Message

String

Alphabet

C

 

Response description

 

accessTo ken

String

Alphanum eric

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

Alphanum eric

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

-

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

 

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:

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/qr/qr-mpm-notify becomes qr/qr-mpm-notify

 

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/id/snap-bi/apidocs-oauth-snap-bi

B.Notify Payment QR MPM Dinamis

Endpoint Description

API Notify Payment QR MPM Dynamic is used to send Dynamic MPM QR notify payments to partners.

 

General Information

HTTP Method

POST

Path

/v1.0/qr-dynamic/qr-mpm-notify

Format Type

JSON

Authentication

OAuth 2.0

Header Structure

Key

Value

Mandatory

Length

Description

Example

Content-Type

application

/json

M

-

 

 

Authorization

Bearer token

M

-

 

 

X-SIGNATURE

signature

M

64

With the asymmetric signature algorithm SHA256withRSA

 

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

 

X-TIMESTAMP

timestamp

M

-

Current client local time yyyy-MM- ddTHH:mm:ss.SSSTZD format

2020-01-15T17:01:11+07:00

ORIGIN

 

O

 

 

www.hostname.com

X-PARTNER-ID

 

M

 

Partner ID provided by partner

8215082391904062462182317473

7537

X-EXTERNAL-ID

 

M

 

External ID that is unique for each transaction

4180755335895009318416218079

7837

X-IP-ADDRESS

 

O

 

Device IP Address

172.24.281.24

X-DEVICE-ID

 

O

 

Device ID

09864ADCASA

X-LATITUDE

 

O

 

Device Latitude

-6.108841

X-LONGITUDE

 

O

 

Device Longitude

106.7782137

CHANNEL-ID

 

O

 

Channel ID

95221

Request Structure

Field

Data Type

Mandatory

Length

Description

Example

originalReferenceNo

String

M

12

Transaction identification number on service provider system

123456123456

originalPartnerReference No

String

M

6

The transaction identification number in the customer service system is sent the last 6 digits

123456

latestTransactionStatus

String

O

2

  1. - Success

  2. - Initiated

  3. - Paying

  4. - Pending

  5. - Refunded

  6. - Canceled

  7. - Failed

  8. - Not found

00

transactionStatusDesc

String

O

50

Description of transaction status

success

customerNumber

String

M

64

Customer account number

62813883700

01

accountType

String

O

25

Account type

tabungan

destinationAccountName

String

M

25

Destination account name

John Doe

amount

Object

M

 

Details for the object amount are listed in the table below

 

bankCode

String

O

8

Bank code

002

additionalInfo

Object

O

 

Details for the object additionalInfo are listed in the table below

 

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

12345678.00

currency

String

M

3

3 digit ISO Currency code

IDR

Request Structure in Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

reffId

String

O

 

Reff ID

1001016773

issuerName

String

O

 

Issuer name

GOPAY

Response Structure

Field

Data Type

Mandatory

Length

Description

Example

responseCode

String

M

7

Response code

2005200

responseMessage

String

M

150

Response description

Request has been processed successfully

additionalInfo

Object

O

 

Details for the object additionalInfo are listed in the table below

 

Response Structure in Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

reffId

String

O

 

Reff ID

1001016773

issuerName

String

O

 

Issuer name

GOPAY

 

Request & Response Payload Sample

Request :


{
  "originalReferenceNo":"2020102977770000000009",
  "originalPartnerReferenceNo":"2020102900000000000001",
  "latestTransactionStatus":"00",
  "transactionStatusDesc":"success",
  "customerNumber":"6281388370001",
  "accountType": "tabungan",
  "destinationAccountName": "John Doe",
  "amount":

{
  "value": "12345678.00",
  "currency": "IDR"

},

  "sessionID": "0UYEB77329002HY",
  "bankCode": "002",
  "externalStoreID":"124928924949487",
  "additionalInfo":

{
  "reffId": "1001016773",
  "issuerName": "GOPAY"

}

}

Normal Response :

{
    "responseCode": "2005200",
    "responseMessage": "Successfull",
    "additionalInfo":",
{
    "reffId": "1001016773",
    "issuerName": "GOPAY"
}

}

Error Response :


 

 

List of Error/Response Code

 

HTTP Status

Code

Status

Response Description

Description

200

00

Success

Successful

Success

400

01

Failed

Invalid Field Format {field name}

Invalid Format

400

02

Failed

Invalid Mandatory Field {field name}

Missing or invalid format on mandatory field

500

00

Failed

General Error

General Error

500

01

Failed

Internal Server Error

Retrieve Data Failed or Database Error

504

00

Failed

Timeout

timeout from the issuer

C.Get Token

Endpoint Description

API Get Token used to obtain tokens as a security measure from partners.

 

General Information

HTTP Method

POST

Path

/v1.0/qr-dynamic/token

Type Format

x-www-form-urlencoded

Authentication

OAuth 2.0

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

grantTy pe

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

response Code

String

Numeric

C

 

Response code

 

response Message

String

Alphabet

C

 

Response description

 

accessTo ken

String

Alphanum eric

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

Alphanum eric

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

Description

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