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

url

string

required

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

events

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.

description

string

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

Response

status

boolean

true when the subscription was created.

message

string

"Webhook subscription created successfully".

data

object

The created subscription.

Show Subscription object

string

Unique subscription ID (UUID).

url

string

The registered endpoint URL.

events

string[]

Event types this subscription listens to.

active

boolean

Whether the subscription is currently active.

description

string

Human-readable description, if provided.

createdAt

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"
  }
}

List subscriptions

Retrieve all webhook subscriptions for your merchant account.

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

Query parameters

page

number

default:"1"

Page number for pagination.

limit

number

default:"10"

Number of records per page.

activeOnly

boolean

default:"false"

When true, only returns active subscriptions.

Response

status

boolean

true when the request succeeded.

data

object[]

Array of subscription objects.

metadata

object

Pagination metadata.

Show Pagination

page

number

Current page.

limit

number

Records per page.

total

number

Total number of matching subscriptions.

totalPages

number

Total pages.

availableEvents

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"
  }
}

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

url

string

New HTTPS endpoint URL.

events

string[]

Updated list of event types to subscribe to.

description

string

Updated description.

active

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

data

object

Hide Settings object

webhookMode

string

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

callbackURL

string

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

sandboxCallbackURL

string

Sandbox callback URL. null if not set.

availableModes

object[]

Descriptions of each available mode.

Show Mode object

value

string

Mode identifier: LEGACY, SUBSCRIPTIONS, or BOTH.

label

string

Human-readable label.

description

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

webhookMode

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"
  }
}

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

eventType

string

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

Response

success

boolean

true when your endpoint returned a 2xx HTTP status.

statusCode

number

The HTTP status code your endpoint returned.

responseTime

number

Round-trip response time in milliseconds.

message

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"
  }
}

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"
  }
}

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

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