Gift Card

Gift card

The current gift card integration consists of four actions: create, activate, read and pay. These will be called at appropriate times and allow for your server to control the creation and payment flow.

All four integrations should return a full Giftcard entity with the new state:

{
    "amount": "<number, required>",
    "code": "<string, required>",
    "create_date": "<unix time stamp with decimals, number, required>",
    "currency_code": "<string, required, ISO 4217 currency code>",
    "expiry_date": "<unix time stamp with decimals, number, required>",
    "id": "<string, required>",
    "status": "<number, required, may be 1=created, 2=active or 3=used>",
    "external_giftcard": "<json object, optional>"
}

Here amount is the currently available amount, code is the customer-displayed id of the gift card, which is used to create bar codes for printing, create_date and expiry_date are pretty self-explanatory, currency_code is required in order to prevent usage in the wrong market, id is an internal identification of the gift card, status is the current state of the gift card, and external_giftcard may be used by you to carry any information that is not directly relevant to the Ka-ching system, but may be required by your integration.

Create

From an action in the Ka-ching POS, you can create a gift card and add it to the basket. The gift card will be created in an inactive state, and only activated once the sale has been fully paid.

Activate

Called with the details of an inactive gift card once the gift card has been paid.

Read

Called from an action in the Ka-ching POS to let the customer know the balance.

Pay

Called from the Ka-ching POS when a gift card is being used for payment in the POS.

Customer account payment

The current customer account integration consists of two actions:read and pay. These will be called at appropriate times and allow for your server to control the payment flow.

Both integrations should return an entity containing an amount:

{
    "amount": "<number, required>",
}

For the customer account read action, the amount should refer to the current balance of the customer account.

For the pay action, the amount should contain the actual amount that was used. This could be different than the amount requested to be used, but if it is not possible to pay with the desired amount, a better option is probably to let the payment fail.

Any non-200 response from the server will be treated as a failure to perform the payment.

Read

Called from an action in the Ka-ching POS to get the current balance. Parameters are customer_id and currency_code.

Pay

Called from the Ka-ching POS when a customer account is being used for payment in the POS. Parameters are amount, customer_id and currency_code.