REST API

General:

• All webservices use JSON. Make sure your POST requests set ContentType: application/json.
• Authentication is using basic auth (and so the service needs to be provided over HTTPS). The basic auth details come from normal Django user.

Errors

When a request is invalid (ie missing keys from the JSON payload), we return a 400 Bad Request response with a JSON body containing a message:

{
    'message': "Missing 'amount' key"
}

Whenever a request cannot be honoured due to business logic (eg not enough funds on giftcard), we return a 403 Forbidden response with a JSON body containing a code and a message:

{
    'code': '101'
    'message': "Account ARX9V1KH6UG7 is no longer active"
}

Create a new giftcard

Request:

POST /api/accounts/
Body
{
        'start_date': '2013-01-01T09:00:00+11:00', # dates must be timezone aware
        'end_date': '2014-01-01T09:00:00+11:00',
        'amount': '50.00',
        'account_type': '$50 giftcards', 
}

The available account types must be configured as part of the service.

Response:

{
        'code': 'ARX9V1KH6UG7'
        'start_date': '2013-01-01',
        'end_date': '2014-01-01',
        'balance': '120.00',
        'redemptions_url': /api/accounts/ARX9V1KH6UG7/redemptions/',
        'refunds_url': /api/accounts/ARX9V1KH6UG7/refunds/',
}

• If successful, a "201 Created" response, linking to the newly created resource, identified by the card number (eg: /api/accounts/ARX9V1KH6UG7/)
• If forbidden (eg dates wrong way round, exceed maximum amount on card), a 403 Forbidden (see above)
• If server error, return 500

Error codes:

• C100 - Cannot create giftcard (catchall)
• C101 - Amount too low
• C102 - Amount too high

Fetch details of a giftcard

Request:

GET /api/accounts/ARX9V1KH6UG7/

Response:

{
        'code': 'ARX9V1KH6UG7'
        'start_date': '2013-01-01',
        'end_date': '2014-01-01',
        'balance': '120.00',
        'redemptions_url': /api/accounts/ARX9V1KH6UG7/redemptions/',
        'refunds_url': /api/accounts/ARX9V1KH6UG7/refunds/',
}

Redeem an amount from a giftcard

Request:

POST /api/accounts/ARX9V1KH6UG7/redemptions/
Body
{
        'amount': '50.00',
        'merchant_reference': '14334555',
}

Note that we are using 'redemptions' instead of 'transfers' in the URL as this request does not have to specify the source account, only the destination. It is basically a shortcut. We could also have a more general webservice for creating transfers where you pass in both the source and the destination account although that's probably not needed for phase 1.

Response:

{
	'source_code': '...',
	'source_url': /api/accounts/...',
	'destination_code': 'ARX9V1KH6UG7',
	'destination_url': /api/accounts/ARX9V1KH6UG7',
	'amount': '50.00',
	'available_to_refund': '50.00',
	'datetime': '2012-10-02 09:00:03+00:00',
	'reverse_url': '/api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/reverse/',
	...
}

• If successful, a 201 Created redirect to the newly created transfer (eg: /api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/)
• If unsuccessful (eg not enough funds), a 403 Forbidden response

Error codes:

• T100 - Cannot create transfer (catchall error code for anything that isn't handled by the below)
• T101 - Insufficient funds
• T102 - Account inactive

Fetch details of a transfer (redemption or refund)

Request:

GET /api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/

Response:

{
	'source_code': '...',
	'source_url': /api/accounts/...',
	'destination_code': 'ARX9V1KH6UG7',
	'destination_url': /api/accounts/ARX9V1KH6UG7',
	'amount': '50.00',
	'available_to_refund': '50.00',
	'datetime': '2012-10-02 09:00:03+00:00',
	'reverse_url': '/api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/reverse/',
	...
}

Both redemptions and refunds are "transfers" ultimately, so we can inspect them in the same way.

Refund back to an account

This a general-purpose refund API - no validation is performed against the requested amount.

Request:

POST /api/accounts/ARX9V1KH6UG7/refunds/
Body
{
        'amount': '25.00',
        'merchant_reference': '1234', # optional
}

Response:

• If successful, a 201 Created, linking to the newly created transfer
• If unsuccessful, a 403 Forbidden (same as when redeeming)

Error codes:

• T100 - Cannot create transfer (catchall error code for anything that isn't handled by the below)
• T102 - Account inactive (can't refund to an inactive account)

Refund against a previous transaction

This is for refunding against a specific redemption. This API validates the requested refund amount to ensure that no more than the original redemption amount can be refunded.

Request:

POST /api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/refunds/
Body
{
        'merchant_reference': '1234', # optional
        'amount': '10.23' # Can't be more than original transfer (or balance remaining if multiple refunds)
}

Response:

• If successful, a 201 Created, linking to the newly created transfer (eg /api/transfers/1A61FE24A3F1F42AD20464C8CC51393F/)
• If unsuccessful, a 403 Forbidden (same as when redeeming)

Error codes:

• T100 - Cannot create transfer (catchall error code for anything that isn't handled by the below)
• T102 - Account inactive (can't refund to an inactive account)

Reverse a previous transaction

This is for situation where other payment sources are being used along with an account. If the transaction on the other payment source fails, you will need to immediately reverse the giftcard transaction.

Request:

POST /api/transfers/0A61FE24A3F1F42AD20464C8CC51393F/reverse/
Body
{
        'merchant_reference': '1234', # optional - an empty POST body can be used
}

Response:

• If successful, a 201 Created, linking to the newly created transfer (eg /api/transfers/1A61FE24A3F1F42AD20464C8CC51393F/)
• If unsuccessful, a 403 Forbidden (same as when redeeming)

Error codes:

• T100 - Cannot create transfer (catchall error code for anything that isn't handled by the below)
• T102 - Account inactive (can't refund to an inactive account)