Local Terminal API

Direct HTTP communication with VelaPay terminals on your local network for real-time payment processing, device control, and terminal management.

Getting Started

VelaPay Manager serves as a universal payment middleware running on Android terminals, providing HTTP API access on port 7501 for payment processing and device management.

Prerequisites

• VelaPay Manager application installed on a compatible terminal
• Terminal connected to your local network
• Terminal's IP address (find in VelaPay Manager settings)
• Store secret (for remote authentication - configured in terminal settings)

Server Configuration

• Port: 7501
• Protocol: HTTP
• Content-Type: application/json; charset=utf-8
• CORS: Enabled for all origins
• Base URL: http://[terminal-ip]:7501

Authentication

Local Requests

Requests from localhost (127.0.0.1 or ::1) do not require authentication.

Remote Requests - HMAC-SHA256 Signature

Remote requests require cryptographic signature authentication using HMAC-SHA256:

• X-Timestamp: Current Unix timestamp in seconds (epoch time)
• X-Signature: HMAC-SHA256(secret, timestamp + body)
• The secret is configured in store_secret and is never transmitted
• Timestamps must be within 5 minutes of server time (prevents replay attacks)

Signature Calculation Example (JavaScript)

const crypto = require('crypto');

function generateSignature(secret, timestamp, body) {
    const message = timestamp + body;
    return crypto.createHmac('sha256', secret)
        .update(message)
        .digest('hex');
}

const timestamp = Math.floor(Date.now() / 1000).toString();
const body = JSON.stringify({ requestType: 'payment', amount: '100.00' });
const signature = generateSignature(secret, timestamp, body);

Request/Response Format

Base Request Structure

{
  "requestType": "string",  // Required: Type of request
  "resourceType": "string", // Context-specific resource
  "actionType": "string",   // Context-specific action
  "requestId": "string",    // Optional: For logging
  // Additional parameters...
}

Base Response Structure

{
  "status": "ok|error",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "message": "string",
  // Additional data...
}

Supported Payment Types

VelaPay Manager supports all major payment types for in-person transactions:

• Credit/Debit Cards: Visa, Mastercard, Amex, Discover
• EMV Chip: Full EMV compliance for card-present transactions
• Contactless: NFC tap-to-pay support
• EBT: Electronic Benefits Transfer processing
• Gift Cards: Integrated gift card management system

API Request Types

System API

The System API provides access to application management, configuration, logging, and screen capture.

Request Parameters

// Request
{
  "requestType": "system",
  "resourceType": "app",
  "actionType": "restart"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

// Request
{
  "requestType": "system",
  "resourceType": "screen",
  "actionType": "capture"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "imageData": "base64_encoded_png_data",
  "format": "png"
}

// Request
{
  "requestType": "system",
  "resourceType": "log",
  "logType": "requestResult",
  "actionType": "getList",
  "logFilter": {
    "createdSince": 1234567890000
  }
}

// Response
{
  "status": "ok",
  "logs": [...],
  "count": 10
}

Device API

Retrieve device information and terminal status.

// Request
{
  "requestType": "device",
  "resourceType": "info"
}

// Response
{
  "status": "ok",
  "uid": "GN1234567890",
  "manufacture": "GENERIC",
  "model": "GENERIC",
  "sn": "1234567890"
}

Payment API

Process card-present transactions including sale, authorization, capture, refund, and batch settlement.

Transaction Types

• sale - Regular sale transaction
• auth - Authorization only
• capture - Capture a previous authorization
• return - Return/refund transaction
• void - Void transaction
• adjust - Adjust tip amount
• batch - Batch settlement

Tender Types

• credit - Credit card
• debit - Debit card
• EBT - Electronic Benefits Transfer
• gift - Gift card
• loyalty - Loyalty card

Payment Request Parameters

Tip Prompt Parameters

Optional parameters for customizing tip prompts during payment:

Payment Response Fields

Batch Settlement Response Fields

Additional fields returned for batch settlement transactions:

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "tenderType": "credit",
  "amount": "100.00",
  "amountTip": "10.00",
  "invoiceNumber": "INV-123",
  "signatureCapture": true,
  "tipPrompt": "button",
  "tip1Label": "15%",
  "tip1Amount": "15.00",
  "tip2Label": "18%",
  "tip2Amount": "18.00",
  "tip3Label": "20%",
  "tip3Amount": "20.00",
  "tipShowCustomTip": true,
  "tipShowNoTip": true,
  "company": "ACME Corp",
  "printReceipt": "true",
  "requestId": "unique_request_id"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "paymentStatus": "APPROVED",
  "batchID": "123",
  "transactionID": "456789",
  "transactionType": "SALE",
  "tenderType": "CREDIT",
  "amount": "100.00",
  "amountTip": "10.00",
  "amountCashBack": "0.00",
  "amountRequest": "100.00",
  "invoiceNumber": "INV-123",
  "resultCode": "00",
  "token": "tokenized_card_data",
  "token2": "additional_token",
  "cardEntry": "CHIP",
  "transactionNumber": "789",
  "referenceNumber": "REF123",
  "authCode": "AUTH456",
  "merchantID": "MERCHANT123",
  "cardType": "VISA",
  "cardNumber": "****1234",
  "cardHolder": "JOHN DOE",
  "signatureData": "base64_signature"
}

// Request
{
  "requestType": "payment",
  "transactionType": "batch"
}

// Response
{
  "status": "ok",
  "batch_settlementTime": "2023-12-01T10:00:00Z",
  "batch_creditSaleCount": "10",
  "batch_creditSaleAmount": "1000.00",
  "batch_creditReturnCount": "2",
  "batch_creditReturnAmount": "50.00",
  "batch_debitSaleCount": "5",
  "batch_debitSaleAmount": "250.00",
  "batch_debitReturnCount": "1",
  "batch_debitReturnAmount": "25.00"
}

Dialog API

Display customer input dialogs, signature capture, and button prompts on the terminal screen.

Dialog Types

• input - Collect various types of user input (number, phone, money, email, date, time)
• signature - Capture customer signature
• button - Display multiple button options (up to 5 buttons)

Common Dialog Parameters

Input Dialog Specific Parameters

Input Dialog Response Fields:

Button Dialog Specific Parameters

Support for up to 5 buttons with customizable labels and return values:

Button Dialog Response Fields:

Signature Dialog Specific Parameters

Signature Dialog Response Fields:

// Request
{
  "requestType": "dialog",
  "dialogType": "button",
  "title": "
Select Option
",
  "description": "Choose an option",
  "button1Label": "Option 1",
  "button2Label": "Option 2",
  "button3Label": "Option 3",
  "button4Label": "Option 4",
  "button5Label": "Option 5",
  "button1Value": "value1",
  "button2Value": "value2",
  "button3Value": "value3",
  "button4Value": "value4",
  "button5Value": "value5"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "buttonLabel": "Option 2",
  "buttonValue": "value2"
}

// Request
{
  "requestType": "dialog",
  "dialogType": "input",
  "inputType": "money",
  "title": "
Enter Amount
",
  "timeout": 30
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "inputValue": "1000",
  "inputValueFormatted": "10.00"
}

// Request
{
  "requestType": "dialog",
  "dialogType": "signature",
  "title": "
APPROVED
Signature Required",
  "description": "I agree to pay the above total amount according to the card issuer agreement",
  "timeout": 60
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "signatureData": "base64_encoded_signature_image"
}

Print API

Print receipts and custom templates using the terminal's built-in printer.

Print Types

• image - Print a base64-encoded image
• template - Print using a structured template with multiple item types

Common Print Parameters

Image Print Parameters

Template Print Parameters

Print Item Types

Each item in printItemList must have a type field. Supported types:

Text Item

Barcode Item

QR Code Item

Line Item

Feed Item

Cut Item

// Request
{
  "requestType": "print",
  "printType": "image",
  "imageData": "base64_encoded_image_data"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

// Request
{
  "requestType": "print",
  "printType": "template",
  "printItemList": [
    {
      "type": "text",
      "fontSize": "large",
      "textCenter": "Receipt",
      "isBold": true,
      "isUnderline": true
    },
    {
      "type": "text",
      "textLeft": "Item",
      "textRight": "$10.00"
    },
    {
      "type": "line",
      "height": 2
    },
    {
      "type": "qrcode",
      "code": "https://example.com",
      "height": 200,
      "alignment": "center"
    },
    {
      "type": "barcode",
      "code": "123456789",
      "format": "code128",
      "width": 300,
      "height": 100,
      "alignment": "center"
    },
    {
      "type": "feed",
      "height": 50
    },
    {
      "type": "cut"
    }
  ]
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0"
}

MSR API

Magnetic stripe reader operations for reading card data.

Request Parameters

Response Fields

// Request
{
  "requestType": "msr",
  "actionType": "read"
}

// Response
{
  "status": "ok",
  "timestamp": 1234567890000,
  "version": "1.0.0",
  "track1": "...",
  "track2": "...",
  "track3": "...",
  "cardNumber": "****1234",
  "expiryDate": "1225",
  "cardholderName": "JOHN DOE"
}

VelaPay Cloud API

External developer API for the VelaPay platform: payments and hosted payment links, courier delivery, SMS, merchant wallet, and campaign blasts.

How Requests Work

The Cloud API uses a single endpoint. Every call is an HTTP POST with a JSON body; the operation is selected by requestType + actionType in the body.

POST <API_URL>          // provided by VelaPay Support
Content-Type: application/json

{
  "requestType": "payment",
  "actionType": "getPaymentLink",
  "transactionType": "sale",
  "amount": "10.00"
}

• requestType is case-insensitive (payment and PAYMENT are equivalent).
• actionType is case-sensitive as documented below.
• Money crosses this API as decimal strings (e.g. "50.00").

Request Types

Authentication

Every request is authenticated with an API key + HMAC-SHA256 signature.

Required Headers

The signature covers the exact raw bytes of the JSON body you send — sign the same string you POST.

Example (JavaScript)

const crypto = require('crypto');

// API_URL, API_KEY and API_SECRET are provided by VelaPay Support.
// Keep them in server-side configuration (environment variables).
const body = JSON.stringify({ requestType: 'payment', actionType: 'getPaymentLink', transactionType: 'sale', amount: '10.00' });
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto.createHmac('sha256', API_SECRET).update(timestamp + body).digest('hex');

await fetch(API_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': API_KEY,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body,
});

Example (PHP)

$bodyJson  = json_encode($body);
$timestamp = (string)time();
$signature = hash_hmac('sha256', $timestamp . $bodyJson, $apiSecret);

Permissions

Each API key carries a list of permissions. The required permission for a call is {REQUESTTYPE}_{actionType} (matched case-insensitively), e.g. payment_getPaymentLink, delivery_getQuote, sms_send. A {requestType}_manage permission is a wildcard for that whole request type (e.g. wallet_manage, campaign_manage).

See the full API Permissions Reference.

Preconditions

• PAYMENT (all actions except search) requires the store to have an active payment processor configured.
• DELIVERY requires an active delivery provider.
• SMS requires the store's SMS product to be configured.

Response Envelope

Every response is JSON with at minimum:

Action-specific fields are merged into this envelope and documented per action below.

Payment API (requestType: payment)

Payments and hosted payment links.

• getPaymentLink — create a hosted payment page link
• getPaymentInfo — look up a payment created with getPaymentLink
• process — direct card transaction (server-to-server)
• search — list the store's logged payment transactions
• Payment Webhook — server-to-server notification when a link finishes

Hosted Payment Page

The Hosted Payment Page provides a secure, pre-built payment form hosted by VelaPay. Instead of collecting card details directly, your application generates a payment link and redirects the customer to VelaPay's hosted page to complete the payment (or save a card). This approach simplifies PCI compliance since sensitive card data never touches your servers.

How It Works

The hosted payment flow involves three parties: Your Server, VelaPay Cloud API, and the Customer's Browser. The diagram below shows the complete lifecycle of a hosted payment.

Flow Summary

1. Create Payment Link — Your server calls getPaymentLink with the amount, return URL, webhook URL, and optional customer/invoice details. VelaPay creates a payment session and returns a paymentId and a hosted payment page link.
2. Redirect Customer — Your application redirects the customer's browser to the payment link. The customer sees a secure, VelaPay-hosted form where they enter their card details and complete payment.
3. Payment Processing — VelaPay processes the payment through the configured payment processor. No card data passes through your server.
4. Dual Notification — After payment completes, two things happen in parallel:
   • Webhook (server-to-server) — VelaPay sends a POST request to your webhook URL with the full payment result. This is the most reliable way to confirm payment since it does not depend on the customer's browser.
   • Return URL (browser redirect) — The customer's browser is redirected to your returnUrl with paymentId and status as query parameters so you can display the appropriate confirmation page.
5. Verify Payment — Your server calls getPaymentInfo with the paymentId to retrieve the full payment details and confirm the transaction status. This is recommended as a final verification step.

actionType: getPaymentLink

Creates a hosted payment page link. The customer opens the link, pays (or saves a card), and is redirected / your webhook is called.

Request Parameters

Response

The link's domain is driven by the store's LIGHTBOX feature setting: lightbox-enabled stores get the hosted payment app (root path), other stores get the customer site's /pay/ page.

Example

// Request
{
  "requestType": "payment",
  "actionType": "getPaymentLink",
  "transactionType": "sale",
  "amount": "99.99",
  "invoiceNumber": "INV-2024-001",
  "customerName": "John Doe",
  "email": "customer@example.com",
  "returnUrl": "https://yourapp.com/payment/complete",
  "webhook": "https://yourapp.com/api/payment-webhook",
  "webhookFormat": "standard",
  "webhookSecret": "your-webhook-signing-key",
  "paymentPageOptions": {
    "customerEmail": "REQUIRED",
    "addressBilling": "SHOW",
    "totalSummary": "SHOW"
  }
}

// Response
{
  "status": "ok",
  "timestamp": 1754314211,
  "version": "1.0.0",
  "paymentId": "507f1f77bcf86cd799439011",
  "link": "https://[payment-page-host]/pay?paymentId=507f1f77bcf86cd799439011"
}

Return URL

When the payment finishes, the customer is redirected to:

{returnUrl}?paymentId={paymentId}&status={approved|declined|cancelled}

Set paymentPageOptions.showResultScreen = "YES" to keep the customer on the hosted result screen instead of redirecting.

Payment Page Options

paymentPageOptions controls what the hosted payment page shows for this link. All keys are optional; an omitted key uses the default. Unknown keys are stored and echoed back but ignored by the page.

Validated at link creation (invalid values are rejected)

Form field visibility

Value is one of "SHOW", "REQUIRED", "OPTIONAL"; omitted = field hidden:

Page chrome

actionType: getPaymentInfo

Look up a payment created with getPaymentLink. Use this to verify the payment result on your server after receiving a webhook notification or when the customer returns via the return URL.

Request Parameters

Response Fields

Example — Completed Payment

// Request
{
  "requestType": "payment",
  "actionType": "getPaymentInfo",
  "paymentId": "507f1f77bcf86cd799439011"
}

// Response
{
  "status": "ok",
  "timestamp": 1754314211,
  "version": "1.0.0",
  "paymentId": "507f1f77bcf86cd799439011",
  "cartStatus": "COMPLETED",
  "request": {
    "amount": "99.99",
    "transactionType": "sale",
    "email": "customer@example.com",
    "invoiceNumber": "INV-2024-001"
  },
  "result": {
    "paymentStatus": "APPROVED",
    "transactionId": "TXN_123",
    "authCode": "AUTH456",
    "referenceNumber": "REF789",
    "cardType": "VISA",
    "cardNumber": "1234",
    "message": "APPROVAL"
  },
  "addPaymentMethod": false,
  "created": 1754313800,
  "modified": 1754314100
}

Example — Pending Payment

// Request
{
  "requestType": "payment",
  "actionType": "getPaymentInfo",
  "paymentId": "507f1f77bcf86cd799439011"
}

// Response
{
  "status": "ok",
  "timestamp": 1754314211,
  "version": "1.0.0",
  "paymentId": "507f1f77bcf86cd799439011",
  "cartStatus": "ACTIVE",
  "request": {
    "amount": "99.99",
    "transactionType": "sale"
  },
  "result": {},
  "created": 1754313800,
  "modified": 1754313800
}

actionType: process

Direct card transaction (server-to-server, no hosted page). Requires the payment_process permission.

Request Parameters

Response Fields

Example — Sale with a New Card

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "amount": "10.00",
  "cardNumber": "4111111111111111",
  "cardExpDate": "1225",
  "cvv": "123",
  "cardHolder": "John Doe",
  "invoiceNumber": "INV-12345",
  "customerIp": "203.0.113.10",
  "getToken": true,
  "addressBilling": {
    "name": "John Doe",
    "street": "123 Main St",
    "city": "Anytown",
    "state": "CA",
    "zipcode": "12345",
    "country": "US"
  }
}

// Response
{
  "status": "ok",
  "timestamp": 1754314211,
  "version": "1.0.0",
  "paymentStatus": "APPROVED",
  "message": "APPROVAL",
  "authCode": "112892",
  "referenceNumber": "211025O2C-EE3A17F7-70FD-4061-AEA3-30F60DEFBA68",
  "transactionId": "MH169X56_AC3556463BD8957C_5RVH_L93D",
  "transactionType": "SALE",
  "amount": "10.00",
  "token": "4034762327081111",
  "cardType": "VISA",
  "cardNumber": "1111",
  "cardExpDate": "1225"
}

Example — Sale with a Stored Token

// Request
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "sale",
  "amount": "144.11",
  "invoiceNumber": "INV-67890",
  "token": "4459079401220002",
  "customerIp": "203.0.113.10"
}

Example — Capture / Void / Return

Reference the original transaction with referenceNumber:

// Capture a prior auth (amount optional for partial capture)
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "capture",
  "referenceNumber": "211025O2C-AUTH-12345",
  "amount": "50.00"
}

// Void a transaction
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "void",
  "referenceNumber": "281025C45-9C229B8E-DD67-4434-AC25-293C9DD037AF"
}

// Return (refund) a transaction
{
  "requestType": "payment",
  "actionType": "process",
  "transactionType": "return",
  "referenceNumber": "211025O2C-SALE-12345",
  "amount": "25.00"
}

actionType: search

List the store's logged payment transactions. Scoped to the API key's store.

Request Parameters

Response

{
  "status": "ok",
  "transactions": [ ... ]
}

Payment Webhook

When a link created with a webhook URL finishes, VelaPay POSTs to it.

Legacy Payload (default)

{
  "paymentId": "...",
  "storeId": "...",
  "status": "APPROVED",
  "request": { "...": "what the link was created with" },
  "result": { "...": "processor outcome" }
}

Standard Envelope (opt in with webhookFormat: "standard")

{
  "type": "PAYMENT",
  "event": "payment.approved",
  "source": "PAYMENT",
  "sourceId": "<paymentId>",
  "timestamp": 1754314211,
  "data": { "paymentId": "...", "storeId": "...", "status": "...", "request": {}, "result": {} }
}

Signing (opt in with webhookSecret)

Each delivery carries x-vela-timestamp and x-vela-signature headers, where the signature is base64 HMAC-SHA256 over timestamp + rawBody keyed with your webhookSecret. Verify against the raw request bytes and reject deliveries older than ~300 seconds.

// Node.js webhook verification
const crypto = require('crypto');

function verifyWebhook(headers, rawBody, webhookSecret) {
  const timestamp = headers['x-vela-timestamp'];
  const signature = headers['x-vela-signature'];

  const expected = crypto.createHmac('sha256', webhookSecret)
    .update(timestamp + rawBody)   // raw request bytes, not re-serialized JSON
    .digest('base64');

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Delivery API (requestType: delivery)

Courier delivery (DoorDash Drive). Fees are charged to the merchant wallet. Requires an active delivery provider on the store.

actionType: getQuote

Response

{
  "status": "ok",
  "estimatedMinutes": 35,
  "fee": "9.75",
  "feeBreakdown": { "rawFeeCents": 875, "extraCents": 100, "totalCents": 975 }
}

actionType: deliver

Books the courier. Same request fields as getQuote. The merchant wallet must cover the full charge (courier fee + platform fee + tip) or the call fails without booking.

Response

{
  "status": "ok",
  "deliveryId": "...",
  "externalDeliveryId": "...",
  "trackingUrl": "...",
  "deliveryStatus": "...",
  "fee": "9.75",
  "charge": { "...": "fee/tip breakdown" }
}

actionType: getStatus

Pass deliveryId — OR — externalDeliveryId.

Response

{
  "status": "ok",
  "deliveryId": "...",
  "externalDeliveryId": "...",
  "deliveryStatus": "...",
  "trackingUrl": "...",
  "events": [ ... ]        // when tracked locally
}

actionType: cancel

Pass deliveryId (required).

Response

{
  "status": "ok",
  "deliveryId": "...",
  "cancelled": true
}

actionType: getLocations

No parameters. Returns the store's pickup locations.

{
  "status": "ok",
  "defaultPickup": { ... },
  "locations": [ ... ]
}

SMS API (requestType: sms)

actionType: send

Sends one text message; the cost is charged to the merchant wallet. Requires the store's SMS product to be configured.

Response

{
  "status": "ok",
  "messageId": "...",
  "messageStatus": "...",
  "to": "...",
  "from": "...",
  "cost": "0.02",
  "billingStatus": "..."
}

Wallet API (requestType: wallet)

The merchant wallet funds DELIVERY, SMS, and other platform products. Money crosses this API as decimal strings ("50.00").

actionType: getBalance

No parameters.

{
  "status": "ok",
  "balance": "50.00",
  "pendingBalance": "0.00",
  "availableBalance": "50.00",
  "currency": "USD",
  "walletStatus": "ACTIVE",              // ACTIVE, SUSPENDED, or null
  "autoRecharge": { "enabled": true, "threshold": "10.00", "amount": "50.00" },
  "paymentMethodId": "..."               // or null
}

actionType: topUp

• paymentMethodId: string (required; a saved funding card)
• amount: string (required)

Response: paymentStatus, transactionId, balance.

actionType: getActivity

No parameters. Returns activity: the date-sorted wallet statement.

actionType: setAutoRecharge

• enabled: boolean
• threshold: string (required when enabling; recharge when available balance drops below)
• amount: string (required when enabling; amount to charge)
• paymentMethodId: string (required when enabling)

Response: autoRecharge, paymentMethodId.

actionType: addCard

Tokenizes and saves a merchant funding card. The card token is never returned.

• cardNumber: string (required)
• cardExpDate: string (required, MMYY)
• cvv: string (required)
• name: string (required)
• description: string (optional)
• primary: boolean (optional)
• addressBilling: object (optional)

Response: card { id, name, description, cardType, cardNumber (masked), cardExpDate, status, primary, addressBilling }.

actionType: listCards

No parameters. Returns cards: array of saved funding cards (same shape as addCard).

actionType: updateCard

• paymentMethodId: string (required)
• name, description, status, primary (mutable fields only)

actionType: deleteCard

• paymentMethodId: string (required)

Response: deleted: true.

Campaign API (requestType: campaign)

Email/SMS campaign blasts over your own recipient lists. Compliance split: you certify your list has consent (setConsent); the platform owns suppression, scrubbing, footers and the unsubscribe path. send/schedule are refused until the campaign has a consent attestation.

Campaign Content Fields

Writable via create/update:

Campaign lifecycle: DRAFT → SCHEDULED → SENDING → SENT (or FAILED / CANCELLED). Content edits are DRAFT-only. Dispatch is asynchronous — send schedules for "now" and a background job fans it out within the minute.

Lifecycle Actions

Campaign responses return a campaign object: id, name, channel, subject, fromName, html, body, status, scheduledAt, timezone, audience ({ contactListId, recipientCount }), stats ({ received, invalid, duplicates, suppressed, deliverable, sent, failed }), sentAt, failureReason, created, modified. Audiences report a COUNT, never the addresses.

Saved Audiences

Reusable recipient lists, owned by the CAMPAIGN request type.

Audience responses return an audience object: id, name, source, contactCount, created, modified.

API Permissions Reference

payment_process, payment_search, payment_getPaymentLink, payment_getPaymentInfo

delivery_getQuote, delivery_deliver, delivery_cancel, delivery_getStatus, delivery_getLocations

sms_send

wallet_getBalance, wallet_topUp, wallet_getActivity, wallet_setAutoRecharge,
wallet_addCard, wallet_listCards, wallet_updateCard, wallet_deleteCard, wallet_manage

campaign_list, campaign_get, campaign_create, campaign_update, campaign_duplicate,
campaign_delete, campaign_schedule, campaign_send, campaign_cancel,
campaign_getAudienceCount, campaign_getEstimate, campaign_sendTest, campaign_getReport,
campaign_setConsent, campaign_getConsent,
campaign_addAudience, campaign_listAudiences, campaign_getAudience,
campaign_updateAudience, campaign_replaceAudienceContacts, campaign_deleteAudience,
campaign_manage

Common Error Messages

• "Not authenticated - Invalid API key or signature" — missing/wrong X-API-Key, X-Timestamp, or X-Signature
• "Missing request type" / "Missing action type"
• "You do not have permission for {REQUESTTYPE}_{actionType}"
• "Merchant payment processor not configured"
• "Delivery provider not configured"
• "SMS product not configured"
• "Unsupported request type: ..." / "Unsupported action type: ..."
• "Invalid paymentPageOptions.lightbox (ENABLED|DISABLED)"
• "Invalid paymentPageOptions.customerLogin (SHOW|HIDE)"