Voucher Management

Our Voucher Management APIs allow you to manage clients, orders, and voucher distributions efficiently.

Requirements

Managing Third-Party Client Vouchers

These APIs follow our asynchronous Operation Result Token pattern. This means operations return a token that must be used in a follow-up call to retrieve the final result.

Below is a high-level overview of the key workflows and data fields. For full details, refer to the API reference documentation.

Clients

Clients represent your corporate customers, and all voucher orders are associated with them.

Endpoint

POST /api/v1/voucher-management/client

Sample Request Body (abbreviated)

{
  "code": "ABC123",
  "name": "Vista",
  "contact": {
    "name": "John Smith",
    "email": "johnsmith@vista.co",
    "phone": "0211231234",
    "fax": ""
  },
  "externalClientId": "xyz123",
  "externalData": "my additional free-text reference data",
  "voucherTypeCodes": ["VOUCHERTYPE1", "VOUCHERTYPE2"]
}

Key Fields

• externalClientId: A searchable identifier for cross-referencing this client in your system.
• externalData: A free-text field for storing additional metadata about the client.

Response

Returns an Operation Result Token that resolves to the client ID:

{
  "responses": [
    {
      "operationResultToken": "aGVsbG8gd..."
    }
  ]
}

Client Orders

Creates a client order and issues vouchers.

Endpoint

POST /api/v1/voucher-management/client-order

Sample Request Body (abbreviated)

{
  "clientCode": "ABC123",
  "reference": "My internal ref #1234",
  "electronicDistribution": true,
  "externalUserId": "User-123",
  "deliveryAddress": {
    ...
  },
  "externalData": "my additional free-text reference data",
  "vouchers": [
    {
      "productCode": "ABC12",
      "quantity": 5,
      "salePrice": 12.34,
      "redeemPrice": 12.34,
      "expiryDate": "2024-02-01T00:00:00Z"
    }
  ]
}

Key Fields

• externalUserId: A searchable identifier for the user who created the order.
• externalData: A customizable field for attaching additional metadata to the order.

Response

Returns an operation token to be resolved for final order status:

{
  "responses": [
    {
      "operationResultToken": "Vm91Y2hlckNsaWVudE..."
    }
  ]
}

Large orders may take a long time to process, the resolve Operation Result Token API endpoint returns a status field indicating the processing status.

[
  {
    "operationResultToken": "Vm91Y2hlckNsaWVudE...",
    "entityId": "6052",
    "status": "Processing",
    "entityType": "VoucherClientOrder"
  }
]

Distributions

Distributions send vouchers to recipients via email or mobile.

Currently, only external distribution is supported. Vista-managed internal distribution is not yet available.

Email Distribution

POST /api/v1/voucher-management/email-distribution

Mobile Distribution

POST /api/v1/voucher-management/mobile-distribution

Common Key Fields

• distributionData: Free-text metadata, such as image links or personalized messages.
• externallyDistributed: Must be true.

{
  "reference": "abc",
  "distributionData": "string",
  "distributionItems": [
    {
      "clientOrderItemId": 1234,
      "quantityPerRecipient": 123
    }
  ],
  "externallyDistributed": true,
  ...
}

Response Handling

The distribution creation endpoints return a separate Operation Result Token for each distribution item requested.

You can resolve all tokens in a single request using the Resolve Operation Result Tokens API endpoint.