1. Overview
QRIS (Quick Response Code Indonesian Standard) Acquirer API is used to enable merchant to receive QRIS Payment with API integration to BNC as the acquirer.
2. The Types of QRIS Payment Methods
Merchant Presented Mode (MPM)
The client generates transaction QR according to BNC payment protocol, containing transaction amount. User will scan the QR code to make payment. Clients will be notified via callback about the payment status of the transaction. This spec represents BNC QRIS MPM Acquirer API
Customer Presented Mode (CPM)
The user will show his user QR code to the cashier at the merchant store. Cashier will enter the payment amount and scan the user’s QR code in order to make payment directly
3. The Difference Between QRIS On-us vs QRIS Off-us
QRIS On-us
A transaction within a single payment network. For example: QRIS issued by BNC is scanned and paid by the customer using the Neobank app from BNC. Thus, the transaction will be processed from BNC issuer (Neobank app) to BNC acquirer
QRIS Off-us
A transaction within cross-payment network where customers can pay the QR using various issuer application other than the Neobank app from BNC. For example: QRIS issued by BNC is scanned and paid by OVO, m-Banking BCA, Octo Mobile, GoPay, etc.). Thus, the transaction will be processed from non-BNC issuer to BNC acquirer
4. BNC Merchant Registration Open API
Merchant registration APIs refers to APIs that are used for the sub-merchants onboarding of BNC, or for the store setting requested from the merchant's system
API Name | Function |
|---|---|
Support with the province list inquiry for registration scenario | |
Support with the city list inquiry through the province ID for registration scenario | |
Support with the district list inquiry through the city ID for registration scenario | |
Support with the postcode list inquiry through the district ID for registration scenario | |
Support with the image upload for registration scenario | |
Support merchants create a new sub-merchant in the BNC system | |
Support merchants create a new franchisee store in the BNC system. The franchisee store must use a different merchant identity to process the registration | |
Support merchants create a new direct store in the BNC system. Here this direct store allows you to register a store through the same merchant identity and settlement details with the parent merchant. | |
The call back would be raised by BNC once the registration had already done | |
Support the registration result inquiry when the merchant can not get the result back from BNC | |
Support merchants create a new store in the BNC system |
5. BNC QRIS MPM Acquirer Open API SNAP
API Name | Function |
|---|---|
MPM Code Generation | Interface used to generate the QR. Support to generate both static and dynamic QR |
Transaction Status Notification | The payment status will be sent by BNC to partner system. Currently only notification for success payment will be sent |
Transaction Status Inquiry | Interface used to inquiry payment status for dynamic QR only |
Refund | Interface used to initiate refund for payment with success status |
Transaction History List | Interface used to inquiry payment status for static QR only |
Daily Report Download | Interface used to download the daily transaction or settlement report within 90 days |
Transaction Cancellation | Interface used to cancel the pending transaction. The payment status will be changed into cancelled. It is only for dynamic QR |
6. Term Definitions
Term | Definition |
|---|---|
Client | Refers to the party making API calls |
Merchant | A business entity that can have one or more stores operating under it |
Store | A shop at a physical location offering BNC as a payment method |
Terminal ID | If terminal ID information is contained in QR code scanned by the user, the payment transaction will contain this identifier of the merchant’s terminal that the payment was made at |
7 System Requirement
7.1 Prerequisite
After the commercial agreement between BNC and client is finalized, each merchant will be assigned the following parameters for integration testing purposes.
Name | Description |
|---|---|
appId | Unique identifier to identify the caller of each request, to be added into the request header of each API method. |
Secret key | It should be shared offline and kept confidential between BNC and each client. |
7.2 API Rules
7.2.1 Protocol rules
This specifies the rules for calling APIs in this document.
Interface Call Rules
Banks using rest APIs are HTTP APIs designed in the STYLE of RESTful. All API requests must use HTTPS, and the message body of the request and answer must use the JSON format.
Data Format
The REST API uses only JSON as the data exchange format for the message body. The request must set the Http header for Enter-Type and Accept as application/json.
Character Set Specification
The REST API supports only a subset of UTF-8 character encoding: characters encoded by one to three bytes. This means that characters encoded by four to six bytes in the Unicode secondary plane are not supported.
Parameter Rules
The request was successful, regardless of the order in which the parameters were requested
The success of the request is independent of the order in which the key value pairs in the request JSON appear
When processing answers, you should not assume the order in which key value pairs in the answer JSON appear
The new API version may include new parameters or key value pairs for JSON
The new API version does not remove existing parameters or JSON key value pairs
When the value of the JSON key pair in the request or answer is empty (null), it can be omitted
The data in the API answer may contain data incoming from the merchant, i.e. user input that may be unchecked. To avoid XSS (Cross-site scripting) attacks, callers do appropriate escapes or filtering of the scenario before using the answer data.
Response Language
The API uses English as the default language for response, and only English is supported for the time being.
7.2.2 Request Header
All requests will require this 6 parameters as SNAP standard in the header.
Name | Type | Description | Mandantary | Sample |
Content-Type | application/json | Content type | M | application/json |
Authorization | String | / | M | Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a" |
X-TIMESTAMP | String | yyyy-MM-dd HH:mm:ss | M | 2020-12-17T10:55:00+07:00 |
X-SIGNATURE | String | / | M | 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c8625 61b19a5 |
ORIGIN | String | / | M | |
X-PARTNER-ID | String | / | M | 82150823919040624621823174737537 |
X-EXTERNAL ID | String （36） | / | M | 41807553358950093184162180797837 |
CHANNEL-ID | String | / | M | 95221 |
Sample
Content-type: application/json
Authorization: Bearer gp9HjjEj813Y9JGoqwOeOPWbnt4CUpvIJbU1mMU4a11MNDZ7Sg5u9a"
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
ORIGIN: http://www.hostname.com
X-PARTNER-ID: 82150823919040624621823174737537
X-EXTERNAL-ID: 41807553358950093184162180797837
CHANNEL-ID: 95221