Fat Zebra

Fat Zebra was built as a simple way for merchants to accept credit card payments online while still maintaining a strong focus on security, reliability and great user experience.

Our online payment gateway provides you with all the features and benefits you deserve with no hidden fees or charges to ensure you have all the right tools to trade online.

Source Code: https://github.com/fatzebra

API Documentation Overview

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 http lib.

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

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.

Example

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

Errors

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.

Responses

The response data from Fat Zebra follows the following pattern:

·         successful: Boolean (indicates if the operation was successful or failed)

·         response: hash (data from the operation if successful)

·         test: Boolean (indicates if the gateway is in test mode or not)

·         errors: array (any errors from the operation - if the successful field is false this field should be checked)

Example

1.      {

2.          "successful": false,

3.          "response": {

4.              "test": true

5.          },

6.          "errors": ["Invalid Card Number"]

7.      }

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 backend. This mode is useful for testing changes to your live website.

Purchases

Creating a Purchase

In order to create a purchase you must submit the following details:

·         Amount (numerical)

·         Reference (It should be unique, Best send order id. string - maximum 30 characters)

·         Customer IP (RFC standard IP address)

Either

·         Card Holder (string)

·         Card Number (string, numerical, 13 to 16 digits)

·         Card Expiry (string, mm/yyyy format)

·         CVV (numerical, 3 or 4 digits)

Or

·         Card Token (String)

Definition

1.      Authentication: Basic xxxxxxxxxxxxx

2.      POST /v1.0/purchases HTTP/1.1

Example Request

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

2.          { \

3.              \"card_holder\": \"Jim Smith\", \

4.              \"card_number\": \"5123456789012346\", \

5.              \"card_expiry\": \"05/2023\", \

6.              \"cvv\": \"987\", \

7.              \"amount\": 1000, \

8.              \"reference\": \"ORD98976\", \

9.              \"customer_ip\": \"111.222.111.123\" \

10.      }"

Testing with Fat Zebra

How do I test my website with Fat Zebra?

When you are registered with Fat Zebra you will be provided with a Test Account, which includes its own username and token. Using these details will ensure that transactions are not sent to your live merchant facility but allow you to do a full end-to-end test from your site to our service.

Which test data should I use?

This depends on your merchant bank. Banks using MiGS (which includes ANZ and Bendigo Bank) have specific amounts and card numbers which should be used. We follow these recommendations to simplify and standardize testing. See our test data for more details.

The following table outlines the expected responses from your transaction amount when using a variable card number:

Amount	Response	Explanation
$XXX.00	0	Approved
$XXX.10	1	Could not be processed
$XXX.05	2	Declined - Contact issuing bank
$XXX.68	3	No reply from processing host Note: you may experience valid transactions failing for a few minutes after this response code.
$XXX.33	4	Card has expired
$XXX.51	5	Insufficient credit

Card Numbers

These card numbers are valid for use with Fat Zebra:

Type	Number	Expiry	CVV	Amount	Response
MasterCard	5123 4567 8901 2346	05/2023	123	Any	Approved
MasterCard	5313 5810 0012 3430	05/2023	123	Any	Declined
MasterCard	5555 5555 5555 4444	05/2023	123	Varying	See Table
VISA	4005 5500 0000 0001	05/2023	123	Any	Approved
VISA	4557 0123 4567 8902	05/2023	123	Any	Declined
VISA	4111 1111 1111 1111	05/2023	123	Varying	See Table
AMEX	3456 7890 1234 564	05/2023	1234	Any	Approved
AMEX	3714 4963 5398 431	05/2023	1234	Any	Declined
AMEX	3787 3449 3671 000	05/2023	1234	Varying	See Table
JCB	3530 1113 3330 0000	05/2023	123	Any	Approved
JCB	3566 0020 2036 0505	05/2023	123	Any	Declined
JCB	3569 9900 0000 0009	05/2023	123	Varying	See Table

Errors

Fat Zebra will return errors to you in plain text format. When you receive your response from Fat Zebra you should check the response payload for the success value - this will be true or false depending on the outcome - please note, this only indicates if the request was accepted by Fat Zebra and then sent to your merchant bank, not if the transaction was approved or declined.

If the request is not successful you should check the errors value to see where the problem lies.

If the request is successful you should then check the response value and inspect the status value to determine whether or not the transaction was approved or declined.

Some of the errors you may receive include:

·         Invalid card number

·         Invalid expiry date (e.g. invalid format, or expiry date past)

·         Invalid amount

·         Invalid original transaction reference (in the case of refunds)

Logging

When you send a request to Fat Zebra the data send and returned to you is recorded in our database, for debugging purposes and accounting.

The last 20 requests are available for you to examine through the Merchant Dashboard under the Account section.

Please note that any credit card data (for example, card numbers, CVV etc) will be masked out.

Web Hooks

What are Web Hooks?

Web Hooks are URLs on your website which Fat Zebra sends data to when an event occurs with your account. An example of this would be when a recurring payment has successfully transacted, or when a stored credit card number is about to expire and requires updating.

How do I test Web Hooks?

Web Hooks defined in your dashboard can be tested by clicking the Test Webhook icon on the right of the table.

The Frequently and Infrequently Asked Questions

How long does it take to get up and running?


Once you complete our registration form, our team will review your details and get you up and running within 24 hours, provided you have an established Internet Merchant Facility. If you still need to setup an Internet Merchant Facility it might take a bit longer, but we can help out with that, and there is no extra charge.

Can I start integrating with Fat Zebra while I wait?

Yes. You can start to integrate against our test system before you sign up. Check out our API 
documentation to see how.

Do I need to sign any contracts?


No. signing up is as simple as completing our registration form.

When do I have to pay the annual fee?

You don't pay anything until you activate your account - we know that building a new site, integrating with a payment gateway and ironing out niggling bugs can take time, so we don't take a cent until you go live.

What type of payments can I accept?

Fat Zebra supports MasterCard, VISA, JCB and American Express. If you wish to accept American Express and JCB on your website there is a separate application process with the schemes. Feel free to contact us for assistance.

Can I customise a plan to suit my business?

Of course! We've setup a form just for this purpose - let us know what you're looking for and we're more then happy to tailor a plan to suit your needs.

Can I change my plan at any time?


Yes you can. If you find that you need to change your plan, you can easily change it by contacting us, or by logging into your dashboard and heading to 'my plan'. The change will take place at the start of your new billing cycle.

When I charge someone using Fat Zebra, what do they see on their Credit Card statement?


This is dependent on your agreement with your Internet Merchant Facility bank. Most banks will be able to setup an identifier based on your business or your website.

What information do I need to provide to use Fat Zebra?

Signing up with Fat Zebra is simple. We have a short registration form you need to submit. No paperwork!

Can I take recurring/subscription payments?


Yes you can. Check out our Recurring Billing API.

Can I process refunds with Fat Zebra?

Yes. Our dashboard will allow you to process refunds on any transaction processed by Fat Zebra. There is also functionality in the API to refund a transaction.

Do I get charged for a refund?


Yes. A refund is seen as a transaction and will add to your monthly transactions.

Do you have any Terms & Conditions or Privacy Policies?


Yes we do. Our Terms & Conditions and Privacy Policy explain everything. But if you have any questions please contact us and we'll be more then happy to answer your questions.

When will the money I charge with Fat Zebra end up in my bank account?


Most payments processed by Fat Zebra will appear in your merchant account by the following business day - this will usually be mentioned within your Internet Merchant Facility letter of offer.