Skip to main content

​
Overview

This page explains the webhook feature and how to configure it. To start receiving webhook events, you need to set up a single URL endpoint that accepts POST requests. This endpoint should be hosted on a server you control and able to handle the incoming webhook payloads. All webhook events generated by the Paywint such as initiated, processing, success, failed, and rejected— will be sent to the configured URL.

​
Where To Setup

​
Sandbox

Use the Sandbox environment to test your webhook setup before moving to production.
  1. Create a Sandbox Account:
    Sign up for a Sandbox account to start testing your integration.
  2. Get API Key:
    Go to the Sandbox Merchant Panel → Settings → API Key section to generate your Sandbox API key.
  3. Configure Webhook URLs:
    In the Sandbox Merchant Panel → Settings → Redirect/Webhook section, you’ll find fields to enter your test endpoint:
    • Webhook URL:
      The endpoint that receives specific event webhooks for payment status updates (e.g., payment.success, payment.failed).
      Example: https://example.com/webhook

​
Production

Once your Sandbox testing is complete, you can move to the Production environment. Before enabling your Production setup, please contact our support team to ensure your API and webhook configurations are properly activated.
  1. Create a Production Account:
    Sign up for a Production account.
  2. Enable Production Access:
    Contact our support team to request activation of your Production API and webhook setup.
  3. Get API Key:
    Go to the Sandbox Merchant Panel → Settings → API Key section to obtain your Production API key.
  4. Configure Webhook URLs: In the Sandbox Merchant Panel → Settings → Redirect/Webhook section, enter your live endpoint:
  • Webhook URL:
    The live endpoint that receives real-time event webhooks.
    Example: https://yourapp.com/webhook
  1. Support Contacts:
    If you need assistance during setup:

​
Available Event Types

Below is the complete list of webhook events sent by Paywint.

​
KYC Events

Event NameDescription
kyc.appliedUser has submitted KYC details.
kyc.approvedKYC verification has been approved.
kyc.rejectedKYC verification has been rejected.
kyc.failedKYC verification has failed.
kyc.completedKYC process is completed.
kyc.deletedKYC record has been deleted.

​
KYB Events

Event NameDescription
kyb.approvedKYB verification has been approved.
kyb.rejectedKYB verification has been rejected.
kyb.deletedKYB record has been deleted.

​
Wallet Funding Events

Event NameDescription
wallet.funding.initiatedWallet funding request initiated.
wallet.funding.processingWallet funding is in progress.
wallet.funding.successWallet funding was successful.
wallet.funding.failedWallet funding failed.
wallet.funding.rejectedWallet funding request rejected.

​
Wallet Withdrawal Events

Event NameDescription
wallet.withdrawal.initiatedWallet withdrawal initiated.
wallet.withdrawal.processingWallet withdrawal is in progress.
wallet.withdrawal.settlingWallet withdrawal is being settled.
wallet.withdrawal.successWallet withdrawal was successful.
wallet.withdrawal.failedWallet withdrawal failed.
wallet.withdrawal.rejectedWallet withdrawal was rejected.

​
Card Events

Event NameDescription
card.addedA new card has been added.
card.images_uploadedCard images have been uploaded.

​
Payment Events

Event NameDescription
payment.initiatedPayment was initiated.
payment.processingPayment is being processed.
payment.settlingPayment is being settled.
payment.successPayment was successful.
payment.failedPayment failed.
payment.rejectedPayment was rejected.
payment.refundedPayment was refunded.
payment.fee_refundedPayment fee was refunded.

​
Basic Structure

FieldDescription
eventThe type of event that occurred (e.g., kyc.applied).
idA unique identifier for this webhook delivery.
dataThe event-specific payload object.
eventGeneratedTimeUNIX timestamp (in seconds) when the event was generated.
Example payload: 
{
  "event": "kyc.applied",
  "id": "a891bfc2-ffff-464b-89e4-xxxxx",
  "data": {
    // Event-specific payload
  },
  "eventGeneratedTime": 1718006400.0
}

​
Delivery & Retry Behavior

If your webhook endpoint fails to return a 2xx HTTP response, Paywint will automatically retry delivery up to two more times, for a total of three attempts per event.
  • Retries are sent within a predefined timeframe.
  • If all attempts fail, Paywint will notify your account’s admin email with details of the failed event.
Note: To avoid missed events, ensure your webhook endpoint is highly available and returns 200 OK quickly. Any internal processing should happen asynchronously to avoid missed events.

​
Detailed Webhook Responses

For complete webhook payload examples and detailed field descriptions for each event type, see our Webhook Responses documentation page.

Webhook Responses

View detailed webhook payload examples, field descriptions, and implementation guidance for all payment events.