Last Updated 15 March, 2014

Fat Zebra provides a simple to use REST API. It is designed to be simple, have predictable URLs and uses HTTP response codes to indicate errors. In addition to this it uses HTTP features such as Basic Authentication and HTTP verbs (GET, PUT, POST etc). This means that it is highly compatible with most HTTP clients including Net::HTTP, cURL and System.Net.WebClient and httplib.

Fat Zebra supports JSON for data transmitted and received to the API. It is recommended, if you are having problems, to test the well-formedness of your data against a lint tool, such as JSONLint (https://jsonlint.com/).

Note: It is important that you ensure no sensitive data is included in the data you are validating - this includes card numbers and CVV/CVN numbers. We also recommend that you replace card holder names with example data, however names with diacritics, umlauts or accents may cause validation issues, so remember this while you are testing.


Authentication with the Fat Zebra API is via HTTP Basic Authentication. When your account is setup you are provided with two sets of credentials - one for the test environment (also known as the Sandbox), and one for the live system. Your test username will always be prefixed with TEST

API request *must* be made over HTTPS - any requests over HTTP will fail. All requests require authentication.

It is important to note that your username is *not* case sensitive however your API token (password) is.


$ curl https://gateway.sandbox.fatzebra.com.au/v1.0/purchases -u TEST:TEST


Fat Zebra will return a HTTP response code to indicate whether the request was successful or failed.

The following HTTP response codes are used by Fat Zebra:

  • HTTP 200 (OK) - This indicates the request was successfully completed.
  • HTTP 400 (Bad Data) - Indicates bad data was received.
  • HTTP 401 (Unauthorized) - Indicates your API credentials were not valid.
  • HTTP 403 (Forbidden) - The resource you were requesting is not available for your credentials. You will most commonly see this is you are attempting to fetch a payment or refund created by your live credentials with your test credentials.
  • HTTP 404 (Not Found) - This indicates that the requested object was not found.
  • HTTP 500 (Server Error) - A problem occurred processing your request.
  • HTTP 501 (Not Implemented) - This indicates there was a problem processing your request, possibly with your payload.


The response data from Fat Zebra follows the following pattern:


    "successful": false,
    "response": {
        "test": true
    "errors": ["Invalid Card Number"]

Test Card Numbers

In the test environment (sandbox, or sending test: true) there are a predefined set of cards and values you can use to receive an expected response:

Number Outcome
MasterCard 5123 4567 8901 2346 Approved
5313 5810 0012 3430 Declined
VISA 4005 5500 0000 0001 Approved
4557 0123 4567 8902 Declined
AMEX 3456 7890 1234 564 Approved
3714 4963 5398 431 Declined
JCB 3530 1113 3330 0000 Approved
3566 0020 2036 0505 Declined

What's the difference between Test and Sandbox?

There are two test modes in the Fat Zebra system - one is a sandbox environment and the other is a test mode flag.

The Sandbox Environment is an identical copy of the live environment which is 100% functional except for communicating with the banks.

The Test Mode Flag is used to switch the live environment into test mode. If test: true is sent with your request your transactions will be executed in the live environment, but not communicate with the bank backends. This mode is useful for testing changes to your live website.