Webhooks

SwitchApp initiates calls to your webhook endpoints to notify you of actions or changes on your profile.

SwitchApp initiates calls to your webhook endpoints configured on your dashboard or provided on the transaction/request body itself. Webhook-enabled actions include payments, top-ups, disbursements, and payouts.

Each webhook call includes an event property that describes the status change. This can be used to configure your system's reaction to the webhook call.

The example below simulates the possible endpoints in a merchant's application for handling SwitchApp webhook calls.

Sample Merchant Payment Webhook Endpoint

Payment webhook events include the following

  • charge.successful
  • charge.partial
  • charge.failed
  • charge.abandoned
  • charge.refunded
  • charge.pending
post
Body
eventstring | nullableOptional
descriptionstring | nullableOptional
Responses
200
Success
post
POST /v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-payments-webhooks HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 3539

{
  "event": "text",
  "description": "text",
  "data": {
    "id": "text",
    "tx_ref": "text",
    "is_live": true,
    "currency": "text",
    "amount": 1,
    "gateway_code": "text",
    "is_webhook_sent": true,
    "is_webhook_confirmed": true,
    "webhook_confirmed_timestamp": "2025-07-05T17:25:27.530Z",
    "is_webhook_failed": true,
    "webhook_failed_count": 1,
    "webhook_retries_count": 1,
    "webhook_resend_request_count": 1,
    "status": "text",
    "device_fingerprint": "text",
    "ip": "text",
    "narration": "text",
    "card_pan": "text",
    "card_issuer": "text",
    "card_country": "text",
    "card_type": "text",
    "card_expiry": "text",
    "bank_trsf_country": "text",
    "bank_trsf_bank_code": "text",
    "bank_trsf_account_number": "text",
    "bank_trsf_swift": "text",
    "bank_trsf_iban": "text",
    "bank_trsf_session_id": "text",
    "source_gateway_merchant_id_or_code": "text",
    "source_gateway_merchant_name": "text",
    "source_gateway_gateway_code": "text",
    "source_gateway_session_id": "text",
    "dedicated_virtual_account_reference": "text",
    "paid_at": "2025-07-05T17:25:27.530Z",
    "metadata": "text",
    "created_at": "2025-07-05T17:25:27.530Z",
    "charged_amount": 1,
    "amount_settled": 1,
    "base_charge": 1,
    "app_fee": 1,
    "merchant_fee": 1,
    "bearer": "text",
    "expected_settlement_date": "2025-07-05T17:25:27.530Z",
    "redirect_url": "text",
    "amount_paid": 1,
    "partial_payment_enabled": true,
    "max_partial_payment_count": 1,
    "partial_payments_count": 1,
    "partial_payments_total": 1,
    "partial_payment_parent_tx_ref": "text",
    "is_child_partial_payment": true,
    "is_amount_modifier_applied": true,
    "title": "text",
    "logo_url": "text",
    "description": "text",
    "customer": {
      "id": "text",
      "full_name": "text",
      "email": "text",
      "phone_number": "text",
      "address": "text"
    },
    "transaction_payout_tags": [
      {
        "id": "text",
        "tagged_bank_account_not_found": true,
        "payout_tag": "text",
        "amount": 1,
        "percentage": 1,
        "app_fee_percentage": 1,
        "description": "text",
        "metadata": "text",
        "created_at": "2025-07-05T17:25:27.530Z"
      }
    ],
    "partial_payments": [
      {
        "id": "text",
        "tx_ref": "text",
        "is_live": true,
        "currency": "text",
        "amount": 1,
        "gateway_code": "text",
        "is_webhook_sent": true,
        "is_webhook_confirmed": true,
        "webhook_confirmed_timestamp": "2025-07-05T17:25:27.530Z",
        "is_webhook_failed": true,
        "webhook_failed_count": 1,
        "webhook_retries_count": 1,
        "webhook_resend_request_count": 1,
        "status": "text",
        "device_fingerprint": "text",
        "ip": "text",
        "narration": "text",
        "card_pan": "text",
        "card_issuer": "text",
        "card_country": "text",
        "card_type": "text",
        "card_expiry": "text",
        "bank_trsf_country": "text",
        "bank_trsf_bank_code": "text",
        "bank_trsf_account_number": "text",
        "bank_trsf_swift": "text",
        "bank_trsf_iban": "text",
        "bank_trsf_session_id": "text",
        "source_gateway_merchant_id_or_code": "text",
        "source_gateway_merchant_name": "text",
        "source_gateway_gateway_code": "text",
        "source_gateway_session_id": "text",
        "dedicated_virtual_account_reference": "text",
        "paid_at": "2025-07-05T17:25:27.530Z",
        "metadata": "text",
        "created_at": "2025-07-05T17:25:27.530Z",
        "charged_amount": 1,
        "amount_settled": 1,
        "base_charge": 1,
        "app_fee": 1,
        "merchant_fee": 1,
        "bearer": "text",
        "expected_settlement_date": "2025-07-05T17:25:27.530Z",
        "redirect_url": "text",
        "amount_paid": 1,
        "partial_payment_enabled": true,
        "max_partial_payment_count": 1,
        "partial_payments_count": 1,
        "partial_payments_total": 1,
        "partial_payment_parent_tx_ref": "text",
        "is_child_partial_payment": true,
        "is_amount_modifier_applied": true,
        "title": "text",
        "logo_url": "text",
        "description": "text",
        "customer": {
          "id": "text",
          "full_name": "text",
          "email": "text",
          "phone_number": "text",
          "address": "text"
        }
      }
    ],
    "amount_modifiers": [
      {
        "id": "text",
        "reference": "text",
        "type": "discount",
        "tx_ref": "text",
        "amount": 1,
        "description": "text",
        "metadata": "text",
        "created_at": "2025-07-05T17:25:27.530Z",
        "edited_at": "2025-07-05T17:25:27.530Z"
      }
    ]
  }
}
200

Success

No content

Sample Merchant Top-Up Webhook Endpoint

Top-up webhook events include the following

  • topup.successful
post
Body
eventstring | nullableOptional
descriptionstring | nullableOptional
Responses
200
Success
post
POST /v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-topups-webhooks HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1248

{
  "event": "text",
  "description": "text",
  "data": {
    "id": "text",
    "tx_ref": "text",
    "is_live": true,
    "currency": "text",
    "amount": 1,
    "gateway_code": "text",
    "is_webhook_sent": true,
    "is_webhook_confirmed": true,
    "webhook_confirmed_timestamp": "2025-07-05T17:25:27.530Z",
    "is_webhook_failed": true,
    "webhook_failed_count": 1,
    "webhook_retries_count": 1,
    "webhook_resend_request_count": 1,
    "status": "text",
    "device_fingerprint": "text",
    "ip": "text",
    "narration": "text",
    "card_pan": "text",
    "card_issuer": "text",
    "card_country": "text",
    "card_type": "text",
    "card_expiry": "text",
    "bank_trsf_country": "text",
    "bank_trsf_bank_code": "text",
    "bank_trsf_account_number": "text",
    "bank_trsf_swift": "text",
    "bank_trsf_iban": "text",
    "bank_trsf_session_id": "text",
    "source_gateway_merchant_id_or_code": "text",
    "source_gateway_merchant_name": "text",
    "source_gateway_gateway_code": "text",
    "source_gateway_session_id": "text",
    "dedicated_virtual_account_reference": "text",
    "paid_at": "2025-07-05T17:25:27.530Z",
    "metadata": "text",
    "created_at": "2025-07-05T17:25:27.530Z",
    "wallet_account_tags": [
      {
        "id": "text",
        "tagged_bank_account_not_found": true,
        "account_tag": "text",
        "amount": 1,
        "description": "text",
        "metadata": "text",
        "created_at": "2025-07-05T17:25:27.530Z"
      }
    ],
    "charged_amount": 1,
    "amount_settled": 1,
    "base_charge": 1,
    "app_fee": 1
  }
}
200

Success

No content

Sample Merchant Disbursement Webhook Endpoint

Disbursement webhook events include the following

  • transfer.successful

  • transfer.failed

  • transfer.awaitingAuthorization

  • transfer.authorizationFailed

post
Body
eventstring | nullableOptional
descriptionstring | nullableOptional
Responses
200
Success
post
POST /v1/sample-switchapp-merchant-webhooks/sample-v1-switchapp-transfers-webhooks HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1023

{
  "event": "text",
  "description": "text",
  "data": {
    "id": "text",
    "wallet_account_tags": [
      {
        "id": "text",
        "tagged_bank_account_not_found": true,
        "account_tag": "text",
        "amount": 1,
        "description": "text",
        "metadata": "text",
        "created_at": "2025-07-05T17:25:27.530Z"
      }
    ],
    "is_live": true,
    "gateway_code": "text",
    "is_reversed": true,
    "transfer_failed_count": 1,
    "is_webhook_sent": true,
    "is_webhook_confirmed": true,
    "webhook_confirmed_timestamp": "2025-07-05T17:25:27.530Z",
    "is_webhook_failed": true,
    "webhook_failed_count": 1,
    "webhook_retries_count": 1,
    "webhook_resend_request_count": 1,
    "reference": "text",
    "source_currency": "text",
    "currency": "text",
    "country": "text",
    "amount": 1,
    "transfer_fee": 1,
    "description": "text",
    "status": "text",
    "transfer_type": "text",
    "account_number": "text",
    "account_name": "text",
    "bank_name": "text",
    "bank_code": "text",
    "destination_gateway_merchant_id": "text",
    "destination_gateway_merchant_name": "text",
    "destination_gateway_name": "text",
    "destination_gateway_code": "text",
    "paid_at": "2025-07-05T17:25:27.530Z",
    "created_at": "2025-07-05T17:25:27.530Z"
  }
}
200

Success

No content

Last updated