Recurring Purchases

Deprecation Notice

Recurring Purchsaes is being deprecated in favor of an updated payment plans system. This documentation will be maintained for reference only.

Creating a Plan

To create a new plan the following details are required:

  • Name
  • Reference (your internal reference - this will be used to look up the plan)
  • Description
  • Amount (this is the amount charged for each time the plan is billed)

Definition

Authentication: Basic xxxxxxxxxxxxx
POST /v1.0/plans HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/plans -u TEST:TEST -d " \
  {
    \"name\": \"Gold Membership\",
    \"amount\": 2399,
    \"reference\": \"gold-1\",
    \"description\": \"Gold level membership\"
  }"

Responses

Successful — HTTP 201
  {
      "successful": true,
      "response": {
          "name": "Gold Membership",
          "id": "001-PL-VQPMB92P",
          "amount": 2399,
          "reference": "gold-1",
          "description": "Gold level membership"
      },
      "errors": [],
      "test": true
  }

Failed (bad data) — HTTP 400
{
  "successful": false,
  "response": {
    "name": "Gold Membership",
    "id": null,
    "amount": 2399,
    "reference": "gold-1",
    "description":""
  },
  "errors": [
    "Description can't be blank"
  ],
  "test": true
}

Retrieve all Plans

Definition

Authentication: Basic xxxxxxxxxxxxx
GET /v1.0/plans.json HTTP/1.1

Example Request

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

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": [
    {
      "name": "Gold Membership",
      "id": "067-PL-KFG3OXX9",
      "amount": 2399,
      "reference" :"gold-1",
      "description" :"Gold level membership",
      "currency": "AUD",
      "subscription_count": 0
    }
  ],
  "errors": [],
  "test": false,
  "records": 1,
  "total_records": 1,
  "pages": 1,
  "current_page": 1
}

Retrieve a Plan

Definition

Authentication: Basic xxxxxxxxxxxxx
GET /v1.0/plans/{PLAN_ID} HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/plans/001-PL-ZX8J9K.json -u TEST:TEST

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "name": "Gold Membership",
    "id": "001-PL-VQPMB92P",
    "amount": 2399,
    "reference": "gold-1",
    "description": "Gold level membership"
  },
  "errors": [],
  "test": true
}
Failed (Not Found) — HTTP 404
{
    "successful": false,
    "response": null,
    "test": true
    "errors": ["Record not found"]
}

Update a Plan

Note: You can only update a plans name or description - the reference or amount can not be changed once the plan is in use.

Definition

Authentication: Basic xxxxxxxxxxxxx
PUT /v1.0/plans/{PLAN_ID} HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/plans/001-PL-ZX8J9K.json -u TEST:TEST -d " \
  {
      \"name\": \"Silver Plan\",
      \"description\": \"Silver level membership\"
  }"

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "name": "Silver Plan",
    "id": "067-PL-KFG3OXX9",
    "amount": 2399,
    "reference": "gold-1",
    "description":"Silver level membership",
    "currency": "AUD",
    "subscription_count": 0
  },
  "errors": [],
  "test":false
}
Failed (Invalid data or unable to process) — HTTP 501
{
  "successful": false,
  "response": {
    "name": "",
    "id": "067-PL-KFG3OXX9",
    "amount": 2399,
    "reference": "gold-1",
    "description": "Gold level membership",
    "currency": null,
    "subscription_count": 0
  },
  "errors": [
    "Name can't be blank"
  ],
  "test": false
}

Creating a Customer

To create a new customer the following details are required:

  • First Name
  • Last Name
  • Reference (such as your customer's ID number)
  • Email address (used to deliver email receipts if requested)
  • IP Address Optional
  • Card details
    • Card Holder (if different from the customer's name)
    • Card Number
    • Expiry Date
    • CVV
  • Address Details Optional
    • Address
    • City
    • State
    • Postcode
    • Country

Definition

Authentication: Basic xxxxxxxxxxxxx
POST /v1.0/customers HTTP/1.1

Example Request

$ curl https://gateway.sandbox.fatzebra.com.au/v1.0/customers -u TEST:TEST -d " \
  {
    \"first_name\": \"Harrold\",
    \"last_name\": \"Humphries\",
    \"reference\": \"Cust1234\",
    \"email\": \"hhump@gmail.com\",
    \"ip_address\": \"180.200.33.181\",
    \"card\": {
      \"card_holder\": \"Harrold Humphries Senior\",
      \"card_number\": \"5123456789012346\",
      \"expiry_date\": \"05/2023\",
      \"cvv\": \"123\"
    },
    \"address\": {
      \"address\": \"1 Harriet Road\",
      \"city\": "Kooliablin",
      \"state\": \"NSW\",
      \"postcode\": \"2222\",
      \"country\": \"Australia\"
    }  
  }"

Responses

Successful — HTTP 201
{
  "successful": true,
  "response": {
    "id": "067-C-EWMAAHMO",
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "Harrold",
    "last_name": "Humphries",
    "created_at": "2012-05-25T17:46:26+10:00",
    "card_token": "lhypjhrv",
    "address": {
      "address": "1 Harriet Road",
      "city": "Kooliablin",
      "state": "NSW",
      "postcode": "2222",
      "country": "Australia"
    }
  },
  "errors": [

  ],
  "test": false
}
Failed (Bad Data/Duplicate Reference) — HTTP 400
{
  "successful": false,
  "response": {
    "id": null,
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "Harrold",
    "last_name": "Humphries",
    "created_at": null
  },
  "errors": [
    "Reference has already been taken"
  ],
  "test": false
}
Failed (Bad Data/Missing Field) — HTTP 400
{
  "successful": false,
  "response": {
    "id": null,
    "email": "hhump@gmail.com",
    "reference": null,
    "first_name": "Harrold",
    "last_name": "Humphries",
    "created_at": null
  },
  "errors": [
    "Reference can't be blank"
  ],
  "test": false
}

Retrieve a Customer

Definition

Authentication: Basic xxxxxxxxxxxxx
GET /v1.0/customers/067-C-EWMAAHMO.json HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/customers/067-C-EWMAAHMO.json -u TEST:TEST

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "id": "067-C-EWMAAHMO",
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "Harrold",
    "last_name": "Humphries",
    "created_at": "2012-05-25T17:46:26+10:00",
    "card_token": "lhypjhrv"
  },
  "errors": [

  ],
  "test": false
}
Failed (Not Found) — HTTP 404
{
  "successful": false,
  "response": null,
  "errors": [
    "Record not found"
  ],
  "test": false
}

Update a Customer

Definition

Authentication: Basic xxxxxxxxxxxxx
PUT /v1.0/customers/067-C-EWMAAHMO.json HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/customers/067-C-EWMAAHMO.json -u TEST:TEST -X PUT -d" \
  {
    \"first_name\": \"William\"
  }"

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "id": "067-C-EWMAAHMO",
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "William",
    "last_name": "Humphries",
    "created_at": "2012-05-25T17:46:26+10:00",
    "card_token": "lhypjhrv"
  },
  "errors": [

  ],
  "test": false
}
Failed (Not Found) — HTTP 404
{
  "successful": false,
  "response": null,
  "errors": [
    "Record not found"
  ],
  "test": false
}
Failed (Bad Data) — HTTP 400
{
  "successful": false,
  "response": {
    "id": "067-C-EWMAAHMO",
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "",
    "last_name": "Humphries",
    "created_at": "2012-05-25T17:46:26+10:00",
    "card_token": "lhypjhrv"
  },
  "errors": [
    "First name can't be blank"
  ],
  "test": false
}

Delete a Customer

Definition

Authentication: Basic xxxxxxxxxxxxx
DELETE /v1.0/customers/067-C-EWMAAHMO.json HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/customers/067-C-EWMAAHMO.json -u TEST:TEST -X DELETE

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "id": "067-C-EWMAAHMO",
    "email": "hhump@gmail.com",
    "reference": "Cust1234",
    "first_name": "William",
    "last_name": "Humphries",
    "created_at": "2012-05-25T17:46:26+10:00",
    "card_token": "lhypjhrv"
  },
  "errors": [

  ],
  "test": false
}
Failed (Not Found) — HTTP 404
{
  "successful": false,
  "response": null,
  "errors": [
    "Record not found"
  ],
  "test": false
}

Creating a Subscription

Definition

Authentication: Basic xxxxxxxxxxxxx
POST /v1.0/subscriptions HTTP/1.1

Example Request

$ curl https://sandbox.gateway.fatzebra.com.au/v1.0/subscriptions -u TEST:TEST -d " \
  {
    \"customer\": \"001-C-80NCSQBE\",
    \"plan\": \"sbdt-1\",
    \"frequency\": \"Weekly\",
    \"start_date\": \"2017-11-26\",
    \"reference\": \"JSMITH1\",
    \"is_active\": true
  }"

Responses

Successful — HTTP 201
{
  "successful": true,
  "response": {
    "customer": "001-C-80NCSQBE",
    "plan": "001-PL-TDX67R1F",
    "frequency": "Weekly",
    "start_date": "2017-11-26",
    "end_date": null,
    "next_billing_date": "2017-11-26",
    "reference": "JSMITH1",
    "last_status": "Scheduled",
    "is_active": true
  },
  "errors": [],
  "test": false
}
Failed (Bad Data) — HTTP 400
{
  "successful": false,
  "response": {
    "id": null,
    "customer": "067-C-EWMAAHMO",
    "plan": "067-PL-KFG3OXX9",
    "frequency": "Daily",
    "start_date": "2012-06-02",
    "end_date": null,
    "next_billing_date": null,
    "reference": null,
    "last_status": "Scheduled",
    "is_active": false
  },
  "errors": [
    "Reference can't be blank"
  ],
  "test": false
}

Retrieving a Subscription

Definition

Authentication: Basic xxxxxxxxxxxxx
POST /v1.0/subscriptions HTTP/1.1

Example Request

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

Responses

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "customer": "001-C-80NCSQBE",
    "plan": "001-PL-TDX67R1F",
    "frequency": "Weekly",
    "start_date": "2017-11-26",
    "end_date": null,
    "next_billing_date": "2017-11-26",
    "reference": "JSMITH1",
    "last_status": "Scheduled",
    "is_active": true
  },
  "errors": [],
  "test": false
}
Failed (Not Found) — HTTP 404
{
  "successful": false,
  "response": null,
  "errors": [
    "Record not found"
  ],
  "test": false
}

Updating a Subscription

A subscription can be updated to stop or pause it. If you wish to subscribe a customer to a new plan you should stop the current subscription and create a new one.

Definition

Authentication: Basic xxxxxxxxxxxxx
PUT /v1.0/subscriptions/067-S-R5TPVPHZ.json HTTP/1.1 

Example Request

  $ curl https://sandbox.gateway.fatzebra.com.au/v1.0/subscriptions/067-S-R5TPVPHZ.json -X PUT -u TEST:TEST -d " \
    {
      \"is_active\": false
    }"

Response

Successful — HTTP 200
{
  "successful": true,
  "response": {
    "id": "067-S-R5TPVPHZ",
    "customer": "067-C-EWMAAHMO",
    "plan": "067-PL-KFG3OXX9",
    "frequency": "Daily",
    "start_date": "2012-06-02",
    "end_date": null,
    "next_billing_date": "2012-06-02",
    "reference": "Hello1235",
    "last_status": "Scheduled",
    "is_active": false
  },
  "errors": [

  ],
  "test": false
}

Web Hooks

Fat Zebra uses web hooks to notify your application of events relating to your recurring subscriptions. Web Hooks are triggered for the following events: charge:pending, charge:successful, charge:retry, charge:failed, card:expiring, card:expired.

Web Hooks are sent with a payload of the following format (in JSON):

  • event — the event name
  • payload — array of payload objects
    • These objects may include purchases, customers, cards or otherwise.

Web Hooks are also accompanied by an HTTP header, X-FatZebra-Mode, which will indicate the environment (Live or Sandbox)

charge:pending

Charge pending will be triggered when subscriptions are queued for processing each day.

Example Payload
{
  "event": "charge:pending",
  "payload": [
    {
      "id": "001-S-GMDS9GG9",
      "frequency": "Daily",
      "start_date": "2012-05-18",
      "end_date" :null,
      "reference": "MAG123",
      "customer": {
        "email": "wally@gmail.com",
        "first_name": "Wally",
        "last_name": "Kravitz",
        "reference": "WK123",
        "id": "001-C-RG3DCTR"
      }
    }
  ]
}

charge:successful

Charge successful will be triggered when subscription charges are successfully completed.

Example Payload
{
  "event": "charge:successful",
  "payload": [
    {
      "subscription": {
        "id": "067-S-R5TPVPHZ",
        "frequency": "Daily",
        "start_date": "2012-06-02",
        "end_date": null,
        "reference": "Hello1235",
        "customer": {
          "email": "hhump@gmail.com",
          "first_name": "Harrold Billy",
          "last_name": "Humphries",
          "reference": "Cust1234",
          "id": "067-C-EWMAAHMO"
        }
      },
      "response": {
        "successful": true,
        "response": {
          "authorization": 1339157688,
          "id": "067-P-4ERGWF0P",
          "card_number": "512345XXXXXX2346",
          "card_holder": "Harrold Humphries Senior",
          "card_expiry": "2012-08-08",
          "card_token": "lhypjhrv",
          "amount": 2399,
          "decimal_amount": 23.99,
          "successful": true,
          "message": "Approved",
          "reference": "HelloXXXX XXXXXXXX-XXXX47",
          "source": "Recurring",
          "currency": "AUD"
        },
        "errors": [

        ],
        "test": true
      }
    }
  ]
}

charge:retry

When a charge fails (e.g. declined or otherwise) it will be added to the retry queue and you will receive this notification.

Example Payload
{
  "event": "charge:retry",
  "payload": [
    {
      "subscription": {
        "id": "067-S-ZL1Q1YDM",
        "frequency": "Daily",
        "start_date": "2012-06-02",
        "end_date": null,
        "reference": "Hello123",
        "customer": {
          "email": "jsmith@gmail.com",
          "first_name": "John",
          "last_name": "Smith",
          "reference": "9cb09b54d987a3532cb79ff9bfc59eae",
          "id": "067-C-FGDZTYIA"
        },
        "last_status": "Failed (2), Pending"
      },
      "response": {
        "successful": true,
        "response": {
          "authorization": 1339160553,
          "id": "067-P-MDWU6LGH",
          "card_number": "455701XXXXXX8902",
          "card_holder": "John Smith",
          "card_expiry": "2012-09-08",
          "card_token": "g1r7y4wr",
          "amount": 2399,
          "decimal_amount": 23.99,
          "successful": false,
          "message": "Declined",
          "reference": "Hello123 XXXXXXXX-XXXXXX",
          "source": "Recurring",
          "currency": "AUD"
        },
        "errors": [

        ],
        "test": true
      }
    }
  ]
}

charge:failed

After three retries a charge will be abandoned and you will receive the charge:failed notification

Example Payload
{
  "event": "charge:failed",
  "payload": [
    {
      "subscription": {
        "id": "067-S-ZL1Q1YDM",
        "frequency": "Daily",
        "start_date": "2012-06-02",
        "end_date": null,
        "reference": "Hello123",
        "customer": {
          "email": "jsmith@gmail.com",
          "first_name": "John",
          "last_name": "Smith",
          "reference": "9cb09b54d987a3532cb79ff9bfc59eae",
          "id": "067-C-FGDZTYIA"
        },
        "last_status": "Failed (3), Aborted"
      },
      "response": {
        "successful": true,
        "response": {
          "authorization": 1339160258,
          "id": "067-P-5ZV92Y3K",
          "card_number": "455701XXXXXX8902",
          "card_holder": "John Smith",
          "card_expiry": "2012-09-08",
          "card_token": "g1r7y4wr",
          "amount": 2399,
          "decimal_amount": 23.99,
          "successful": false,
          "message": "Declined",
          "reference": "Hello123 XXXXXXXX-XXXXXX",
          "source": "Recurring",
          "currency": "AUD"
        },
        "errors": [

        ],
        "test": true
      }
    }
  ]
}

card:expiring

Card expiring will be triggered when a card is due to expire within 30 days.

Example Payload
{
  "event": "card:expiring",
  "payload": [
    {
      "email": "hhump@gmail.com",
      "first_name": "Harrold Billy",
      "last_name": "Humphries",
      "reference": "Cust1234",
      "id": "067-C-EWMAAHMO"
    }
  ]
}

card:expired

Card expired will be triggered when a credit card has expired for an active supscription. At this point the subscription will be set to inactive.

Example Payload
{
  "event": "card:expired",
  "payload": [
    {
      "email": "hhump@gmail.com",
      "first_name": "Harrold Billy",
      "last_name": "Humphries",
      "reference": "Cust1234",
      "id": "067-C-EWMAAHMO"
    }
  ]
}