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:

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"
}

5.2 Get Gift Vouchers

Get a list of gift vouchers.

Request:

URL parameters:

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:

URL parameters:

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:

URL parameters:

Response body:

Returns a gift voucher object.

5.5 Redeem A Gift Voucher

Deduct the specified amount of balance from a gift voucher.

Request:

URL parameters:

Request body:

Response status 204 (No content).