You can use Bongloy accept online payments from your customers. Bongloy currently supports UnionPay credit, debit and prepaid cards. Integrating Bongloy into your app or website can begin as soon as you create a Bongloy Sandbox account, requiring only three steps:
In order to get started with the API, you'll need to get your API Keys. Your test API keys can be found in the developer section on the Bongloy Sandbox. There are two types of API keys: publishable and secret.
Bongloy's API is inspired by Stripe's REST API. Stripe is a US-based technology company which allows individuals and businesses to receive online payments. We thank Stripe for inspiring us to create a product which enables digital payments in Cambodia.
Where possible we try to make the Bongloy API compatible with Stripe's REST API. This makes integration easier because Stripe already has official libraries for different programming languages and mobile platforms. There's also bunch of pre-built extensions, platforms, and plugins to use Bongloy without needing to write any code.
We encourage you to use Stripe's official libraries, or third party libraries and plugins written for Stripe when connecting to Bongloy. This will ensure that you receive the latest security updates and bug fixes.
Integrating a Stripe library or plugin with Bongloy varies according to the particular library. Below are some code snippits for some popular programming languages and platforms.
# Gemfile
gem "stripe", github: "stripe/stripe-ruby"
# config/initializers/bongloy.rb
Bongloy = Stripe
Bongloy.api_base = "https://api.bongloy.com"$ composer require stripe/stripe-php
<?php
require_once('vendor/autoload.php');
use Stripe As Bongloy;
Bongloy\Stripe::$apiBase = "https://api.bongloy.com";
?>To check that your integration is working correctly, make a test API request using your test secret key to create a charge. If the request is successful you should see the charge in your sandbox dashboard.
# bongloy_test.rb
# replace the API key in the following line with your secret API key
Bongloy.api_key = "sk_test_abcde..."
charge = Bongloy::Charge.create(
amount: 999,
currency: "usd",
source: "tok_union_pay"
)
<?php
// bongloy_test.php
// replace the API key in the following line with your secret API key
Bongloy\Stripe::setApiKey("sk_test_abcde...");
$charge = Bongloy\Charge::create([
"amount" => 999,
"currency" => "usd",
"source" => "tok_union_pay"
]);
?>
Anyone involved with the processing, transmission, or storage of card data must comply with the Payment Card Industry Data Security Standards (PCI DSS). Bongloy has been audited by an independent PCI Qualified Security Assessor (QSA) and is certified as a PCI Level 1 Service Provider. This is the most stringent level of certification available in the payments industry.
PCI compliance is a shared responsibility and applies to both Bongloy and your business. When accepting payments, you must do so in a PCI compliant manner. The simplest way for you to be PCI compliant is to never see (or have access to) card data at all. Bongloy makes this easy for you as we can do the heavy lifting to protect your customers' card information. You can simplify your PCI compliance as long as you:
Bongloy.js makes it easy to collect credit card details without having the information touch your server. Bongloy.js gives you complete control over the UI and does not depend on JQuery. Use Bongloy.js if you want to accept payments on your website. If your building a mobile application then we recommend that you use Stripe's official libraries for iOS and Android.
Add the following script tag to your page to get started with Bongloy.js:
<script type="text/javascript" src="https://js.bongloy.com/v3"></script>
You must set your publishable key with setPublishableKey before using Bongloy.js to identify your website when communicating with Bongloy. Remember to replace the test key with your live key in production. You can get all your keys from the developer section of the dashboard.
Bongloy.setPublishableKey('pk_test_abcde...');
// Note: We could also get our Bongloy Publishable Key from a meta tag attribute in the HTML head. E.g.
// var publishableKey = document.head.querySelector("meta[name=bongloy-publishable-key]").content;
// Bongloy.setPublishableKey(publishableKey);
Bongloy.createToken
createToken converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.
var cardObject = {
// The HTML in this example uses `data-name` attribute
// instead of the HTML name attribute to prevent
// sending credit card information fields to the backend server via HTTP POST
number: document.querySelector('[data-name="cardNumber"]').value,
exp_month: document.querySelector('[data-name="expMonth"]').value,
exp_year: document.querySelector('[data-name="expYear"]').value,
cvc: document.querySelector('[data-name="cvc"]').value
}
Bongloy.createToken('card', cardObject, bongloyResponseHandler);
The first argument to Bongloy.createToken is the type of token you want to create. For now this the value must be `card`.
The second argument to is a JavaScript object containing credit card data entered by the user. It should contain the following required fields:
number
'4242424242424242'
exp_month
4
exp_year
2019
cvc
'123'
The following fields are entirely optional. They cannot result in a token creation failing:
name
The third argument bongloyResponseHandler is a callback you provide to handle the response from Bongloy. It should do the following:
Here's a sample implementation of bongloyResponseHandler:
function bongloyResponseHandler(status, response) {
// hide error messages
var errorMessages = document.querySelector('[data-name="errorMessages"]');
errorMessages.classList.add('hidden');
if (statusCode === 201) {
// On success, set token in your checkout form
document.querySelector('[data-name="cardToken"]').value = response.id;
// Then, submit the form
checkoutForm.submit();
}
else {
// If unsuccessful, display an error message.
// Note that `response.error.message` contains a preformatted error message.
document.querySelector("input[type=submit]").removeAttribute('disabled');
errorMessages.classList.remove('hidden');
errorMessages.innerHTML = response.error.message;
}
}
response is of the following form:
{
"id": "af2a6c7c-11f4-4db1-bff6-ee991ebb41f1",
"object": "token",
"created": 1535543720,
"livemode": false,
"card": {
"id": "b4199585-dc1c-4e06-9fdd-4261d703c6a1",
"object": "card",
"created": 1535543720,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "visa",
"country": null,
"customer": null,
"cvc_check": "pass",
"exp_month": 8,
"exp_year": 2020,
"fingerprint": null,
"last4": "4242",
"name": null
},
"client_ip": "96.9.66.131",
"type": "card",
"used": false
}
createToken is an asynchronous call. It returns immediately and invokes bongloyResponseHandler when it receives a response from Bongloy's servers.
Bongloy.js doesn't validate credit card data before sending it to the API. But if the card isn't valid the API will send you a message in the response containing the errors. If you need client side validation you can use something like jessepollak/payment
Stripe has native libraries for Android and iOS which let you collect credit card information without having to deal with sensitive data passing through your servers. Stripe's Mobile Libraries are compatible with Bongloy. Below are some code snippits to get Stripe's Mobile Libraries working with Bongloy.
Here's an example of how to configure Stripe iOS with Bongloy and CocoaPods.
# Podfile
pod "Stripe"$ pod install
Don't forget to use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.
To update to the latest version of the SDK, simply run:
$ pod update Stripe
// AppDelegate.swift
import UIKit
import Stripe
@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
STPPaymentConfiguration.shared().publishableKey = "pk_test_abcde..."
// do any other necessary launch configuration
return true
}
}
// BongloyAPIClient.h
#import <Stripe/Stripe.h>
@interface BongloyAPIClient : STPAPIClient
@property (nonatomic, strong, readwrite) NSURL *apiURL;
@property (nonatomic, strong, readonly) NSURLSession *urlSession;
@property (nonatomic, strong, readwrite) NSString *apiKey;
- (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration NS_DESIGNATED_INITIALIZER;
@end
// BongloyAPIClient.m
#import "BongloyAPIClient.h"
static NSString * const APIBaseURL = @"https://api.bongloy.com/v1";
@implementation BongloyAPIClient
- (instancetype)initWithConfiguration:(STPPaymentConfiguration *)configuration {
NSString *publishableKey = [configuration.publishableKey copy];
self = [super initWithConfiguration:configuration];
if (self) {
_apiKey = publishableKey;
_apiURL = [NSURL URLWithString:APIBaseURL];
_urlSession = [NSURLSession sessionWithConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration]];
}
return self;
}
@end
Create a bridging header for BongloyAPIClient
#import "BongloyAPIClient.h"
let cardParams = STPCardParams()
cardParams.number = "6200000000000005"
cardParams.expMonth = 12
cardParams.expYear = 2020
cardParams.cvc = "123"
BongloyAPIClient.shared().createTokenWithCard(cardParams) { (token: STPToken?, error: Error?) in
guard let token = token, error == nil else {
// Present error to user...
return
}
submitTokenToBackend(token, completion: { (error: Error?) in
if let error = error {
// Present error to user...
}
else {
// Continue with payment...
}
})
}
Wherever possible, Bongloy's API is compatible with Stripe's REST API. The examples in the API reference are cURL commands. While cURL is useful for testing, we highly recommend that you make use of Stripe's API libraries when building your application.
The examples in this documentation actually work. You can perform the requests using your test-mode secret API key which is linked to your account. If you login to the Bongloy Sandbox, your API keys will be automatically pre-filled for you.
The Bongloy API uses API keys to authenticate requests. You can view and manage your API keys in the Bongloy Dashboard
Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
$ curl https://api.bongloy.com/v1/charges \
-u sk_test_abcde...:
# The colon prevents curl from asking for a password.
All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list charges, list customers, and list refunds. These list API methods share a common structure, taking at least these three parameters: limit, starting_after, and ending_before.
Bongloy utilizes cursor-based pagination via the starting_after and ending_before parameters. Both parameters take an existing object ID value (see below) and return objects in reverse chronological order. The ending_before parameter returns objects listed before the named object. The starting_after parameter returns objects listed after the named object. If both parameters are provided, only ending_before is used.
limit
optional, default is 10
starting_after
optional
starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
ending_before
optional
ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
object
string, value is "list"
data
array
has_more
boolean
false, this set comprises the end of the list.
url
string
$ curl https://api.bongloy.com/v1/charges?limit=3 \
-u sk_test_abcde...: \
-G
{
"has_more": true,
"object": "list",
"url": "/v1/charges",
"data": [
{
"id": "9b32d559-c371-447a-8e18-45bd4a7c2310",
"object": "charge",
"created": 1553145031,
"livemode": false,
"amount": 500,
"amount_refunded": 0,
"balance_transaction": "dcbea81e-4ca0-49c6-ba44-d7240d448967",
"captured": true,
"currency": "USD",
"customer": null,
"description": "Test live charge",
"dispute": null,
"failure_code": null,
"failure_message": null,
"paid": true,
"refunded": false,
"refunds": {
"has_more": false,
"object": "list",
"url": "/v1/charges",
"data": []
},
"source": {
"id": "22671728-cc4f-45d7-b445-a0d939b5690a",
"object": "card",
"created": 1553144990,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": null,
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0005",
"name": null
},
"statement_descriptor": null,
"status": "succeeded",
"metadata": {
"foo": "bar"
}
},
{...},
{...}
]
}
Some Bongloy objects including charges, customers, and refunds have a metadata parameter. You can use this parameter to attach key-value data to these Bongloy objects.
Metadata is useful for storing additional, structured information on an object. As an example, you could store your user's full name and corresponding unique identifier from your system on a Bongloy Customer object. Metadata is not used by Bongloy. For example, it's not used to authorize or decline a charge and won't be seen by your users unless you choose to show it to them.
Some of the objects listed above also support a description parameter. You can use the description parameter to annotate a charge with, for example, a human-readable description like 2 shirts for test@example.com. Unlike metadata, description is a single string.
Do not store any sensitive information (personally identifiable information, card details, etc.) as metadata or in the description parameter.
$ curl https://api.bongloy.com/v1/charges \
-u sk_test_abcde...: \
-d amount=10000 \
-d currency=USD \
-d source=token_id \
-d "metadata[order_id]=6735" \
-d "description=Charge for 1 case of Singha at KTV"
{
"id": "f1cb560f-e0ac-454e-9bf1-2917bff4d978",
"metadata": {
"order_id": "6735"
},
"description": "Charge for 1 case of Singha at KTV",
...
}To charge a credit card, you create a new charge object. You can retrieve and refund individual charges as well as list all charges. Charges are identified by a unique random ID.
To charge a credit card, you create a new Charge object. If your API key is in test mode, the supplied card won't actually be charged, though everything else will occur as if in live mode. (Bongloy assumes that the charge would have completed successfully).
amount
required
100 cents to charge $1.00). The minimum amount is $1.00 USD.
currency
required
customer
optional
description
optional
metadata
optional
source
optional
statement_descriptor
optional
RunClub and the item you're charging for is a race ticket, you might want to specify a statement_descriptor of RunClub 5K race ticket. The statement description must contain at least one letter, must not contain ><'" characters, and will appear on your customer’s statement in capital letters. Non-ASCII characters are automatically stripped. While most banks and card issuers display this information consistently, some might display it incorrectly or not at all.
Returns a Charge object if the charge succeeded. Returns an error if something goes wrong. A common source of error is an invalid or expired card, or a valid card with insufficient available balance.
To charge a card you first need to create a token that represents the card. You can create a token using Bongloy.js
$ curl https://api.bongloy.com/v1/charges \
-u sk_test_abcde...: \
-d amount=10000 \
-d currency=USD \
-d source=token_id \
-d "description=Charge for 1 case of Singha at KTV" \
-d "statement_descriptor=Singha" \
-d "metadata[foo]=bar"
{
"id": "f1cb560f-e0ac-454e-9bf1-2917bff4d978",
"object": "charge",
"created": 1535543359,
"livemode": false,
"amount": 10000,
"amount_refunded": 0,
"balance_transaction": "beeabc87-bbed-421d-91a8-c3983877b63c",
"captured": true,
"currency": "USD",
"customer": null,
"description": "Charge for 1 case of Singha at KTV",
"dispute": null,
"failure_code": null,
"failure_message": null,
"paid": true,
"refunded": false,
"refunds": {
"has_more": false,
"object": "list",
"url": "/v1/charges/f1cb560f-e0ac-454e-9bf1-2917bff4d978/refunds",
"data": [
]
},
"source": {
"id": "f8430eb4-9f61-4e8b-a703-5b3312ddd840",
"object": "card",
"created": 1535543359,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "visa",
"country": null,
"customer": null,
"cvc_check": "unchecked",
"exp_month": 8,
"exp_year": 2018,
"fingerprint": null,
"last4": "4242",
"name": null
},
"statement_descriptor": "Singha",
"status": "succeeded",
"metadata": {
"foo": "bar"
}
}
Retrieves the details of a charge that has previously been created. Supply the unique charge ID that was returned from your previous request, and Bongloy will return the corresponding charge information. The same information is returned when creating the charge.
charge
required
Returns the Charge object.
$ curl https://api.bongloy.com/v1/charges/f1cb560f-e0ac-454e-9bf1-2917bff4d978 \
-u sk_test_abcde...:
{
"id": "f1cb560f-e0ac-454e-9bf1-2917bff4d978",
"object": "charge",
"created": 1535543359,
"livemode": false,
"amount": 10000,
"amount_refunded": 0,
"balance_transaction": "beeabc87-bbed-421d-91a8-c3983877b63c",
"captured": true,
"currency": "USD",
"customer": null,
"description": "Charge for 1 case of Singha at KTV",
"dispute": null,
"failure_code": null,
"failure_message": null,
"paid": true,
"refunded": false,
"refunds": {
"has_more": false,
"object": "list",
"url": "/v1/charges/f1cb560f-e0ac-454e-9bf1-2917bff4d978/refunds",
"data": [
]
},
"source": {
"id": "f8430eb4-9f61-4e8b-a703-5b3312ddd840",
"object": "card",
"created": 1535543359,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "visa",
"country": null,
"customer": null,
"cvc_check": "unchecked",
"exp_month": 8,
"exp_year": 2018,
"fingerprint": null,
"last4": "4242",
"name": null
},
"statement_descriptor": "Singha",
"status": "succeeded"
}
Returns a list of charges you’ve previously created. The charges are returned in sorted order, with the most recent charges appearing first.
ending_before
optional
ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional
starting_after
optional
starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
A dictionary with a data property that contains an array of up to limit charges, starting after charge starting_after. Each entry in the array is a separate charge object. If no more charges are available, the resulting array will be empty.
$ curl https://api.bongloy.com/v1/charges?limit=3 \
-u sk_test_abcde...: \
-G
{
"has_more": true,
"object": "list",
"url": "/v1/charges",
"data": [
{
"id": "9b32d559-c371-447a-8e18-45bd4a7c2310",
"object": "charge",
"created": 1553145031,
"livemode": false,
"amount": 500,
"amount_refunded": 0,
"balance_transaction": "dcbea81e-4ca0-49c6-ba44-d7240d448967",
"captured": true,
"currency": "USD",
"customer": null,
"description": "Test live charge",
"dispute": null,
"failure_code": null,
"failure_message": null,
"paid": true,
"refunded": false,
"refunds": {
"has_more": false,
"object": "list",
"url": "/v1/charges",
"data": []
},
"source": {
"id": "22671728-cc4f-45d7-b445-a0d939b5690a",
"object": "card",
"created": 1553144990,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": null,
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0005",
"name": null
},
"statement_descriptor": null,
"status": "succeeded",
"metadata": {
"foo": "bar"
}
},
{...},
{...}
]
}
Customer objects allow you to perform recurring charges and track multiple charges that are associated with the same customer. The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.
Creates a customer object
description
optional
email
optional
metadata
optional
source
optional
source will create a new card object and make it the customer default source. If you want to add an additional source to an existing customer instead, use the card creation API.
Returns a Customer object if the call succeeded. If a source has been attached to the customer, the returned customer object will have a default_source attribute, which is an ID that can be expanded into the full source details when retrieving the customer.
$ curl https://api.bongloy.com/v1/customers \
-u sk_test_abcde...: \
-d source=token_id \
-d "description=Customer for jenny.rosen@example.com" \
-d "metadata[foo]=bar"
{
"id": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"object": "customer",
"created": 1553324006,
"livemode": false,
"default_source": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"description": "Customer for jenny.rosen@example.com",
"email": null,
"sources": {
"has_more": false,
"object": "list",
"url": "/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources",
"data": [
{
"id": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"object": "card",
"created": 1553323914,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0005",
"name": null
}
]
},
"metadata": {
"foo": "bar"
}
}
Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.
id
required
Returns the Customer object.
$ curl https://api.bongloy.com/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41 \
-u sk_test_abcde...:
{
"id": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"object": "customer",
"created": 1553324006,
"livemode": false,
"default_source": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"description": "Customer for jenny.rosen@example.com",
"email": null,
"sources": {
"has_more": false,
"object": "list",
"url": "/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources",
"data": [
{
"id": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"object": "card",
"created": 1553323914,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0005",
"name": null
}
]
},
"metadata": {
"foo": "bar"
}
}
Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.
ending_before
optional
ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional
starting_after
optional
starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
A dictionary with a data property that contains an array of up to limit customers, starting after customer starting_after. Each entry in the array is a separate customer object. If no more customers are available, the resulting array will be empty.
$ curl https://api.bongloy.com/v1/customers?limit=3 \
-u sk_test_abcde...: \
-G
{
"has_more": false,
"object": "list",
"url": "/v1/customers",
"data": [
{
"id": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"object": "customer",
"created": 1553324006,
"livemode": false,
"default_source": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"description": "Customer for jenny.rosen@example.com",
"email": null,
"sources": {
"has_more": false,
"object": "list",
"url": "/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources",
"data": [
{
"id": "b817ff09-bd58-4dca-8349-fed5e1d59a67",
"object": "card",
"created": 1553323914,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0005",
"name": null
}
]
},
"metadata": {
"foo": "bar"
}
},
{...},
{...}
]
}
You can store multiple cards on a customer in order to charge the customer later.
When you create a new card, you must specify a customer to create it on. If the card's owner has no default card, then the new card will become the default. However, if the owner already has a default then it will not change.
source
required
Returns a Card object.
To create a card you first need to create a customer and a token that represents the customer's card. You can create a customer by using the Customers API. For the token, you can create one using Bongloy.js
$ curl https://api.bongloy.com/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources \
-u sk_test_abcde...: \
-d source=token_id
{
"id": "b783dfe1-5b76-4005-8adf-a53dd5faa9da",
"object": "card",
"created": 1553324655,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0007",
"name": null
}
You can always see the 10 most recent cards directly on a customer; this method lets you retrieve details about a specific card stored on the customer.
id
required
Returns the Card object.
$ curl https://api.bongloy.com/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources/b783dfe1-5b76-4005-8adf-a53dd5faa9da \
-u sk_test_abcde...:
{
"id": "b783dfe1-5b76-4005-8adf-a53dd5faa9da",
"object": "card",
"created": 1553324655,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0007",
"name": null
}
You can delete cards from a customer.
If you delete a card that is currently the default source, then the most recently added source will become the new default. If you delete a card that is the last remaining source on the customer, then the default_source attribute will become null.
id
required
204
No Content
$ curl https://api.bongloy.com/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources/b783dfe1-5b76-4005-8adf-a53dd5faa9da \
-u sk_test_abcde...: \
-X DELETE
204
No Content
You can see a list of the cards belonging to a customer. Note that the 10 most recent sources are always available on the Customer object. If you need more than those 10, you can use this API method and the limit and starting_after parameters to page through additional cards.
customer
required
ending_before
optional
ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional
starting_after
optional
starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
Returns a list of the cards stored on the customer.
$ curl https://api.bongloy.com/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources?limit=3 \
-u sk_test_abcde...: \
-G
{
"has_more": false,
"object": "list",
"url": "/v1/customers/826aacc5-a4c2-4b7a-807a-50c09ed64a41/sources",
"data": [
{
"id": "b783dfe1-5b76-4005-8adf-a53dd5faa9da",
"object": "card",
"created": 1553324655,
"livemode": false,
"address_city": null,
"address_country": null,
"address_line1": null,
"address_line1_check": "unchecked",
"address_line2": null,
"address_state": null,
"address_zip": null,
"address_zip_check": "unchecked",
"brand": "UnionPay",
"country": "KH",
"customer": "826aacc5-a4c2-4b7a-807a-50c09ed64a41",
"cvc_check": "unchecked",
"exp_month": 12,
"exp_year": 2019,
"fingerprint": null,
"last4": "0007",
"name": null
},
{...},
{...}
]
}
Refund objects allow you to refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged.
When you create a new refund, you must specify a charge to create it on.
Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged. The fees you were originally charged are also refunded.
You can optionally refund only part of a charge. You can do so as many times as you wish until the entire charge has been refunded.
Once entirely refunded, a charge can't be refunded again. This method will return an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.
charge
required
amount
optional
metadata
optional
Returns a Refund object if the refund succeeded. Returns an error if the charge has already been refunded or an invalid charge identifier was provided.
To create a refund you first need to create a charge You can create a charge by using the Charges API.
curl -X POST https://api.bongloy.com/v1/refunds \
-u sk_test_abcde...: \
-d "charge=<charge_id>"
{
"id": "3ab28291-139e-4635-a65d-01d4f422436b",
"object": "refund",
"created": 1553326197,
"amount": 1000,
"balance_transaction": "6ce5cdad-fb62-4a96-a82f-2c814663afc8",
"charge": "33be96dd-ce44-49b3-91b7-b21f9fcb33c2",
"currency": "USD",
"metadata": {},
"status": "succeeded",
"failure_balance_transaction": null
}
Retrieves the details of an existing refund.
refund_id
required
Returns the Refund object.
$ curl https://api.bongloy.com/v1/refunds/3ab28291-139e-4635-a65d-01d4f422436b \
-u sk_test_abcde...:
{
"id": "3ab28291-139e-4635-a65d-01d4f422436b",
"object": "refund",
"created": 1553326197,
"amount": 1000,
"balance_transaction": "6ce5cdad-fb62-4a96-a82f-2c814663afc8",
"charge": "33be96dd-ce44-49b3-91b7-b21f9fcb33c2",
"currency": "USD",
"metadata": {},
"status": "succeeded",
"failure_balance_transaction": null
}
Returns a list of all refunds you've previously created. The refunds are returned in sorted order, with the most recent refunds appearing first. For convenience, the 10 most recent refunds are always available by default on the charge object.
ending_before
optional
ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
limit
optional
starting_after
optional
starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
A dictionary with a data property that contains an array of up to limit refunds, starting after refund starting_after. Each entry in the array is a separate refund object. If no more refunds are available, the resulting array will be empty.
$ curl https://api.bongloy.com/v1/refunds?limit=3 \
-u sk_test_abcde...: \
-G
{
"has_more": true,
"object": "list",
"url": "/v1/refunds",
"data": [
{
"id": "3ab28291-139e-4635-a65d-01d4f422436b",
"object": "refund",
"created": 1553326197,
"amount": 1000,
"balance_transaction": "6ce5cdad-fb62-4a96-a82f-2c814663afc8",
"charge": "33be96dd-ce44-49b3-91b7-b21f9fcb33c2",
"currency": "USD",
"metadata": {},
"status": "succeeded",
"failure_balance_transaction": null
},
{...},
{...}
]
}
| Number | Description |
|---|---|
6200000000000005
|
Debit card. |
6200160000000007
|
Credit card. |
62001400000009
|
Card with a 14 digit number. |
620015000000008
|
Card with a 15 digit number. |
62001700000000004
|
Card with a 17 digit number. |
620018000000000005
|
Card with a 18 digit number. |
6200190000000000000
|
Card with a 19 digit number. |
6200160000000000
|
Valid card that fails luhn check. |
6200010000000004
|
Invalid card. |
6200160000000015
|
Charge is declined with an insufficient_funds code. |
6200160000000023
|
Charge is declined with a card_not_supported code. |
6200160000000031
|
Charge is declined with a card_expired code. |
6200160000000049
|
Charge succeeds but refunding a captured charge fails with a card_expired code. |
You can use webhooks to be notified about events that happen in your Bongloy account. This mechanism is especially useful for services that are not directly responsible for making an API request, but still need to know the response from that request. Webhooks are necessary only for behind the scenes transactions. Most Bongloy requests (e.g. creating charges or creating refunds) happen synchronously and don't require webhooks for verification.
When the event occurs, Bongloy creates an Event object which contains the relevant information about what just happened, including the type of event and the data associated with that event. Bongloy then sends the Event object, via an HTTP POST request, to any endpoint URLs that you have created in your account's Webhook endpoints page.
{
"id": "3ddc184a-42c6-422e-9d39-8978d38afaa0",
"object": "event",
"created": 1549084295,
"livemode": false,
"data": {
"object": {
"id": "ecc28a2c-07d5-4504-b514-3a0ad1571cd0",
"paid": true,
"amount": 500,
"object": "charge",
"source": {
"id": "96db6b0c-102e-435d-8ef9-32cbe234a5cf",
"name": null,
"brand": "UnionPay",
"last4": "0005",
"object": "card",
"country": null,
"created": 1549084204,
"customer": null,
"exp_year": 2019,
"livemode": false,
"cvc_check": "unchecked",
"exp_month": 12,
"address_zip": null,
"fingerprint": null,
"address_city": null,
"address_line1": null,
"address_line2": null,
"address_state": null,
"address_country": null,
"address_zip_check": "unchecked",
"address_line1_check": "unchecked"
},
"status": "succeeded",
"created": 1549084291,
"dispute": null,
"refunds": {
"url": "/v1/charges/ecc28a2c-07d5-4504-b514-3a0ad1571cd0/refunds",
"data": [],
"object": "list",
"has_more": false
},
"captured": true,
"currency": "USD",
"customer": null,
"livemode": false,
"metadata": {},
"refunded": false,
"description": "Test live charge",
"failure_code": null,
"amount_refunded": 0,
"failure_message": null,
"balance_transaction": "272f810d-5df2-4a18-87a7-59082bc82564",
"statement_descriptor": null
}
},
"type": "charge.succeeded"
}
Webhooks are configured in the Dashboard's Webhook endpoints section. Click on the New button and fill in URL for the endpoint.
Creating a webhook endpoint on your server is no different from creating any page on your website. With PHP, you might create a new .php file on your server; with a framework like Sinatra, you would add a new route with the desired URL.
Webhook data is sent as JSON in the POST request body. The full event details are included and can be used directly, after parsing the JSON into an Event object.
require 'json'
# Using Sinatra
post '/my/webhook/url' do
# Retrieve the request's body and parse it as JSON:
event_json = JSON.parse(request.body.read)
# Do something with event_json
status 200
endIf you're using Rails, Django, or another web framework, your site might automatically check that every POST request contains a CSRF token. This is an important security feature that helps protect you and your users from cross-site request forgery attempts. However, this security measure might also prevent your site from processing legitimate webhooks. If so, you might need to exempt the webhooks route from CSRF protection.
If you use an HTTPS URL for your webhook endpoint, Bongloy will validate that the connection to your server is secure before sending your webhook data. For this to work, your server must be correctly configured to support HTTPS with a valid server certificate.
To acknowledge receipt of a webhook, your endpoint should return a 2xx HTTP status code. All response codes outside of this range, including 3xx codes, will indicate to Bongloy that you did not receive the webhook. This means that a URL redirection or a "Not Modified" response will be treated as a failure. Bongloy will ignore any other information returned in the request headers or request body.
In case of failure, Bongloy will attempt to deliver your webhooks for up to five days with an exponential back off. Webhooks cannot be manually retried after this time.
Bongloy signs the webhook events it sends to your endpoints. We do this by including a signature in each event's Bongloy-Signature header. This allows you to validate that the events were sent by Bongloy, not by a third party. Because Bongloy's API is compatible with Stripe's API you can verify signatures using Stripe's official libraries. You can also verify signatures manually using your own solution.
We recommend using one of Stripe libraries to verify signatures. You perform the verification by providing the event payload, the Bongloy-Signature header, and the endpoint's secret. If verification fails, Stripe library returns an error. Here's an example of how to verify a signature using Stripe's offical Ruby library.
# Verifying a Webhook signature in Ruby
# You can find your endpoint's signing secret in your webhook settings page
webhook_signing_secret = 'ZeNerJt...'
payload = request.body.read
bongloy_signature = request.env['HTTP_BONGLOY_SIGNATURE']
# if the signature is invalid a Stripe::SignatureVerificationError will be raised
event = Stripe::Webhook.construct_event(payload, bongloy_signature, webhook_signing_secret)
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate such attacks, Bongloy includes a timestamp in the Bongloy-Signature header. Because this timestamp is part of the signed payload, it is also verified by the signature, so an attacker cannot change the timestamp without invalidating the signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.
Stripe's official libraries have a default tolerance of five minutes between the timestamp and the current time. You can change this tolerance by providing an additional parameter when verifying signatures. We recommend that you use Network Time Protocol (NTP) to ensure that your server's clock is accurate and synchronizes with the time on Bongloy's servers.
Bongloy generates the timestamp and signature each time we send an event to your endpoint.
If Bongloy retries an event (e.g., your endpoint previously replied with a non-2xx status code), then we generate a new signature and timestamp for the new delivery attempt.
Although we recommend using Stripe's official libraries to verify webhook event signatures, you can use the following steps to create a custom solution.
The Bongloy-Signature header contains a timestamp and signature. The timestamp is prefixed by t=, and the signature is prefixed by v1=. Here's an example:
"Bongloy-Signature": "t=1548737520, v1=e9094db9be3d8957e973471936b7ec41c82a24582f9d4751f57427430f47ce62"
Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.
The value for the prefix t corresponds to the timestamp, and the value for the prefix v1 corresponds to the signature. You can discard all other elements.
signed_payload can be constructed by concatenating:
.Compute a HMAC with the SHA256 hash function. Use the endpoint's signing secret as the key, and use the signed_payload string as the message.
Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use constant-time string comparison to compare the expected signature to each of the received signatures.
Bongloy has been audited by a PCI-certified auditor and is certified to PCI Service Provider Level 1. This is the most stringent level of certification available in the payments industry. To accomplish this, we make use of best-in-class security tools and practices to maintain a high level of security at Bongloy.
Bongloy forces HTTPS for all services using TLS (SSL), including our public website and the Dashboard.
We use HSTS to ensure browsers interact with Bongloy only over HTTPS. Bongloy is also on the HSTS preloaded lists for both Google Chrome and Mozilla Firefox.
Below is a list of unofficial open source sample applications that work with Bongloy. If you would like your application listed below please contact us.
| Application | Author(s) |
|---|---|
| Ruby Demo | Multiple |
| Laravel Demo | Khom Sovon |
| iOS Demo | Khom Sovon |