RESTful API
1. Introduction
Welcome to the VaocherApp RESTful API, a powerful and user-friendly interface designed to streamline your voucher and gift card management. With a focus on simplicity and efficiency, our API is organized around REST principles, ensuring seamless integration into your applications and systems.
VaocherApp accepts JSON-encoded requests. The responses are also JSON-encoded, and the API leverages standard HTTP response codes, authentication methods, and verbs. Whether you're a developer looking to enhance your platform's capabilities or a business seeking a reliable solution for voucher management, VaocherApp's RESTful API offers the flexibility and functionality you need to elevate your experience. Unlock the potential of effortless voucher management such as building your own in-house dashboard, integrating with your software, or generating a custom report.
2. API Overview
2.1 Base URLs
VaocherApp's APIs are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
The API base url is:
https://api.vaocher.app
2.2. API Keys
You can obtain a new API key through VaocherApp dashboard.
Note: Your API keys carry many privileges, so be sure to keep them secure! Avoid disclosing your confidential API keys in publicly accessible platforms.
2.3 Live and test APIs
By default, API requests will be treated as LIVE mode. VaocherApp has a built-in test mode that allow you to play around with your account test data, and it does not affect your live data.
To enable test mode in your API requests, pass in a HTTP header:
x-vaocherapp-test-mode: 1
2.4 Response Codes
VaocherApp employs standard HTTP response status codes to signal whether an API request has been successful or has encountered failure.
2.5 Data Formats
- The date and time fields are in UTC and they follow the ISO 8601 standard.
- All API requests expect amounts to be provided in a currency’s smallest unit. For example, to charge 10 AUD, provide an amount value of 1000 (that is, 1000 cents).
3. Authentication
VaocherApp allows you to issue API tokens that can be used to authenticate API requests. When making requests using API
tokens, the token should be included in the Authorization
header as a Bearer
token:
Authorization: Bearer {{apikey}}
Ensure the security of your VaocherApp API keys, as they come with significant privileges. Avoid sharing confidential API keys in publicly accessible spaces like GitHub or client-side code.
4. Accounts
An account is also known as a VaocherApp account. Multiple users can have access to a single VaocherApp account.
4.1 Account Object
Example account:
{
"id": "98b73a81-8d6b-4e8e-8aa3-76ee9384d583",
"name": "My Account",
"email": "demo@demo.com",
"phone": "0400000000",
"address": "1 Swanson St, Melbourne VIC 3000",
"website": "https://example.com",
"country_code": "AU",
"timezone": "Australia/Melbourne",
"currency": "AUD",
"created_at": "2020-12-31T00:00:00.000000Z",
"updated_at": "2020-12-31T00:00:00.000000Z"
}
4.2 Get Account
Get the current account details.
Request:
Method | URL |
---|---|
GET | /restful-api/v1/accounts/current |
Response body:
Returns an account objects.
5. Gift Vouchers
A gift voucher in VaocherApp represents the entity sent to a recipient when an individual completes an order through the VaocherApp checkout or when it is issued through the dashboard/API.
5.1 Gift Voucher Object
Example gift voucher:
{
"id": "98b7b342-28f5-4cf7-b1c3-baacca77cdc2",
"item_name": "60 Minutes Massage",
"item_terms": "Terms & conditions...",
"code": "ABC123",
"expiry": "2030-12-31T14:00:00.000000Z",
"message": "Happy birthday!",
"purchaser_name": "Buyer Name",
"purchaser_email": "buyer@mail.com",
"recipient_name": "Receiver Name",
"recipient_email": "receiver@mail.com",
"initial_balance": 10000,
"remaining_balance": 10000,
"status": "active",
"test_mode": false,
"created_at": "2023-01-01T02:00:00.000000Z",
"updated_at": "2023-01-01T02:00:00.000000Z"
}
Property | Description |
---|---|
id | Unique identifier for the entity |
item_name | Name of the purchased item |
item_terms | Terms and conditions associated with the item |
code | Gift voucher unique reference code |
expiry | Expiration date in ISO 8601 format. If empty, this gift voucher never expires |
message | Personalized message from the buyer |
purchaser_name | Purchaser's name |
purchaser_email | Purchaser's email |
recipient_name | Recipient's name |
recipient_email | Recipient's email |
initial_balance | Initial balance in a currency’s smallest unit |
remaining_balance | Remaining balance in a currency’s smallest unit |
status | Current status of the gift voucher. Available values: active, expired, redeemed, voided, pending |
test_mode | A flag indicating whether this is a test gift voucher |
created_at | Timestamp indicating when the gift voucher was created |
updated_at | Timestamp indicating when the gift voucher was last updated |
5.2 Get Gift Vouchers
Get a list of gift vouchers.
Request:
Method | URL |
---|---|
GET | /restful-api/v1/gift-vouchers |
URL parameters:
Parameter | Description |
---|---|
page | Specify the desired page number |
Response body:
Returns a list of gift voucher objects.
Example response:
{
"data": [
{
"id": "98b7b342-28f5-4cf7-b1c3-baacca77cdc2",
"item_name": "60 Minutes Massage",
"item_terms": "Terms & conditions...",
"code": "ABC123",
"expiry": "2030-12-31T14:00:00.000000Z",
"message": "Happy birthday!",
"purchaser_name": "Buyer Name",
"purchaser_email": "buyer@mail.com",
"recipient_name": "Receiver Name",
"recipient_email": "receiver@mail.com",
"initial_balance": 10000,
"remaining_balance": 10000,
"status": "active",
"test_mode": false,
"created_at": "2023-01-01T02:00:00.000000Z",
"updated_at": "2023-01-01T02:00:00.000000Z"
},
{...},
{...}
],
"meta": {
"pagination": {
"total": 50,
"count": 10,
"per_page": 10,
"current_page": 1,
"total_pages": 5,
"links": {
"next": "https://api.vaocher.app/restful-api/v1/gift-vouchers?page=2"
}
}
}
}
5.3 Get A Gift Voucher
Retrieves a single gift voucher.
Request:
Method | URL |
---|---|
GET | /restful-api/v1/gift-vouchers/{id} |
URL parameters:
Parameter | Description |
---|---|
id | Gift voucher unique identifier |
Response body:
Returns a gift voucher object.
5.4 Get A Gift Voucher By Code
Retrieves a single gift voucher using gift voucher unique reference code.
Request:
Method | URL |
---|---|
GET | /restful-api/v1/gift-vouchers/search-by-code/{code} |
URL parameters:
Parameter | Description |
---|---|
code | Gift voucher unique reference code |
Response body:
Returns a gift voucher object.
5.5 Redeem A Gift Voucher
Deduct the specified amount of balance from a gift voucher.
Request:
Method | URL |
---|---|
PUT | /restful-api/v1/gift-vouchers/{id}/redeem |
URL parameters:
Parameter | Description |
---|---|
id | Gift voucher unique identifier |
Request body:
Parameter | Type | Required | Description |
---|---|---|---|
amount | integer | Yes | The amount to redeem against this gift voucher |
reason | string | No | The reason for this redemption (will appear in the history log) |
Response status 204 (No content).