PayPerWA API Documentation

Getting Started

The PayPerWA API lets you send WhatsApp messages, manage contacts, templates, and campaigns programmatically. All endpoints use the /api/v1 prefix and require API key authentication.

Base URL

https://payperwa.com/api/v1

Response Format

All responses follow a consistent JSON format:

// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "success": false,
  "error": "Human-readable error message",
  "code": "OUTSIDE_24H_WINDOW"   // on some errors only
}

Some errors add more fields, such as details (validation) or required / available (wallet). See Error Codes. POST /api/v1/contacts also returns a top-level created field (true when a new contact was made).

Authentication

Include your API key in the Authorization header as a Bearer token with every request.

Authorization: Bearer ppw_live_sk_your_key_here

Keys look like ppw_live_sk_ followed by 32 lowercase hex characters. There are no test or sandbox keys. Every key is live, so every message you send reaches WhatsApp and is charged to your wallet. To test, send to a phone you own (not the WhatsApp number you send from). Write the header exactly as shown, with Bearer followed by one space. Other headers such as X-API-Key are ignored.

Generate your API key in Dashboard → Settings → API tab. You can have up to 5 keys per account. Switched-off keys count toward the 5, so delete one to make room. You can reveal and copy a key again at any time from that list, which means anyone who can log in to your dashboard can read your keys. To revoke a key, switch it off (its requests then get 401 API key is deactivated) or delete it.

Quick Example — Check Balance

curl https://payperwa.com/api/v1/balance \
  -H "Authorization: Bearer ppw_live_sk_your_key_here"

Pick a language once — every other code sample on this page switches with you.

Call the API from your server, never from browser JavaScript. The API sends no CORS headers, so browsers block the response, and a key in front-end code is visible to anyone. The JavaScript samples use top-level await, so run them with Node.js 18+ as an ES module (for example a file named app.mjs).

Rate Limits

Each API key can make 100 requests per minute. The limit applies to each key, not to the whole account, and is shown on every key in Dashboard → Settings → API. You cannot change it yourself. Contact support if you need a higher limit.

• The window is a fixed 60 seconds that starts with the key's first request. When it ends, the count starts again from zero.
• Every request made with a valid key counts, including ones that end in 400, 403 (missing permission), 404 or 500. Requests rejected with 401 do not count.
• Over the limit you get 429 until the window ends, which can take up to 60 seconds. No Retry-After or X-RateLimit-* headers are sent, so wait up to a minute before you retry.
• The OTP / Verify API also has its own limits per recipient number. Those 429s carry a code such as OTP_COOLDOWN, a retry_after_seconds field and a Retry-After header.

// HTTP 429
{
  "success": false,
  "error": "Rate limit exceeded. Try again later."
}

Channels (Multi-WABA)

If your account has more than one connected WhatsApp Business Account (WABA) — for example, separate numbers for Sales and Support — you can scope a call to one channel by passing its ID in the X-Channel-Id header. Without it, each endpoint picks for you: a template send uses the number the template is approved on (your primary number's copy first), a text or media reply uses the number whose 24-hour window is open, the list endpoints return data from all your channels, and POST /api/v1/contacts uses your primary channel. The "Where it applies" table below has the details.

Where to find your channel ID

A channel ID is a UUID such as 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90. It is not the WABA ID or the phone number ID from Meta. You can get it in three places:

1. Dashboard → Settings → API: the "Your channel IDs" list shows every connected number with its ID and a copy button.
2. Dashboard → Settings → WhatsApp: each number card shows "Channel ID" next to the WABA ID.
3. The API: GET /api/v1/channels (below) returns all your channels with their IDs.

If you have only one number connected you can skip the header entirely — every call uses your primary channel.

Lists your connected numbers: active ones only, primary first, then in the order they were connected. Any valid API key can call it; no permission is needed.

{
  "success": true,
  "data": {
    "channels": [
      {
        "id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
        "label": "Sales line",
        "phone_number": "+91 98765 43210",
        "display_name": "Acme Stores",
        "display_name_status": "APPROVED",
        "waba_id": "118600000000000",
        "phone_number_id": "964190000000000",
        "is_primary": true,
        "coexistence": false,
        "quality_rating": null,
        "messaging_tier": null,
        "connected_at": "2026-09-24T07:34:30.000Z"
      }
    ],
    "usage": "Pass a channel's id as the X-Channel-Id header (or channelId in the body/query) to scope a request. Without it each endpoint chooses (template sends use the template's number, free-form sends the number with the open window, list endpoints return all numbers) — see the API docs, Channels."
  }
}

curl https://payperwa.com/api/v1/channels \
  -H "Authorization: Bearer YOUR_API_KEY"

How to specify a channel

Three options, in resolution order:

1. X-Channel-Id HTTP header (recommended)
2. channelId in the request body (POST /api/v1/messages/send, POST /api/v1/otp/send and POST /api/v1/contacts only)
3. ?channelId= query parameter (GET only)

Where it applies

Example — Send from a specific channel

curl -X POST https://payperwa.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Channel-Id: 3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "template_name": "order_confirmation",
    "variables": ["Rahul", "ORD-4521"]
  }'

Find your channel IDs in Dashboard → Settings → API ("Your channel IDs") or with GET /api/v1/channels. A channel ID that is not one of yours returns 400 Invalid channelId on the send, contacts, templates and campaigns endpoints (sends also reject a disconnected number). GET /api/v1/messages/window does not check it and answers open: false.

Send Message

Send a single WhatsApp message using an approved template — at any time. The PayPerWA fee (₹0.20 per message, $0.004 on USD wallets) is deducted from your wallet; Meta bills its own template fee to your WhatsApp Business Account. To reply with free-form text or media inside the 24-hour customer service window, see Text & Media.

Opt-out: a MARKETING or UTILITY template is refused with 403 CONTACT_OPTED_OUT, before anything is charged or sent, when one of your contacts (not deleted, on any of your channels) has that number and has opted out. Numbers are compared by their digits, so +91 98765-43210 and 919876543210 match. AUTHENTICATION templates are still sent, because the person asked for the code. A number with no opted-out contact is sent as usual, so only send to people who agreed to hear from you (WhatsApp requires opt-in).

Permission required: messages:send

Request Body

{
  "to": "919876543210",
  "template_name": "order_confirmation",
  "language": "en",
  "variables": ["Rahul", "ORD-4521", "₹1,299"]
}

Document header example (invoice / bill PDF)

{
  "to": "919876543210",
  "template_name": "bill",
  "language": "en",
  "variables": ["Rahul", "01 Jul - 31 Jul 2026", "₹1,250.00", "https://example.com/pay"],
  "document_url": "https://your-cdn.com/bills/BILL-201.pdf",
  "document_filename": "BILL-201.pdf"
}

{
  "to": "919876543210",
  "template_name": "login",
  "language": "en",
  "variables": ["483920"]
}

Response

{
  "success": true,
  "data": {
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MA==",
    "status": "sent",
    "cost": {
      "meta_fee": 0,
      "platform_fee": 0.2,
      "wallet_deduction": 0.2,
      "total_outlay": 0.2,
      "billing_mode": "meta_direct",
      "breakdown": "Meta bills customer directly + PayPerWA ₹0.20 fee",
      "country": "IN",
      "pricing_source": "meta_direct"
    }
  }
}

Example delivery_warning (added next to status; the send is still charged):

"delivery_warning": {
  "code": 141006,
  "message": "There is an error with the payment method. This will block business initiated conversations.",
  "action": "This is a Meta account issue (not PayPerWA). Meta accepted this message but will NOT deliver it until you fix it — open Meta Business Settings > WhatsApp Accounts and check your payment method / account status. Messages sent within a 24-hour customer service window are unaffected."
}

Errors

{
  "success": false,
  "error": "Insufficient wallet balance. Please recharge to send messages.",
  "code": "INSUFFICIENT_WALLET_BALANCE",
  "required": "0.20",
  "available": "0.10",
  "currency": "INR",
  "breakdown": "Meta bills customer directly + PayPerWA ₹0.20 fee"
}

required and available are strings in your wallet currency's decimals (2 for INR, 4 for USD), and currency names that currency. available is rounded down, so it never shows as much as required while it falls short. On a USD wallet with $0.003 the 402 has "required": "0.0040", "available": "0.0030", "currency": "USD" and the breakdown "Meta bills customer directly + PayPerWA $0.0040 fee". If another request uses up the balance in between, the 402 instead reads "Insufficient wallet balance. Required ₹0.20, available ₹0.05. Please recharge to continue." with required / available to 4 decimals, currency and breakdown.

Example

curl -X POST https://payperwa.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "template_name": "order_confirmation",
    "language": "en",
    "variables": ["Rahul", "ORD-4521", "₹1,299"]
  }'

Send Text & Media (24-hour window)

Reply to a customer with free-form text, an image, a video, a document or an audio file — no template needed. The same endpoint is used; pick the message with type.

Permission required: messages:send

Text message

{
  "to": "919876543210",
  "type": "text",
  "text": "Hi Rahul, your order ORD-4521 has been packed and ships today. Track it here: https://example.com/t/4521",
  "preview_url": true
}

Image, video, document or audio

{
  "to": "919876543210",
  "type": "image",
  "media_url": "https://your-cdn.com/orders/ORD-4521.jpg",
  "caption": "Your order is packed"
}

{
  "to": "919876543210",
  "type": "document",
  "media_url": "https://your-cdn.com/invoices/INV-4521.pdf",
  "filename": "INV-4521.pdf",
  "caption": "Invoice for order ORD-4521"
}

Media limits (set by WhatsApp)

Response

{
  "success": true,
  "data": {
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MA==",
    "inbox_message_id": "5ceb6e10-af90-4702-b690-df31c11d8412",
    "status": "sent",
    "type": "text",
    "window": { "open": true, "expires_at": "2026-10-14T09:12:40.000Z" },
    "cost": {
      "meta_fee": 0,
      "platform_fee": 0.2,
      "wallet_deduction": 0.2,
      "currency": "INR",
      "billing_mode": "meta_direct",
      "breakdown": "Service / inbound reply (free from Meta) + PayPerWA ₹0.20 fee",
      "note": "Free-form messages inside the 24-hour window are charged only the PayPerWA fee here; any Meta charge is billed by Meta to your WhatsApp Business Account."
    }
  }
}

inbox_message_id is the message's ID in your PayPerWA Inbox (null if it could not be recorded). On a USD wallet platform_fee and wallet_deduction are 0.004 and currency is USD.

Window closed (409)

{
  "success": false,
  "error": "The 24-hour customer service window for this number has closed. Send an approved template instead; free-form messages are possible again once the customer replies.",
  "code": "OUTSIDE_24H_WINDOW",
  "window": { "open": false, "expires_at": "2026-10-13T07:30:00.000Z" },
  "hint": "POST /api/v1/messages/send with template_name, or check GET /api/v1/messages/window?to=<number> first."
}

If you have never exchanged any message with the number, error reads "No conversation with this number yet. Free-form text and media can only be sent within 24 hours of the customer's last message — send an approved template instead." and window.expires_at is null. If you have only sent to the number and it has never replied, you get the "window has closed" text above, also with window.expires_at null. The same 409 is returned (and the fee refunded) when WhatsApp itself reports the window closed (Meta error 131047).

Other errors

401, 403 (permission), 429 and 500 are the same as for template sends.

Example

curl -X POST https://payperwa.com/api/v1/messages/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "919876543210",
    "type": "text",
    "text": "Hi Rahul, your order ORD-4521 ships today."
  }'

Check the 24-hour window

Tells you whether free-form messages can be sent to a number right now, and until when. Use it to decide between a text reply and a template before sending. The window is the customer's last message to you plus 24 hours, as recorded by PayPerWA.

Permission required: messages:send

{
  "success": true,
  "data": {
    "to": "+919876543210",
    "open": true,
    "expires_at": "2026-10-14T09:12:40.000Z",
    "channel_id": "3f2a9c1e-5b7d-4e8a-9c21-7d4e5f6a8b90",
    "last_customer_message_at": "2026-10-13T09:12:40.000Z",
    "can_send": ["template", "text", "image", "video", "document", "audio"]
  }
}

When the window has closed, open is false, can_send is ["template"] and expires_at shows when it closed. If you have never exchanged any message with the number, expires_at, channel_id and last_customer_message_at are null (if you have only sent to it, channel_id is set and the other two are null):

{
  "success": true,
  "data": {
    "to": "+919899999999",
    "open": false,
    "expires_at": null,
    "channel_id": null,
    "last_customer_message_at": null,
    "can_send": ["template"]
  }
}

A to without 10–15 digits returns 400 with Query parameter 'to' must be a phone number with country code (10–15 digits). 401, 403 and 429 are as for every endpoint; an unexpected failure returns 500 Failed to check the messaging window.

OTP / Verify API

Let PayPerWA create, send and check one-time codes for logins, sign-ups and other confirmations. PayPerWA generates a random numeric code, sends it to the person's WhatsApp with your approved Authentication template, and later tells you whether the code your user typed is right. The code is never returned to you, so you do not generate or store it yourself.

1. Your server calls POST /api/v1/otp/send with the person's number and gets back a verification_id.
2. The person receives the code on WhatsApp, in the message and on its copy-code button, and types it into your app or site.
3. Your server calls POST /api/v1/otp/verify with that code and the verification_id (or the number). data.valid is true only when the code is right.

Both endpoints use your API key (see Authentication) and need the permission messages:send. Each request also counts toward your key's rate limit.

Send a code

{
  "to": "+91 98765 43210",
  "code_length": 6,
  "expiry_minutes": 10
}

Only to is required. The body is checked strictly: a field that is not in this table (for example variables or otp_button_type) is refused with 400.

How to is read

PayPerWA trims the value, removes one leading +, every space and dash, and then one leading 00 (the international dialling prefix). What remains must be 10 to 15 digits and must not start with 0.

A refused to returns 400 with {"to": ["to must be 10–15 digits starting with the country code, not 0 (a leading + or 00, spaces and dashes are allowed)"]} in details. The response gives the number in the form it was read (data.to), and every way of writing one number shares one set of limits.

PayPerWA cannot tell whether a country code is there. A 10-digit Indian mobile number written without 91 (9876543210) is accepted and sent as written, and WhatsApp reads its first digits as a country code, so it is a different number. Always include the country code.

Which template is used

• Without template_name: your most recently updated APPROVED Authentication template that is not archived. With a channel (X-Channel-Id or channelId) only that channel's templates count; without one, templates on any connected number or with no number. None found: 400 OTP_TEMPLATE_REQUIRED. If you have more than one Authentication template, pass template_name so the choice does not depend on which one was updated last.
• With template_name: the APPROVED, not archived template of that name (on the given channel, if any). If the name exists more than once, an Authentication copy is used, your primary number's first. No approved template of that name: 404. Only a template of another category (for example MARKETING): 400 OTP_TEMPLATE_NOT_AUTHENTICATION.
• Language: the one stored with the chosen template, unless you pass language.
• Number it is sent from: the given channel; without one, the number the template belongs to (your primary number if the template has none or its number is disconnected), as for template sends.

PayPerWA puts the code in the message body and in the copy-code button; you do not pass variables. Opt-out does not block a code: Authentication templates are sent even when a contact with that number has opted out, because the person asked for the code.

Response

{
  "success": true,
  "data": {
    "verification_id": "6f1c2b9e-4d3a-4f7e-9b21-0c8d5e7a1f42",
    "to": "919876543210",
    "status": "pending",
    "expires_at": "2026-11-09T10:10:00.000Z",
    "code_length": 6,
    "template_name": "login_otp",
    "message_id": "wamid.HBgLMTIzNDU2Nzg5MA==",
    "cost": {
      "meta_fee": 0,
      "platform_fee": 0.2,
      "wallet_deduction": 0.2,
      "total_outlay": 0.2,
      "billing_mode": "meta_direct",
      "breakdown": "Meta bills customer directly + PayPerWA ₹0.20 fee",
      "country": "IN",
      "pricing_source": "meta_direct"
    }
  }
}

On a USD wallet platform_fee, wallet_deduction and total_outlay are 0.004 and breakdown reads "Meta bills customer directly + PayPerWA $0.0040 fee". This cost object has no currency field: the amounts are in your wallet's currency. country is detected from the number and can be null.

• PayPerWA keeps only a keyed hash (HMAC-SHA256) of the code with its expiry and attempt count. The code is not stored, logged or returned.
• Like every API send, the message appears in your Inbox under the template name ("Template: login_otp"), never the code; the number is added to your contacts if it is not there yet; and the message.sent webhook fires with sentFrom: "api" and the templateName, without the code.
• A new code to the same number replaces the earlier one once it has gone out. The earlier verification_id then answers not_found, and the earlier code checked by number counts as a wrong code against the new one. The new code starts with 5 attempts. Ask your user for the newest code.
• If the send request fails (any error response), no new code is created and any earlier code for the number stays valid. If Meta accepts the message and later reports it failed (a message.failed webhook), the new code has already replaced the earlier one and still counts toward the cooldown and the hourly limit; PayPerWA's fee is refunded. Send a new code.

Limits per number

These limits apply per recipient number within your account (another account sending to the same number has its own). The send limits are checked before anything is charged or sent, so a refused send costs nothing.

• The cooldown and the hourly count include only codes that went out. A send refused after the check (for example 402, 409, an immediate WhatsApp API error or 503) gives its slot back, so an immediate retry is not refused with 429. A message Meta accepts and later reports as failed still counts. Requests refused for validation or the template never reach the check.
• Wrong codes are the ones answered incorrect, plus the one that causes max_attempts. Right codes, expired codes and not_found checks do not count.
• Every 429 from these limits has retry_after_seconds (whole seconds, at least 1) and the same value in a Retry-After header. When more than one limit applies, the 429 names the first of them in this order: wrong codes per 24 hours, codes per hour, cooldown.

// HTTP 429
{
  "success": false,
  "error": "A code was sent to this number less than 30 seconds ago. Wait before sending another.",
  "code": "OTP_COOLDOWN",
  "retry_after_seconds": 30
}

Errors

Every error has "success": false and error; most add a code. The send itself runs through the same code as template sends, so those errors come back with the same status and body.

CONTACT_OPTED_OUT is never returned here: Authentication templates are not blocked by opt-out.

Check a code

Checks the code your user typed. Free: it never charges your wallet. A valid request gets 200 whether or not the code is right, and data.status says what happened. A wrong code is not an HTTP error.

{
  "code": "483920",
  "verification_id": "6f1c2b9e-4d3a-4f7e-9b21-0c8d5e7a1f42"
}

Send exactly one of verification_id and to; any other field is refused with 400. Each check is a single atomic step: a code is approved at most once, even when several checks arrive together, and never takes more than 5 wrong codes.

Response

// Right code
{
  "success": true,
  "data": {
    "valid": true,
    "status": "approved",
    "verification_id": "6f1c2b9e-4d3a-4f7e-9b21-0c8d5e7a1f42"
  }
}

// Wrong code
{
  "success": true,
  "data": {
    "valid": false,
    "status": "incorrect",
    "verification_id": "6f1c2b9e-4d3a-4f7e-9b21-0c8d5e7a1f42",
    "attempts_remaining": 3
  }
}

valid is true only for approved. Sign the user in on that alone and treat every other status as a failure.

Errors

Example: send a code, then check it

# 1. Send a code
curl -X POST https://payperwa.com/api/v1/otp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+91 98765 43210",
    "code_length": 6,
    "expiry_minutes": 10
  }'

# 2. Check the code your user typed, with the verification_id from step 1
curl -X POST https://payperwa.com/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "483920",
    "verification_id": "6f1c2b9e-4d3a-4f7e-9b21-0c8d5e7a1f42"
  }'

# ...or check against the number's newest code instead
curl -X POST https://payperwa.com/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "483920", "to": "919876543210" }'

Contacts

// Response
{
  "success": true,
  "data": {
    "contacts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Rahul Sharma",
        "phone": "+919876543210",
        "email": "rahul@example.com",
        "optedIn": true,
        "tags": ["customer", "delhi"],
        "createdAt": "2026-01-15T10:30:00.000Z"
      }
    ],
    "total": 1250,
    "page": 1,
    "pageSize": 50
  }
}

curl "https://payperwa.com/api/v1/contacts?page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

// Request — create or update by phone, merge tags
{
  "name": "Priya Patel",
  "phone": "919123456789",
  "email": "priya@example.com",
  "tags": ["lead", "mumbai"]
}

// Response — 201 Created (new) or 200 OK (updated)
{
  "success": true,
  "created": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Priya Patel",
    "phone": "+919123456789",
    "email": "priya@example.com",
    "optedIn": true,
    "tags": ["lead", "mumbai"],
    "createdAt": "2026-03-20T14:00:00.000Z",
    "updatedAt": "2026-03-20T14:00:00.000Z"
  }
}

// 400 — a field failed validation (details lists each field)
{
  "success": false,
  "error": "Validation failed",
  "details": { "phone": ["Too big: expected string to have <=15 characters"] }
}

// 400 — phone is not all digits after cleaning (this one has no "success" field)
{ "error": "Invalid phone number format. Use E.164 format: +919876543210" }

// 400 — X-Channel-Id / channelId is not one of your channels
{ "success": false, "error": "Invalid channelId" }

// 409 — only with "upsert": false
{ "success": false, "error": "A contact with this phone number already exists on this channel" }

# Default: upsert + merge tags
curl -X POST https://payperwa.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Priya Patel","phone":"919123456789","tags":["lead","mumbai"]}'

# Replace tags entirely instead of merging
curl -X POST https://payperwa.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Priya Patel","phone":"919123456789","tags":["customer"],"tagsMode":"replace"}'

# Strict create-only — return 409 if the phone already exists
curl -X POST https://payperwa.com/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Priya Patel","phone":"919123456789","upsert":false}'

// Response
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Priya Patel",
    "phone": "+919123456789",
    "email": "priya@example.com",
    "optedIn": true,
    "notes": null,
    "tags": ["lead", "mumbai"],
    "groups": ["Mumbai customers"],
    "createdAt": "2026-03-20T14:00:00.000Z",
    "updatedAt": "2026-03-20T14:00:00.000Z"
  }
}

curl https://payperwa.com/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

// Request
{
  "name": "Priya P.",
  "tags": ["customer", "vip"]
}

// Response
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "name": "Priya P.",
    "phone": "+919123456789",
    "email": "priya@example.com",
    "optedIn": true,
    "tags": ["customer", "vip"],
    "groups": ["Mumbai customers"],
    "updatedAt": "2026-03-21T09:15:00.000Z"
  }
}

curl -X PUT https://payperwa.com/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Priya P.","tags":["customer","vip"]}'

// Response
{
  "success": true,
  "data": { "message": "Contact deleted" }
}

curl -X DELETE https://payperwa.com/api/v1/contacts/CONTACT_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Templates

List your message templates: approved ones by default, or one other status. Every match comes back in one list (no pagination), newest first. Archived templates are not listed.

Permission: templates:read

Query Parameters

// Response
{
  "success": true,
  "data": {
    "templates": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "name": "order_confirmation",
        "category": "UTILITY",
        "language": "en",
        "status": "APPROVED",
        "header": { "type": "TEXT", "value": "Order confirmed" },
        "body": "Hi {{1}}, your order {{2}} of {{3}} has been confirmed!",
        "footer": "Thank you for shopping with us",
        "buttons": [
          { "type": "URL", "text": "View order", "url": "https://example.com/orders" }
        ],
        "metaTemplateId": "1234567890123456",
        "createdAt": "2026-02-01T12:00:00.000Z"
      }
    ]
  }
}

header is null or { type, value } with type TEXT, IMAGE, VIDEO or DOCUMENT. For media headers value is an internal Meta media handle (or null), not a URL you can download. buttons is the template's button list or null.

Example

curl "https://payperwa.com/api/v1/templates?status=APPROVED" \
  -H "Authorization: Bearer YOUR_API_KEY"

Campaigns

// Response
{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "name": "Diwali Offer 2026",
        "status": "COMPLETED",
        "template": "promo_offer",
        "templateCategory": "MARKETING",
        "totalMessages": 5000,
        "sentCount": 5000,
        "deliveredCount": 4850,
        "readCount": 3200,
        "failedCount": 150,
        "estimatedCost": "1000",
        "actualCost": "970",
        "scheduledAt": null,
        "startedAt": "2026-03-10T09:00:05.000Z",
        "completedAt": "2026-03-10T09:12:40.000Z",
        "createdAt": "2026-03-10T09:00:00.000Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20
  }
}

// Request
{
  "name": "March Sale",
  "templateId": "550e8400-e29b-41d4-a716-446655440005",
  "contactIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "550e8400-e29b-41d4-a716-446655440001"
  ],
  "variables": {
    "1": "name",
    "2": "20%",
    "3": "MARCH20"
  },
  "send": true
}

// Response (201) — sent (marketing template, INR wallet)
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "name": "March Sale",
    "status": "SENDING",
    "totalContacts": 2,
    "estimatedCost": {
      "meta_fee": "1.72",
      "platform_fee": "0.40",
      "wallet_deduction": "0.40",
      "total_outlay": "2.12",
      "note": "meta_fee is charged separately by Meta. Only platform_fee is deducted from PayPerWA wallet."
    },
    "message": "Campaign queued. 2 messages will be sent."
  }
}

// Response (201) — send omitted/false: same, with "status": "DRAFT" and no "message"

// Response (201) — not enough balance: saved as DRAFT, not sent, not charged
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440004",
    "name": "March Sale",
    "status": "DRAFT",
    "totalContacts": 2,
    "estimatedCost": {
      "meta_fee": "1.72",
      "platform_fee": "0.40",
      "wallet_deduction": "0.40",
      "total_outlay": "2.12",
      "note": "meta_fee is charged separately by Meta to your WhatsApp Business account. Only platform_fee is deducted from your PayPerWA wallet."
    },
    "error": "Insufficient wallet balance to send. Campaign created as DRAFT.",
    "required": "0.40",
    "available": "0.15"
  }
}

// 400 — no WhatsApp number connected to the account
{ "success": false, "error": "WhatsApp Business Account not connected" }

// 400 — a field failed validation (e.g. an ID that is not a UUID)
{ "success": false, "error": "Validation failed", "details": { "groupIds": ["Invalid UUID"] } }

// 404 — templateId is not one of your templates
{ "success": false, "error": "Template not found" }

// 400 — the template is not approved yet
{ "success": false, "error": "Template must be approved. Current status: PENDING" }

// 400 — no contactIds / groupIds / tagIds (or all empty)
{ "success": false, "error": "Provide at least one of: groupIds, tagIds, or contactIds" }

// 400 — nobody in the audience is opted in, not deleted and on the template's channel
{ "success": false, "error": "No opted-in contacts found in the selected audience" }

// 409 — send: true, but WhatsApp API access is off for the number (the campaign is still saved as a DRAFT)
{
  "success": false,
  "error": "WhatsApp API is OFF for this number. The connected token cannot access this WhatsApp Business Account (expired token, missing permissions, or the WABA was removed). Reconnect WhatsApp from Settings → WhatsApp Channels, then try again. You can still save drafts.",
  "code": "META_API_OFF"
}

curl -X POST https://payperwa.com/api/v1/campaigns \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 120 \
  -d '{
    "name": "March Sale",
    "templateId": "YOUR_TEMPLATE_ID",
    "contactIds": ["CONTACT_ID_1", "CONTACT_ID_2"],
    "variables": { "1": "name", "2": "20%", "3": "MARCH20" },
    "send": true
  }'
# Sent only if the response has "status": "SENDING"

Wallet / Balance

Check your current wallet balance. Amounts are in your wallet's currency, INR or USD, given in currency. The wallet pays only the PayPerWA fee (₹0.20 per message on INR wallets, $0.004 on USD wallets). Meta bills its own fee to your WhatsApp Business Account's payment method, so that fee never comes out of this balance.

Permission: balance:read

// Response
{
  "success": true,
  "data": {
    "balance": 4520.6,
    "currency": "INR"
  }
}

balance is a JSON number with up to 4 decimal places (e.g. 12.3456 on a USD wallet). An account with no wallet yet returns 0 and "INR".

Example

curl https://payperwa.com/api/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

PayPerWA can POST a signed JSON event to your server when a customer messages you, when WhatsApp reports a message as delivered, read or failed, when you send a message through the API, and when a campaign finishes.

Add an Endpoint

• Go to Dashboard → Settings → API → Webhook Events, enter your endpoint URL and tick the events it should receive. Webhooks are managed in the dashboard only; there is no API endpoint for them.
• The URL must start with https://. You can add up to 5 endpoints, and each one receives its events for all of your WhatsApp numbers.
• Each endpoint has its own signing secret: whsec_ followed by 48 hex characters. Reveal or copy it on the Webhooks page at any time.
• You can pause, resume or delete an endpoint. Its URL and events can't be edited: to change them, or to get a new secret, delete the endpoint and add it again.

Webhook Payload

Every event is a POST with the same JSON envelope: event (the event name), timestamp (when PayPerWA sent it, ISO 8601 UTC) and data, whose fields are camelCase. To match an event to a message you sent, compare data.wamid with the message_id returned by POST /api/v1/messages/send.

// message.sent: a template sent with POST /api/v1/messages/send
{
  "event": "message.sent",
  "timestamp": "2026-11-09T10:15:00.214Z",
  "data": {
    "messageId": "c644e8be-cf13-4b2f-887a-76e6ad45ac2d",
    "campaignId": null,
    "contactPhone": "+919876543210",
    "contactName": "Asha",
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNEQ5RTI3QjA3RjE0RDBBNzAA",
    "status": "sent",
    "templateName": "otp_login",
    "sentFrom": "api",
    "sentAt": "2026-11-09T10:15:00.198Z"
  }
}

// message.delivered: the same message, delivered
{
  "event": "message.delivered",
  "timestamp": "2026-11-09T10:15:02.418Z",
  "data": {
    "messageId": "c644e8be-cf13-4b2f-887a-76e6ad45ac2d",
    "campaignId": null,
    "contactPhone": "+919876543210",
    "contactName": "Asha",
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNEQ5RTI3QjA3RjE0RDBBNzAA",
    "status": "delivered",
    "sentFrom": "api",
    "errorCode": null,
    "errorMessage": null,
    "sentAt": null,
    "deliveredAt": "2026-11-09T10:15:01.000Z",
    "readAt": null,
    "failedAt": null
  }
}

// message.failed: a campaign message WhatsApp could not deliver
{
  "event": "message.failed",
  "timestamp": "2026-11-09T10:40:12.903Z",
  "data": {
    "messageId": "05cf4de6-9776-46be-8320-8881182cc050",
    "campaignId": "9724bf78-6e9f-4872-b7c4-e0da86c325e2",
    "contactPhone": "+919812345678",
    "contactName": "Ravi",
    "wamid": "wamid.HBgMOTE5ODEyMzQ1Njc4FQIAERgSMjQxQUIzQzRENUU2RjcwODkA",
    "status": "failed",
    "errorCode": "131049",
    "errorMessage": "This message was not delivered to maintain healthy ecosystem engagement.",
    "failedAt": "2026-11-09T10:40:11.000Z"
  }
}

// message.received: a customer messaged you
{
  "event": "message.received",
  "timestamp": "2026-11-09T10:20:44.031Z",
  "data": {
    "from": "+919876543210",
    "contactName": "Asha",
    "type": "text",
    "content": "Is my order shipped?",
    "wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgUM0E4RkQ2QjYyQjVGMzQ5MkE0RDQA",
    "messageId": "84c440c1-f964-4ee3-aa72-e396931d884c",
    "conversationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "channelId": "1e2d3c4b-5a69-4788-9a0b-c1d2e3f4a5b6"
  }
}

// campaign.completed
{
  "event": "campaign.completed",
  "timestamp": "2026-11-09T11:02:10.775Z",
  "data": {
    "campaignId": "9724bf78-6e9f-4872-b7c4-e0da86c325e2",
    "campaignName": "Diwali Offer",
    "totalMessages": 1000,
    "sentCount": 980,
    "deliveredCount": 951,
    "readCount": 402,
    "failedCount": 20
  }
}

Events

Event Data Fields

Status events are message.sent, message.delivered, message.read and message.failed. Which fields appear depends on where the message came from, so read them defensively and ignore fields you don't know.

Request Headers

Verifying Webhooks

Compute an HMAC-SHA256 of the raw request body (the exact bytes received, before any JSON parsing) with your endpoint's secret as the key, put sha256= in front of the hex digest, and compare it with the X-PayPerWA-Signature header using a constant-time comparison. Use the whole secret, including whsec_, as the key; don't strip or decode it. Reply 401 if it doesn't match. Only the body is signed, so to stop replayed requests, check the body's timestamp (for example, refuse events older than 5 minutes) and skip events you have already handled.

# Test your endpoint: send it a correctly signed sample event.
SECRET='whsec_your_webhook_secret'
BODY='{"event":"message.delivered","timestamp":"2026-11-09T10:15:02.418Z","data":{"messageId":"c644e8be-cf13-4b2f-887a-76e6ad45ac2d","campaignId":null,"contactPhone":"+919876543210","contactName":"Asha","wamid":"wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSNEQ5RTI3QjA3RjE0RDBBNzAA","status":"delivered","sentFrom":"api","errorCode":null,"errorMessage":null,"sentAt":null,"deliveredAt":"2026-11-09T10:15:01.000Z","readAt":null,"failedAt":null}}'
SIG="sha256=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')"

curl -i https://your-server.com/webhooks/payperwa \
  -H "Content-Type: application/json" \
  -H "User-Agent: PayPerWA-Webhooks/1.0" \
  -H "X-PayPerWA-Event: message.delivered" \
  -H "X-PayPerWA-Timestamp: $(date +%s)" \
  -H "X-PayPerWA-Signature: $SIG" \
  --data-binary "$BODY"

The cURL tab signs a sample event with your secret and sends it to your endpoint, so you can test your receiver.

Delivery, Timeouts and Retries

• Each event is sent once to every active endpoint subscribed to it. Any 2xx response within 8 seconds counts as delivered.
• Failed deliveries are not retried. If your endpoint times out, returns another status or can't be reached, that event is lost, and the dashboard keeps no delivery log. Reply 200 first and do slow work in the background. Campaign totals can be read again at any time with GET /api/v1/campaigns.
• Register the exact final URL. A 301 or 302 redirect turns the request into a GET without a body, and the event is lost.
• Events can arrive out of order, and a status can be skipped: if WhatsApp's read report is processed before its delivered report, you get only message.read. Treat sent → delivered → read as moving forward only, and failed as final.
• Events that happen while an endpoint is paused are not queued or sent later.

Error Codes

Errors return "success": false and a human-readable error. Many also carry a fixed code. Base your handling on the HTTP status and code, not on the wording of error. Validation errors add a details object keyed by field.

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "to": ["Too small: expected string to have >=10 characters"]
  }
}

Permissions

Every key created in Dashboard → Settings → API has all seven permissions below. The dashboard has no option to narrow them. If a key lacks the permission an endpoint needs, the request gets 403 with Missing required permission: <permission>.