Skip to main content

Overview

Webhooks allow you to receive real-time HTTP notifications when key events occur on the platform. Instead of polling our API for updates, we push the data directly to your server as soon as an event occurs. We send a POST request to the webhook URL you registered with us, containing the full event payload.

Webhook Events

Register Your Webhook URL

Register one callback URL for each event type you want to receive. Each pay center can have one record per event type.

Request Headers

string
required
The JWT Access Token of the authenticated user.
string
default:"fincode"
required
Platform identifier. Use fincode.
string
default:"200"
required
Unique request identifier.

Request Body

string
required
The event to subscribe to: TRANSACTION_STATUS or COMPLIANCE_RISK_PROFILE_UPDATED.
string
required
The HTTPS endpoint on your server that receives the notification.
boolean
Set to true to receive encrypted payloads.
cURL
The response contains the id of the new record. Registering an event type that already has a record returns an error asking you to update it instead. Use update-callback/{id} with the same request body to change an existing record.

TRANSACTION_STATUS

Webhook notifications are sent for terminal transaction statuses: PAID, FAILED, and CANCELLED.

How It Works

1

Register your webhook URL

Set up your webhook callback URL in the dashboard, or register it through the API as described in Register Your Webhook URL above. This is the HTTPS endpoint where we will send event notifications as they occur.
2

A transaction status changes

When a payout transaction reaches a terminal status (PAID, FAILED, or CANCELLED), we build a webhook event with the full transaction details.
3

We send a POST request

Each event is sent individually as a JSON payload via HTTP POST to your registered webhook URL.
4

You acknowledge with 200 OK

Your server must respond with a 200 HTTP status code to confirm receipt. Any other response code triggers a retry.

Event Structure

Each webhook notification is a JSON object with the following fields:

Required Fields

Transaction Details

Example Webhook Payload

Successful Transaction (PAID)

Failed Transaction

Cancelled Transaction

Status Values

Common msgCode Values

Retry Strategy

Your server must respond with a 200 HTTP status code to acknowledge receipt of the webhook. If your server returns any other status code (e.g., 4xx, 5xx) or the request times out, the webhook delivery is considered failed and will be retried.
If your endpoint consistently fails, the message will be retried until the SQS message retention period expires. Ensure your endpoint is reliable and responds promptly.

Handling Webhooks

Respond quickly

Return a 200 status code as fast as possible. Do any heavy processing asynchronously after acknowledging the webhook.

Be idempotent

The same event may be delivered more than once. Use the Reference field to deduplicate and avoid processing the same transaction twice.

Verify the source

See Webhook Security for how to verify that requests are genuinely from our system.

Handle all statuses

Your endpoint should handle PAID, FAILED, and CANCELLED statuses gracefully.

Example Implementation (Node.js)

Example Implementation (Java / Spring Boot)


COMPLIANCE_RISK_PROFILE_UPDATED

This event is fired whenever a customer’s compliance risk profile is updated. It is triggered by two situations:
  • Identity verification (IDV) result — when an eKYC provider returns a decision and our system processes it.
  • AML screening update — when a sanctions, PEP, or adverse media screening produces a new result.
Use this event to keep your own customer records in sync with our compliance decisions without polling.

Payload Fields

defaultIdentificationDocument

complianceApprovalHistories

Each entry represents one compliance scoring event, in chronological order.

customerKycVerificationRecordEntity

Each entry represents one KYC requirement assigned to the customer.

complianceDecision Values

Example Payload