Subscriptions

Webhook subscriptions let you register HTTPS endpoints that TagPay calls whenever specific events occur in your account. Each subscription can listen to one or more event types, and you can manage them independently without changing your existing callback URL configuration.

Before subscriptions take effect, make sure your webhook mode is set to SUBSCRIPTIONS or BOTH. See Get webhook settings below.

Create a subscription

POST https://api.tagpay.ng/v1/merchant/webhook/subscribe

Request body

string

required

The HTTPS URL TagPay will POST events to. Must be a publicly reachable endpoint. HTTP URLs are not accepted in production.

string[]

required

Array of event type strings to subscribe to. At least one event is required. Use ["*"] to subscribe to all events. See Event Types for the full list.

string

Optional human-readable label for the subscription, useful when managing multiple endpoints.

Response

boolean

true when the subscription was created.

string

"Webhook subscription created successfully".

object

The created subscription.

Show Subscription object

string

Unique subscription ID (UUID).

string

The registered endpoint URL.

string[]

Event types this subscription listens to.

boolean

Whether the subscription is currently active.

string

Human-readable description, if provided.

string

ISO 8601 creation timestamp.

curl --request POST \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscribe" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "wallet.credit", "wallet.debit"],
    "description": "Production webhook endpoint"
  }'

{
  "status": true,
  "message": "Webhook subscription created successfully",
  "data": {
    "id": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "wallet.credit", "wallet.debit"],
    "active": true,
    "description": "Production webhook endpoint",
    "createdAt": "2024-04-01T10:00:00.000Z"
  }
}

{
  "status": false,
  "message": "Webhook URL is required"
}

{
  "status": false,
  "message": "At least one event type is required",
  "availableEvents": ["transaction.success", "transaction.failed", "wallet.credit", "..."]
}

List subscriptions

Retrieve all webhook subscriptions for your merchant account.

GET https://api.tagpay.ng/v1/merchant/webhook/subscriptions

Query parameters

number

default:"1"

Page number for pagination.

number

default:"10"

Number of records per page.

boolean

default:"false"

When true, only returns active subscriptions.

Response

boolean

true when the request succeeded.

object[]

Array of subscription objects.

object

Pagination metadata.

Show Pagination

number

Current page.

number

Records per page.

number

Total number of matching subscriptions.

number

Total pages.

string[]

Complete list of available event types for reference.

curl --request GET \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscriptions?page=1&limit=10" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Subscriptions retrieved successfully",
  "data": [
    {
      "id": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
      "url": "https://example.com/webhooks/tagpay",
      "events": ["transaction.success", "wallet.credit"],
      "active": true,
      "description": "Production webhook endpoint",
      "createdAt": "2024-04-01T10:00:00.000Z"
    }
  ],
  "metadata": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "totalPages": 1
  },
  "availableEvents": ["transaction.success", "transaction.failed", "wallet.credit", "wallet.debit", "..."]
}

Get a subscription

Retrieve a single subscription by its ID.

GET https://api.tagpay.ng/v1/merchant/webhook/subscription/:id

Path parameters

string

required

The UUID of the subscription.

curl --request GET \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscription/sub_e5f6a7b8-c9d0-1234-efab-567890123456" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Subscription retrieved successfully",
  "data": {
    "id": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "wallet.credit"],
    "active": true,
    "description": "Production webhook endpoint",
    "createdAt": "2024-04-01T10:00:00.000Z"
  }
}

{
  "status": false,
  "message": "Subscription not found"
}

Update a subscription

Modify an existing subscription’s URL, events, description, or active status.

PUT https://api.tagpay.ng/v1/merchant/webhook/subscription/:id

Path parameters

string

required

The UUID of the subscription to update.

Request body

string

New HTTPS endpoint URL.

string[]

Updated list of event types to subscribe to.

string

Updated description.

boolean

Set to false to pause deliveries to this subscription without deleting it.

curl --request PUT \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscription/sub_e5f6a7b8-c9d0-1234-efab-567890123456" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "events": ["transaction.success", "transaction.failed", "wallet.credit", "wallet.debit"],
    "active": true
  }'

{
  "status": true,
  "message": "Subscription updated successfully",
  "data": {
    "id": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "transaction.failed", "wallet.credit", "wallet.debit"],
    "active": true,
    "description": "Production webhook endpoint",
    "updatedAt": "2024-04-02T09:00:00.000Z"
  }
}

Delete a subscription

Permanently remove a webhook subscription. In-flight deliveries for this subscription will not be retried.

DELETE https://api.tagpay.ng/v1/merchant/webhook/subscription/:id

Path parameters

string

required

The UUID of the subscription to delete.

curl --request DELETE \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscription/sub_e5f6a7b8-c9d0-1234-efab-567890123456" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Subscription deleted successfully"
}

Get webhook settings

Retrieve your current webhook delivery mode and configured callback URLs.

GET https://api.tagpay.ng/v1/merchant/webhook/settings

Response

object

Hide Settings object

string

Current delivery mode. One of LEGACY, SUBSCRIPTIONS, or BOTH.

string

Production callback URL configured in your merchant profile. null if not set.

string

Sandbox callback URL. null if not set.

object[]

Descriptions of each available mode.

Show Mode object

string

Mode identifier: LEGACY, SUBSCRIPTIONS, or BOTH.

string

Human-readable label.

string

Explanation of what this mode does.

curl --request GET \
  --url "https://api.tagpay.ng/v1/merchant/webhook/settings" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Webhook settings retrieved successfully",
  "data": {
    "webhookMode": "LEGACY",
    "callbackURL": "https://example.com/legacy-webhook",
    "sandboxCallbackURL": "https://sandbox.example.com/legacy-webhook",
    "availableModes": [
      {
        "value": "LEGACY",
        "label": "Legacy Only",
        "description": "Send webhooks only to the callback URL configured in your profile"
      },
      {
        "value": "SUBSCRIPTIONS",
        "label": "Subscriptions Only",
        "description": "Send webhooks only to your webhook subscriptions (ignore callback URL)"
      },
      {
        "value": "BOTH",
        "label": "Both (Recommended for Migration)",
        "description": "Send webhooks to both callback URL and matching subscriptions"
      }
    ]
  }
}

Update webhook settings

Change the webhook delivery mode for your merchant account.

PUT https://api.tagpay.ng/v1/merchant/webhook/settings

Request body

string

required

The delivery mode to activate. Must be one of:

LEGACY — deliver only to your profile’s callback URL.
SUBSCRIPTIONS — deliver only to matching webhook subscriptions.
BOTH — deliver to both the callback URL and matching subscriptions. Use this during migration.

If you are migrating from the legacy callback URL to subscriptions, set the mode to BOTH first. Once you have verified your subscription endpoint is receiving events correctly, switch to SUBSCRIPTIONS.

curl --request PUT \
  --url "https://api.tagpay.ng/v1/merchant/webhook/settings" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "webhookMode": "SUBSCRIPTIONS"
  }'

{
  "status": true,
  "message": "Webhook mode updated to SUBSCRIPTIONS",
  "data": {
    "webhookMode": "SUBSCRIPTIONS"
  }
}

{
  "status": false,
  "message": "Invalid webhook mode. Valid options: LEGACY, SUBSCRIPTIONS, BOTH",
  "validModes": ["LEGACY", "SUBSCRIPTIONS", "BOTH"]
}

Send a test event

Immediately deliver a test payload to a subscription endpoint to verify your integration without waiting for a real event.

POST https://api.tagpay.ng/v1/merchant/webhook/test/:id

Path parameters

string

required

The UUID of the subscription to test.

Request body

string

The event type to simulate, e.g. transaction.success. Defaults to test.webhook when omitted.

Response

boolean

true when your endpoint returned a 2xx HTTP status.

number

The HTTP status code your endpoint returned.

number

Round-trip response time in milliseconds.

string

Result description.

curl --request POST \
  --url "https://api.tagpay.ng/v1/merchant/webhook/test/sub_e5f6a7b8-c9d0-1234-efab-567890123456" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "eventType": "transaction.success"
  }'

{
  "status": true,
  "data": {
    "success": true,
    "statusCode": 200,
    "responseTime": 142,
    "message": "Test webhook delivered successfully"
  }
}

{
  "status": true,
  "data": {
    "success": false,
    "statusCode": 404,
    "responseTime": 98,
    "message": "Request failed with status code 404",
    "error": null
  }
}

Replay a failed delivery

Create a new delivery attempt for a previously failed webhook delivery.

POST https://api.tagpay.ng/v1/merchant/webhook/replay/:id

Path parameters

string

required

The UUID of the delivery record to replay. Retrieve delivery IDs from Delivery History.

Response

Returns the newly created delivery record. The new delivery has a reference prefixed with replay-.

curl --request POST \
  --url "https://api.tagpay.ng/v1/merchant/webhook/replay/del_f6a7b8c9-d0e1-2345-fabc-678901234567" \
  --header "Authorization: Bearer <token>"

{
  "status": true,
  "message": "Delivery replayed successfully",
  "data": {
    "id": "del_new1234-d0e1-2345-fabc-678901234999",
    "subscriptionId": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
    "eventType": "transaction.success",
    "status": "pending",
    "attempts": 0,
    "reference": "replay-del_f6a7b8c9-d0e1-2345-fabc-678901234567",
    "createdAt": "2024-04-03T11:00:00.000Z"
  }
}

{
  "status": false,
  "message": "Delivery not found"
}

{
  "status": false,
  "message": "Subscription is not active"
}

Export Transactions

Delivery History

curl --request POST \
  --url "https://api.tagpay.ng/v1/merchant/webhook/subscribe" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "wallet.credit", "wallet.debit"],
    "description": "Production webhook endpoint"
  }'

{
  "status": true,
  "message": "Webhook subscription created successfully",
  "data": {
    "id": "sub_e5f6a7b8-c9d0-1234-efab-567890123456",
    "url": "https://example.com/webhooks/tagpay",
    "events": ["transaction.success", "wallet.credit", "wallet.debit"],
    "active": true,
    "description": "Production webhook endpoint",
    "createdAt": "2024-04-01T10:00:00.000Z"
  }
}

{
  "status": false,
  "message": "Webhook URL is required"
}

{
  "status": false,
  "message": "At least one event type is required",
  "availableEvents": ["transaction.success", "transaction.failed", "wallet.credit", "..."]
}

Wallets

Transfers

Transactions

Webhooks

Create a subscription

Request body

Response

List subscriptions

Query parameters

Response

Get a subscription

Path parameters

Update a subscription

Path parameters

Request body

Delete a subscription

Path parameters

Get webhook settings

Response

Update webhook settings

Request body

Send a test event

Path parameters

Request body

Response

Replay a failed delivery

Path parameters

Response

​Create a subscription

​Request body

​Response

​List subscriptions

​Query parameters

​Response

​Get a subscription

​Path parameters

​Update a subscription

​Path parameters

​Request body

​Delete a subscription

​Path parameters

​Get webhook settings

​Response

​Update webhook settings

​Request body

​Send a test event

​Path parameters

​Request body

​Response

​Replay a failed delivery

​Path parameters

​Response

Create a subscription

Request body

Response

List subscriptions

Query parameters

Response

Get a subscription

Path parameters

Update a subscription

Path parameters

Request body

Delete a subscription

Path parameters

Get webhook settings

Response

Update webhook settings

Request body

Send a test event

Path parameters

Request body

Response

Replay a failed delivery

Path parameters

Response