Esc

Quick Navigation

Overview

Dashboard home

Documentation

API Reference

Playground

Test live

API Keys

Manage credentials

Usage Stats

Analytics

Webhooks

Event endpoints

Pricing

Plans & limits

SDKs

Code examples

Error Codes

Troubleshooting

Authentication

Bearer token setup

Gift Cards API

Purchase gift cards

Airtime API

Top up mobile

Wallet API

Balance & funding

↵ select Esc close

v1 · REST · JSON

Iascroft API Reference

The Iascroft REST API lets you integrate gift cards, airtime, digital products, wallet management and vouchers into any application using standard HTTP requests.

Base URL

https://api.iascroft.com/v1

Response Format

application/json

Authentication

Bearer Token

Authentication

All API requests must include your secret key as a Bearer token in the Authorization header.

Authorization Header

⚠️ Never expose your secret key in client-side code or public repos. Use server-side environment variables.

Base URL & Headers

All API requests go to this base URL. Include the following headers on every request.

Required Headers

POST https://api.iascroft.com/v1/{endpoint}

Authorization: Bearer sk_live_your_secret_key
Content-Type:  application/json
Accept:        application/json

Content-Type application/json

Required on POST/PUT requests

Accept application/json

Ensures JSON response

Authorization Bearer <key>

Required on every request

X-Idempotency-Key string

Optional. Prevent duplicate requests

Rate Limits

Limits depend on your plan. Exceeding limits returns a 429 Too Many Requests error with a Retry-After header.

Rate Limit Headers in Response
X-RateLimit-Limit:     60
X-RateLimit-Remaining: 54
X-RateLimit-Reset:     1706619600
Retry-After:           30  # only on 429 responses

Plan	Requests / Min	Requests / Month	Endpoints
Starter	10	1,000	Gift Cards, Airtime
Merchant	60	10,000	All endpoints
Enterprise	Unlimited	Unlimited	All + priority SLA

GET /v1/giftcard/products

List all available gift card products in the catalogue. Filter by country or currency.

Query Parameters (optional)

countrystringFilter by ISO country code (US, GB, NG)

currencystringFilter by ISO currency code (USD, GBP)

limitintegerResults per page (default: 20, max: 100)

pageintegerPage number (default: 1)

200 OK

{
  "status": "success",
  "data": [
    {
      "id":       "GC-AMZN-US-50",
      "name":     "Amazon Gift Card",
      "country":  "US",
      "currency": "USD",
      "denoms":   [10,25,50,100]
    }
  ]
}

POST /v1/giftcard/purchase

Purchase a gift card. Amount is deducted from your merchant wallet. Code is returned immediately.

        
          ParameterTypeRequiredDescription

            product_id
            string
            required
            Product ID from GET /v1/giftcard/products
          
            amount
            number
            required
            Must match a valid denomination for the product
          
            currency
            string
            required
            ISO 4217 code: USD, GBP, EUR, NGN, GHS, KES
          
            recipient_email
            string
            optional
            Optional — code will also be emailed to recipient
          
            reference
            string
            optional
            Your own idempotency key (max 64 chars)

Parameter	Type	Required	Description
`product_id`	`string`	required	Product ID from GET /v1/giftcard/products
`amount`	`number`	required	Must match a valid denomination for the product
`currency`	`string`	required	ISO 4217 code: USD, GBP, EUR, NGN, GHS, KES
`recipient_email`	`string`	optional	Optional — code will also be emailed to recipient
`reference`	`string`	optional	Your own idempotency key (max 64 chars)

Request

{
  "product_id": "GC-AMZN-US-50",
  "amount": 50.00,
  "currency": "USD",
  "recipient_email": "user@example.com",
  "reference": "ORDER-001"
}

200 OK

{
  "status": "success",
  "data": {
    "reference": "TXN-GC-00192",
    "code":      "AMZN-X7K2-P8M4",
    "amount":    50.00,
    "currency":  "USD",
    "status":    "delivered"
  }
}

Try in Playground

GET /v1/giftcard/status/{reference}

Check the delivery status of a gift card transaction by its reference ID.

200 OK
{
  "status": "success",
  "data": {
    "reference": "TXN-GC-00192",
    "status":    "delivered",
    "delivered_at": "2025-01-30T09:12:00Z"
  }
}

GET /v1/airtime/operators

List available airtime operators. Filter by country code.

200 OK
{
  "status": "success",
  "data": [
    { "id": "MTN-NG", "name": "MTN Nigeria", "country": "NG", "min": 0.5, "max": 100 }
  ]
}

POST /v1/airtime/topup

Top up any phone number. Supports 200+ operators in 150+ countries.

Request

{
  "phone": "+2348012345678",
  "amount": 5.00,
  "operator_id": "MTN-NG",
  "currency": "USD"
}

200 OK

{
  "status": "success",
  "data": {
    "reference": "TXN-AT-00191",
    "phone":     "+2348012345678",
    "amount":    5.00,
    "operator":  "MTN Nigeria",
    "status":    "completed"
  }
}

Try in Playground

GET /v1/digital/products

List all available digital products (license keys and activation codes).

POST /v1/digital/purchase

Purchase a digital product. License key or activation code is returned immediately.

Request

{
  "product_id": "DPL-001",
  "currency": "USD",
  "reference": "MY-ORDER-002"
}

200 OK
{
  "status": "success",
  "data": {
    "reference": "TXN-DP-00190",
    "key":       "XXXXX-XXXXX-XXXXX",
    "product":   "Windows 11 Pro",
    "status":    "delivered"
  }
}

GET /v1/wallet/balance

Get current merchant wallet balance.

200 OK
{
  "status":  "success",
  "data": {
    "balance":  4200.00,
    "currency": "USD"
  }
}

POST /v1/wallet/fund

Initiate a wallet funding request. Returns payment instructions.

Request
{
  "amount": 500.00,
  "currency": "USD",
  "method": "bank_transfer"
}

POST /v1/wallet/withdraw

Request a withdrawal from your merchant wallet. Subject to admin approval.

Request
{
  "amount": 200.00,
  "currency": "USD",
  "method": "bank",
  "reference": "PAYOUT-001"
}

Webhook Events

Subscribe to these events from the Webhooks page. We send a signed POST to your endpoint on each event.

Event	Trigger
`transaction.completed`	Any transaction succeeds
`transaction.failed`	Any transaction fails
`transaction.pending`	Transaction awaiting processing
`wallet.funded`	Merchant wallet funded
`wallet.withdrawn`	Withdrawal processed
`kyc.approved`	User KYC approved
`kyc.rejected`	User KYC rejected
`voucher.redeemed`	Voucher code redeemed

Webhook Payload Structure
{
  "event": "transaction.completed",
  "created_at": "2025-01-30T09:12:00Z",
  "data": {
    "reference": "TXN-GC-00192",
    "amount": 50.00,
    "currency": "USD",
    "status": "completed"
  }
}

Verify Webhook Signatures

Every webhook includes a X-Iascroft-Signature header. Always verify it.

Signature Verification

Error Format

All errors follow this consistent structure. Use error.code for programmatic error handling.

4xx / 5xx
{
  "status":       "error",
  "error":        {
    "code":         "INSUFFICIENT_BALANCE",
    "message":      "Wallet balance is too low.",
    "http_status":  402
  }
}

View all error codes