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

Cardholder Authorization

Getting a Cardholder Access Token

For some API endpoints, such as Transfers you need explicit permission from the cardholder. Obtaining an access token requires a cardholder to authorize the app for the requested scopes. Then the cardholder's access token can be requested.

Request Cardholder Authorization

Direct the user to /oauth/authorize with the following query parameters:

Query Parameter Description
response_type Access response type being requested. The supported authorization workflow requires the value code.
redirect_uri URI to handle successful user authorization. Must match with Development or Production Redirect URI in your OAuth app settings.
client_id OAuth application's Development or Production Client ID.
cardholder_id The id of the cardholder
scope The scopes in which to authorize. Only transactions:transfer is supported at this time

Example:

https://cms-sandbox.bongloy.com/oauth/authorize?client_id=3T_pVr97_RJ3xMbYFTarDw1XVlcrUaz3GBKAZWYT79s&cardholder_id=2810059e-7a76-4b33-9ba6-65d4bf8491bd&redirect_uri=your-app://back-from-oauth&scope=transactions:transfer&response_type=code

After the cardholder has been redirected, they will be asked to enter their phone number. For testing purposes you can use the following phone number and OTP. Note that the phone number must match the provided cardholder's phone number.

Phone Number OTP
85513333333 123456

If authorized, the user will be redirected to the redirect_uri with the authorization code in the code query parameter.

your-app://back-from-oauth?code=obBEe8ewaL_KdyNjniT4KPd8ffDWt9fGB

Create a cardholder access token

Request

Endpoint

POST /oauth/token

POST /oauth/token

Parameters

{
  "grant_type": "authorization_code",
  "code": "j9-8C58Y7pxGqDV9c9GcqDvs-Iv8XT0H5rWh2NPEfdk",
  "redirect_uri": "https://www.example.com",
  "client_id": "SChO1QQJVtOhQeXc56oX9SpSwJEUteMNh6r_hLkvCaU",
  "client_secret": "KLZbba2HiuvhMZs9HKGPNUZRK41sCW5MZQRbSbrTd_M"
}
Name Description
grant_type required The grant_type of the token. Must be authorization_code
code required The code returned from the authorization flow
client_id required The client id of the application
client_secret required The client secret of the application
redirect_uri required The redirect_uri for your application

Response


200 OK

[binary data]

curl "https://cms-sandbox.bongloy.com/oauth/token" -d '{
  "grant_type": "authorization_code",
  "code": "j9-8C58Y7pxGqDV9c9GcqDvs-Iv8XT0H5rWh2NPEfdk",
  "redirect_uri": "https://www.example.com",
  "client_id": "SChO1QQJVtOhQeXc56oX9SpSwJEUteMNh6r_hLkvCaU",
  "client_secret": "KLZbba2HiuvhMZs9HKGPNUZRK41sCW5MZQRbSbrTd_M"
}' -X POST \
    -H "Content-Type: application/vnd.api+json"

Refresh a cardholder access token

Request

Endpoint

POST /oauth/token

POST /oauth/token

Parameters

{
  "grant_type": "refresh_token",
  "refresh_token": "rLqd0yXgjzp5yd4n7wDPRw",
  "client_id": "QvEzKwHdqec8TekuL4Rz6jQ1V6fOYI1lOvaP5FB-AuY",
  "client_secret": "RnI_zqeP8YBUKHJehgOEaQ4PGQHX-0_9BftF9Varrys"
}
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": "rLqd0yXgjzp5yd4n7wDPRw",
  "client_id": "QvEzKwHdqec8TekuL4Rz6jQ1V6fOYI1lOvaP5FB-AuY",
  "client_secret": "RnI_zqeP8YBUKHJehgOEaQ4PGQHX-0_9BftF9Varrys"
}' -X POST \
    -H "Content-Type: application/vnd.api+json"

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 /v1/transactions?page[size]=2

GET /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/v1/transactions?page[size]=2" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJPb0xXOFc5THVfNDFsM3BjRnVlVXdpX0hab1FiVU1iNFB6OVFjQTBGNC1ZIiwidGltZXN0YW1wIjoiMTYxMzEwNDE0OSJ9.hdSnvzEamaAd-dT1CyNQNgGrm0_xB48dXnom-_LSTa8Selbbtq5UlTvtDvM5U9VVMm1Nb2XE8SCOpe-gJsp3mHxa00kpBZy_qK9WSKf77uc_hWgvrQbqC-OUB8UaeUvSPovdaS9PtWK_o18ltY2YVBWdXPwDMOOwrsXr04Pd2rTJJ_uKCVrk5pClAe8fik-vXeuCfZ_p3ml7uMjfl21MgmAFZhXdZMTEUth-gq87hNWIh3cRmDKeFtKD7DvB_pf4E3LkXJF_2DjsIaVA0vX_CJuakxh_KU4kTuQorfQ-5Mexk7pkNO6LbPaTT2srTLYe03tlZ-gFHDA-P3YIvL8Czg"

Account Inquiry

Lookup an account

Request

Endpoint

GET /v1/account_inquiry?filter[account_identifier]=001123456

GET /v1/account_inquiry

Parameters

filter: {"account_identifier"=>"001123456"}
Name Description
filter[account_identifier] required The account identifier of the account to inquire

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/account_inquiry?filter[account_identifier]=001123456" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJXWlgyM3gwa0RWeTIwdHB3UlBZejA3bzdWS1c1TFo3X0NtTF9ZVEJVRFVrIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NSJ9.TkstTlOTgk-uM3MjoSOu_zb-npvHFq2Q025RyI7aF4-JF0UjznmbblokrTF2qrU_i12iyxqibBl3PiFbBgeNqAwUT-ngxLMWnQVXiMTB2bktJkiBN0t7THeplPKo63CGCrOegDoGT0KoOY-yyE69lzx1H7Cy4j0IOUivnVkSsCRku6ZlU6JHwCEdPAV47-yABTUfWQGcrowpdynovyHNO8yZ7Wrd2i04TaVrpKq7CUgw9dXVMbY7oSiKv3d0pPeT6RbjB-Mb94UaA6mEBmJqMUS898S-xnu8LDV20mnXKhOo8lutxOS3lujv4rmY540cfNqrzN39W185bDO6GIypPA"

Account Balance

Retrieve an account balance

Request

Endpoint

GET /v1/accounts/42c32ebe-6e30-4a54-88b4-080d3d0e500d/balance

GET /v1/accounts/:account_id/balance

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/accounts/42c32ebe-6e30-4a54-88b4-080d3d0e500d/balance" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJkV1d2Y3dLdDZXd2gycE40c2hmWTZJRDJNRnRGNjczSnhLRnVJdzByb3NjIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NSJ9.BmTSCPKCaTkS2Cg1srA61c7JsJ6i1OmwbGGyL4AQD1itFCMXG2xaAGspkAogKT-hnoU6v4QA_25WkqWN3123uuMDZ-B41QviFx--5MmIptDOuSJL_pnaopNAF1RSkPEz6YkUjZjDaz97ejBbBc87XNT11DOZV1t1KsF5_Xf8_ygHCUKUBo121f4GG4ss6NPJ_dA9TkDtJW6xJOXUiErHqKnq5F2FXfX2eLe6zeza7McGmiV7swd5WEyZwG1xyyccRiAgJU24ju782xRfrATZk9lai80ZTutmxDPcKX1S8Rr1GGHFY6kfN7HbsWlubV3kQhGVZn_rdA1JxEU-7xk39Q"

Accounts

Create an account

Request

Endpoint

POST /v1/accounts

POST /v1/accounts

Parameters

{
  "data": {
    "type": "account",
    "attributes": {
      "number": "123456",
      "currency": "USD",
      "metadata": {
        "foobar": "foobar"
      }
    },
    "relationships": {
      "cardholder": {
        "data": {
          "type": "cardholder",
          "id": "61af32e8-0ea4-48bf-a41a-5e971d34b1c9"
        }
      }
    }
  }
}
Name Description
data[attributes][currency] required The currency of the account. Only USD is supported at this time
data[attributes][number] required A unique 6 digit number set by the issuer. This must uniquely identify the account in the issuer's system.
data[attributes][metadata] Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
data[relationships][cardholder] required The id of the cardholder in which the account will be created for

Response


201 Created

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/accounts" -d '{
  "data": {
    "type": "account",
    "attributes": {
      "number": "123456",
      "currency": "USD",
      "metadata": {
        "foobar": "foobar"
      }
    },
    "relationships": {
      "cardholder": {
        "data": {
          "type": "cardholder",
          "id": "61af32e8-0ea4-48bf-a41a-5e971d34b1c9"
        }
      }
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJtWVhmLURBaW00Qk5RLThvM2hMUlpsQzZfQ01wNkRCbmNHNVhlUGh5MVQ4IiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NSJ9.LaAtGQxNwbmFBUXtl_PEFZDZrPHmAVc8--GxFWsnCEPP5_ugRzOfHPwz2rjvE0-UL5E69aXojaeqEWWIcaiI1n_faCa3RaMkGusXO9lIW61YNHsIHMt6Gvw6K2h5KX6x7a_0_LTfXsb7-JAJwo6rgrJpiAkIrQT9BtNJaEaFw1BUuhbFw0HRkX7qir1HKNr0kV_lIOHUhPWt4VkzxKZXwBPk9BOh3QsJbnP_8GRbUZkU7a2oClUFUOZZ2QH28SACtw1vOEdyH2Ekp2btMsZmOH5nGlPNSQXLu9CPJ3B_lZWckPCS46CUSYvmof2ehtWjoRlueRKMcwFn5F2KejdcHw"

Update an account

Request

Endpoint

PATCH /v1/accounts/bd39b6d0-db30-4dab-9a9b-3ee17a19fd89

PATCH /v1/accounts/:id

Parameters

{
  "data": {
    "type": "account",
    "id": "bd39b6d0-db30-4dab-9a9b-3ee17a19fd89",
    "attributes": {
      "metadata": {
        "buzz": "foobar"
      }
    }
  }
}

None known.

Response


200 OK

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/accounts/bd39b6d0-db30-4dab-9a9b-3ee17a19fd89" -d '{
  "data": {
    "type": "account",
    "id": "bd39b6d0-db30-4dab-9a9b-3ee17a19fd89",
    "attributes": {
      "metadata": {
        "buzz": "foobar"
      }
    }
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJJb1NlaE1TYkdYSnpwa2VnRkFDSkdndmRGOEhZZ0pWQ2VPSk0xUjBCNGJZIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NiJ9.JYcY7Teq8udwjDvlWYWCK5IsxDIn6E2_5TT742np4JZkfKhQc6zbIn4XaUdZkLda8oExC5kFnlRqhQM571TlHdEa1GxCxTuJQWPoFRde504sOauMBs28VqlDL1k1zrV4aJzp-ZexgKTSlKW0Zlk_BjRNqG-ncojM2X1G9e8jO5fVfSMHN8Mri2XBxxKX-G8O_c27dZi40fIcJ1O5-z-XLq5__F2JAsFLGtJxNTb1yWt5agaEZ2Q4Q2cxqh32jsT90-uaGrnzTBTvsoT4eaf6rZ12bpjlKLwvy6noYdoCTE4iRLubrJh5fZDXBBa9tkBGfMgWq_gBgaEsT46vkKR4vQ"

Retrieve an account

Request

Endpoint

GET /v1/accounts/08fa6486-19a0-4e4e-a7b5-a90ed1bfacee

GET /v1/accounts/:id

Parameters

Name Description
id required The id of the account to be retrieved.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/accounts/08fa6486-19a0-4e4e-a7b5-a90ed1bfacee" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiIweVdEOENKNzZ4SnY1TnhuT0dtTTNnS0lteHVjM1NGVTNseUI2cnpmcllBIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NiJ9.HygnrsUuo9lJyyb4l-e56u7XJVK9yue-oNgtFRg9BzT9FQtIuWJp1-S5-ijTgTl8iv-fTAnEZe3LXJ3N1xKqPXAfUrFwT2ynp98pJLzrvNf9Tp3YGu3yl_qLRia_I467jTyD0YiBWnVqArzcMvgsFtIaWniidiu0KPGlQ8tWw9adbw8mVUk2L7MxpwU39d0IiJ22ooRmLgWnDuvYhxMqATAIwEvnUryWIV1e2IKKavhe0Ye7ITxenyYqq-bGH6pHQ-lBax1mzndvLB7mNR7eEqBTYdedKHLiV4gyr3oZRaKE0t4CJBwZ1qJaWXNA9OeRdD7DFlqeEqK6z7eCXzU7hA"

List all accounts

Request

Endpoint

GET /v1/accounts

GET /v1/accounts

Parameters

Name Description
filter[cardholder] Only return accounts belonging to the Cardholder with the provided ID.
filter[account_identifier] Returns the account with the given identifier

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/accounts" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJmc0ZoZFRsTUpFQnN2RXdnWVVQc0JBX283RUswa0U0UjVSWVNJYm01RUlVIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NiJ9.M2XA2y2QocYGBymtHXnv1f4VFnKHNURvJF9anmTl8waiyZF7HjsgZGs84sQyQKUInV6T1Nfq2hFxQqZT4dZwASO2q4WjA4bFh25--6kzC6OaqUq2Nt17lwZAQkculufOMdzkQ28Yttl5F_op0lcPCnEx0vWorABX7lIHlEAK-of6ug3PxLENSlSXFvdgVNcB1B8TdZIHRrn3uAEpGiyszZ22MVsWoDSsg9JJOT_2KmmuISLPHK_NARo1x-Ge3ninJsvmplOEz0jT24UHaPJtNA06C_soJXFk76Dx4rmxcjrvHfH1PiDE88sMztRApLo79NkuB9VSM_HVd5EjKOiuVQ"

Cardholders

Create a cardholder

Request

Endpoint

POST /v1/cardholders

POST /v1/cardholders

Parameters

{
  "data": {
    "attributes": {
      "name": null,
      "name": "Tang Dara",
      "phone_number": "855715200960",
      "type": "individual",
      "individual": {
        "date_of_birth": "20161220",
        "address": "#87, Street 63 (Trasak Paem), Sangkat Boeung Raing, Khan Daun Penh, Phnom Penh, Cambodia",
        "remote_photo_url": "https://via.placeholder.com/150.png",
        "remote_identity_document_url": "https://via.placeholder.com/600.png",
        "identity_document_number": "123456789",
        "identity_document_type": "id_card"
      },
      "additional_details": {
        "name_km": "តាំង តារា",
        "member_since": "2017",
        "member_id": "P01-123456"
      },
      "metadata": {
        "foobar": "foobar"
      }
    },
    "type": "cardholder"
  }
}
Name Description
data[attributes][name] required The cardholder's name. This will be printed on cards issued to them.
data[attributes][phone_number] required The cardholder's phone number. This will be transformed to E.164 if it is not provided in that format already.
data[attributes][type] required Must be individual.
data[attributes][individual] required KYC requirements for an individual cardholder.
data[attributes][additional_details] Additional details to print on the card.
data[attributes][metadata] Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

Response


202 Accepted

{
  "data": {
    "id": "eb936ee1-c493-4d7f-abd1-dc8d22ca018f",
    "type": "cardholder",
    "attributes": {
      "created_at": "2021-02-12T04:29:16Z",
      "updated_at": "2021-02-12T04:29:16Z",
      "name": "Tang Dara",
      "phone_number": "855715200960",
      "email": null,
      "type": "individual",
      "status": "processing_profile",
      "additional_details": {
        "name_km": "តាំង តារា",
        "member_since": "2017",
        "member_id": "P01-123456"
      },
      "metadata": {
        "foobar": "foobar"
      },
      "individual": {
        "address": "#87, Street 63 (Trasak Paem), Sangkat Boeung Raing, Khan Daun Penh, Phnom Penh, Cambodia",
        "date_of_birth": "2016-12-20",
        "identity_document_number": "123456789",
        "identity_document_type": "id_card"
      }
    }
  }
}

curl "https://cms-sandbox.bongloy.com/v1/cardholders" -d '{
  "data": {
    "attributes": {
      "name": null,
      "name": "Tang Dara",
      "phone_number": "855715200960",
      "type": "individual",
      "individual": {
        "date_of_birth": "20161220",
        "address": "#87, Street 63 (Trasak Paem), Sangkat Boeung Raing, Khan Daun Penh, Phnom Penh, Cambodia",
        "remote_photo_url": "https://via.placeholder.com/150.png",
        "remote_identity_document_url": "https://via.placeholder.com/600.png",
        "identity_document_number": "123456789",
        "identity_document_type": "id_card"
      },
      "additional_details": {
        "name_km": "តាំង តារា",
        "member_since": "2017",
        "member_id": "P01-123456"
      },
      "metadata": {
        "foobar": "foobar"
      }
    },
    "type": "cardholder"
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJqR0tvVGRlS2NGcjJVdHpocFdLZmJOME44UmxLSXFlRm9JM3NzUEZLVGRZIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NiJ9.P3p7950MgwvIYmAoRe_2iBvXFACFwsbeMmJvNeNkhvtD6W-u6-sAs912Y9qlsMGF6Vg-_nmwTh9IcliGOmH5LmDu_rLHUzjOiVc8JakC4qD8k02inTKTXTlgb995XJfPM3YbpCPbFEw2TT75Mh4bzI9SYM0A2YexbKpVjsUe2WX74bjl_PQ8Dj2jucc3rFD601SX0mnQIir42EyKBA4k8f2_nSzQJKIgVPvzdDQwNNgFBrhNQTz0cK-B0Ifb4Mh1iowX-hqB1Me6FL4sxkIPRdyc_Cjnk6EbvIBcE96HfUNa0tJFkoZkV5Ip3tolmQPRqc5OwpByeYiM8PVrGPL-zg"

Update a cardholder

Request

Endpoint

PATCH /v1/cardholders/cb8ef5e6-6e8b-4f59-a6c8-49e5f02d838e

PATCH /v1/cardholders/:id

Parameters

{
  "data": {
    "type": "cardholder",
    "id": "cb8ef5e6-6e8b-4f59-a6c8-49e5f02d838e",
    "attributes": {
      "name": "Tang Dara",
      "phone_number": "855715100860",
      "individual": {
        "address": "new address",
        "remote_photo_url": "https://via.placeholder.com/150.png",
        "remote_identity_document_url": "https://via.placeholder.com/600.png"
      },
      "additional_details": {
        "member_since": "2017"
      },
      "metadata": {
        "foobar": "foobar"
      }
    }
  }
}

None known.

Response


202 Accepted

{
  "data": {
    "id": "cb8ef5e6-6e8b-4f59-a6c8-49e5f02d838e",
    "type": "cardholder",
    "attributes": {
      "created_at": "2021-02-12T04:29:17Z",
      "updated_at": "2021-02-12T04:29:17Z",
      "name": "Tang Dara",
      "phone_number": "855715100860",
      "email": null,
      "type": "individual",
      "status": "processing_profile",
      "additional_details": {
        "name_km": "តាំង តារា",
        "member_id": "P01-123456",
        "member_since": "2017"
      },
      "metadata": {
        "foo": "bar",
        "foobar": "foobar"
      },
      "individual": {
        "address": "new address",
        "date_of_birth": "2016-12-20",
        "identity_document_number": "123456789",
        "identity_document_type": "id_card"
      }
    }
  }
}

curl "https://cms-sandbox.bongloy.com/v1/cardholders/cb8ef5e6-6e8b-4f59-a6c8-49e5f02d838e" -d '{
  "data": {
    "type": "cardholder",
    "id": "cb8ef5e6-6e8b-4f59-a6c8-49e5f02d838e",
    "attributes": {
      "name": "Tang Dara",
      "phone_number": "855715100860",
      "individual": {
        "address": "new address",
        "remote_photo_url": "https://via.placeholder.com/150.png",
        "remote_identity_document_url": "https://via.placeholder.com/600.png"
      },
      "additional_details": {
        "member_since": "2017"
      },
      "metadata": {
        "foobar": "foobar"
      }
    }
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJ4OWtXTnZfajF2QWw5NzN6UDRGeFlwaEVucnp3NTNpLWhMR1F1YnV2bDY0IiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NyJ9.oXMGBNZZVoRO3jvvSSq70-jJGfHjKJZWhm7bXQDwFKgVayjTsK1oxhI8iyLIfhK1KEOO1yB5WDUeLNB5VNHpNQdwdNLBii4x0dY6cRbHlZ49YVL3rXzg7n4ZQ89yoUYlb2YaqVDeGmgVdSB_khNuqlRSsdZkWJI37abHB9csnldAE8RMcMQej6fI40KX36IGSkQof_0PJtl-h0RQfFlzwFxPZ_nz2oqU2p7G0zvVriMV_GascSidJPtHP3u9cxMw7lZcqZgfAsApUyT-SR45XayTHB5iJy0K1jYi76iyrWltyFZBgwJL5mJD-uUGQx2_oRokCjd-XzcIJOWhvCtaqQ"

Retrieve a cardholder

Request

Endpoint

GET /v1/cardholders/bc251aab-d33b-4453-93e9-695f150122c8

GET /v1/cardholders/:id

Parameters

Name Description
id required The id of the cardholder to be retrieved.

Response


200 OK

{
  "data": {
    "id": "bc251aab-d33b-4453-93e9-695f150122c8",
    "type": "cardholder",
    "attributes": {
      "created_at": "2021-02-12T04:29:17Z",
      "updated_at": "2021-02-12T04:29:17Z",
      "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/v1/cardholders/bc251aab-d33b-4453-93e9-695f150122c8" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJmZldxWFpMaklobW9ldXc3czBzdHRPSkNJSVNlWnV1bndhWklDLVFsSG5zIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1NyJ9.vPdBR7vaU-AIlu668K-Z-QkvSrYYsDqdb__v_GxF9p3RnvqIcd3S75Gp2hFys1QjrxW06NAeSZxbDOS2LP4Y6eGURWLPl-f8_vGmVEBfhPyk5yLBaj-nsBLD1oOySCGyWSMAmBIhxrF41Tq_Hiu9wkQTHXQw3mu6Vgr1-NgLO73eUaQ_cWWqxo5X881hHcO-fXVHv9AtzfG7JsE1Gi4_lkBS-ji9S4ra4Oy9I2sssePNopLTjnrUTFLJyUEabsav6jGGAGb1OUXb_r2TbCUCIkmE3b-Ynw5y_8sAMOCNpcJ-HRpcZBeYiEyPr26Zw-YMsJ4NC0NWxVSGCzIr-FfqHA"

List all cardholders

Request

Endpoint

GET /v1/cardholders

GET /v1/cardholders

Parameters

None known.

Response


200 OK

{
  "data": [
    {
      "id": "ae114747-7b71-405a-bd7d-7871a434ebf3",
      "type": "cardholder",
      "attributes": {
        "created_at": "2021-02-12T04:29:17Z",
        "updated_at": "2021-02-12T04:29:17Z",
        "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"
        }
      }
    }
  ],
  "links": {
    "prev": "http://example.org/v1/cardholders?page%5Bbefore%5D=ae114747-7b71-405a-bd7d-7871a434ebf3",
    "next": null
  }
}

curl -g "https://cms-sandbox.bongloy.com/v1/cardholders" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJKWGFvX2dETmVFUDFfZl9Id0VFdVhKNFhiT3NLTnVSeHRXSFZmdVZMWGNFIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OCJ9.hX6ZYCcYXpVVhf47LmoHRpMygw6Ngz5pMR__HygyeOvYWoBTt3_9IZbjW4PZp9THLJSsu8p7i2z4oDYljUOFE8x1r2Gvi1UuUbmWF6WfpNjdx3syw1MjMlOX4POfUsxOj7pB1hE3mlKRRwfzQ9OwCWBlwvraOAULnyg8Zpyt13c9HMVmFiPfU13nA3LzO8NqVLurl2Qyn2RpRznzm-JqF2qdhD4lfg5EmXiNDpvoYgTajG3nUZFcLtN5c-mRWd3I0IhNK49H59NA_gmugb8Th9EScO_3nbMbFIiwnhbnCbErZPBdhXMQwTh5eql88awMIwrwYKEcSrojI66jn0cNbg"

Cards

Create a card

Request

Endpoint

POST /v1/cards

POST /v1/cards

Parameters

{
  "data": {
    "type": "card",
    "attributes": {
      "type": "physical"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "9d5d8075-d039-4cc2-a325-070c90184058",
          "type": "account"
        }
      }
    }
  }
}
Name Description
data[attributes][currency] required The currency for the card. This currently must be USD.
data[attributes][type] required The type of card to issue. Possible values are physical or virtual.
data[relationships][account] required The id of the account in which the card will be created for

Response


201 Created

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/cards" -d '{
  "data": {
    "type": "card",
    "attributes": {
      "type": "physical"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "9d5d8075-d039-4cc2-a325-070c90184058",
          "type": "account"
        }
      }
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJnQVBiUnJrTUZHZzd0UWI2a0lNUWl4YVA4NGU3aVc5ODFnYXE2QnVsSnQ0IiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OCJ9.VcO-eaiH1zIUAS56C4RXNBXqkt18UYcog15Zjxo67_G8Wjpolk0IqIj8WRB6crXqboPq3OnE9OKmzLCILPrkLmdmZPjV3hgSzbqPRAHoFhS8ZuTeh65Zc429YYLzh4VhWrPBsP9_EWkhOzXJ6GvJcH24cycyXzuSxErercgzkc7-YzpMm9TINs58L9uajEoBYiXAaqrsic605nGdHtr0eKdgURjs16qOVo6R82TLoYnmNRVyLCqH4uXt2FB3SpcEgL_1WvJuonF38RdvrrgGulH0TZuoWfuqr6-JdpQTr7feIC1tIUMoLRw2gkRHp8L-JYJCzXiN8zyzDapTRzlOkg"

Retrieve a card

Request

Endpoint

GET /v1/cards/5dabb918-106b-4e6c-9145-793ea60618d2

GET /v1/cards/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/cards/5dabb918-106b-4e6c-9145-793ea60618d2" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJtdjJfT1gxYTNQdkJvQVZMZERRZmkxeW42YjhBZ0N5MVJuUTNFUFlBdmxrIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OCJ9.abBXuBg8oaBqPZ3Smeg5_M6DR_5-Kp8yWCitu4N3NV01v9u39opiDGgUl4KAYmSN1_fIodXX8mQMg_vHsgKrIyFiCQrjBWbT-x_D_FvXnnh2LB1NLnOVy6mwntWbn111PqtDkw26BmMCvRYSr7geFuNIz-V-ikP600ubuqydtm0OjWHSOG6nX-S9j14FyBz_2vjWHLCDRAivQuiQYq7QNxw4TuW6CN1kQIH1uE1L363X4UNUbdn7AvNnWLmM8THKG4xYpEEyAclntd99LojizIVzjnHIGcsczdzd8hs0c4NiKmj8_ctuaW2B0s8lD15N9oLfnqjg0vm8_hDAbIECNQ"

Update a card

Request

Endpoint

PATCH /v1/cards/7ff0296c-9ca7-45fe-b2d2-6570e14ef62a

PATCH /v1/cards/:id

Parameters

{
  "data": {
    "attributes": {
      "status": null,
      "status": "inactive"
    },
    "type": "card",
    "id": "7ff0296c-9ca7-45fe-b2d2-6570e14ef62a"
  }
}
Name Description
data[attributes][status] Specifies the status of the card. Possible values are active, inactive, canceled, lost or stolen. Note that once the card is marked as canceled, lost or stolen it cannot be reactivated. Virtual cards cannot be marked as lost or stolen.

Response


200 OK

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/cards/7ff0296c-9ca7-45fe-b2d2-6570e14ef62a" -d '{
  "data": {
    "attributes": {
      "status": null,
      "status": "inactive"
    },
    "type": "card",
    "id": "7ff0296c-9ca7-45fe-b2d2-6570e14ef62a"
  }
}' -X PATCH \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJ3SlVRckN2MUlsRTl5d241eDlYQ2lLYk9VMEJKQnhiUUhhWWVQM1hQR01NIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OCJ9.NVsoJqyruGLllciwQ9u38BZyV_4NUTq21duW8XapsQn9EZnDeGYqFoFICj1XzmGeFEb_u7jn6YHvop466-90M_anvT34eP8m-JQfnXnSAMpUUns9BBbEKDxTzCD2SrO-l44VxZnK0UYV5MqJQNK1O9O2jl-LqRfN62UrxD0oIqffZ6JqlgjZDVUGHJom1QtUf1jjuiQRPa82buoH5SaqaAK-vwsr4ykdUWCIq9lN2TlNOZLPf8pJfv0nWnXDghVBjkviTqVvv3Hi_IAWVbIbRtAuarKCM0KGznxOTaxtS2c-tY9Ebp_x-6XoT3nkxWJH_Y8S-A_9wu4HJ-G1sJVSqg"

List all cards

Request

Endpoint

GET /v1/cards

GET /v1/cards

Parameters

Name Description
filter[cardholder] Only return cards belonging to the Cardholder with the provided ID.
filter[type] Either physical or virtual.
filter[status] One of unactivated, inactive, active, lost, stolen or canceled.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/cards" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJPVWg0WXUyamthWUQxdU83RDg5RkY0eEUtZ1JLWEJwQ2I5LWNvZ3c4WUVRIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OSJ9.dDS5Dp8DjBoodu6MrzL0M8rPPBSLTeqf1S0ILGSa76hdt6Cf-p8LAmwtu24oNirS-NXtELEf4ACKIoulKgP2x-w-y2pU6PyfZrGKDUGCt0Vaca4ZtaRBKglBgShhnpiS4k1XjBAGZdye4LvnVHI6gfcFubEHW6dECJRUwODDw07Ca5Gd-dSbU7U9z3S9v7hQk0UPQ8tscM5wIE10JL-lnHoqyyOKMAVSG5rfyD6sP7QVi-wGFJUX9Ka3yr4j1abZ2H_JrhmPJpSWHpa_sjobECXElCC95QppfMbfM4y40HF3Z2PdCx6azpKKjqOAPfApauKvC9Gu02S4PL7vXhnHEw"

Create a management token

Request

Endpoint

POST /v1/cards/566c0239-7d65-4ae1-bfa2-8eb576995429/management_tokens

POST /v1/cards/:card_id/management_tokens

Parameters

{
  "data": {
    "type": "card_management_token",
    "attributes": {
      "type": "card_activation"
    }
  }
}
Name Description
type required The type of management token to issue. Possible values are card_activation, pin_reset, card_elements_data, or card_elements_data. Note that card_elements_data can only be used for virtual cards.

Response


201 Created

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/cards/566c0239-7d65-4ae1-bfa2-8eb576995429/management_tokens" -d '{
  "data": {
    "type": "card_management_token",
    "attributes": {
      "type": "card_activation"
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJ6Y0k2THgtTXRqY0I3ZlEwVXlHVHo0X2hXRU9VZ1RucnNjYnpmRFo5Ti1NIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OSJ9.jhzhtP6oGNoSV1VjdMXoGGmWjXOwdCQ2rgDOqiHtqo2hZIXXJhX5nKkPWruKf-Il7OQSxw4IdXuEGyccKHip83wNnCEgCsz4qtcD9pY1Ig5BYG1K_9t_RjR0HzVlRVsgWGA8x0RRs4eZryLcxUfKTfRfPvamXFQ5AbEj3gDXJBxTTVN2JG8vDFJceRPBgGDTHMjU7FnSjWP-0c7WrDQs_SNStsRq--P7TTmbuhvHqBTwZqCrvjbpThAKmaTnW2vOEyCL4Ui8PKffn0NUW2delZAcBb-NMgd9qOumGWWhDCXc5-06_vYU43GKJRjx-r874TzP1PG3lltvGEPqYOpnsw"

Retrieve a card management token

Request

Endpoint

GET /v1/cards/909ce090-9dbd-4fd3-8d25-9bf1f0282526/management_tokens/89d140b6-eab4-4b44-a95f-79c547eedcd2

GET /v1/cards/:card_id/management_tokens/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/cards/909ce090-9dbd-4fd3-8d25-9bf1f0282526/management_tokens/89d140b6-eab4-4b44-a95f-79c547eedcd2" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJjbmJiZlUtOHNDc1ZNM0FFNTJFWWRmMERQQ0NOeGVPWGlmVS1YeFZXZkg4IiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OSJ9.M74RNHqNL5M2gebPJEEOQbiJakz_2FRfHXM3tGdtfAwq4uacTFq2J3HXt3WeIKufDPymfJARK51gWBnV3qmnzw4VE6WKnJvtLCKFKy7wfz-I3SmDvV5RoqdaKXik8ep4LPDXCca4g6YwUxlxg-mbeoBWns3cX8wpbzi8WaCCeiOmb9orV53SU1EkpmInNEcEzTHbQB1JhbKPALyOXJFf8Md_WLYpjL4gKiYvIrigJxWsqIehiUIHpDi451w0iQiTT_0UvYoh6FOxrd87NFtOwB34xXiBUfAA22uI1IoLSrbwLCrZUuawukFTCpAzkntf6jsbTak3QLkajevFnPvpRA"

Display a virtual card

Data security compliance

Companies that store, transmit, or process sensitive card data, including the primary account number (PAN), expiration date, and card verification value (CVV2), must comply with the Payment Card Industry Data Security Standard (PCI DSS). Achieving PCI DSS certification is both time consuming and expensive.

Bongloy card elements javascript library offloads some of the PCI compliance burden (for certain use cases) by enabling the encrypted transmission of sensitive card data. Bongloy is fully PCI-Level 1 compliant and handle the unencrypted sensitive card data for you. Your servers never store, transmit, or process the card data.

Dynamic card data iframes

The iframes injected by the Bongloy javascript libary enable you to control the styling and layout of the HTML pages you serve to client applications while delegating secure handling of the sensitive data to Bongloy servers. You create and style pages in whatever manner you desire and Bongloy inserts the card data into the page locations specified in the HTML.

Note: To display virtual cards within a mobile application, you can embed the iframes using a web element.

Example

Environment JS Host
Sandbox https://cdn.bongloy.com/sandbox/assets/js/card_elements.js
Production https://cdn.bongloy.com/assets/js/card_elements.js 
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width,initial-scale=1.0">
    <script src="https://cdn.bongloy.com/sandbox/assets/js/card_elements.js"></script>

    <style>
      @font-face {
        font-family: 'credit_card';
        src: url('https://cdn.bongloy.com/assets/fonts/credit-card-font-webfont.woff2') format('woff2'),
            url('https://cdn.bongloy.com/assets/fonts/credit-card-font-webfont.woff') format('woff');
        font-weight: normal;
        font-style: normal;
      }

      #virtual-card {
        background-image: url("card-image-front.png");
        background-repeat: no-repeat;
        background-size: cover;
        width: 350px;
        height: 220px;
        margin: 30px auto;
      }

      #show-button {
        width: 100px;
        height: 40px;
        top: 145px;
        left: 25px;
        position: relative;
      }

      #card-elements {
        margin-top: 60px;
        margin-left: 20px;
      }

      #card-pan {
        width: 320px;
        height: 40px;
        margin: 0 auto;
      }

      #card-cvv {
        float: left;
        margin-left: 110px;
        height: 50px;
        width: 40px;
      }

      #card-expiry {
        margin-left: 150px;
        height: 50px;
        width: 80px;
      }

      #cardholder-name {
        margin-left: 25px;
        color: white;
        font-family: "credit_card", "Courier";
        text-transform: uppercase;
      }

      .label {
        color: white;
        font-size: 0.5em;
        font-family: "Courier";
      }
    </style>
  </head>

  <body>
    <div id="virtual-card">
      <div id="show-button"></div>

      <div id="card-elements">
        <div id="card-pan"></div>

        <div id="card-cvv">
          <span class="label">CVV</span>
        </div>

        <div id="card-expiry">
          <span class="label">VALID THRU</span>
        </div>
      </div>

      <div id="cardholder-name">
        <span>John Doe</span>
      </div>
    </div>

    <script>
      // fetch card management token from server side
      const cardManagementToken = {
        token: "[card-management-token]",
        expiresAt: Date.parse("[card-management-token-expires-at]")
      }

      const cardElementsComponent = Bongloy.cardElementsComponent({
        token: () => {
          //if (cardManagementToken.expiresAt <= Date.now()) {
          //   fetch a new card management token from server side
          //}

          return cardManagementToken.token;
        },
        showButton: {
          containerId: "show-button",
          text: "Show",
          style: `
            color: white;
            font-size: 0.9em;
            font-family: Arial;
            text-decoration: none;
            display: inline-block;
            cursor: pointer;

            padding: 5px 15px;
            border-radius: 30px;
            border: 2px solid white;
            background-color: #999;
            text-shadow: rgb(47, 102, 39) 0px 1px 0px;
          `
        },
        elements: {
          pan: {
            containerId: "card-pan",
            style: `
              font-size: 1.7em;
            `
          },
          expiry: {
            containerId: "card-expiry",
            style: `
              font-size: 0.8em;
            `
          },
          cvv: {
            containerId: "card-cvv",
            style: `
              font-size: 0.8em;
            `
          }
        }
      })

      cardElementsComponent.on("ready", () => {
        console.log("Ready")
      })

      cardElementsComponent.on("click", () => {
        console.log("Clicked")
      })

      cardElementsComponent.on("complete", () => {
        console.log("Success")
      })

      cardElementsComponent.on("failure", () => {
        console.log("Failed")
      })

      cardElementsComponent.render()
    </script>
  </body>
</html>

Request

Endpoint

POST /v1/cards/442538db-a979-48fc-a72a-c7a46bb98251/management_tokens

POST /v1/cards/:card_id/management_tokens

Parameters

{
  "data": {
    "type": "card_management_token",
    "attributes": {
      "type": "card_elements_data"
    }
  }
}
Name Description
type required Must be card_elements_data

Response


201 Created

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/cards/442538db-a979-48fc-a72a-c7a46bb98251/management_tokens" -d '{
  "data": {
    "type": "card_management_token",
    "attributes": {
      "type": "card_elements_data"
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiItNUc5YzhfVU5nNWFUb3pXVUZYSTc1WnJrYmlMNF8xT3dMbGVsdnJQQlpRIiwidGltZXN0YW1wIjoiMTYxMzEwNDE1OSJ9.hyVL_DuO4FWZU1WkFfaGOHG-BK-cI-gOEVFz-bl88MWT9rmIUm_SZt9dFrkuZdUqoSSwwa62m7QScf78g0BoTJSROKoEZMxen1A6hDzkNyUIbWy7TikttWe-cAMM1x1WDfOttu3gdwa2aFYwPtxPNR0HFHQJjvfEk_XwiGIfxlUh4z38kEJwH8OJGzIVOjPkCCZzFTHbEbkFNl9pen5cmOf4gVcL-xQi73Huv1d8LNhNr2qRhHBRbAOsOPtxiyZE737i6pzmZDqFwpJxBMXDpdVlaU5JvPw0bgUwJXT8EEk0ijf42Va_F2UVYm37LHGTCNm7U1DzuZEJlLRKqBzXzg"

Events

List all events

Types of events

This is a list of all the types of events we currently send. We may add more at any time, so in developing and maintaining your code, you should not assume that only these types exist.

You'll notice that these events follow a pattern: resource.event. Our goal is to design a consistent system that makes things easier to anticipate and code against.

Event
card.activated
card.fulfillment.updated
transaction.created

Request

Endpoint

GET /v1/events

GET /v1/events

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/events" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJxaEVVRjJHR3o4bndzM2tnZFpsbkUtRVhGMy1TdkM3dGpCZ2dQb09pZkM0IiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MCJ9.uGtg1wK_oYD4jW1lPaeV4dHvnsWEU_8OjC7EGcTblHlwvbBE1k-QZfwDENG6R9fDgKtO9x9PELP2Yf9ZWnMOJZySGIYgCV-ewWloiH0-PdZ2OO-gYensaMKfwJP7sW9bua537hVChY6lrNftnjqPJ6OVySFpFT6vg7EMiFaV4DnqfM-82eCHsN266Vk-g99uFo8Xv4nMkg-Tf3m051o9Cghfpe723F6IYte8QD7pDam8mM_NALVAGAdTSf4ATtwH3xbB2UgBiwUkprN6tGVFB6vS3Kpbb4BbEDcDE1EjsAPy4VohatZrB4EaXtufmOWO1k1VbTzSPDAdQjodBZc3qg"

Retrieve an Event

Request

Endpoint

GET /v1/events/f6406ade-df10-47da-9905-3d6bdcd41e03

GET /v1/events/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/events/f6406ade-df10-47da-9905-3d6bdcd41e03" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJ2UzcwZzg2UXZhaV9obGdpWWc4YUZBUVN4Z2tLUFRzNG5vc25TWVZGNHdzIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MCJ9.GZJNHUiYNtAzxsXxYFOt2VkBix-IQLElnsqLYHqKCI2EwXW5io1NrHa4egqXwfymf39Sja0J0evhSVv3olXnRyR38dEF9kE-lRXADcH_OPeRlY3JcuyxgRrNEaIXcVOcGV6S_uYr9ql8kqys_O-4DmdTACdPWdT60TgvcMrVBjkxw7Rb9bJjW5Bbm-AY1_i5owSmvDez1CCroiwb4NJ-6Kju6QWwV5szWOpcbe-0HTngez53vifXohj6T-AE4rpNnftC9dJBP1E5_W_CMi3TW6cPioq0wyXAiqfI4d4N3cBY2HRFFjYlcugoDgyvICPcKguRwSVZwFbmWsCeYwUryA"

Transactions

List all transactions

Request

Endpoint

GET /v1/transactions?filter[status]=settled&amp;filter[account]=cce74315-e80f-43e7-b178-1b0ace77b35a&amp;filter[from_date]=2020-01-01T00%3A00%3A00Z&amp;filter[to_date]=2020-01-01T12%3A00%3A00Z

GET /v1/transactions

Parameters

filter: {&quot;status&quot;=&gt;&quot;settled&quot;, &quot;account&quot;=&gt;&quot;cce74315-e80f-43e7-b178-1b0ace77b35a&quot;, &quot;from_date&quot;=&gt;&quot;2020-01-01T00:00:00Z&quot;, &quot;to_date&quot;=&gt;&quot;2020-01-01T12:00:00Z&quot;}
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/v1/transactions?filter[status]=settled&filter[account]=cce74315-e80f-43e7-b178-1b0ace77b35a&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 eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiI1VE9KaEowbm5qYmRXbGRCRzhNNWdnU2FPTHFydFdRbDlqREM4QmUwbFIwIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MSJ9.MSpnIPaX8YTuQ6Qo2yPby5tlAsjX4K22igChr3Bn1doqzqyIBNKQm_IIhyI8GZgE_bdWJq6aeo7lzjYGOon2VvFKyEdLAGi-YboO1IJhqcdbGecVIR_ToCXWVr-vjpyFn1Rh5spCUnii4-fL3fToLj5Dd80NkooO1DVvuje7clZPAdOYs03A4MHHQ2jgAabdQqbI2guawveeLDxdbee81Y9jpJxCsGXjWybhAbjvq65ltrzXUJh9b0IvhE4F6oMA_Ddv6Hf6yAP3sbC1IWYdVcMT_sC3dbKy6TmgX-cbmyf9BAgDF7dtjx_KGxOmtP-TvYNPeyXMG47cmOCzLFPpHg"

Retrieve a transaction

Request

Endpoint

GET /v1/transactions/966bc859-c511-4932-8822-ff1f26bd9715

GET /v1/transactions/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/transactions/966bc859-c511-4932-8822-ff1f26bd9715" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJzZTlBa0N3YWliUmM4bFZhRU9iRDVfUnVPRG1oUVk4Xy1VN2R4MVBncE0wIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MSJ9.L8abQTtU_60Q5cuVbuKNsJlWGoJ6XRgw4Ag5aqFeb7bz9yLgOUkC_KJH_X-E-3pzzIlXY2S4N0fyzmkwHQPrl2RM4Xs5HWQAr_ziMT5Z_09dQIJLHE6NmiIXlGmHIPFAYA584D_zC2qvPqpGXP7GDxdrgva9jCtdKx7QdOkgOZr1w1BkCh9AvjBITyoZKSlKYndbRSbt9r6xh-LEq-fZ0SqzrH4HRfPDQzLNlA_k4Stzn7CVMTA0UJYdqf-gEENg9TwmxGVfcfO8VtBx_xYdlYVyEBECc7p1kCMddHSmMxmpWx_qtbGLW2D-RBcvdKHfNZoG5aCnxufRjVQzttsE6A"

Get a transaction summary

Returns a summary of transactions for the current month

Request

Endpoint

GET /v1/transactions/summary?filter[account]=abccb6ac-f2ab-4c76-a82a-2305138271ba

GET /v1/transactions/summary

Parameters

filter: {&quot;account&quot;=&gt;&quot;abccb6ac-f2ab-4c76-a82a-2305138271ba&quot;}
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/v1/transactions/summary?filter[account]=abccb6ac-f2ab-4c76-a82a-2305138271ba" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiI3SUJMT2ZibXE1RnAyZmE3YzJyTGItVVdwWDJBaVQ1QWhyWG9MekhNR2hBIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MSJ9.kAljLkjYBst0ngt96fP8Ate3_uChXEw3Y66WSsKMO6WMQ0VecfEBbX2FsxIBjaCps_hVer0q64laus7Xuq998joxSqeQ2oU7eqUhZopbBpJNk9Fv2puF3Vm3nwzVaXTYDxomnl8CiYwH-G1p3I-mECIQQFnAVa_UxkPEuPDDruxtN07Gz_cFY0cI6yDfTetwfr0LdmYYk0sjow2MXo3vSStuqGmqEJaCLqnRaflfkTBWacdFm3fYGU1xn4sMl5IqL4aho8JA_YHd2gD3ImQ3Cb7-VXwK--eqxkNTMMpsv-wZGOz01VrDa2obAYDlraxR8kEZJ3xq2zoNm9Q6ped-Kw"

Transfers

In order to use this API, you must first ask the cardholder for explicit permission using the OAuth Authorization Code flow. See Cardholder Authorization for more details. Once you have obtained a oauth token for the cardholder, pass it in the X-Cardholder-Auth-Token request header.

Create a transfer

Request

Endpoint

POST /v1/transfers

POST /v1/transfers

Parameters

{
  "data": {
    "type": "transfer",
    "attributes": {
      "amount": 5000,
      "currency": "USD",
      "description": "Foobar",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "source": {
        "data": {
          "id": "9521323b-a23f-4003-a5f4-15ff290dc695",
          "type": "account"
        }
      },
      "destination": {
        "data": {
          "id": "a222ca18-93db-4cb4-b36c-217ef71234f2",
          "type": "account"
        }
      }
    }
  }
}
Name Description
data[attributes][amount] required The amount to transfer in cents. e.g. 10000 for $100.00.
data[attributes][currency] required The currency of the transfer. Only USD is supported at this time.
data[attributes][description] An arbitrary string attached to the object. Often useful for displaying to users.
data[attributes][metadata] Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
data[relationships][source][id] required The id of the sender's account
data[relationships][source][type] required Must be account
data[relationships][destination][id] required The id of the receiver's account. Use the Account Inquiry API to look up the destination account
data[relationships][destination][type] required Must be account

Response


201 Created

[binary data]

curl "https://cms-sandbox.bongloy.com/v1/transfers" -d '{
  "data": {
    "type": "transfer",
    "attributes": {
      "amount": 5000,
      "currency": "USD",
      "description": "Foobar",
      "metadata": {
        "foo": "bar"
      }
    },
    "relationships": {
      "source": {
        "data": {
          "id": "9521323b-a23f-4003-a5f4-15ff290dc695",
          "type": "account"
        }
      },
      "destination": {
        "data": {
          "id": "a222ca18-93db-4cb4-b36c-217ef71234f2",
          "type": "account"
        }
      }
    }
  }
}' -X POST \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJWTmhacl9rbVRNcjlxUzJPOTF1VWZFVFJhZnhuLTA0TUlXdk9uRERHVXFFIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MSJ9.BVKqDclz-qfqcAbbWpDIN5KybzjG71UuapYZrbvyl8vW3czYArNEP9uZ60h4LXg5kNL-Q3tiGYp1tiuEPizjaSHEubIoZt-tDoDpTSM2rb0W5ZIgRCe0q2pMxBhtw4oeR7hamQF7DR4F_PlgjUmeFBboXVyFdggztOC8Ng96HKzJViEse12VxtQg4c5oZkPMp7tuVak9w8JPZKEDjtmP0AqbVVy284NEwNKu1gPYQkWiA6AQL-9QLGMYUs4R39pYhGAu-C0LdG43DCKWGiDe8ke1WoXy7YqYROI7LV3vmYKLtdCH754bKhmtp3M5kc8IgeVYfVWGzGcuN_j-3AuuHw" \
    -H "X-Cardholder-Auth-Token: TQ7YtBUY0DGHcttQualjCb7wjIiJ1wx6IzNPMeH2XyY"

List all transfers

Request

Endpoint

GET /v1/transfers

GET /v1/transfers

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/transfers" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJXbXYyRUZiUTFLTXVncDQ1Zl9YSHhwbHRIM1JtQ0pVN0M0eUpXdTB6TFUwIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MSJ9.ebRxjB-IEb7FirBxyGNqCEUDNCsz87g_F6G96c5uXzCZLqHcV8DWWvRHnoyu641zFWB5zY6EjAqwrRj4lYJr3iCR3rsUBbxxK7p2fsKEoq_EFlvKNQSeY9JmwlSDFVBgzG0EJEIf3xE3pDdmg1lanDXOLtHMgmkd7ydtEEnyg4VNlh5jc3FyRLm8l-l3dy6ckNCjeKha552nhENvnH27RMrvSohthNOKKeA-2coo0QHZ3Sp-0guxl2jfF3_LNaBlyOhnVlZ2yaKW_oQrBdjrVCcvh6Nj17oPI4Kq4cafjlWt4DIHbYgR4MqlK5VHIvlEb5Dl-fk5irqzQKrzHp9klQ" \
    -H "X-Cardholder-Auth-Token: LMddUcMy0slyoLtb_yAZjNtighgtyVes3KAhxnqUYkw"

Retrieve a transfer

Request

Endpoint

GET /v1/transfers/19113101-d4f9-4291-9a3e-c60630e61c6c

GET /v1/transfers/:id

Parameters

None known.

Response


200 OK

[binary data]

curl -g "https://cms-sandbox.bongloy.com/v1/transfers/19113101-d4f9-4291-9a3e-c60630e61c6c" -X GET \
    -H "Content-Type: application/vnd.api+json" \
    -H "Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJhcGlfdG9rZW4iOiJvQzFfdUxMM0lKLXh2enJoZ29mclZHcnNXUU1zRVdVckVkU05NQ3J2SDBRIiwidGltZXN0YW1wIjoiMTYxMzEwNDE2MiJ9.G7QpC7ykt2yEFIwEEJhMJrm6xS2hjwGHkBWwTxAkIkhSqvLCwSS1HlrXRjN9GNutvwfhCZUuVzwh4qmpilvLC9Tc--NvFBpuXG5UnSWSVWd1EuAApbrX895K4MMA6e4fgvskZeB1XdBNfE_J0prll88hJVWlfmEp-1dBXP-T1Z7yc2XH4Y8O0E2Cd8WHM7DWK6c1Zu7xrqUzlDd5XSBEkFhIkYWttRXGahTWKCT01_zmVH6Yoc8CJdxflfvyakfmC478ADVEK_ATe-r68xgakkoyVdL0T0vtBMMJgURGNguZKwOwoaiQR5Pjc0UXYRai_90Fv6vxs8A3fBYGz2--cQ" \
    -H "X-Cardholder-Auth-Token: LMddUcMy0slyoLtb_yAZjNtighgtyVes3KAhxnqUYkw"
JSON cURL