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).

How can we help?

RESTful API