Introduction

So you’re a developer, huh? This’ll be fun .. let me show you around.

We built this API to make it easy for you to accept payments in your own application or website. That’s right: no redirects, and no horribly designed forms. You get full control over the User Experience.

We have language bindings in Ruby and PHP! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

API Wrappers

This is an API, so you can communicate with it in pretty much any language you like. We have however built some wrapper libraries to make it even easier for you.

Check them out:

• White Ruby
• White PHP

Authentication

We can’t have random people off the Internet hitting our API, which is why it’s protected with a secret key (which, as the name implies, should be kept secret). We use Basic Auth for all our API endpoints, and the secret key is the username.

I know what you’re thinking. With all this talk about secret keys, where’s my secret key?

Your secret key

To authenticate, here’s the code you’ll need:

require "white"
White.api_key = "secret_api_key"

<?php
require_once('./lib/White.php');
White::setApiKey('secret_api_key');
?>

curl https://api.whitepayments.com/ \
  -u "secret_api_key:" \
  ...

Fear not, because the moment you loaded this page .. we went ahead and fetched your API keys for you.

Here’s your secret key: secret_api_key

Errors

Things don’t always work out, and White makes handling errors painless. It’s easy to tell if an error has happened, since White uses REST principles when issuing responses (so you can rest).

Status Codes

Status Codes

200 OK - Everything's A-OK

201 Created - Something was successfully created

400 Bad Request - Usually means invalid parameters

401 Unauthorized - Usually a problem with your API key

402 Request Failed - Params seemed OK, but the request failed

404 Not Found - The item you asked for couldn't be found

500, 502, 503, 504 Server Errors - Our bad. Something went wrong on our end

We return standard HTTP status codes, so you can easily tell if something’s not working like it should.

In general, that means:

Status Code	Meaning
200 - 299	Request successful (It’s no one’s fault)
400 - 499	Request failed – often an input or card problem (techically your fault - but still kinda our fault for not being clear)
500 - 599	Server error – usually means something wrong on our end.

Here’s what a typical error response looks like:

{
  "error": {
    "type": "authentication",
    "code": "unauthorized",
    "message": "Can't authenticate with provided API Key.",
    "extras": {
      "provided_api_key":"test_key_imadethiskeyup"
      }
    }
  }

You’ll see a sample error response to the right. Let’s break it down:

Attributes	Description
type	This is either request, processing, banking or authentication
code	A code that describes what’s wrong. Great for a switch statement
message	Human-readable message that explains exactly why the request failed
extras	Usually includes a list of params that caused the failure

Error Types

The error type gives you a pretty good idea about why a transaction might have failed. There are 4 types, and here’s a brief description of each one:

Type	Description
Request	There’s a problem with the parameters that were passed in the original request.
Banking	The transaction was rejected by our banking provider. This could be due to insufficient funds for a charge, for example.
Authentication	The API key used in the request is invalid or expired.
Processing	There’s a problem on White’s end, and we were unable to process the transaction. These should be rare.

Error Codes

If you’ve got a Banking error on your hands, then you can have a look at the specific error code to know exactly what went wrong.

Here’s a list of the Error Codes, and their corresponding meaning

Error Code	Description
card_declined	The card was declined by the acquiring bank (e.g. insufficient funds, closed account, ..)

Handling Errors

<?php
try {
  // Use White's bindings...
} catch(White_Error_Banking $e) {
  // Since it's a decline, White_Error_Banking will be caught
  print('Status is:' . $e->getHttpStatus() . "\n");
  print('Code is:' . $e->getErrorCode() . "\n");
  print('Message is:' . $e->getMessage() . "\n");

} catch (White_Error_Request $e) {
  // Invalid parameters were supplied to White's API

} catch (White_Error_Authentication $e) {
  // Invalid API key

} catch (White_Error_Processing $e) {
  // Something wrong on White's end

} catch (White_Error $e) {
  // Display a very generic error to the user, and maybe send
  // yourself an email

} catch (Exception $e) {
  // Something else happened, completely unrelated to White

}
?>

begin
  # Use White's bindings...
rescue White::BankingError => e
  # Since it's a decline, White::BankingError will be caught
  puts "Status is: #{e.http_status}"
  puts "Code is: #{e.code}"
  puts "Message is: #{e.message}"
rescue White::RequestError => e
  # Invalid parameters were supplied to White's API
rescue White::AuthenticationError => e
  # Invalid API key used
rescue White::ProcessingError => e
  # Something wrong with the White API
rescue White::WhiteError => e
  # Display a very generic error to the user, and maybe send
  # yourself an email
rescue => e
  # Something else happened, completely unrelated to White
end

Our API wrappers can raise exceptions for many reasons, like a failed charge, invalid parameters, authentication errors, or network unavailability. We recommend always trying to gracefully handle exceptions from our API.

Examples of how this can be done are shown on the right hand side.

Charges

To charge a credit or a debit 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 (e.g. ch_913ac1cf34bb962d84f39f729ca4a).

The Charge object

{
  "id": "ch_913ac1cf34bb962d84f39f729ca3a",
  "object": "charge",
  "amount": 1000,
  "currency": "aed",
  "description": "Test charge for [email protected]",
  "email": "[email protected]",
  "ip": "127.0.0.1",
  "state": "captured",
  "captured_amount": 1000,
  "refunded_amount": 0,
  "failure_reason": null,
  "failure_code": null,
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",
  "card": {
    "id": "card_aa3860e5fa119adeea1f612164e",
    "object": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_year": 2015,
    "exp_month": 12,
    "name": "Abdullah Ahmed"
    }
  }

Attributes

Attribute	Description
id	string A string that uniquely references this charge
object	string, value is “charge”
amount	positive integer The amount of the charge, in the smallest currency unit. For example, for $1.00, the amount=100 (cents). For BHD1.000, the amount=1000 (fils).
currency	string The 3 letter currency code
description	string A description of the charge
email	string The cardholders email address
ip	string The IP address of the client that sent the charge request
state	string Can be either authorized, captured, refunded, partially_refunded or failed
captured_amount	integer The amount that has been captured in the smallest currency unit. For authorization-only charges, this would be 0 until the charge is captured.
refunded_amount	integer The amount refunded, in the same currency as the original transaction
failure_reason	string Only filled in if the charge failed
failure_code	string One of the failure codes listed in the Error Codes section above.
created_at	string DateTime representation of the date the charge was created. Follows the ISO8601 DateTime representation standard.
updated_at	string DateTime representation of the date the charge was last modified
card	Card object Passes the card details that were used to process this charge.

Create a new Charge

To create a charge, simply use the following:

curl https://api.whitepayments.com/charges \
   -u secret_api_key: \
   -d "amount=1000" \
   -d "currency=aed" \
   -d "[email protected]" \
   -d "card[name]=Abdullah Ahmed" \
   -d "card[number]=4242424242424242" \
   -d "card[exp_month]=11" \
   -d "card[exp_year]=2016" \
   -d "card[cvc]=123" \
   -d "description=Two widgets ([email protected])"

require "white"
White.api_key = "secret_api_key"

White::Charge.create(
  :amount => 1000,
  :currency => "aed",
  :email => "[email protected]",
  :card => {
    :name => "Abdullah Ahmed",
    :number => "4242424242424242",
    :exp_month => 11,
    :exp_year => 2016,
    :cvc => 123
  },
  :description => "Two widgets ([email protected])"
)

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Charge::create(array(
  "amount" => 1000,
  "currency" => "aed",
  "card" => array(
    "name" => "Abdullah Ahmed",
    "number" => "4242424242424242",
    "exp_month" => 11,
    "exp_year" => 2016,
    "cvc" => "123"
  ),
  "description" => "Two widgets ([email protected])",
  "email" => "[email protected]"
));
?>

And here’s what the response might look like:

{
  "id": "{CHARGE_ID}",
  "object": "charge",
  "amount": 1000,
  "currency": "aed",
  "description": "Test charge for [email protected]",
  "email": "[email protected]",
  "ip": null,
  "state": "captured",
  "captured_amount": 1000,
  "refunded_amount": 0,
  "failure_reason": null,
  "failure_code": null,
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",
  "card": {
    "id": "{CARD_ID}",
    "object": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_year": 2015,
    "exp_month": 12,
    "name": "Abdullah Ahmed"
    }
  }

This is where the action happens – creating a Charge is how you charge a credit / debit card with White, and it’s really easy as you’ll see in a bit.

HTTP Request

POST https://api.whitepayments.com/charges/

Query Parameters

Parameter	Description
amount:	required A positive integer in the smallest currency unit (e.g. amount=100 cents to charge $1.00, or amount=1000 to charge BHD1.000) which represents how much you want to charge the card. The minimum amount is $0.50 (or equivalent in charge currency).
currency:	required 3 letter ISO Code for the currency.
card:	optional, either customer or card is required A card to be charged. The card must either be a token, like the ones returned by White.js, or a hash containing the user’s credit card details.
customer_id:	optional, either customer or card is required The ID of an existing customer that you would like to charge. The default card will be charged.
description:	optional, default is null A string that you can attach to the charge to help you remember what it was about.
email:	optional, either customer_id or email is required The email address of the cardholder. If customer_id is provided, the email will be retrieved from the corresponding Customer object.
ip	optional The IP address of your customer.
statement_descriptor:	optional, default is your account-wide descriptor What the customer sees on their credit card statement. Maximum length is 37 characters; only allow numbers, letters and spaces.
capture:	optional, default is true Indicates whether or not to immediately capture the charge. If you set this to false, then the charge issues an authorization, and will need to be captured later. Uncaptured charges expire in 7 days.

Response

You will receive a Charge object in response.

Retrieve an existing Charge

To get the charge details:

curl -X GET https://api.whitepayments.com/charges/{CHARGE_ID} \
   -u secret_api_key:

require "white"
White.api_key = "secret_api_key"

White::Charge.get("{CHARGE_ID}");

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Charge::get("{CHARGE_ID}");
?>

Here’s what the response looks like:

{
  "id": "{CHARGE_ID}",
  "object": "charge",
  "amount": 1000,
  "currency": "aed",
  "description": "Test charge for [email protected]",
  "email": "[email protected]",
  "ip": null,
  "state": "captured",
  "captured_amount": 1000,
  "refunded_amount": 0,
  "failure_reason": null,
  "failure_code": null,
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",
  "card": {
    "id": "{CARD_ID}",
    "object": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_year": 2015,
    "exp_month": 12,
    "name": "Abdullah Ahmed"
    }
  }

Just pass the unique Charge ID that you got when creating the Charge and we’ll send you back the latest details on the charge.

HTTP Request

GET https://api.whitepayments.com/charges/{CHARGE_ID}

Query Parameters

Parameter	Description
id:	required The charge identifier that you’d like to get the details for.

Response

This call returns a Charge object.

Capture a Charge

To capture a previously authorized charge:

curl -X GET https://api.whitepayments.com/{CHARGE_ID}/capture \
  -u secret_api_key:

require "white"
White.api_key = "secret_api_key"

White::Charge.capture("{CHARGE_ID}");

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Charge::capture("{CHARGE_ID}");
?>

This step only applies to Authorizations (i.e. charges originally created with capture=false).

HTTP Request

POST https://api.whitepayments.com/charges/{CHARGE_ID}/capture

Query Parameters

Parameter	Description
id:	required The charge identifier that you’d like to capture.
amount:	optional The amount to capture, which must be less than or equal to the original amount. Any remaining amount will be automatically refunded.

Response

Here’s what the response could look like:

{
  "id": "{CHARGE_ID}",
  "object": "charge",
  "amount": 1000,
  "currency": "aed",
  "description": "Test charge for [email protected]",
  "state": "captured",
  "email": "[email protected]",
  "ip": null,
  "captured_amount": 1000,
  "refunded_amount": 0,
  "failure_reason": null,
  "failure_code": null,
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",
  "card": {
    "id": "{CARD_ID}",
    "object": "card",
    "last4": "4242",
    "brand": "visa",
    "exp_year": 2015,
    "exp_month": 12,
    "name": null
    }
  }

This call will return a Capture confirmation message, that’s shown on the right.

Attributes

Attribute	Description
id	The charge ID that was captured
amount	The total amount of the charge, in the original charge currency
state	captured if the Capture operation was successful. Otherwise, will return an Error
captured_amount	The amount that was captured, in the original charge currency

List all Charges

To retrieve a list of all of the charges, just do:

curl -X GET https://api.whitepayments.com/charges/ \
  -u secret_api_key:

require "white"
White.api_key = "secret_api_key"
White::Charge.all()

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");
White_Charge::all();
?>

Here’s what the response looks like:

{
  "charges": 
  [
    {
      "id": "{CHARGE_ID}",
      "object": "charge",
      "amount": 1000,
      "currency": "aed",
      "description": "Test charge for [email protected]",
      "email": "[email protected]",
      "ip": null,
      "state": "captured",
      "captured_amount": 1000,
      "refunded_amount": 0,
      "failure_reason": null,
      "failure_code": null,
      "created_at": "2015-01-10T15:17:13.902Z",
      "updated_at": "2015-01-10T15:17:13.907Z",
      "card": {
        "id": "{CARD_ID}",
        "object": "card",
        "last4": "4242",
        "brand": "visa",
        "exp_year": 2015,
        "exp_month": 12,
        "name": null
        },
      },
    {
      "id": "...",
      ...
      }
    ]
  }

This endpoint retrieves all the charges that you’ve got on your account. That’s right .. all of it. The good, the bad and the ugly. (The failed and the successful charges).

The charges are returned in sorted order, with the most recent charges appearing first.

HTTP Request

GET https://api.whitepayments.com/charges/

Query Parameters

This endpoint does not take any parameters

Response

This call returns an array of Charge objects.

Customers

Customer objects allow you to do recurring charges. Unlike Tokens (which can only be used once), you can bill a Customer object as many times as needed.

The Customer object

{
  "id": "cus_c1cf34bb962d84f39f729ca3a",
  "object": "customer",
  "name": "Abdullah Ahmed",
  "email": "[email protected]",
  "description": "Signed up at the Trade Show in Dec 2014",
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",
  "cards": 
    [
      {
      "id": "card_aa3860e5fa119adeea1f612164e",
      "object": "card",
      "last4": "4242",
      "brand": "visa",
      "exp_year": 2015,
      "exp_month": 12,
      "name": "Abdullah Ahmed"
      },
      { ... }
    ],
  "default_card_id": "card_aa3860e5fa119adeea1f612164e"
}

Attributes

Attribute	Description
id	string A string that uniquely references this customer
object	string, value is “customer”
name	string The full name of this customer
email	string The email address of this customer
description	string Can be anything you like
created_at	string DateTime representation of the date the charge was created. Follows the ISO8601 DateTime representation standard.
updated_at	string DateTime representation of the date the charge was last modified
cards	Array of Card objects This includes a list of all of the cards that the customer has.
default_card_id	string ID of the default Card attached to this Customer. This card will always be charged first, unless another card is specified.

Create a new Customer

To create a Customer, simply use the following:

curl https://api.whitepayments.com/customers \
   -u secret_api_key: \
   -d "name=Abdullah Ahmed" \
   -d "[email protected]" \
   -d "card[number]=4242424242424242" \
   -d "card[exp_month]=12" \
   -d "card[exp_year]=2016" \
   -d "card[cvc]=123" \
   -d "description=Signed up at the Trade Show in Dec 2014"

require "white"
White.api_key = "secret_api_key"

White::Customer.create(
  :name => "Abdullah Ahmed",
  :email => "[email protected]",
  :card => {
    :number => "4242424242424242",
    :exp_month => 11,
    :exp_year => 2016,
    :cvc => 123
  },
  description => "Signed up at the Trade Show in Dec 2014"
)

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Customer::create(array(
  "name" => "Abdullah Ahmed",
  "email" => "[email protected]",
  "card" => array(
    "number" => "4242424242424242",
    "exp_month" => 11,
    "exp_year" => 2016,
    "cvc" => "123"
  ),
  "description" => "Signed up at the Trade Show in Dec 2014"
));
?>

And here’s what the response might look like:

{
  "id": "cus_c1cf34bb962d84f39f729ca3a",
  "object": "customer",
  "name": "Abdullah Ahmed",
  "email": "[email protected]",
  "description": "Signed up at the Trade Show in Dec 2014",
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z",  
  "cards": 
    [
      {
      "id": "card_aa3860e5fa119adeea1f612164e",
      "object": "card",
      "last4": "4242",
      "brand": "visa",
      "exp_year": 2015,
      "exp_month": 12,
      "name": "Abdullah Ahmed"
      },
      { ... }
    ],
  "default_card_id": "card_aa3860e5fa119adeea1f612164e"
}

HTTP Request

POST https://api.whitepayments.com/customers/

Query Parameters

Parameter	Description
name:	optional, default is null The name of the customer that you’re creating.
email:	required The email address of the customer that you are creating.
card:	optional The card can be a token, like the ones returned by white.js, or a hash containing the card details. The choice is yours.
description:	optional, default is null A string that you can attach to the customer to help you remember them by.

Response

You will receive a Customer object in response.

Retrieve an existing Customer

To get the customer details:

curl -X GET https://api.whitepayments.com/customers/{CUSTOMER_ID} \
   -u secret_api_key:

require "white"
White.api_key = "secret_api_key"

White::Customer.get("{CUSTOMER_ID}")

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Customer::get("{CUSTOMER_ID}");
?>

Here’s what the response looks like:

{
  "id": "cus_c1cf34bb962d84f39f729ca3a",
  "object": "customer",
  "name": "Abdullah Ahmed",
  "email": "[email protected]",
  "description": "Signed up at the Trade Show in Dec 2014",
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z"
,  "cards": 
    [
      {
      "id": "card_aa3860e5fa119adeea1f612164e",
      "object": "card",
      "last4": "4242",
      "brand": "visa",
      "exp_year": 2015,
      "exp_month": 12,
      "name": "Abdullah Ahmed"
      },
      { ... }
    ],
  "default_card_id": "card_aa3860e5fa119adeea1f612164e"
}

Just pass the unique Customer ID that you got when creating the Customer and we’ll send you back the latest details on the customer.

HTTP Request

GET https://api.whitepayments.com/customers/{CUSTOMER_ID}

Query Parameters

Parameter	Description
id:	required The customer ID that you’d like to get the details for.

Response

This call returns a Customer object.

Update a Customer

To update a customer:

curl -X PUT https://api.whitepayments.com/customers/{CUSTOMER_ID} \
   -u secret_api_key: \
   -d "[email protected]"

require "white"
White.api_key = "secret_api_key"

cu = White::Customer.retrieve("{CUSTOMER_ID}")
cu.email = "[email protected]"
cu.save()

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

$cu = White_Customer::retrieve("{CUSTOMER_ID}");
$cu->email = "[email protected]";
$cu->save();
?>

Here’s what the response looks like:

{
  "id": "cus_c1cf34bb962d84f39f729ca3a",
  "object": "customer",
  "name": "Abdullah Ahmed",
  "email": "[email protected]",
  "description": "Signed up at the Trade Show in Dec 2014",
  "created_at": "2015-01-10T15:17:13.902Z",
  "updated_at": "2015-01-10T15:17:13.907Z"
,  "cards": 
    [
      {
      "id": "card_aa3860e5fa119adeea1f612164e",
      "object": "card",
      "last4": "4242",
      "brand": "visa",
      "exp_year": 2015,
      "exp_month": 12,
      "name": "Abdullah Ahmed"
      },
      { ... }
    ],
  "default_card_id": "card_aa3860e5fa119adeea1f612164e"
}

Use this action to update the details for an existing customer. We only overwrite the parameters that are passed (i.e. if you don’t pass an attribute, it remains unchanged.)

HTTP Request

PUT https://api.whitepayments.com/customers/{CUSTOMER_ID}

Query Parameters

Parameter	Description
id	string The ID of the customer you’d like to update
name:	optional The updated name of the customer that you’re modifying.
email:	optional The updated email address of the customer.
card:	optional The card can be a token, like the ones returned by white.js, or a hash containing the card details. The choice is yours. This will override the existing default card for the customer. If you’d like to add a card instead of overriding, use the Card creation API
description:	optional The updated customer description.

Response

This action returns the updated Customer object.

List all Customers

To get a list of all of the customers that you’ve created:

curl -X GET https://api.whitepayments.com/customers/ \
  -u secret_api_key:

require "white"
White.api_key = "secret_api_key"

White::Customer.all()

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Customer::all();
?>

This endpoint returns a list of all of the customers that you have created.

The customers are returned in sorted order, with the most recent customers appearing first.

HTTP Request

GET https://api.whitepayments.com/customers

Query Parameters

None – this endpoint doesn’t take any parameters

Response

Here’s what the response could look like:

{
  "customers":[
    {
      "id":"cus_60fd3d74a65d568c87979e13ad67",
      "email":"[email protected]",
      "description":"Lovely Customer Description",
      "default_card_id":"card_817b66b6017967832a538197820",
      "name":"Lovely Customer",
      "created_at":"2015-01-22T15:35:22.664Z",
      "updated_at":"2015-01-22T15:35:22.669Z",
      "object":"customer",
      "cards":[
        {
          "id":"card_817b66b6017967832a538197820",
          "last4":"4242",
          "brand":"visa",
          "exp_year":2020,
          "exp_month":11,
          "name":null,
          "object":"card"
        }
      ]
    }
  ]
}

This call will return an array of Customer objects.

Refunds

To refund a previously created Charge, you can create a refund. We allow partial refunds, so you can choose to refund the entire amount, or a part of it if you wish. You can also do multiple partial refunds.

The Refund object

Here’s the Refund object, in all its glory:

{
  "id": "{REFUND_ID}",
  "object": "refund",
  "amount": 1000,
  "created_at": "",
  "reason": "requested_by_customer",
  "charge_id": "ch_xxx",
  "charge": {
    "id": "ch_xxx",
    "object": "charge",
    "captured_amount": 1000,
    "refunded_amount": 500,
    "state": "partially_refunded"
  }
}

Attributes

Attribute	Description
id	string A string that uniquely references this refund
object	string, value is “refund”
amount	positive integer The amount of the charge, in the smallest currency unit. For example, for $1.00, the amount=100 (cents). For BHD1.000, the amount=1000 (fils).
reason	string A brief description of why this refund was done
created_at	string DateTime representation of the date the charge was created. Follows the ISO8601 DateTime representation standard.
charge_id	string The unique ID of the Charge that this refund was issued against.
charge	Charge object The actual Charge object that this refund was issued against.

Create a new Refund

To create a refund, simply use the following:

curl -X POST https://api.whitepayments.com/charges/{CHARGE_ID}/refunds \
   -u secret_api_key: \
   -d "amount=1000" \
   -d "reason=requested_by_customer"

require "white"
White.api_key = "secret_api_key"

White::Refund.create(
  :charge_id => "{CHARGE_ID}",
  :amount => 1000,
  :reason => "requested_by_customer"
)

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Refund::create(array(
  "charge_id" => "{CHARGE_ID}",
  "amount"    => 1000,
  "reason"    => "requested_by_customer"
));
?>

And here’s what the response might look like:

{
  "id": "{REFUND_ID}",
  "object": "refund",
  "amount": 1000,
  "created_at": "",
  "reason": "requested_by_customer",
  "charge_id": "ch_xxx",
  "charge": {
    "id": "ch_xxx",
    "object": "charge",
    "captured_amount": 1000,
    "refunded_amount": 500,
    "state": "partially_refunded"
  }
}

This is where the action happens – creating a Charge is how you charge a credit / debit card with White, and it’s really easy as you’ll see in a bit.

HTTP Request

POST https://api.whitepayments.com/charges/{CHARGE_ID}/refunds

Query Parameters

Parameter	Description
id:	required The identifier of the charge to be refunded
amount:	optional, default is entire charge A positive integer in cents that represents how much of this charge to refund. You can only refund up to the unrefunded amount remaining in the charge.
reason:	optional, default is null A string that indicates the reason for the refund. If set, the acceptable values are duplicate, fraudulent and requested_by_customer. If you choose fraudulent, then that will help us improve our fraud detection system.

Response

You will receive a Refund object in response.

List all Refunds for a Charge

curl -X GET https://api.whitepayments.com/charges/{CHARGE_ID}/refunds \
   -u secret_api_key:

require "white"
White.api_key = "secret_api_key"

White::Refund.all(
  :charge_id => "{CHARGE_ID}")

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Refund::all(array("charge_id" => "{CHARGE_ID}"));
?>

And here’s what the response might look like:

{
  "refunds": 
  [
    {
      "id": "{REFUND_ID}",
      "object": "refund",
      "amount": 1000,
      "created_at": "",
      "reason": "requested_by_customer",
      "charge_id": "ch_xxx",
      "charge": {
        "id": "ch_xxx",
        "object": "charge",
        "captured_amount": 1000,
        "refunded_amount": 500,
        "state": "partially_refunded"
        }
      },
    { 
      "id": ..,
      ..
      }
    ]
  }

You can get a list of all of the refunds on a particular charge by using the following request:

HTTP Request

GET https://api.whitepayments.com/charges/{CHARGE_ID}/refunds

Query Parameters

Parameter	Description
id:	required The identifier of the charge that you’d like to see the refunds for

Response

You will receive an array of Refund objects.

Tokens

You don’t want sensitive card information ending up on your servers. Therefore, it’s best to replace them (immediately) with a token. You do this by sending the Card details directly from the customers browser to our API .. so that the card details never touch your server.

You can easily do this using our white.js library.

The Token object

Here’s what the Token object looks like up-close:

{
  "id": "tok_xxx",
  "object": "token",
  "created_at": "",
  "used": "false",
  "card": {
    "id": "card_xxx",
    "last4": "4242",
    "brand": "Visa",
    "exp_month": 12,
    "exp_year": 2016
  }
}

Attributes

Attribute	Description
id	string A string that uniquely references this token
object	string, value is “token”
used	boolean Tokens can only be used once. This flag indicates if the token has been used or not.
card	Card object The actual Card object that this token references.

Create a new Token

Creating a token is a piece of cake. Here’s how it’s done:

curl https://api.whitepayments.com/tokens/ \
   -u open_api_key: \
   -d "number=4242424242424242" \
   -d "exp_month=11" \
   -d "exp_year=2016" \
   -d "cvc=123" \
   -d "name=Abdullah Mohammed"

require "white"
White.api_key = "secret_api_key"

White::Token.create(
  :number => "4242424242424242",
  :exp_month => 11,
  :exp_year => 2016,
  :cvc => 123,
  :name => "Abdullah Mohammed"
)

<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

White_Token::create(array(
  "number" => "4242424242424242",
  "exp_month" => 11,
  "exp_year" => 2016,
  "cvc" => "123",
  "name" => "Abdullah Mohammed"
));
?>

And here’s the response you might get back:

{
  "id": "tok_xxx",
  "object": "token",
  "created_at": "",
  "used": "false",
  "card": {
    "id": "card_xxx",
    "last4": "4242",
    "brand": "Visa",
    "exp_month": 11,
    "exp_year": 2016
  }
}

You can create a token by making the following request:

HTTP Request

POST https://api.whitepayments.com/tokens/

Query Parameters

Parameter	Description
number:	required The complete card number that you would like to exchange for a token.
exp_month:	required The card expiry month
exp_year:	required The full 4-digit card expiry year.
cvc:	required The CVC (or Card Verification code) are the digits on the back of the card.
name:	optional, default is null The name on the card

Response

You will receive a Token object in return.