Create payment voucher

POST /payment/create-voucher

Api key auth

Create a new payment voucher that can be redeemed for account credit. Supports various voucher types and denominations.

application/json

Body Required

data object Required

The actual request data to be processed
Hide data attributes Show data attributes object
- amount number Required
  
  Voucher denomination amount
- currency string Required
  
  Voucher currency
- voucherType string Required
  
  Type of voucher to create
  
  Values are digital, physical, or gift.
- quantity integer
  
  Number of vouchers to create
  
  Minimum value is 1. Default value is 1.
- expiryDate string(date)
  
  Voucher expiry date
- description string
  
  Voucher description
- customMessage string
  
  Custom message for gift vouchers
- deliveryMethod string
  
  How to deliver the voucher
  
  Values are email, sms, or physical.
signature string Required

ed25519 signature of the data, signed with user's private key
publicKey string Required

User's derived public key for signature verification
timestamp integer Required

Unix timestamp when the request was created (milliseconds)
nonce string Required

Unique nonce to prevent replay attacks

Responses

201 application/json

Voucher created successfully
Hide response attributes Show response attributes object
- success boolean
- vouchers array[object]
  
  Hide vouchers attributes Show vouchers attributes object
  
  id string
  
  Unique voucher identifier
  
  code string
  
  Voucher redemption code
  
  amount number
  
  Voucher denomination
  
  currency string
  
  Voucher currency
  
  type string
  
  Voucher type
  
  Values are digital, physical, or gift.
  
  status string
  
  Voucher status
  
  Values are active, redeemed, expired, or cancelled.
  
  expiryDate string(date)
  
  When the voucher expires
  
  createdAt string(date-time)
  
  When the voucher was created
  
  redeemedAt string(date-time)
  
  When the voucher was redeemed
  
  redeemedBy string
  
  User ID who redeemed the voucher
- totalValue number
  
  Total value of all vouchers created
- currency string
- expiryDate string(date)
  
  When the vouchers expire
400

Invalid request parameters
401

Authentication failed
403

Insufficient permissions
429

Rate limit exceeded
500

Internal server error

POST /payment/create-voucher

curl \
 --request POST 'https://pay-api-dev.aiic.nz/v1/payment/create-voucher' \
 --header "X-Public-Key: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '{"data":{"amount":100,"currency":"NZD","voucherType":"digital","quantity":1,"expiryDate":"2025-05-04","description":"Gift voucher for services","customMessage":"string","deliveryMethod":"email"},"signature":"base64-encoded-signature","publicKey":"base64-encoded-public-key","timestamp":1703123456789,"nonce":"abc123-def456-ghi789"}'

Request examples

{
  "data": {
    "amount": 100,
    "currency": "NZD",
    "voucherType": "digital",
    "quantity": 1,
    "expiryDate": "2025-05-04",
    "description": "Gift voucher for services",
    "customMessage": "string",
    "deliveryMethod": "email"
  },
  "signature": "base64-encoded-signature",
  "publicKey": "base64-encoded-public-key",
  "timestamp": 1703123456789,
  "nonce": "abc123-def456-ghi789"
}

Response examples (201)

{
  "success": true,
  "vouchers": [
    {
      "id": "vch_xyz789",
      "code": "ABC123-DEF456",
      "amount": 100,
      "currency": "NZD",
      "type": "digital",
      "status": "active",
      "expiryDate": "2025-05-04",
      "createdAt": "2025-05-04T09:42:00Z",
      "redeemedAt": "2025-05-04T09:42:00Z",
      "redeemedBy": "string"
    }
  ],
  "totalValue": 100,
  "currency": "NZD",
  "expiryDate": "2025-05-04"
}