QRIS Merchant Presented mode (MPM) Dinamis Notification

API Information

Title

QRIS Merchant Presented Mode (MPM) Dinamis Notification

Version

v1.0

URL Sandbox

diprovide oleh partner

URL Production

diprovide oleh partner

Version Control

API Version

Date

Link to document

Description

v1.0

13 April 2022

this pages

Baseline version.

Product Description

Product Overview

 

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.0/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

grantTy pe

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

response Code

String

Numeric

C

 

Kode respon

 

response Message

String

Alphabet

C

 

Respon deskripsi

 

accessT oken

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:

 

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

 

 

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.0/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

Not found

  1. - Success

  2. - Initiated

  3. - Paying

  4. - Pending

  5. - Refunded

  6. - Canceled

  7. - Failed

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

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

 

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

Sukses

Successful

Sukses

400

01

Gagal

Invalid Field Format {field name}

Invalid Format

400

02

Gagal

Invalid Mandatory Field {field name}

Missing or invalid format on mandatory field

500

00

Gagal

General Error

General Error

500

01

Gagal

Internal Server Error

Retrieve Data Failed or Database Error

504

00

Gagal

Timeout

timeout from the issuer

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.0/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

grantTy pe

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

response Code

String

Numeric

C

 

Kode respon

 

response Message

String

Alphabet

C

 

Respon deskripsi

 

accessT oken

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