WizzGift B2B API Documentation

Introduction

Welcome to the WizzGift Business API documentation. This guide will help you integrate your applications with the WizzGift platform to programmatically create gift card orders and access other business features.

Authentication

WizzGift uses the OAuth 2.0 protocol for API authentication. This implementation is designed for secure server-to-server integrations. Before making API requests, you need to register a client application and implement the OAuth flow to obtain an access token.

Creating a Client

To create a new OAuth client, follow these steps in the WizzGift dashboard:

1. Log in to your WizzGift business account
2. Navigate to Developer Settings in your dashboard
3. Click Create New App
4. Fill in the required details:
   • App Name: A name for your integration
   • Redirect URI: Your server endpoint that will receive the authorization code
   • Required Scopes: Select the permissions your app needs
5. Click Register Application
6. You'll be provided with a client_id and client_secret - store these securely on your server

Available Scopes

When creating your client, you'll need to select the scopes (permissions) your application requires. Available scopes:

Authorization Flow

WizzGift implements a server-to-server OAuth 2.0 flow optimized for secure backend integrations:

Authorization Endpoint

The authorization endpoint is the starting point of the OAuth 2.0 flow. Direct users to this URL to begin the authorization process.

https://myapp.example.com/callback?code=auth_code_123456789abcdef&state=random_state_1234

/oauth/authorize?client_id=client_123456789abcdef&redirect_uri=https://myapp.example.com/callback&response_type=code&scope=account%20createOrder&state=random_state_1234

Token Endpoints

Obtaining Access Tokens

After receiving an authorization code, exchange it for access and refresh tokens using the token endpoint.

{
  "grant_type": "authorization_code",
  "code": "auth_code_123456789abcdef",
  "client_id": "client_123456789abcdef",
  "client_secret": "cs_123456789abcdef123456789abcdef",
  "redirect_uri": "https://your-server.example.com/callback"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "account createOrder"
}

{
  "grant_type": "refresh_token",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "client_id": "client_123456789abcdef",
  "client_secret": "cs_123456789abcdef123456789abcdef"
}

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "NEW_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token_expires_in": 2592000,
  "scope": "account createOrder"
}

Creating Orders

Create new gift card orders through the order endpoint.

Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "amount": 50,
  "referenceId": "order_12345",
  "quantity": 1,
  "productId": "product_123456",
  "requiredInfoFromUser": [
    { "id": "7FeXMgqYEgndkQVuG8n1", "value": "recipient@example.com" },
    { "id": "dN5TxW7Qez0IBkCc9Jnp", "value": "John Doe" },
    { "id": "kR9sP2mLxTyZaQvB5Wn3", "value": "Birthday" }
  ],
  "isTest": false
}

{
  "success": true,
  "message": "Order created successfully",
  "data": {
    "id": "order_987654321",
    "referenceId": "order_12345"
  }
}

Get Order

Retrieve details of an existing order by either orderId or referenceId.

Authorization: Bearer YOUR_ACCESS_TOKEN

/order?id=order_987654321
OR
/order?referenceId=order_12345

{
  "success": true,
  "data": {
    "id": "order_987654321",
    "referenceId": "order_12345",
    "amount": 50,
    "quantity": 1,
    "productId": "product_123456",
    "status": "completed",
    "orderedQuantity": 1,
    "redeemInfos": [
      {
        "link": "https://redeem.example.com/giftcard123",
        "rewardId": "reward_789",
        "instruction": "Follow the link and enter the code to redeem your gift card",
        "pin": "1234",
        "code": "ABCD-EFGH-IJKL-MNOP",
        "serial": "GC123456789",
        "transactionId": "tx_987654321",
        "expiryDate": "2025-12-31",
        "status": "completed"
      }
    ]
  }
}

Products API

Get a list of all available gift card products that your business can purchase.

Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "success": true,
  "data": [
    {
      "id": "paypal-usa",
      "description": "",
      "disclosure": "",
      "name": "PayPal USA Gift Card",
      "image": "https://wizzgiftt.s3.ap-south-1.amazonaws.com/dkb6VzOEVsMUdrR5pDH4r/normal.png",
      "skus": [
        {
          "min": 0.01,
          "max": 2000,
          "minCost": 0.0105,
          "changeStep": 0.1
        }
      ],
      "currencyCode": "USD",
      "costCurrency": "USD",
      "countries": ["US"],
      "category": ["payments"],
      "requiredInfoFromUser": []
    },
    {
      "id": "ntc-nepal",
      "name": "Nepal Telecom Refill",
      "description": " ",
      "image": "https://wizzgiftt.s3.ap-south-1.amazonaws.com/ntc-nepal/normal.png",
      "currencyCode": "NPR",
      "costCurrency": "NPR",
      "requiredInfoFromUser": [
        {
          "id": "7FeXMgqYEgndkQVuG8n1",
          "name": "mobile",
          "type": "input",
          "description": "phone",
          "required": true,
          "selectValues": []
        }
      ],
      "skus": [
        {
          "min": 10,
          "max": 3000,
          "minCost": 10.5,
          "description": "NTC Topup"
        }
      ],
      "category": ["topup"],
      "countries": ["NP"],
      "fee": 1
    }
  ]
}

Webhooks

WizzGift can send webhook notifications to your application when certain events occur, such as when an order is completed or fails.

Setting Up Webhooks

To configure webhooks for your application:

1. Log in to your WizzGift business account
2. Navigate to Developer Settings in your dashboard
3. Select the Webhooks tab
4. Click Add Webhook Endpoint
5. Enter your endpoint URL that will receive the webhook notifications
6. WizzGift will generate a webhook signing secret that you should store securely

Webhook Payload Structure

When an order is processed, WizzGift will send a webhook with the following fields:

Order Status Information

RedeemInfo Fields

The redeemInfos array contains objects with information about each gift card. Depending on the gift card provider, some fields may be present while others might be absent. Below are all possible fields that might be included:

{
  "id": "order_987654321",
  "referenceId": "order_12345",
  "status": "completed",
  "orderedQuantity": 2,
  "redeemInfos": [
    {
      "link": "https://example.com/redeem/123",
      "rewardId": "reward-12345",
      "instruction": "This is instruction",
      "pin": "12345",
      "code": "1234556",
      "serial": "123serial",
      "transactionId": "Ref123transaction",
      "expiryDate": "2025-02-06",
      "status": "completed"
    },
    {
      "link": "https://example.com/redeem/456",
      "rewardId": "reward-67890",
      "instruction": "This is another instruction",
      "pin": "67890",
      "code": "6789010",
      "serial": "456serial",
      "transactionId": "Ref456transaction",
      "expiryDate": "2025-03-10",
      "status": "completed"
    }
  ]
}

Verifying Webhook Signatures

To ensure the webhook request originated from WizzGift, you should verify the signature in the X-Signature header.

Here's how the signature verification process works:

1. Extract the X-Signature header from the incoming request
2. Take the JSON object from the request body and stringify it exactly (JSON.stringify(req.body))
3. Create an HMAC-SHA256 hash using your webhook secret key and the stringified JSON as input
4. Compare the calculated hash with the signature from the header
5. Only process the webhook if the signatures match

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const expectedSignature = hmac.update(payload).digest('hex');
  return expectedSignature === signature;
}

// In your webhook handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const payload = JSON.stringify(req.body);
  const isValid = verifyWebhookSignature(
    payload,
    signature,
    'YOUR_WEBHOOK_SECRET'
  );
  
  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }
  
  // Process the webhook
  const webhookData = req.body;
  
  // Check the order status
  if (webhookData.status === 'completed') {
    // Handle completed order
    // Access gift card info from webhookData.redeemInfos
  } else if (webhookData.status === 'failed') {
    // Handle failed order
  } else if (webhookData.status === 'partial') {
    // Handle partial order (some completed, some failed)
    // Check webhookData.redeemInfos for successful redemptions
  }
  
  res.status(200).send('Webhook received');
});

Error Handling

The WizzGift API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error due to the information provided, and codes in the 5xx range indicate an error with WizzGift's servers.

Error Response Format

When an error occurs, the API will return a JSON response with an error object containing details about what went wrong.

{
  "success": false,
  "message": "Message About the Error"
}

Common Error Codes