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.
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.
For testing purposes you can use your own test API credentials which can be managed from your account or you can use the following API Keys:
pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430
sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705
Note that the examples in this document actually work so feel free to try them. For examples written in Ruby, see the bongloy-ruby gem.
To charge a credit or a Wing 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 or Wing 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).
key- Required. Your Secret API Key.
amount- Required. A positive integer in the smallest currency unit (e.g 100 cents to charge $1.00, or 4000 to charge 4000 ៛, a 0-decimal currency) representing how much to charge the card.
currency- Required. 3-letter ISO code for currency. e.g. USD or KHR
customer- Optional. Either a customer or card is required. The ID of an existing customer that will be charged in this request.
card- Optional. Either a card or customer is required. A card to be charged. If you also pass a customer ID, the card must be the ID of a card belonging to the customer. Otherwise, if you do not pass a customer ID, the card you provide must be a token, like the ones returned by Bongloy Checkout 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.
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.
curl -d "amount=500¤cy=usd&card=tok_b9222c5bc6f7c4d10a473356661f9c4e13dd2b5bbfe84270668de3e3cba6ce23&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/charges"
{"amount":500,"currency":"usd","livemode":false,"description":null,"object":"charge","captured":true,"id":"ch_9d5c5c86b302a152393d1f2331eb878287087c432d6e87d64c9c4fc949829bfb","created":1412070406,"customer":null,"balance_transaction":"txn_651cccd793e173feee0c9803c19949462fdb5545bcd85e8883cf0b503eb040f7","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"63","id":"card_2484fff4d8ea031b4f99fb7872e2533e9a7e645f25499402aec31c0c9f893983","created":1412070355,"customer":null,"type":"wing"}}curl -d "amount=10000¤cy=khr&customer=cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/charges"
{"amount":10000,"currency":"khr","livemode":false,"description":null,"object":"charge","captured":true,"id":"ch_9330336636f0b3d42ce467e92f09dd7d9c534b7add8d06aed1d03d885b44d6d1","created":1412071237,"customer":"cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2","balance_transaction":"txn_fef743b7671be68bec33f3d73048bdcd616665b582dbeec1a8384cdf2ff92d26","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"62","id":"card_0d118787ec9b7118a13aa77d552017f1396e6137c57d4e96b5cd91c3100ba5dc","created":1412071096,"customer":"cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2","type":"wing"}}curl -d "amount=100000¤cy=khr&customer=cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/charges"
{"error":{"card_object":[". ERROR: Not enough wallet balance to do transactions."],"message":["Card object . ERROR: Not enough wallet balance to do transactions."],"param":["card_object"]}}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.
key- Required. Your Secret API Key.
id- Required. The identifier of the charge to be retrieved.
curl "https://bongloy-staging.herokuapp.com/api/v1/charges/ch_9330336636f0b3d42ce467e92f09dd7d9c534b7add8d06aed1d03d885b44d6d1?key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705"
{"amount":10000,"currency":"khr","livemode":false,"description":null,"object":"charge","captured":true,"id":"ch_9330336636f0b3d42ce467e92f09dd7d9c534b7add8d06aed1d03d885b44d6d1","created":1412071237,"customer":"cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2","balance_transaction":"txn_fef743b7671be68bec33f3d73048bdcd616665b582dbeec1a8384cdf2ff92d26","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"62","id":"card_0d118787ec9b7118a13aa77d552017f1396e6137c57d4e96b5cd91c3100ba5dc","created":1412071096,"customer":"cus_6827d92c9afcd3847a98b7de6b5ede31cadeb8d2490e87a8438fbd9a1f28d9f2","type":"wing"}}curl "https://bongloy-staging.herokuapp.com/api/v1/charges/wrong_charge_id?key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705"
{"status":"404","error":"Not Found"}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 new customer object.
key- Required. Your Secret API Key.
card- Optional. If supplied, it must be a token, like the ones returned by Bongloy Checkout or created using the Tokens API
description- Optional.
email- Optional. An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
Returns a customer object if the call succeeded. The returned customer object will have a default_card attribute, which is an ID that can be expanded into the full card details when retrieving the customer.
curl -d "card=tok_c11740a0608df49fcd442b0ce816019911067e2d6c1c76d2359821b82c91a60e&email=someone%40example.com&description=My+first+customer&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/customers"
{"livemode":false,"email":"someone@example.com","description":"My first customer","object":"customer","default_card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"14","id":"card_ead71fedc837c9096d30ff1801c38bdc1f32dae9b9a3068a3839e957d26af5a6","created":1410514218,"customer":"cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0","type":"wing"},"id":"cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0","created":1410686719}curl -d "card=tok_c11740a0608df49fcd442b0ce816019911067e2d6c1c76d2359821b82c91a60e&email=someone%40example.com&description=My+first+customer&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/customers"
{"error":{"default_card":["can't be blank"],"message":["Default card can't be blank"],"param":["default_card"]}}Retrieves the details of an existing customer. You need only supply the unique customer identifier that was returned upon customer creation.
key- Required. Your Secret API Key.
id- Required. The identifier of the customer to be retrieved.
Returns a customer object if a valid identifier was provided. Returns a 404 otherwise.
curl "https://bongloy-staging.herokuapp.com/api/v1/customers/cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0?key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705"
{"livemode":false,"email":"someone@example.com","description":"My first customer","object":"customer","default_card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"14","id":"card_ead71fedc837c9096d30ff1801c38bdc1f32dae9b9a3068a3839e957d26af5a6","created":1410514218,"customer":"cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0","type":"wing"},"id":"cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0","created":1410686719}curl "https://bongloy-staging.herokuapp.com/api/v1/customers/wrong_customer_id?key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705"
{"status":"404","error":"Not Found"}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 card parameter, that becomes the customer's active card to be used for all charges in the future.
Same as Create a Customer
Same as Create a Customer
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.
curl -v -X PUT -d "card=tok_2b3c02bebf6630f23bd9544df0477b229095540cbf8db6bcdc0c7cf499c462a8&email=someone2%40example.com&description=My+updated+first+customer&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/customers/cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0"
HTTP/1.1 204 No Contentcurl -X PUT -d "card=tok_2b3c02bebf6630f23bd9544df0477b229095540cbf8db6bcdc0c7cf499c462a8&key=sk_test_1eae96c756bc3ef50826c99ce10b9623bd076d8e720e476ac7817a33b8eb0705" "https://bongloy-staging.herokuapp.com/api/v1/customers/wrong_customer"
{"status":"404","error":"Not Found"}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.
Creates a single use token that wraps the details of a credit card or a wing card. These tokens can only be used once: by creating a new charge object, or attaching them to a customer.
key- Required. Your Publishable API Key.
card- Required. The card this token will represent. A dictionary containing a user's card details, with the options described below:
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- Optional. Card security code. For for credit cards this refers to the CVC code and is optional but highly recommended. For Wing Cards it apply's to the Cardholder's PIN and is required.
name- Optional. Cardholder's full name.
address_line1- Optional
address_line2- Optional
address_city- Optional
address_state- Optional
address_zip- Optional
address_country- Optional
email- Optional
The created card token object is returned if successful. Otherwise, this call returns an error.
curl -d "card[number]=4242424242424242&card[exp_month]=12&card[exp_year]=2020&key=pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430" "https://bongloy-staging.herokuapp.com/api/v1/tokens"
{"used":false,"livemode":false,"object":"token","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"cvc_check":null,"address_line1_check":null,"address_zip_check":null,"object":"card","last4":"4242","id":"card_3d0452855cdff75284e496b7d978c860be94e97acb8dd6f8b18c5d3b73e74ef6","created":1410512780,"customer":null,"type":"visa"},"type":"card","id":"tok_2b3c02bebf6630f23bd9544df0477b229095540cbf8db6bcdc0c7cf499c462a8","created":1410512780}curl -d "card[number]=5018188000383662&card[exp_month]=12&card[exp_year]=2020&card[cvc]=2008&key=pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430" "https://bongloy-staging.herokuapp.com/api/v1/tokens"
{"used":false,"livemode":false,"object":"token","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"62","id":"card_af959e24f3b7a0c9b96cb2f486ec7cab5ea186c31c9ca99b36f6c928042280d3","created":1412068483,"customer":null,"type":"wing"},"type":"card","id":"tok_7d43eb97f4dd632797e79c1c8255eb3e6a48869b0369334b2721e7a4b20fb888","created":1412068483}curl -d "card[number]=5018188000001614&card[exp_month]=12&card[exp_year]=2020&key=pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430" "https://bongloy-staging.herokuapp.com/api/v1/tokens"
{"error":{"card":["is invalid"],"message":["Card is invalid"],"param":["card"]}}Retrieves the token with the given ID.
key- Required. Your Publishable API Key.
id- Required. The ID of the desired token.
Returns a token if a valid ID was provided. Returns a 404 otherwise.
curl "https://bongloy-staging.herokuapp.com/api/v1/tokens/tok_c11740a0608df49fcd442b0ce816019911067e2d6c1c76d2359821b82c91a60e?key=pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430"
{"used":true,"livemode":false,"object":"token","card":{"exp_month":12,"exp_year":2020,"name":null,"address_line1":null,"address_line2":null,"address_city":null,"address_state":null,"address_zip":null,"address_country":null,"fingerprint":null,"country":null,"object":"card","last4":"14","id":"card_ead71fedc837c9096d30ff1801c38bdc1f32dae9b9a3068a3839e957d26af5a6","created":1410514218,"customer":"cus_3472b369b8ede0b06da73aaa8dbb51ec07c4dea811444350e7e22d85444df9d0","type":"wing"},"type":"card","id":"tok_c11740a0608df49fcd442b0ce816019911067e2d6c1c76d2359821b82c91a60e","created":1410514218}curl "https://bongloy-staging.herokuapp.com/api/v1/tokens/wrong_token_id?key=pk_test_f4cc494a6ee1d96ada04399f82b6328c70707eb1fa8fd17d60fa7d0a63920430"
{"status":"404","error":"Not Found"}