QRIS Merchant Presented mode (MPM) Dinamis Notification v1.1

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

 

Apa itu QRIS Merchant Presented mode (MPM) Dinamis Notifikasi ?

Quick Response Code Indonesian Standard atau disingkat QRIS (dibaca KRIS) adalah penyatuan berbagai macam QR dari berbagai Penyelenggara Jasa Sistem Pembayaran (PJSP) menggunakan QR Code. QRIS dikembangkan oleh industri sistem pembayaran bersama dengan Bank Indonesia agar proses transaksi dengan QR Code dapat lebih mudah, cepat, dan terjag​a keamanannya.

Dengan QRIS, seluruh aplikasi pembayaran dari Penyelenggara manapun baik bank dan nonbank yang digunakan masyarakat, dapat digunakan di seluruh toko, pedagang, warung, parkir, tiket wisata, donasi (merchant) berlogo QRIS, meskipun penyedia QRIS di merchant berbeda dengan penyedia aplikasi yang digunakan masyarakat.

QRIS Customer Presented Mode (MPM) Dinamis sendiri adalah kode QR dengan metode yakni menunjukan kode QR dari aplikasi pembayaran pelanggan lalu melakukan scan pada alat yang dimiliki oleh merchant.

Contoh Penggunaan API QRIS Customer Presented Mode (CPM) Dinamis Notifikasi

QRIS CPM Dinamis ditujukan untuk merchant yang membutuhkan kecepatan transaksi tinggi seperti penyedia transportasi, parkir dan ritel modern. Dimana pelanggan hanya perlu melakukan scan kode QR dari aplikasi pembayaran kepada alat yang telah disediakan merchant.

Informasi API

Title

QRIS Merchant Presented Mode (MPM) Dinamis Notification

Version

v1.1

URL Sandbox

diprovide oleh partner

URL Production

diprovide oleh partner

Kendali Versi

API Version Date Link to document Deskripsi
v1.0 13 April 2022 Here Baseline version.
v1.1 19 Februari 2024 this pages Penambahan Field issuerRrn pada Endpoint Inquiry QR

Deskripsi Produk

Gambaran Produk

Dokumen ini bertujuan untuk menjelaskan spesifikasi API dari pengembangan QRIS Dinamis - MPM Notification 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.

Enpoint

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.1/access-token/b2b

Tipe Format

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_cre dentials

 

Response Structure

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

responseCode

String

Numeric

C

 

Kode respon

 

responseMessage

String

Alphabet

C

 

Respon deskripsi

 

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

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

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

 
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 tergabung dari verb, path, token, timestamp, and body. Dengan format Symetric-Signature:

HMAC_SHA512 (clientSecret, stringToSign) dengan 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/qr/qr-mpm-notify menjadi qr/qr-mpm-notify

 

Verb

Method HTTP dengan menggunakan huruf kapital. Contoh: GET, POST, PUT, PATCH, and DELETE.

 

Token

Token yang dipakai di header Authorization. Contoh:

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 Example:

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

 

Body

Body saat mengirimkan request API. Lowercase(HexEncode(SHA-256(minify(RequestBody)))) Contoh: {"hello":"world"}

Hasil SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749 Jika tidak terdapat body request, contoh menggunakan metode GET, biarkan saja kosong.

Contoh: &body=

Referensi :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 Dinamis digunakan untuk mengirimkan notify payment QR MPM Dinamis ke partner.

 

General Information

HTTP Method

POST

Path

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

Type Format

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

Dengan algoritma asymmetric signature SHA256withRSA

 

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

 

X-TIMESTAMP

timestamp

M

-

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

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

ORIGIN

 

O

 

 

www.hostname.com

X-PARTNER-ID

 

M

 

ID Partner yang diprovide oleh partner

8215082391904062462182317473

7537

X-EXTERNAL-ID

 

M

 

ID External yang bersifat unik pada setiap transaksi

4180755335895009318416218079

7837

X-IP-ADDRESS

 

O

 

IP Address Perangkat

172.24.281.24

X-DEVICE-ID

 

O

 

ID Perangkat

09864ADCASA

X-LATITUDE

 

O

 

Latitude Perangkat

-6.108841

X-LONGITUDE

 

O

 

Longitude Perangkat

106.7782137

CHANNEL-ID

 

O

 

ID Channel

95221

Request Structure

Field

Data Type

Mandatory

Length

Description

Example

originalReferenceNo

String

M

12

Nomor identifikasi transaksi pada sistem penyedia layanan

123456123456

originalPartnerReferenceNo

String

M

6

Nomor identifikasi transaksi pada sistem layanan konsumen dikirim 6 digit terakhir

123456

latestTransactionStatus

String

O

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

success

customerNumber

String

M

64

Nomor rekening konsumen

6281388370001

accountType

String

O

25

Jenis akun

tabungan

destinationAccountName

String

M

25

Nama pemilik rekening tujuan

John Doe

amount

Object

M

 

Detail isian dari object amount terdapat pada tabel dibawah ini

 

bankCode

String

O

8

Kode Bank

002

additionalInfo

Object

O

 

Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

 

 

Request Structure dalam Object "amount"

Field

Data Type

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

12345678.00

currency

String

M

3

3 digit kode ISO Currency

IDR

Request Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

reffId

String

O

 

ID Reff

1001016773

issuerName

String

O

 

Nama issuer

GOPAY
issuerRrn String O   issuer RRN 110002756582

Response Structure

Field

Data Type

Mandatory

Length

Description

Example

responseCode

String

M

7

Kode response

2005200

responseMessage

String

M

150

Deskripsi response

Request has been processed successfully

additionalInfo

Object

O

 

Isian dari Object additionalInfo ini dijelaskan pada tabel di bawah

 

Response Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Description

Example

reffId

String

O

 

ID Reff

1001016773

issuerName

String

O

 

Nama issuer

GOPAY
issuerRrn String O   issuer RRN 110002756582

 

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"
  "issuerRrn": "110002756582"
}
}

Normal Response :

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

List of Error/Response Code

 

HTTP Status

Service Code

Code

Status

Response Description

Description

200

52

00

Sukses

Successful

Sukses

400

52

01

Gagal

Invalid Field Format {field name}

Invalid Format

400

52

02

Gagal

Invalid Mandatory Field {field name}

Missing or invalid format on mandatory field

500

52

00

Gagal

General Error

General Error

500

52

01

Gagal

Internal Server Error

Retrieve Data Failed or Database Error

504

52

00

Gagal

Timeout

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

C.Get Token

Endpoint Description

API Notify Payment QR MPM Dinamis digunakan untuk mendapatkan token sebagai security measure dari partner.

 

General Information

HTTP Method

POST

Path

/v1.1/qr-dynamic/token

Type Format

x-www-form-urlencoded

Authentication

OAuth 2.0

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_cre dentials

Response Structure

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

responseCode

String

Numeric

C

 

Kode respon

 

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

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

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