Webhooks

When a program is configured to deliver cards via webhook, iQpay sends a POST request to your configured endpoint with the card activation details and member information.

Webhook endpoints are configured during program setup in the iQpay Admin portal.

Webhook Payload

When an order is created and the program uses webhook delivery, iQpay sends the following payload to your endpoint:

object

Card activation details.

Show Activation code fields

string

The card activation URL to deliver to the member.

string

iQpay generated verification code.

string

Status of the card (empty string).

object

Member details associated with the order.

Show Member fields

string

Member’s first name.

string

Member’s last name.

string

Member’s email address.

string

Member’s mobile number.

string

Sponsor’s external identifier for the member.

string

The sponsor-supplied identifier for tracing, matching the value sent in the Create Order request.

Example Payload

{
  "activation_code": {
    "url": "https://activate.iqpay.com/card/abc123",
    "code": "ACT-789XYZ",
    "status": ""
  },
  "member": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "member@example.com",
    "phone_number": "5551234567",
    "external_id": "EXT-MBR-12345"
  },
  "external_transaction_id": "TXN-2024-00001"
}

Scheduled Orders

When an order includes a processingDate set in the future, the webhook is not sent at the time the order is placed. Instead, iQpay holds the order until the scheduled processing date arrives, then processes the order and sends the webhook payload at that time. The API returns a 200 or 201 response immediately to confirm the order was accepted, but card activation details are only delivered via webhook once the order is actually processed on the scheduled date.

Scenario	Webhook Timing
No `processingDate` (or `null`)	Webhook sent immediately after order creation
`processingDate` set to a future date	Webhook sent on the scheduled date when the order is processed

Response

Your webhook endpoint must return a 200 HTTP status code on success. Any other status code is treated as a failure.

If your webhook fails to respond with 200, the card delivery notification may not be retried automatically. Ensure your endpoint is reliable and handles errors gracefully.

Testing

In the Demo environment, configure a test webhook endpoint (e.g., using a service like webhook.site) to inspect payloads during integration.

Overview

Authentication

Orders

Webhooks

Webhook Payload

Example Payload

Scheduled Orders

Response

Testing

​Webhook Payload

​Example Payload

​Scheduled Orders

​Response

​Testing

Webhook Payload

Example Payload

Scheduled Orders

Response

Testing