Documentation

Bongloy.js

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.

Including Bongloy.js

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>

Setting your publishable key

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 your account page. 

Bongloy.setPublishableKey('pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572');
// 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);

Collecting card details

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
Card number as a string without any separators, e.g. '4242424242424242'
exp_month
Two digit number representing the card's expiration month, e.g. 10
exp_year
Four digit number representing the card's expiration year, e.g. 2018
cvc
Card security code as a string, e.g. '123'

The following fields are entirely optional. They cannot result in a token creation failing:

name
Cardholder's name
address_line1
Billing address line 1
address_line2
Billing address line 2
address_state
Billing address state
address_zip
Billing address zip as a string, e.g. '94301'
address_country
Billing address country

The third argument bongloyResponseHandler is a callback you provide to handle the response from Bongloy. It should do the following:

  • If the card information entered by the user returned an error, display it on the page.
  • If no errors were returned (i.e. a single-use token was created successfully), add the returned token to the payment form and submit the form to your server.

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

Sample Application

In order to help you to integrate with Bongloy better, we have developed an open source sample application which shows Bongloy.js in action. Check out the live application or have a look at the source code.

Bongloy API Reference

The Bongloy API is organized around REST. To make the Bongloy API as explorable as possible, accounts have test-mode API keys as well as live-mode API keys. These keys can be active at the same time. Data created with test-mode credentials will never result in live charges and will never cost anyone money.

The sample requests in this documentation actually work. You can perform the requests using your test-mode secret API key which is linked to your account.

Authentication

You authenticate to the Bongloy API by providing one of your API keys in the request. You can manage your API keys from your account. You can have multiple API keys active at one time. Your API keys carry many privileges, so be sure to keep them secret!

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Charges

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.

Create a new charge

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

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
amount
Required. A positive integer in the smallest currency unit (e.g 100 cents to charge $1.00) representing how much to charge the card. Also aliased as amount_cents
currency
Required. 3-letter ISO code for currency. e.g. USD
customer
Optional. Either a customer or card is required. The ID of an existing customer that will be charged in this request.
source
Optional. Either a source or customer is required. A payment source to be charged. If you also pass a customer ID, the source must be the ID of a source belonging to the customer. Otherwise, if you do not pass a customer ID, the source you provide must be a token, like the ones returned by bongloy.js
description
Optional. Default is null
capture
Optional. Default is true. Whether or not to immediately capture the charge. When false, the charge issues an authorization (or pre-authorization), and will need to be captured later.
statement_descriptor
Optional. Extra information about a charge. This will appear on your customer's credit card statement. Limited to 22 characters, cannot use the greater than, less than, single quote or double-quote symbols (>, <, ', ")
Returns

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.

Example Request: Charging a Card

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_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d amount=10000 \
  -d currency=USD \
  -d source=<token_id> \
  -d "description=Charge for 1 case of Singha at KTV" \
  -d "statement_descriptor=Singha"

Example Response 

{
  "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,
    "total_count": 0,
    "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": "successful"
}

Retrieve an existing charge

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.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
id
Required. The id of the charge to be retrieved.
Returns

Returns a charge object if a valid id was provided, and returns an error otherwise.

Example Request 

curl https://api.bongloy.com/v1/charges/f1cb560f-e0ac-454e-9bf1-2917bff4d978 \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response 

{
  "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,
    "total_count": 0,
    "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": "successful"
}

Customers

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.

Create a new customer

Creates a customer object

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
source
Optional. If supplied, it must be a token, like the ones returned by bongloy.js
description
Optional.
email
Optional. Customer's email address. It's displayed alongside the customer in your dashboard and can be useful for searching and tracking.
Returns

Returns a customer object if the call succeeded. 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.

Example Request

To create a customer you first need to create a token that represents the customer's card. You can create a token using bongloy.js 

curl https://api.bongloy.com/v1/customers \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d source=<token_id> \
  -d "description=Customer for jenny.rosen@example.com"

Example Response 

{
  "id": "c82d526d-c8dd-4396-8852-be818fdc0b50",
  "object": "customer",
  "created": 1535544463,
  "livemode": false,
  "default_source": "49a5f3c7-f12c-49b6-a85d-c8a7053fbf39",
  "description": "Customer for jenny.rosen@example.com",
  "email": null,
  "sources": {
    "has_more": false,
    "total_count": 0,
    "object": "list",
    "url": "/v1/customers/c82d526d-c8dd-4396-8852-be818fdc0b50/sources",
    "data": [

    ]
  }
}

Retrieve an existing customer

Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
id
Required. The id of the customer to be retrieved.
Returns

Returns a customer object if a valid id was provided. Returns a 404 otherwise.

Example Request 

curl https://api.bongloy.com/v1/customers/c82d526d-c8dd-4396-8852-be818fdc0b50 \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response 

{
  "id": "c82d526d-c8dd-4396-8852-be818fdc0b50",
  "object": "customer",
  "created": 1535544463,
  "livemode": false,
  "default_source": "49a5f3c7-f12c-49b6-a85d-c8a7053fbf39",
  "description": "Customer for jenny.rosen@example.com",
  "email": null,
  "sources": {
    "has_more": false,
    "total_count": 0,
    "object": "list",
    "url": "/v1/customers/c82d526d-c8dd-4396-8852-be818fdc0b50/sources",
    "data": [

    ]
  }
}

Cards

You can store multiple cards on a customer in order to charge the customer later.

Create a new card

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. To change the default, you should update the customer to have a new default_source

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
source
Required. It must be a token, like the ones returned by bongloy.js
Returns

Returns the card object.

Example Request

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/c82d526d-c8dd-4396-8852-be818fdc0b50/sources \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d source=<token_id>

Example Response 

{
  "id": "47b239af-983b-42d7-b222-66e432f550fd",
  "object": "card",
  "created": 1535545089,
  "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": "ccc526e2-4440-4c7d-80a5-0173d3bc6f1f",
  "cvc_check": "unchecked",
  "exp_month": 8,
  "exp_year": 2018,
  "fingerprint": null,
  "last4": "4242",
  "name": null
}

Retrieve an existing card

Retrieves the details of an existing card for a customer.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
id
Required. The id of the card to be retrieved.
Returns

Returns the card object if a valid id was provided. Returns a 404 otherwise.

Example Request 

curl https://api.bongloy.com/v1/customers/ccc526e2-4440-4c7d-80a5-0173d3bc6f1f/sources/47b239af-983b-42d7-b222-66e432f550fd \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response 

{
  "id": "47b239af-983b-42d7-b222-66e432f550fd",
  "object": "card",
  "created": 1535545089,
  "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": "ccc526e2-4440-4c7d-80a5-0173d3bc6f1f",
  "cvc_check": "unchecked",
  "exp_month": 8,
  "exp_year": 2018,
  "fingerprint": null,
  "last4": "4242",
  "name": null
}

List all Cards

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.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
customer
Required. The ID of the customer whose cards will be retrieved.
Returns

Returns a list of the cards stored on the customer.

Example Request 

curl https://api.bongloy.com/v1/customers/ccc526e2-4440-4c7d-80a5-0173d3bc6f1f/sources \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response 

{
  "has_more": false,
  "total_count": 1,
  "object": "list",
  "url": "/v1/customers/ccc526e2-4440-4c7d-80a5-0173d3bc6f1f/sources",
  "data": [
    {
      "id": "16b1634f-e2b9-4455-8544-fa44ccc0118e",
      "object": "card",
      "created": 1535545335,
      "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": "ccc526e2-4440-4c7d-80a5-0173d3bc6f1f",
      "cvc_check": "unchecked",
      "exp_month": 8,
      "exp_year": 2019,
      "fingerprint": null,
      "last4": "5586",
      "name": null
    }
  ]
}

Refunds

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. The fees you were originally charged are also refunded.

Create a new refund

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.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
charge
Required. The identifier of the charge to refund.
amount
Optional. Defaults to entire charge amount. A positive integer representing how much of this charge to refund. Can only refund up to the unrefunded amount remaining on the charge.
Returns

Returns the refund object if the refund succeeded. Returns an error if the charge has already been refunded or an invalid charge identifier was provided.

Example Request

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_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d charge=<charge_id>

Example Response 

{
  "id": "3f19df4e-49a1-4b40-b6d9-6923e1e11664",
  "object": "refund",
  "created": 1535545519,
  "amount": 10000,
  "balance_transaction": "c7a583b2-a0cb-467f-81cc-bfdbbaf02584",
  "charge": "3b4e7ba4-4f90-4400-9e04-14ccc2ccc81c",
  "currency": "USD"
}

Retrieve an existing refund

Retrieves the details of an existing refund.

Authorization Parameters
key
Required. Your Secret API Key. 
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
refund_id
Required. The id of the refund to retrieve.
Returns

Returns a refund if a valid ID was provided. Returns an error otherwise.

Example Request 

curl https://api.bongloy.com/v1/refunds/3f19df4e-49a1-4b40-b6d9-6923e1e11664 \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response 

{
  "id": "3f19df4e-49a1-4b40-b6d9-6923e1e11664",
  "object": "refund",
  "created": 1535545519,
  "amount": 10000,
  "balance_transaction": "c7a583b2-a0cb-467f-81cc-bfdbbaf02584",
  "charge": "3b4e7ba4-4f90-4400-9e04-14ccc2ccc81c",
  "currency": "USD"
}

Bongloy API Libraries

We work hard to keep our underlying REST API simple, but there are also some of pre-built libraries for interacting with Bongloy. If you write your own library and would like us to link to it, just let us know.

Ruby

The Bongloy Ruby library provides convenient access to the Bongloy API from applications written in the Ruby language.

WooCommerce

The Bongloy plugin for WooCommerce allows you to take payments directly on your store via Bongloy's API for mobile and desktop.

Give

The Give Bongloy add-on allows you to collect donations through Give using the Bongloy payment gateway. With Bongloy you can accept Visa, MasterCard, American Express, Discover, JCB, and Diners Club cards directly on your website.