BSI Pembayaran Institusi
BPI - MAJA
API Documentation
Version: 2.0
1. Overview
This specification describes the API specifications and Transaction Flow that will be used by
Merchants to register invoice and payment method to be used.
2. Requirement
You must have username, password, client id and client secret to authenticate with our
resource server. The resource server is uses standard OpenID authentication (Resource
owner password grant).
3. Transaction Flow
* To make sure you get correct payment notification, please do a payment inquiry after receiving the
notification.
4. Authentication
Authentication type: OpenID
Grant type: password (Resource Owner Password Grant)
a) Get Access Token
You can get an access token by authentication to our Authorization Service. For
example:
curl -d "grant_type=password" \
-d "client_id=<YOUR CLIENT ID>" \
-d "client_secret=<YOUR CLIENT SECRET>" \
-d "username=<YOUR USERNAME> " \
-d "password=<YOUR PASSWORD>" \
https://authorization.url
b) List authorization.url
Dev : https://account.makaramas.com/auth/realms/bpi-dev/protocol/openid-connect/token
Prod : https://account.makaramas.com/auth/realms/bpi/protocol/openid-connect/token
c) Add Authorization Header
Please add Authorization header with the following format:
Bearer <ACCESS TOKEN>
Contact us for client credentials information.
5. Invoice Registration
a) Flow
b) End Point
Primary
HTTP Method: POST
URL: https://billing-bpi-dev.maja.id/api/v2/register
Alternative
HTTP Method: POST
URL: https://billing-bpi-dev.maja.id/api/v2/invoice
c) Post Data (JSON)
Field Type Required? Description
name String Yes Customer name
email String No Customer email
phone String No Customer phone
address String No Customer Address
openPayment Boolean No Openpayment status
va String Yes Unique Virtual Account (5-12 Free Digit)
sequenceNumber Int No Sequence number (lowest number has
highest priority)
attribute1 String No Custom Attribute
attribute2 String No Custom Attribute
attribute3 String No Custom Attribute
attribute4 String No Custom Attribute
attribute5 String No Custom Attribute
amount Double Yes Invoice amount
activeDate String No Active Date (YYYY-MM-DD)
inactiveDate String No Inactive Date (YYYY-MM-DD)
date String Yes Invoice Date
items Array Yes Items (see invoice items)
attributes Array Yes Additional attributes (see Invoice
Attributes)
You can fill with empty array
Invoice Items
Field Type Required? Description
description String Yes Description
qty Integer Yes Quantity
unitPrice Double Yes Unit price
amount Double Yes Total amount
Invoice Attributes
Field Type Required Description
?
name String Yes Attribute name
value String Yes Attribute value
d) Example request
{
"date": "2021-02-28",
"amount": 100000,
"name": "Alfiyah",
"email": "alfiya@sebuahdomain.com",
"va": "88081234567",
"openPayment": false,
"attribute1": "Fasilkom",
"attribute2": "Manajemen Sistem Informasi",
"items": [
{
"description": "Registration",
"unitPrice": 100000,
"qty": 1,
"amount": 100000
}
],
"attributes": []
}
e) Example response
{
"timestamp": "2021-02-28T04:45:19.104+00:00",
"code": "00",
"message": "Sukses",
"success": true,
"data": {
"id": 18825,
"date": "2021-02-28T00:00:00.000+00:00",
"number": 2501,
"activeDate": null,
"inactiveDate": null,
"currency": "IDR",
"amount": 100000.0,
"paid": false,
"paidDate": null,
"revision": 3,
"sequenceNumber": 1,
"openPayment": false,
"createdBy": null,
"createdDate": "2021-02-28T14:45:19.416+00:00",
"partialyPaid": false,
"lastPaymentDate": "2021-02-28T15:16:23.975+00:00",
"totalPayment": 0.0,
"remainingAmount": 100000.0,
"va": "88081234567",
"name": "Alfiyah",
"email": "alfiyah@sebuahdomain.com",
"phone": "081222888215",
"address": null,
"attributes": [],
"items": [
{
"id": 18826,
"description": "Registration",
"unitPrice": 100000.0,
"qty": 1,
"amount": 100000.0,
"paid": false,
"createdAt": "2021-02-28T14:45:19.435+00:00",
"updatedAt": "2021-02-28T14:45:19.435+00:00"
}
],
"attribute1": "Fasilkom",
"attribute2": "Manajemen Sistem Informasi",
"attribute3": "",
"attribute4": "",
"attribute5": "",
"tax": 0.0,
"taxDescription": null,
"transactionId": null,
"payMethod": null,
"bankVa": null,
}
}
6. Updating the Invoice
a) End Point
Primary
HTTP Method: POST
URL: https://billing-bpi-dev.maja.id/api/v2/update/{invoice_number}
Alternative
HTTP Method: PUT
URL: https://billing-bpi-dev.maja.id/api/v2/invoice
invoice number are unique number generated by registering invoice.
Update process uses the same specifications as the register process.
b) Post Data (JSON)
Field Type Required? Description
name String Yes Customer name
email String No Customer email
phone String No Customer phone
address String No Customer Address
openPayment Boolean No Openpayment status
va String Yes Unique Virtual Account
sequenceNumber Int No Sequence number (lowest number has
highest priority)
attribute1 String No Custom Attribute
attribute2 String No Custom Attribute
attribute3 String No Custom Attribute
attribute4 String No Custom Attribute
attribute5 String No Custom Attribute
amount Double Yes Invoice amount
activeDate String No Active Date (YYYY-MM-DD)
inactiveDate String No Inactive Date (YYYY-MM-DD)
date String Yes Invoice Date
items Array Yes Items (see invoice items)
attributes Array Yes Additional attributes (see Invoice
Attributes)
You can fill with empty array
number Long Yes Required if using alternative version
Invoice Items
Field Type Required? Description
description String Yes Description
qty Integer Yes Quantity
unitPrice Double Yes Unit price
amount Double Yes Total amount
Invoice Attributes
Field Type Required? Description
name String Yes Attribute name
value String Yes Attribute value
c) Example request
{
"date": "2021-02-28",
"amount": 200000,
"name": "Alfiyah",
"va": "88081234567",
"openPayment": true,
"attribute1": "Fasilkom",
"attribute2": "Manajemen Sistem Informasi",
"items": [
{
"description": "Registration",
"unitPrice": 100000,
"qty": 2,
"amount": 200000
}
],
"attributes": []
}
7. Payment Notification
a) Transaction Flow
After the customer pays for the virtual account through the bank channel (ATM,
I-BANK, SMS, etc.) the core banking will send a notification to the BPI, If the payment
status is successful, the system will update the invoice, then send a payment
notification to the merchant.
b) Default BPI Payments Notification Request (to merchant)
Field Type Description
code String Response Code
message String Response Message
type String Transaction type (“payment”)
id Long Invoice ID
number Long Invoice Number
amount Double Payment Amount
remainingAmount Double Remaining Amount
virtualAccount String Virtual account number (deprecated)
date String Transaction Date
bankCode String Bank Code
bankName String Bank Name
ref String Reference Code
channel String Payment Channel
name String Customer Name
phone String Customer Phone
email String Customer Email
address String Customer Address
va String Virtual account number
c) Example Notification
{
"code": "00",
"message": "Transaksi berhasil",
"type": "payment",
"id": 109021,
"number": 8087,
"amount": 100000,
"remainingAmount": 0,
"va": "88081234567",
"date": "2021-11-22",
"bankCode": "BSM",
"bankName": "Bank Syariah Mandiri",
"ref": "20211221304320001",
"channel": "ATM",
"name": "Alfiyah",
"phone": "",
"email": "alfiyah@sebuahdomain.com",
"address": ""
}
8. Inquiry
You may run inquiry process to make sure you are getting the correct payment
notifications.
a) Endpoint
HTTP Method: POST
URL: https://billing-bpi-dev.maja.id/api/v2/inquiry
b) Post Body
Field Type Required Description
?
va String Yes Virtual Account Number
invoiceNumber String Yes Invoice Number
amount String No Amount
c) Example Request
{
va: “80801234567”,
invoiceNumber: “8087”,
amount: “100000”,
}
d) Example Response
{
code: “00”,
message: “Inquiry Berhasil”,
data: {
date: “2020-11-21”,
amount: 100000,
name: “Alfiyah”,
email: “alfiyah@sebuahdomain.com”,
va: “88081234567”,
attribute1: “Fasilkom”,
attribute2: “Manajemen Sistem Informasi”,
items: [
{
“description”: “Registration”,
“unitPrice”: 100000,
“qty”: 1,
“amount”: 100000
}
],
paid: true,
remainingAmount: 0
}
}
9. Cancel the Invoice
a) Endpoint
HTTP Method: POST
URL: https://billing-bpi-dev.maja.id/api/v2/cancel
b) Post Data
Field Type Required Description
?
va String Yes Virtual Account Number
invoiceNumber Long Yes Invoice Number
amount Double No Amount
c) Example Request
{
va: “80801234567”,
invoiceNumber: 8087,
amount: 100000,
}
d) Example Response
{
code: “00”,
message: “Tagihan dibatalkan”
}
