Documentation

Bongloy.js

Bongloy.js makes it easy to collect credit card (and other similarly sensitive) details without having the information touch your server. Bongloy.js gives you complete control over the UI. If you're looking for a ready-made front-end solution, take a look at Bongloy Checkout.

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/assets/v2/bongloy.js"></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');

Collecting card details

card.createToken

createToken converts sensitive card data to a single-use token which you can safely pass to your server to charge the user.

Bongloy.card.createToken({
  number: $('.card-number').val(),
  cvc: $('.card-cvc').val(),
  exp_month: $('.card-expiry-month').val(),
  exp_year: $('.card-expiry-year').val()
}, bongloyResponseHandler);

The first argument to createToken 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. 12
exp_year
Four digit number representing the card's expiration year, e.g. 2017
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

You may also pass a <form /> element as the first argument to createToken. The relevant information will be pulled from inputs marked up with the data-bongloy attribute, which should be set to one of the values specified above.

The second 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) {
  var $form = $('#payment-form');

  if (response.error) {
    // Show the errors on the form
    $form.find('.payment-errors').text(response.error.message);
    $form.find('button').prop('disabled', false);
  } else {
    // response contains id and card, which contains additional card details
    var token = response.id;
    // Insert the token into the form so it gets submitted to the server
    $form.append($('<input type="hidden" name="bongloyToken" />').val(token));
    // and submit
    $form.get(0).submit();
  }
}

response is of the following form:

{
  "id": "fffd4a4b-adf9-4607-9a5c-26f07fa1b768",
  "used": true,
  "livemode": false,
  "object": "token",
  "card": {
    "id": "c13d9fee-52b1-4956-a04a-b599bfbd646e",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "pass",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1502571059,
    "customer": "cc236cfc-1ec6-44cb-b486-a65cb6a9b956"
  },
  "type": "card",
  "created": 1502571059,
  "client_ip": "35.184.76.192"
}

createToken is an asynchronous call. It returns immediately and invokes bongloyResponseHandler when it receives a response from Bongloy's servers.

Client-side validation helpers

card.validateCardNumber

Checks that the number is formatted correctly and passes the Luhn check.

// These will all return true, indicating a potentially valid card
// number. (Letters, spaces, and other punctuation are ignored.)

Bongloy.card.validateCardNumber('4242424242424242')
Bongloy.card.validateCardNumber('4242-42424242-4242')
Bongloy.card.validateCardNumber('4242 4242 4242 4242')

// These invalid card numbers will all return false.

Bongloy.card.validateCardNumber('4242-1111-1111-1111')
// (Doesn't pass the Luhn check.)
Bongloy.card.validateCardNumber('12345678')
Bongloy.card.validateCardNumber('mistake')

card.validateExpiry

Checks whether or not the expiration date represents an actual month in the future.

Bongloy.card.validateExpiry('02', '15')    // false
Bongloy.card.validateExpiry('02', '10')    // false
Bongloy.card.validateExpiry('12', '2017')  // true
Bongloy.card.validateExpiry(12, 2017)      // true


card.validateCVC

Checks whether or not the supplied number could be a valid verification code.

Bongloy.card.validateCVC('123')            // true
Bongloy.card.validateCVC('')               // false

card.cardType

Returns the type of the card as a string. The possible types are "Visa", "MasterCard", "American Express", "Discover", "Diners Club" and "JCB". If a card isn't recognized, the return value is "Unknown".

Bongloy.card.cardType('4242-4242-4242-4242') // "Visa"
Bongloy.card.cardType('378282246310005')     // "American Express"
Bongloy.card.cardType('1234')                // "Unknown"

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 souce code.

Bongloy Checkout

Bongloy Checkout is the best payment flow, on web and mobile. Bongloy Checkout builds on top of Bongloy.js to provide your users with a streamlined, mobile-ready payment experience that is constantly improving. Bongloy Checkout features include custom logo and text, one-click payment and desktop, mobile and tablet support.

It's worth noting that Bongloy Checkout doesn't actually create charges. It only creates tokens. You can use those tokens to create the actual charge on your server. Alternatively you can save the card for charging later, or sign the user up for recurring charges.

Integration

You can integrate Bongloy Checkout in as little as a single line of client-side code. As we release new features, we'll automatically roll them out to your existing Bongloy Checkout integration, so that you will always be using our latest technology without needing to change a thing.

Checkout supports two different integrations:

Simple
The simple integration provides a blue "Pay with card" button and submits your payment form with a token in a hidden input field.
Custom
The custom integration lets you create a custom button and passes a token to a JavaScript callback.

Simple Integration

The simple integration uses a <script> tag inside your payment <form> to render the blue Checkout button. When a user clicks the button and completes payment, we will submit your form with a token along with any other <input> in your form.

To try it out, copy and paste the following code into a new file called checkout.html and open it in your browser.

<form action="/charge" method="POST">
  <script
    src="https://js.bongloy.com/assets/checkout.js" class="bongloy-button"
    data-key="pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572"
    data-image="https://cdn.js.bongloy.com/assets/marketplace.png"
    data-name="Test Merchant Account's Shop"
    data-description="2 widgets ($20.00)"
    data-amount="2000"
    data-currency="usd">
  </script>
</form>

Received Parameters

These parameters will be submitted to your form's action endpoint, along with any other <input> fields in the form, once the checkout is complete.

bongloyToken
The ID of the token you need to create a charge or a customer.
bongloyEmail
The email address the user entered during the Bongloy Checkout process.

Configuration Options

Required

data-key
Your publishable key (test or live)
pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572

Optional

data-currency
The currency of the amount (3-letter ISO code). The default is USD.
data-panel-label
The label of the payment button in the Checkout form (e.g. "Subscribe", "Pay {{amount}}", etc.). If you include {{amount}}, it will be replaced by the provided amount. Otherwise, the amount will be appended to the end of your label.
data-email
If you already know the email address of your user, you can provide it to Bongloy Checkout to be pre-filled.
data-label
The text to be shown on the default blue button.
data-allow-remember-me
Specify whether to include the option to "Remember Me" for future purchases (true or false). The default is true.

Custom Integration

The custom integration allow you to use your own custom button with our JavaScript API. This permits any HTML element or JavaScript event to start a Bongloy Checkout payment.

When your page loads, you should create a handler object using BongloyCheckout.configure(). You can call open() on the handler in response to any event.

If you need to abort the Bongloy Checkout process e.g. when navigation occurs in a single-page application, you can call close() on the handler. The key parameter, and all callback parameters should be passed to configure(). Any other options can be passed to either configure() or open().

Here is an example of a custom Bongloy Checkout integration using jQuery. To try it out, copy and paste the following code into a new file called checkout.html and open it in your browser.

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.11.1/jquery.min.js"></script>
<script src="https://js.bongloy.com/assets/checkout.js"></script>
<button id="customButton">Purchase</button>
<script>
  var handler = BongloyCheckout.configure({
    key: "pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572",
    image: "https://cdn.js.bongloy.com/assets/marketplace.png",
    token: function(token) {
      // Use the token to create the charge with a server-side script.
      // You can access the token ID with `token.id`
    }
  });

  $('#customButton').on('click', function(e) {
    // Open Checkout with further options
    handler.open({
      name: "Test Merchant Account's Shop",
      description: "2 widgets ($20.00)",
      amount: 2000
    });
    e.preventDefault();
  });

  // Close Checkout on page navigation
  $(window).on('popstate', function() {
    handler.close();
  });
</script>

Configuration Options

Required

key
Your publishable key (test or live)
pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572
token
The callback to invoke when the Checkout process is complete. Where function(token) is the callback function and token is the token object created. token.id can be used to create a charge or customer and token.email contains the email address entered by the user.

Optional

currency
The currency of the amount (3-letter ISO code). The default is USD.
panelLabel
The label of the payment button in the Checkout form (e.g. "Subscribe", "Pay {{amount}}", etc.). If you include {{amount}}, it will be replaced by the provided amount. Otherwise, the amount will be appended to the end of your label.
email
If you already know the email address of your user, you can provide it to Bongloy Checkout to be pre-filled.
allowRememberMe
Specify whether to include the option to "Remember Me" for future purchases (true or false). The default is true.
opened
function() The callback to invoke when Bongloy Checkout is opened (not supported in IE6 and IE7).
closed
function() The callback to invoke when Bongloy Checkout is closed (not supported in IE6 and IE7).

Sample Application

In order to help you to integrate with Bongloy better, we have developed an open source sample application which shows Bongloy Checkout in action. Check out the live application or have a look at the souce 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 Checkout, bongloy.js or created using the Tokens API
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

curl https://www.bongloy.com/api/v1/charges \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d amount=500 \
  -d currency=usd \
  -d source=fd6131df-3832-44ec-a81c-30e62ff70ea1 \
  -d "description=Charge for test@example.com" \
  -d "statement_descriptor=MAX 22 CHARS"

Example Response

{
  "id": "ffff4401-ff38-40e2-8943-56bc800c4f15",
  "currency": "usd",
  "livemode": false,
  "description": "Charge for test@example.com",
  "statement_descriptor": "MAX 22 CHARS",
  "object": "charge",
  "captured": true,
  "status": "successful",
  "refunded": true,
  "refunds": [
    {
      "id": "3c865813-37f4-40c5-9116-87b483439f4d",
      "currency": "USD",
      "object": "refund",
      "created": 1477462811,
      "amount": 9900,
      "balance_transaction": "78b8dbbc-e4ee-410a-b97e-fa0fdb6e676c",
      "charge": "ffff4401-ff38-40e2-8943-56bc800c4f15"
    }
  ],
  "created": 1477462809,
  "amount": 500,
  "amount_refunded": 9900,
  "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44",
  "balance_transaction": "9550d725-9a6c-49ce-a4b5-11704ddc9d2c",
  "source": {
    "id": "a5cc7380-d9a8-4f7d-a051-5013f7f71e47",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "unchecked",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1477462809,
    "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44"
  }
}

Example Request: Charging a Customer

curl https://www.bongloy.com/api/v1/charges \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d amount=10000 \
  -d currency=usd \
  -d customer=ffffb92d-7939-4ea6-abc1-ce2b42734003 \
  -d "description=Charge for My first Customer" \
  -d "statement_descriptor=MAX 22 CHARS"

Example Response

{
  "id": "ffff4401-ff38-40e2-8943-56bc800c4f15",
  "currency": "usd",
  "livemode": false,
  "description": "Charge for My first Customer",
  "statement_descriptor": "MAX 22 CHARS",
  "object": "charge",
  "captured": true,
  "status": "successful",
  "refunded": true,
  "refunds": [
    {
      "id": "3c865813-37f4-40c5-9116-87b483439f4d",
      "currency": "USD",
      "object": "refund",
      "created": 1477462811,
      "amount": 9900,
      "balance_transaction": "78b8dbbc-e4ee-410a-b97e-fa0fdb6e676c",
      "charge": "ffff4401-ff38-40e2-8943-56bc800c4f15"
    }
  ],
  "created": 1477462809,
  "amount": 10000,
  "amount_refunded": 9900,
  "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44",
  "balance_transaction": "9550d725-9a6c-49ce-a4b5-11704ddc9d2c",
  "source": {
    "id": "a5cc7380-d9a8-4f7d-a051-5013f7f71e47",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "unchecked",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1477462809,
    "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44"
  }
}

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://www.bongloy.com/api/v1/charges/ffff4401-ff38-40e2-8943-56bc800c4f15 \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "id": "ffff4401-ff38-40e2-8943-56bc800c4f15",
  "currency": "usd",
  "livemode": false,
  "description": "Charge for My first Customer",
  "statement_descriptor": "MAX 22 CHARS",
  "object": "charge",
  "captured": true,
  "status": "successful",
  "refunded": true,
  "refunds": [
    {
      "id": "3c865813-37f4-40c5-9116-87b483439f4d",
      "currency": "USD",
      "object": "refund",
      "created": 1477462811,
      "amount": 9900,
      "balance_transaction": "78b8dbbc-e4ee-410a-b97e-fa0fdb6e676c",
      "charge": "ffff4401-ff38-40e2-8943-56bc800c4f15"
    }
  ],
  "created": 1477462809,
  "amount": 10000,
  "amount_refunded": 9900,
  "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44",
  "balance_transaction": "9550d725-9a6c-49ce-a4b5-11704ddc9d2c",
  "source": {
    "id": "a5cc7380-d9a8-4f7d-a051-5013f7f71e47",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "unchecked",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1477462809,
    "customer": "5c085f0f-8e43-49a8-926c-ecc7fad91e44"
  }
}

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 Checkout, bongloy.js or created using the Tokens API.
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

curl https://www.bongloy.com/api/v1/customers \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d source=fd6131df-3832-44ec-a81c-30e62ff70ea1 \
  -d "description=My first customer" \
  -d "email=someone@example.com"

Example Response

{
  "id": "ffffb92d-7939-4ea6-abc1-ce2b42734003",
  "livemode": false,
  "email": "someone@example.com",
  "description": "My first customer",
  "object": "customer",
  "default_source": {
    "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "unchecked",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1485730213,
    "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
  },
  "sources": {
    "data": [
      {
        "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
        "exp_month": 12,
        "exp_year": 2024,
        "name": "testy tester",
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "brand": "visa",
        "fingerprint": null,
        "country": null,
        "cvc_check": "unchecked",
        "address_line1_check": "unchecked",
        "address_zip_check": "unchecked",
        "object": "card",
        "last4": "4242",
        "created": 1485730213,
        "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
      }
    ],
    "object": "list",
    "has_more": false,
    "url": null,
    "total_count": 1
  },
  "created": 1485730213
}

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://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003 \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "id": "ffffb92d-7939-4ea6-abc1-ce2b42734003",
  "livemode": false,
  "email": "someone@example.com",
  "description": "My first customer",
  "object": "customer",
  "default_source": {
    "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "unchecked",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1485730213,
    "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
  },
  "sources": {
    "data": [
      {
        "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
        "exp_month": 12,
        "exp_year": 2024,
        "name": "testy tester",
        "address_line1": null,
        "address_line2": null,
        "address_city": null,
        "address_state": null,
        "address_zip": null,
        "address_country": null,
        "brand": "visa",
        "fingerprint": null,
        "country": null,
        "cvc_check": "unchecked",
        "address_line1_check": "unchecked",
        "address_zip_check": "unchecked",
        "object": "card",
        "last4": "4242",
        "created": 1485730213,
        "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
      }
    ],
    "object": "list",
    "has_more": false,
    "url": null,
    "total_count": 1
  },
  "created": 1485730213
}

Update an existing customer

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the source parameter, that becomes the customer's default source to be used for all charges in the future.

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

See Create a Customer for additional params

Returns

Returns a 204 the update succeeded. You'll need to make another API call to Retrieve the Customer if you want to get the updated customer's details. Returns a 404 if the customer cannot be found.

Example Request

curl -i -X PUT https://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003 \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d "description=My updated first customer" \
  -d "email=someone2@example.com"

Example Response

HTTP/1.1 204 No Content

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 Checkout, bongloy.js or created using the Tokens API.
Returns

Returns the card object.

Example Request

curl https://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003/payment_sources \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d source=fd6131df-3832-44ec-a81c-30e62ff70ea1

Example Response

{
  "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
  "exp_month": 12,
  "exp_year": 2024,
  "name": "testy tester",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "brand": "visa",
  "fingerprint": null,
  "country": null,
  "cvc_check": "unchecked",
  "address_line1_check": "unchecked",
  "address_zip_check": "unchecked",
  "object": "card",
  "last4": "4242",
  "created": 1485730213,
  "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
}

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://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003/payment_sources/336f88a2-55a9-457b-a502-8fcdf5c12213 \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
  "exp_month": 12,
  "exp_year": 2024,
  "name": "testy tester",
  "address_line1": null,
  "address_line2": null,
  "address_city": null,
  "address_state": null,
  "address_zip": null,
  "address_country": null,
  "brand": "visa",
  "fingerprint": null,
  "country": null,
  "cvc_check": "unchecked",
  "address_line1_check": "unchecked",
  "address_zip_check": "unchecked",
  "object": "card",
  "last4": "4242",
  "created": 1485730213,
  "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
}

Update an existing card

If you need to update only some card details, like the billing address or expiration date, you can do so without having to re-enter the full card details.

Authorization Parameters
key
Required. Your Secret API Key.
sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30
Request Parameters
id
Required. The id of the card to be updated.
exp_month
Optional. Two digit number representing the card's expiration month.
exp_year
Optional. Four digit number representing the card's expiration year.
name
Optional. Cardholder's full name
address_line1
Optional.
address_line2
Optional
address_city
Optional
address_state
Optional
address_zip
Optional
address_country
Optional
Returns

Returns a 204 the update succeeded. You'll need to make another API call to Retrieve the Card if you want to get the updated card details. Returns a 404 if the card cannot be found.

Example Request

curl -i -X PUT "https://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003/payment_sources/336f88a2-55a9-457b-a502-8fcdf5c12213" \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30: \
  -d "name=Laura Mom"

Example Response

HTTP/1.1 204 No Content

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://www.bongloy.com/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003/payment_sources \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "data": [
    {
      "id": "336f88a2-55a9-457b-a502-8fcdf5c12213",
      "exp_month": 12,
      "exp_year": 2024,
      "name": "testy tester",
      "address_line1": null,
      "address_line2": null,
      "address_city": null,
      "address_state": null,
      "address_zip": null,
      "address_country": null,
      "brand": "visa",
      "fingerprint": null,
      "country": null,
      "cvc_check": "unchecked",
      "address_line1_check": "unchecked",
      "address_zip_check": "unchecked",
      "object": "card",
      "last4": "4242",
      "created": 1485730213,
      "customer": "ffffb92d-7939-4ea6-abc1-ce2b42734003"
    }
  ],
  "object": "list",
  "has_more": false,
  "url": "/api/v1/customers/ffffb92d-7939-4ea6-abc1-ce2b42734003/payment_sources",
  "total_count": 1
}

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

curl -X POST https://www.bongloy.com/api/v1/charges/ffff4401-ff38-40e2-8943-56bc800c4f15/refunds \
  -u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "id": "fffbb8cb-e568-4a88-b9b1-784c278707bf",
  "currency": "USD",
  "object": "refund",
  "created": 1488939630,
  "amount": 9900,
  "balance_transaction": "3eada830-6d09-4139-af4d-e04d78c6a727",
  "charge": "15567b47-67b2-4fbc-ac97-9afaeafe1898"
}

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://www.bongloy.com/api/v1/refunds/fffbb8cb-e568-4a88-b9b1-784c278707bf \
-u sk_test_c8e07580dcda2d352c6244ee0b90f998b5aef6fca37527dc2938a6d968922b30:

Example Response

{
  "id": "fffbb8cb-e568-4a88-b9b1-784c278707bf",
  "currency": "USD",
  "object": "refund",
  "created": 1488939630,
  "amount": 9900,
  "balance_transaction": "3eada830-6d09-4139-af4d-e04d78c6a727",
  "charge": "15567b47-67b2-4fbc-ac97-9afaeafe1898"
}

Tokens

Often you want to be able to charge cards without having to hold sensitive card information on your own servers. Bongloy Checkout makes this easy in the browser, but you can use the same technique in other environments with our token API.

Tokens can be created with your publishable API key, which can safely be embedded in downloadable applications like iPhone and Android apps. You can then use a token anywhere in our API that a card is accepted. Note that tokens are not meant to be stored or used more than once to store these details for use later, you should create Customer objects.

Create a new token

Creates a single use token that wraps the details of a credit card. These tokens can only be used once: by creating a new charge object, or attaching them to a customer.

Authorization Parameters
key
Required. Your Publishable API Key.
pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572
Request Parameters
card
Required. The card this token will represent. A dictionary containing the customers card details (see below).
email
Optional.
Card Parameters
number
Required. The card number, as a string without any separators.
exp_month
Required. Two digit number representing the card's expiration month.
exp_year
Required. Four digit number representing the card's expiration year.
cvc
Required. Card security code. For for credit cards this refers to the CVC code.
name
Optional. Cardholder's full name.
address_line1
Optional
address_line2
Optional
address_city
Optional
address_state
Optional
address_zip
Optional
address_country
Optional
Returns

The created card token object is returned if successful. Otherwise, this call returns an error.

Example Request: Credit Card

curl https://www.bongloy.com/api/v1/tokens \
  -u pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572: \
  -d "card[number]=4242424242424242" \
  -d "card[exp_month]=12" \
  -d "card[exp_year]=2017" \
  -d "card[cvc]=123"

Example Response

{
  "id": "fffd4a4b-adf9-4607-9a5c-26f07fa1b768",
  "used": false,
  "livemode": false,
  "object": "token",
  "card": {
    "id": "c13d9fee-52b1-4956-a04a-b599bfbd646e",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "pass",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1502571059,
    "customer": "cc236cfc-1ec6-44cb-b486-a65cb6a9b956"
  },
  "type": "card",
  "created": 1502571059,
  "client_ip": "35.184.76.192"
}

Retrieve an existing token

Retrieves the token with the given ID.

Authorization Parameters
key
Required. Your Publishable API Key.
pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572
Request Parameters
id
Required. The id of the token to be retrieved.
Returns

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

Example Request

curl https://www.bongloy.com/api/v1/tokens/fffd4a4b-adf9-4607-9a5c-26f07fa1b768 \
-u pk_test_2411c55a75ad6d004eaaf240f99b577dec6d6630789c06a23639967ae3c10572:

Example Response

{
  "id": "fffd4a4b-adf9-4607-9a5c-26f07fa1b768",
  "used": false,
  "livemode": false,
  "object": "token",
  "card": {
    "id": "c13d9fee-52b1-4956-a04a-b599bfbd646e",
    "exp_month": 12,
    "exp_year": 2024,
    "name": "testy tester",
    "address_line1": null,
    "address_line2": null,
    "address_city": null,
    "address_state": null,
    "address_zip": null,
    "address_country": null,
    "brand": "visa",
    "fingerprint": null,
    "country": null,
    "cvc_check": "pass",
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "object": "card",
    "last4": "4242",
    "created": 1502571059,
    "customer": "cc236cfc-1ec6-44cb-b486-a65cb6a9b956"
  },
  "type": "card",
  "created": 1502571059,
  "client_ip": "35.184.76.192"
}

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.