3rd Party Voucher API Code
minutes
It is assumed that the API for the third-party vouchers is a REST API.
Since we only support JSON data, we set the Content-Type header in the request to application/json.
Likewise, it is assumed that the response provides JSON data.
Authentication...
Authentication is done by passing an API key to be communicated to us as a parameter in each request. There must be an API key for each branch.
Error handling...
Errors are returned with the default HTTP status code.
A status code = 200 means that the request was OK. All other status codes mean an error.
BaseURL...
The REST API is called via a URL, the beginning of the URL is always identical.
For example, the <BaseURL> could be "https://www.traumgutscheine.com/services/v1".
methods
The interface for the third-party vouchers only requires 2 methods, which are described in more detail below.
Method: Balance...
Enquires the status and the loaded amount of the foreign voucher.
URL
GET <BaseURL>/vouchers/{code}/balance?apikey={api-key}
parameter
| {code}: | String | Required, the unique alphanumeric voucher number of the voucher. |
| {api-key}: | String | Required, the unique alphanumeric API key for unlocking a branch to use the API. |
Return
| Status code | = 200 | If the status code is <> 200, then an error has occurred. |
| code: | String | The unique alphanumeric voucher number of the voucher. |
| is_redeemable: | Boolean | Indicates whether the requested voucher can be redeemed. If the voucher cannot be redeemed, the reason must be stated in the message. |
| balance_in_cents: | Integer | Remaining amount in cents. See also Countries and currencies. |
| total_amount_in_cents: | Integer | Former total amount in cents. See also Countries and currencies. |
| message: | String |
If the voucher is not redeemable, the message will contain the reason why the requested voucher cannot be redeemed. If message <> "", then an error has occurred. |
Example
Request
GET https://www.traumgutscheine.com/services/v1/vouchers/A567F31B67/ba-lance?apikey=510e32c594d84816a4af9df1
Return
Status code = 200
{
}, "code": "A567F31B67",
"is_redeemable": true,
"balance_in_cents": 2500,
"total_amount_in_cents": 4000,
"message": ""
}
Method: Redeem...
Redeems a partial amount from the voucher and returns the remaining amount on the voucher.
URL
POST <BaseURL>/vouchers/{code}/redeem?apikey={api-key}
parameter
| {code}: | String | Required, the unique alphanumeric voucher number of the voucher. |
| {api-key}: | String |
Required, the unique alphanumeric API key for unlocking a branch to use the API.
|
POST Data
| {amount_in_cents}: | Integer |
Required, amount to be debited in cents. See also Countries and currencies. |
Return
| StatusCode | = 200 |
If StatusCode <> 200, then an error has occurred and the amount has not been redeemed. |
| code: | String | The unique alphanumeric voucher number of the voucher. |
| balance_in_cents: | Integer | Remaining amount in cents. See also Countries and currencies. |
| message: | String |
If the voucher is not redeemable, the message will contain the reason why the requested voucher cannot be redeemed. If message <> "", then an error has occurred and the order has not been honoured. |
Example
Request
POST https://www.traumgutscheine.com/services/v1/vouchers/A567F31B67/ba-lance?apikey=510e32c594d84816a4af9df1
POST Data
{
"amount_in_cents": 2100
}
Return
StatusCode = 200
{
}, "code": "A567F31B67",
"balance_in_cents": 400,
"message": ""
}
Back to the parent page: 3rd Party Voucher Development