NAV
JSON cURL

Introduction

The API is written according to the JSON API Specification. We highly recommend using a JSON API Client for consuming this API.

Environment Endpoint
Sandbox https://cms-sandbox.bongloy.com
Production https://cms.bongloy.com

Authentication

This API uses JSON Web Token (JWT) Bearer authentication. You must generate a JSON Web Token and include it in the Authorization header for all requests.

Request Signing

All requests require you to sign your JWT according to the RS256 (RSA using SHA-256 hash) algorithm.

While using the sandbox you can download this private key. Your sandbox account is already configured with the matching public key.

In production you must generate your own RSA public/private key pair and provide us with your public key.

The payload of your JWT must include:

{
  "api_token": "[your api token]",
  "timestamp": "1581510124"
}

Generating a RSA public/private key pair

$ openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:4096
$ openssl rsa -pubout -in private_key.pem -out public_key.pub

Sample Code (Ruby)

require "net/http"
require "uri"
require "jwt"

jwt_payload = {
  "api_token": "[your api token]",
  "timestamp": Time.now.to_i
}

private_key = OpenSSL::PKey::RSA.new(File.read("[YOUR PRIVATE KEY]"))
jwt = JWT.encode(jwt_payload, private_key, 'RS256')

uri = URI.parse("https://cms-sandbox.bongloy.com/v1/transactions")
request = Net::HTTP::Get.new(uri.request_uri)
request["Content-Type"] = "application/vnd.api+json"
request["Authorization"] = "Bearer #{jwt}"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
response = http.request(request)

p response.body

Webhooks

Bongloy uses webhooks to notify your application when an event happens in your account. Bongloy signs the webhook events it sends to your endpoint by including a signature in each event's Authorization header. This allows you to verify that the events were sent by Bongloy, not by a third party.

All requests are signed using JSON Web Token (JWT) Bearer authentication, according to the HS256 (HMAC-SHA256) algorithm.

You should verify the events that Bongloy sends to your Webhook endpoints. Here's an example in Ruby:

JWT.decode(
  request.headers["Authorization"].sub("Bearer ", ""),
  "[your-webhook-signing-secret]",
  true,
  algorithm: "HS256",
  verify_iss: true,
  iss: "Bongloy"
)

Currencies

All API responses return amounts the currency's smallest unit. For example, a 10 USD transaction, would be returned as 1000 (i.e., 1000 cents).

Pagination

Bongloy utilizes cursor-based pagination via the after and before parameters. Both parameters take an existing ID value (see below) and return objects in reverse chronological order. Requests for resources that support pagination return page navigation links to the next and previous page.

Example

Request

Endpoint

GET /connect/v1/transactions?page[size]=2

GET /connect/v1/transactions

Parameters

page: {"size"=>"2"}
Name Description
page[size] A limit on the number of objects to be returned, between 1 and 100. Default is 10.
page[after] A cursor for use in pagination. after is the ID that defines your place in the list. For instance, if you make a list request and receive 10 objects, ending with ID abc, your subsequent call can include after=abc in order to fetch the next page of the list.
page[before] A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 10 objects, starting with ID def, your subsequent call can include before=def in order to fetch the previous page of the list.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/transactions?page[size]=2" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer lhjZPzxJaWj5f-86Owo_JDhEndLb80b4k2CoO16Tsio"

Authentication

Test Data

While testing in the sandbox you can use the following phone number and OTP code for authentication.

Phone Number OTP
85513333333 123456

Create a cardholder verification

Request

Endpoint

POST /connect/v1/cardholder_verifications

POST /connect/v1/cardholder_verifications

Parameters

{
  "data": {
    "type": "cardholder_verification",
    "attributes": {
      "phone_number": "85512583587",
      "account_identifier": "302000205"
    }
  }
}
Name Description
data[attributes][phone_number] required The cardholder's phone number in E.164 format
data[attributes][account_identifier] required A unique identifier for account

Response


201 Created
[binary data]
curl "https://cms-sandbox.bongloy.com/connect/v1/cardholder_verifications" -d '{
  "data": {
    "type": "cardholder_verification",
    "attributes": {
      "phone_number": "85512583587",
      "account_identifier": "302000205"
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer Q1oGfoQQLTW13c0AtSyXQDySdX00gUSDcE3X4UfsRXQ"

Authenticate a cardholder

Request

Endpoint

POST /oauth/token

POST /oauth/token

Parameters

{
  "grant_type": "password",
  "scope": "connect",
  "auth_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImY1YzlhZWJlMjM0ZGE2MDE2YmQ3Yjk0OTE2OGI4Y2Q1YjRlYzllZWIiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vYm9uZ2xveS1hcHAtc2FuZGJveCIsImF1ZCI6ImJvbmdsb3ktYXBwLXNhbmRib3giLCJhdXRoX3RpbWUiOjE1OTAwNTUxMjEsInVzZXJfaWQiOiJ0R21oMEl2M0dMU2FFandqREYwRHFMS3UzencxIiwic3ViIjoidEdtaDBJdjNHTFNhRWp3akRGMERxTEt1M3p3MSIsImlhdCI6MTU5MDA1NTEyMiwiZXhwIjoxNTkwMDU4NzIyLCJwaG9uZV9udW1iZXIiOiIrODU1MTMzMzMzMzMiLCJmaXJlYmFzZSI6eyJpZGVudGl0aWVzIjp7InBob25lIjpbIis4NTUxMzMzMzMzMyJdfSwic2lnbl9pbl9wcm92aWRlciI6InBob25lIn19.MKsGU4OeyyXDwgroKTu5yZFsw8LK7gubHflJ8TguEQ1nhuSpe3CWi56R-Cvviz54d2IdP09JHdEp5NFyoHcVAb9Pfkmo1wY1GrpVIulzzNBs2b-7JZe9ruEdgycUpDHpGC6glO39rnLaYvd9ZJZijrwDH3AUz5JN5LO0wAHWl9j23kqdTc5P5_n-n5dDQl4rPTwSZRWlXOqnqNfom4gpmYPR5OQf8Eot8meEYYDjpDxVQjobXhe5XaMObiis_EhbIUuZD6x3n3aYY3wj18d_KlN7iLWYTr8Z4_SScTi43cQa11mjdIpd-1BaFweoC30PhZUAINy1ymLx98esHaaIMA",
  "cardholder_verification_id": "661b2833-976f-4267-ad76-4be85c2c17bf",
  "client_id": "_-ByUVN1cFGzFkPXIBA3f6aEC4c_-6A5DNjxY36iPo4",
  "client_secret": "iHZaqNkq9qHwavULoccnTJzENTP6nOgol5N2-pZHd24"
}
Name Description
grant_type required The grant_type of the token. Must be password
scope required Must be connect
client_id required The client id of the application
client_secret required The client secret of the application
auth_token required The auth token from the authentication provider
cardholder_verification_id required The id of the cardholder_verification

Response


200 OK
[binary data]
curl "https://cms-sandbox.bongloy.com/oauth/token" -d '{
  "grant_type": "password",
  "scope": "connect",
  "auth_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImY1YzlhZWJlMjM0ZGE2MDE2YmQ3Yjk0OTE2OGI4Y2Q1YjRlYzllZWIiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vYm9uZ2xveS1hcHAtc2FuZGJveCIsImF1ZCI6ImJvbmdsb3ktYXBwLXNhbmRib3giLCJhdXRoX3RpbWUiOjE1OTAwNTUxMjEsInVzZXJfaWQiOiJ0R21oMEl2M0dMU2FFandqREYwRHFMS3UzencxIiwic3ViIjoidEdtaDBJdjNHTFNhRWp3akRGMERxTEt1M3p3MSIsImlhdCI6MTU5MDA1NTEyMiwiZXhwIjoxNTkwMDU4NzIyLCJwaG9uZV9udW1iZXIiOiIrODU1MTMzMzMzMzMiLCJmaXJlYmFzZSI6eyJpZGVudGl0aWVzIjp7InBob25lIjpbIis4NTUxMzMzMzMzMyJdfSwic2lnbl9pbl9wcm92aWRlciI6InBob25lIn19.MKsGU4OeyyXDwgroKTu5yZFsw8LK7gubHflJ8TguEQ1nhuSpe3CWi56R-Cvviz54d2IdP09JHdEp5NFyoHcVAb9Pfkmo1wY1GrpVIulzzNBs2b-7JZe9ruEdgycUpDHpGC6glO39rnLaYvd9ZJZijrwDH3AUz5JN5LO0wAHWl9j23kqdTc5P5_n-n5dDQl4rPTwSZRWlXOqnqNfom4gpmYPR5OQf8Eot8meEYYDjpDxVQjobXhe5XaMObiis_EhbIUuZD6x3n3aYY3wj18d_KlN7iLWYTr8Z4_SScTi43cQa11mjdIpd-1BaFweoC30PhZUAINy1ymLx98esHaaIMA",
  "cardholder_verification_id": "661b2833-976f-4267-ad76-4be85c2c17bf",
  "client_id": "_-ByUVN1cFGzFkPXIBA3f6aEC4c_-6A5DNjxY36iPo4",
  "client_secret": "iHZaqNkq9qHwavULoccnTJzENTP6nOgol5N2-pZHd24"
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer NjcL0Kr7zC0rnhhMZkpKzHKcBVPIliBdORo-0M2HdaM" \
    -H "X-Device-Token: device-registration-token"

Refresh cardholder access token

Request

Endpoint

POST /oauth/token

POST /oauth/token

Parameters

{
  "grant_type": "refresh_token",
  "refresh_token": "0R9VGdpUvsTajiVq8JH5MQ",
  "client_id": "xtLCzo8n7WP7VQ8hp_EazdSsRdx0WPcJMllg8osWd5o",
  "client_secret": "NHBTzpRfZZJ629XNmKoxX3qoD4fIBZPuHnOQb6lyO30"
}
Name Description
grant_type required The grant_type of the token. Must be refresh_token
refresh_token required The refresh token
client_id required The client id of the application
client_secret required The client secret of the application

Response


200 OK
[binary data]
curl "https://cms-sandbox.bongloy.com/oauth/token" -d '{
  "grant_type": "refresh_token",
  "refresh_token": "0R9VGdpUvsTajiVq8JH5MQ",
  "client_id": "xtLCzo8n7WP7VQ8hp_EazdSsRdx0WPcJMllg8osWd5o",
  "client_secret": "NHBTzpRfZZJ629XNmKoxX3qoD4fIBZPuHnOQb6lyO30"
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer NjcL0Kr7zC0rnhhMZkpKzHKcBVPIliBdORo-0M2HdaM" \
    -H "X-Device-Token: device-registration-token"

Logout a cardholder

Request

Endpoint

POST /oauth/revoke

POST /oauth/revoke

Parameters

{
  "token": "3u7Alb-IgemcwdAAGC1aMGcLuQIHBdz3EAJepNTBR9o",
  "client_id": "5XST4Z87WxKJ9qSb_XTEKcBTR7zTTgY4Kb-YsWaAtsE",
  "client_secret": "8yZ6ig4UN-u5rj9K9DTOaw7ktGt_CO-YC3qhIcukPtA"
}
Name Description
token required The token in which to revoke. Can be either a refresh token or an access token
client_id required The client id of the application
client_secret required The client secret of the application

Response


200 OK
[binary data]
curl "https://cms-sandbox.bongloy.com/oauth/revoke" -d '{
  "token": "3u7Alb-IgemcwdAAGC1aMGcLuQIHBdz3EAJepNTBR9o",
  "client_id": "5XST4Z87WxKJ9qSb_XTEKcBTR7zTTgY4Kb-YsWaAtsE",
  "client_secret": "8yZ6ig4UN-u5rj9K9DTOaw7ktGt_CO-YC3qhIcukPtA"
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer NjcL0Kr7zC0rnhhMZkpKzHKcBVPIliBdORo-0M2HdaM" \
    -H "X-Device-Token: device-registration-token"

Account Balance

Retrieve an account balance

Request

Endpoint

GET /connect/v1/accounts/581e752a-6075-45e3-895e-8835968b7a3e/balance

GET /connect/v1/accounts/:account_id/balance

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/accounts/581e752a-6075-45e3-895e-8835968b7a3e/balance" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer GIQUIQR6K2TPX3a9RrCCprPKBONixops9XXg41xaHC8"

Accounts

List all accounts

Request

Endpoint

GET /connect/v1/accounts

GET /connect/v1/accounts

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/accounts" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer 0EvjuDIrXk585DZh2ChjST-TZg-tXzmqRtXWDQaYgSE"

Retrieve an account

Request

Endpoint

GET /connect/v1/accounts/724118a8-0f06-4b29-b90c-06be99d70992

GET /connect/v1/accounts/:id

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/accounts/724118a8-0f06-4b29-b90c-06be99d70992" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer Jh4aaK-QmBYNOjgEXlftqngtFv2_TXfmyZzJkRejNCk"

Cardholder

Retrieve cardholder information

Request

Endpoint

GET /connect/v1/cardholder

GET /connect/v1/cardholder

Parameters

None known.

Response


200 OK
{
  "data": {
    "id": "323c4ef6-5d21-44ba-b8cb-b45d915a19ea",
    "type": "cardholder",
    "attributes": {
      "created_at": "2021-02-12T04:29:13Z",
      "updated_at": "2021-02-12T04:29:13Z",
      "name": "Meta Kanha",
      "phone_number": "855715100860",
      "email": null,
      "type": "individual",
      "status": "active",
      "additional_details": {
        "name_km": "មេត្តា កញ្ញា",
        "member_id": "P01-123456",
        "member_since": "2020"
      },
      "metadata": {
      },
      "individual": {
        "address": "#87, Street 63 (Trasak Paem), Sangkat Boeung Raing, Khan Daun Penh, Phnom Penh, Cambodia",
        "date_of_birth": "2003-02-12",
        "identity_document_number": "A123456789",
        "identity_document_type": "id_card"
      }
    }
  }
}
curl -g "https://cms-sandbox.bongloy.com/connect/v1/cardholder" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer RsO0UYI4UA8wW_mBjNfXK1bR100Uj-gNS9LmsAdCxo0"

Cards

List all cards

Request

Endpoint

GET /connect/v1/cards

GET /connect/v1/cards

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/cards" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer oaJYKf1ZPRGLc2iA7KqIoHC1wTl23SaBrPF-8dSw1uo"

Retrieve a card

Request

Endpoint

GET /connect/v1/cards/0730f088-7f87-4545-91f4-95b9dadfe6d3

GET /connect/v1/cards/:id

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/cards/0730f088-7f87-4545-91f4-95b9dadfe6d3" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer MVVMIFPwub0tElevE5SJCI7zReTlPT3Hjp0gdmdFPOM"

Transactions

List all transactions

Request

Endpoint

GET /connect/v1/transactions?filter[status]=settled&filter[account]=7c5f5a6c-905f-4a29-b6ad-edbef319acf0&filter[from_date]=2020-01-01T00%3A00%3A00Z&filter[to_date]=2020-01-01T12%3A00%3A00Z

GET /connect/v1/transactions

Parameters

filter: {"status"=>"settled", "account"=>"7c5f5a6c-905f-4a29-b6ad-edbef319acf0", "from_date"=>"2020-01-01T00:00:00Z", "to_date"=>"2020-01-01T12:00:00Z"}
Name Description
filter[account] Return transactions belonging to the account with the provided ID.
filter[card] Return transactions belonging to the card with the provided ID.
filter[status] Return transactions with the provided status. Either settled or pending.
filter[balance_adjustment_type] Return transactions with the provided balance_adjustment_type. Either credit or debit.
filter[from_date] Return transactions on or after the provided date/time in ISO 8601 format.
filter[to_date] Return transactions on or before the provided date/time in ISO 8601 format.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/transactions?filter[status]=settled&filter[account]=7c5f5a6c-905f-4a29-b6ad-edbef319acf0&filter[from_date]=2020-01-01T00%3A00%3A00Z&filter[to_date]=2020-01-01T12%3A00%3A00Z" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer vT0uhn1Gx7gIvdwo0brBRVV4Mc1RVanXimEPYFQPP4Y"

Retrieve a transaction

Request

Endpoint

GET /connect/v1/transactions/94d662c4-b3e6-4ebe-a333-f5ea97d933da

GET /connect/v1/transactions/:id

Parameters

None known.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/transactions/94d662c4-b3e6-4ebe-a333-f5ea97d933da" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer DYIMN323rmF-myqegkGK8YEpYRNjrUmwHCoBKUZXxA4"

Get a transaction summary

Returns a summary of transactions for the current month

Request

Endpoint

GET /connect/v1/transactions/summary?filter[account]=f57d1e7a-60d7-4895-92ca-2bfce1630989

GET /connect/v1/transactions/summary

Parameters

filter: {"account"=>"f57d1e7a-60d7-4895-92ca-2bfce1630989"}
Name Description
filter[account] required Return a summary of transactions belonging to the account with the provided ID.

Response


200 OK
[binary data]
curl -g "https://cms-sandbox.bongloy.com/connect/v1/transactions/summary?filter[account]=f57d1e7a-60d7-4895-92ca-2bfce1630989" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer EoINb3Uh-nvJycG4Wp0crfTpVyEkcH09EWAw4siiBaU"