QRIS Merchant Presented Mode (MPM) Dinamis

Informasi API Information

Title

QRIS Merchant Presented Mode (MPM) Dinamis 

Version

v1.0

URL Sandbox

https://sandbox.partner.api.bri.co.id/

URL Production

https://partner.api.bri.co.id/

Kendali Versi

API Version

Date

Link to document

Deskripsi

v1.0

11 Mei 2022

Halaman Ini

Versi Dasar.

Deskripsi ProdukProduct Description

Product Overview

Materi Onboard: https://intip.in/materiqris

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

Endpoint

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

Format Type

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 + “|” + XTIMESTAMP

 

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_crede ntials

Response Structure

Field

Data Type

Format

Mandatory

Length

Deskripsi

Contoh

responseCode

String

Numeric

C

 

Response code

 

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

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

 

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

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/simulator/qr/qr-cpm-payment-url becomes /simulator/qr/qr-cpm-payment-ur

Verb

Method HTTP dengan huruf kapital.

Contoh: GET, POST, PUT, PATCH, and DELETE.

Token

Token yang dipakai di header Authorization

Contoh:  Bearer R04XSUbnm1GXNmDiXx9ysWMpFWBr

Timestamp

TWaktu saat mengirimkan request API. Format waktu harus mengikuti ISO8601 format (yyyy-MM-ddTHH:mm:ss.SSSZ). Harus dalam zero UTC offset Example:

Contoh:

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

Body

Body saat mengirimkan request API. Lowercase(HexEncode(SHA-256(minify(RequestBody))))

Contoh: {"hello":"world"}

Result SHA256 : a47a5f14b3e78b5e3d3f81b1a1468499be964660f818c10adcac792c42709749

Jika tidak terdapat body request, contoh menggunakan metode GET, biarkan saja kosong

 contoh: &body=

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

B. Generate QR

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

Format

Mandatory

Length

Deskripsi

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

Deskripsi

Contoh

partnerReferenceNo

String

M

64

Nomor identifikasi transaksi pada sistem penyedia layanan

123456123456

amount

Object

M

 

Rincian untuk jumlah objek tercantum dalam tabel

 

merchantId

String

M

64

ID unik yang dimiliki oleh setiap pelanggan

00007100010926

terminalId

String

M

16

Terminal ID

213141251124

Request Structure dalam Object "amount"

Field

Data Type

Mandatory

Length

Deskripsi

contoh

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

123456.00

currency

String

M

3

3 digit kode ISO Currency

IDR

Response Structure

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

responseCode

String

M

7

Kode response

HTTP status code + service code + case code

2004700

responseMessage

String

M

150

Deskripsi response

Successfull

partnerReferenceNo

String

M

64

Nomor identifikasi transaksi pada sistem layanan konsumen

1234567890133

qrContent

String

M

512

QR String MPM

0002xxxxxxxxxx

referenceNo

String

M

12

Nomor identifikasi transaksi pada sistem penyedia layanan.

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"
        }
                  
    

 

C. Inquiry Payment

Endpoint Description

Endpoint untuk melakukan 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

Deskripsi

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

Deskripsi

Contoh

originalReferenceNo

String

M

64

Nomor identifikasi transaksi pada sistem penyedia layanan

000008526955

serviceCode

String

M

2

Indikator jenis transaksi (kode service dari transaksi request asli)

17

additionalInfo

Object

M

 

Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

 

Request Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

terminalId

String

M

16

ID Terminal

10049258

Response Structure

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

responseCode

String

M

7

Kode Response

HTTP status code + service code + case code

2005100

responseMessage

String

M

150

Deskripsi Response

Successful

originalReferenceNo

String

C

64

Nomor Identifikasi transaksi pada sistem penyedia layanan

000008526955

serviceCode

String

M

2

Kode Service

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

Deskripsi dari status transaksi

Successfully

amount

Object

M

 

Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

 

terminalId

String

O

16

Indentifikasi terminal

10049258

additionalInfo

Object

O

 

Detail isian dari object additionalInfo terdapat pada tabel dibawah ini

 

Response Structure dalam Object "amount"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

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

1500100

currency

String

M

3

3 digit kode ISO Currency

IDR

Response Structure dalam Object "additionalInfo"

Field

Data Type

Mandatory

Length

Deskripsi

Contoh

customerName

String

O

 

Nama konsumen

John Doe

customerNumber

String

O

 

Nomor konsumen

9360015723456789

invoiceNumber

String

O

 

Nomor invoice

10009121031000912103

issuerName

String

O

 

Nama issuer

Finnet 2

mpan

String

O

 

Merchant PAN dari original Payment QR

9360000201102921379

Request & Response Payload Sample


    {
    "originalReferenceNo":"000008526955",
    "serviceCode":"17",
    "additionalInfo":{
    "terminalId": "10049258"
    }
   }
   
           
    

Normal Response:

        {
    "responseCode": "2005100",
    "responseMessage": "Successful",
    "originalReferenceNo": "000008526955",
    "serviceCode": "17",
    "latestTransactionStatus": "00",
    "transactionStatusDesc": "Successfully",
    "amount": {
    "value": "1500100",
    "currency": "IDR"
    },
    "terminalId": "10049258",
    "additionalInfo": {
    "customerName": "John Doe",
    "customerNumber": "9360015723456789",
    "invoiceNumber": "10009121031000912103",
    "issuerName": "Finnet 2",
    "mpan": "9360000201102921379"
    }
   }
                  
    

List of Error/Response Code

HTTP Status

Code

Status

Response Description

Deskripsi

200

00

Sukses

Successfull

Sukses

202

00

Pending

Transaction still on process

Transaksi sedang dalam proses

202

00

Pending

Request on progress

Payment sedang di proses / gagal

400

01

Gagal

Invalid Field Format {field name}

Invalid Format

403

00

Gagal

Transaction Expired

Refund sudah tidak bisa dilakukan

403

02

Gagal

Exceeds Transaction Amount Limit

Nominal melebihi limit

403

15

Gagal

Transaction Not Permitted. Invalid Data. Abort Process

Invalid Data. Abort Process

403

15

Gagal

Transaction Not Permitted. QR Expired

QR Expired

403

23

Gagal

Account Limit Exceed

Akumulasi Nominal Melebihi Limit

404

01

Gagal

Transaction Not Found

Data Tidak Ditemukan

404

08

Gagal

Invalid Merchant

Invalid Merchant

404

11

Gagal

Invalid Card/Account/Customer [info]/Virtual Account

Invalid CPAN

404

12

Gagal

Invalid Bill

Invalid transaction / invalid number

404

13

Gagal

Invalid Amount

Invalid Amount

404

14

Gagal

Paid Bill

Transaksi Sudah Terbayar / Transaksi sudah terefund

500

01

Gagal

Internal Server Error

Retrieve Data Failed

500

01

Gagal

Internal Server Error

Database Error