NAV
shell ruby php

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:

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 ahmed@example.com",
  "email": "ahmed@example.com",
  "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=ahmed@example.com" \
   -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 (test@example.com)"
require "white"
White.api_key = "secret_api_key"

White::Charge.create(
  :amount => 1000,
  :currency => "aed",
  :email => "ahmed@example.com",
  :card => {
    :name => "Abdullah Ahmed",
    :number => "4242424242424242",
    :exp_month => 11,
    :exp_year => 2016,
    :cvc => 123
  },
  :description => "Two widgets (test@example.com)"
)
<?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 (test@example.com)",
  "email" => "ahmed@example.com"
));
?>

And here’s what the response might look like:

{
  "id": "{CHARGE_ID}",
  "object": "charge",
  "amount": 1000,
  "currency": "aed",
  "description": "Test charge for ahmed@example.com",
  "email": "ahmed@example.com",
  "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 ahmed@example.com",
  "email": "ahmed@example.com",
  "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 ahmed@example.com",
  "state": "captured",
  "email": "ahmed@example.com",
  "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 ahmed@example.com",
      "email": "ahmed@example.com",
      "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": "abdullah@msn.com",
  "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=abdullah@msn.com" \
   -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 => "abdullah@msn.com",
  :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" => "abdullah@msn.com",
  "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": "abdullah@msn.com",
  "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": "abdullah@msn.com",
  "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=abdullah@gmail.com"
require "white"
White.api_key = "secret_api_key"

cu = White::Customer.retrieve("{CUSTOMER_ID}")
cu.email = "abdullah@gmail.com"
cu.save()
<?php
require_once('./lib/White.php');
White::setApiKey("secret_api_key");

$cu = White_Customer::retrieve("{CUSTOMER_ID}");
$cu->email = "abdullah@gmail.com";
$cu->save();
?>

Here’s what the response looks like:

{
  "id": "cus_c1cf34bb962d84f39f729ca3a",
  "object": "customer",
  "name": "Abdullah Ahmed",
  "email": "abdullah@msn.com",
  "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":"lovely@customer.com",
      "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.