Webhooks - FinCode Platform

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

Event	Trigger
`TRANSACTION_STATUS`	A payout transaction reaches a terminal status (PAID, FAILED, or CANCELLED)
`COMPLIANCE_RISK_PROFILE_UPDATED`	A customer’s compliance profile is updated following an identity verification (IDV) result or an AML screening decision

TRANSACTION_STATUS

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

How It Works

Set up your webhook callback URL in the dashboard. This is the HTTPS endpoint where we will send event notifications as they occur.

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.

We send a POST request

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

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

Field	Type	Description
`eventType`	String	Type of event. Currently `TRANSACTION_STATUS`.
`Reference`	String	Unique transaction reference (PCN). Encrypted if encryption is enabled.
`Status`	String	Transaction status: `PAID`, `FAILED`, or `CANCELLED`.
`msgNote`	String	Human-readable description of the event.
`msgCode`	String	Status code from the processing provider.

Transaction Details

Field	Type	Description
`transactionId`	String	Internal transaction identifier.
`amountSent`	Number	Amount sent by the sender.
`amountReceived`	Number	Amount to be received by the beneficiary.
`totalAmount`	Number	Total charged amount (sending amount + commission + VAT).
`transactionDate`	String	ISO 8601 timestamp of when the transaction was created.
`sendingCurrencyCode`	String	Currency of the sending amount (e.g., `GBP`).
`receivingCurrencyCode`	String	Currency of the receiving amount (e.g., `NGN`).
`bankName`	String	Destination bank name.
`deliveryMethod`	String	How the funds are delivered (e.g., `ACCOUNTPAYMENT`, `CASHPICKUP`, `MOBILE_MONEY`).
`beneficiaryAccountNumber`	String	Beneficiary’s bank account number.
`beneficiaryAccountHoldersName`	String	Name on the beneficiary’s bank account.
`beneficiaryFullName`	String	Full name of the beneficiary.
`beneficiaryEmail`	String	Beneficiary’s email address.
`beneficiaryAddress`	String	Beneficiary’s address.
`sortCode`	String	Bank sort code (where applicable).
`bankCode`	String	Bank code.
`countryTo`	String	Destination country name.
`transactionType`	String	Transaction type (e.g., `ACCOUNTPAYMENT`, `CASHPICKUP`).
`paymentType`	String	Payment method used (e.g., `CARD`).
`accountType`	String	Beneficiary account type (e.g., `SAVINGS_ACCOUNT`).
`customer`	String	Sender’s customer ID.
`compliant`	Boolean	Whether the transaction passed compliance checks.
`complianceCheck`	String	Compliance check result.
`sanctionFlagColor`	String	Sanction screening flag colour.

Example Webhook Payload

Successful Transaction (PAID)

{
  "eventType": "TRANSACTION_STATUS",
  "Reference": "PCN-12345",
  "Status": "PAID",
  "msgNote": "Transaction completed successfully",
  "msgCode": "00",
  "transactionId": "txn-abc-123",
  "amountSent": 500.00,
  "amountReceived": 450.00,
  "totalAmount": 525.50,
  "transactionDate": "2026-02-16T18:58:55.000+00:00",
  "sendingCurrencyCode": "GBP",
  "receivingCurrencyCode": "NGN",
  "bankName": "Access Bank",
  "deliveryMethod": "ACCOUNTPAYMENT",
  "beneficiaryAccountNumber": "0123456789",
  "beneficiaryAccountHoldersName": "John Doe",
  "beneficiaryFullName": "John Doe",
  "beneficiaryEmail": "john@example.com",
  "beneficiaryAddress": "123 Lagos Street, Lagos",
  "sortCode": "123456",
  "bankCode": "044",
  "countryTo": "Nigeria",
  "transactionType": "ACCOUNTPAYMENT",
  "paymentType": "CARD",
  "accountType": "SAVINGS_ACCOUNT",
  "customer": "cust-xyz-789",
  "compliant": true,
  "complianceCheck": "PASSED",
  "sanctionFlagColor": "GREEN"
}

Failed Transaction

{
  "eventType": "TRANSACTION_STATUS",
  "Reference": "PCN-67890",
  "Status": "FAILED",
  "msgNote": "Insufficient funds",
  "msgCode": "0030",
  "transactionId": "txn-def-456",
  "amountSent": 1000.00,
  "amountReceived": 900.00,
  "totalAmount": 1050.00,
  "transactionDate": "2026-02-16T20:30:00.000+00:00",
  "sendingCurrencyCode": "GBP",
  "receivingCurrencyCode": "NGN",
  "bankName": "GTBank",
  "deliveryMethod": "ACCOUNTPAYMENT",
  "beneficiaryFullName": "Jane Smith",
  "countryTo": "Nigeria"
}

Cancelled Transaction

{
  "eventType": "TRANSACTION_STATUS",
  "Reference": "PCN-11111",
  "Status": "CANCELLED",
  "msgNote": "Transaction cancelled by operator",
  "msgCode": "00",
  "transactionId": "txn-ghi-789",
  "amountSent": 250.00,
  "amountReceived": 225.00,
  "totalAmount": 265.00,
  "transactionDate": "2026-02-17T10:15:00.000+00:00",
  "sendingCurrencyCode": "GBP",
  "receivingCurrencyCode": "KES",
  "deliveryMethod": "MOBILE_MONEY",
  "beneficiaryFullName": "Alex Mwangi",
  "countryTo": "Kenya"
}

Status Values

Status	Description
`PAID`	Transaction successfully paid out.
`FAILED`	Transaction failed to process.
`CANCELLED`	Transaction was cancelled.

Common msgCode Values

Code	Description	Details
`00`	Success	Transaction completed.
`0000`	Pending	Transaction is being processed.
`0030`	Insufficient Funds	Not enough balance.
`0031`	Invalid Account	Account not found.
`0099`	Unknown Error	Generic processing error.

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)

app.post('/webhook/notify', async (req, res) => {
  const event = req.body;

  if (!event.eventType || !event.Reference || !event.Status) {
    return res.status(400).json({ error: 'Missing required fields' });
  }

  const alreadyProcessed = await db.webhookEvents.findOne({
    reference: event.Reference
  });

  if (alreadyProcessed) {
    return res.status(200).json({ status: 'already_processed' });
  }

  res.status(200).json({ status: 'received' });

  try {
    switch (event.Status) {
      case 'PAID':
        await markTransactionAsPaid(event);
        break;
      case 'FAILED':
        await markTransactionAsFailed(event);
        break;
      case 'CANCELLED':
        await markTransactionAsCancelled(event);
        break;
    }

    // store to prevent duplicate processing
    await db.webhookEvents.insert({
      reference: event.Reference,
      eventType: event.eventType,
      status: event.Status,
      processedAt: new Date(),
      payload: event
    });
  } catch (error) {
    console.error('Error processing webhook:', error);
  }
});

Example Implementation (Java / Spring Boot)

@RestController
@RequestMapping("/webhook")
public class WebhookController {

    @PostMapping("/notify")
    public ResponseEntity<Map<String, String>> handleWebhook(@RequestBody Map<String, Object> event) {
        String reference = (String) event.get("Reference");
        String status = (String) event.get("Status");
        String eventType = (String) event.get("eventType");

        if (reference == null || status == null || eventType == null) {
            return ResponseEntity.badRequest()
                .body(Map.of("error", "Missing required fields"));
        }

        if (webhookEventRepository.existsByReference(reference)) {
            return ResponseEntity.ok(Map.of("status", "already_processed"));
        }

        switch (status) {
            case "PAID":
                transactionService.markAsPaid(reference, event);
                break;
            case "FAILED":
                transactionService.markAsFailed(reference, event);
                break;
            case "CANCELLED":
                transactionService.markAsCancelled(reference, event);
                break;
        }

        webhookEventRepository.save(new WebhookEvent(reference, eventType, status));

        return ResponseEntity.ok(Map.of("status", "received"));
    }
}

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

Field	Type	Description
`eventType`	String	Always `COMPLIANCE_RISK_PROFILE_UPDATED`
`userId`	String	Unique identifier of the customer
`firstName`	String	Customer’s first name
`lastName`	String	Customer’s last name
`email`	String	Customer’s email address
`phone`	String	Customer’s phone number
`complianceDecision`	String	Current compliance decision: `APPROVED`, `UNDER_REVIEW`, or `REJECTED`
`riskLevel`	String	Current risk level: `LOW`, `MEDIUM`, or `HIGH`
`currentRiskScore`	Number	Current proven risk score
`maximumPotentialRiskScore`	Number	Maximum possible risk score based on the active configuration
`currentRiskScoreRatio`	Number	Ratio of current risk to maximum potential risk (0 to 1)
`currentTrustScore`	Number	Accumulated trust score from passed checks
`relativeMaximumRisk`	Number	Remaining unknown risk (negative means fully proven)
`sanctionsMatch`	Boolean	`true` if the customer matched a sanctions list entry
`pepMatch`	Boolean	`true` if the customer was identified as a Politically Exposed Person
`adverseMediaMatch`	Boolean	`true` if adverse media results were found
`adverseMediaCount`	Number	Number of adverse media hits
`documentVerificationStatus`	String	Status of document verification: `VERIFIED`, `PENDING`, `FAILED`
`fullNameMatch`	Boolean	`true` if the name on the document fully matched the registered name
`partialNameMatch`	Boolean	`true` if the name was a partial match
`nameMatchPercentage`	Number	Percentage similarity between the document name and the registered name
`didNotMatchSignUpName`	Boolean	`true` if the document name did not match the sign-up name
`sourceOfFundsVerified`	Boolean	`true` if source of funds has been verified
`status`	String	Current customer account status
`kycLastUpdateDate`	String	ISO 8601 timestamp of the last KYC update
`defaultIdentificationDocument`	Object	Most recently verified identity document (see below)
`complianceApprovalHistories`	Array	Ordered list of all compliance scoring events (see below)
`customerKycVerificationRecordEntity`	Array	List of all KYC requirements and their current completion state (see below)

defaultIdentificationDocument

Field	Type	Description
`documentNumber`	String	The document’s reference number
`identificationType`	String	Document type, e.g. `PASSPORT`, `DRIVING_LICENSE`, `NATIONAL_ID_CARD`

complianceApprovalHistories

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

Field	Type	Description
`checkCategory`	String	The check that produced this entry, e.g. `Sanctions`, `PEP (Politically Exposed Person)`, `Face Match`, `KYC Rule: 04`
`scoreType`	String	Whether this entry added to risk or trust: `RISK` or `TRUST`
`complianceScore`	Number	Points applied. Negative = risk added; positive = trust earned
`complianceStatus`	String	Outcome of this check: `APPROVED`, `UNDER_REVIEW`, `PENDING_VERIFICATION`
`riskLevel`	String	Risk level at the time of this entry
`reason`	String	Human-readable description of why this entry was created
`createdDate`	String	ISO 8601 timestamp of when this entry was created
`updatedDate`	String	ISO 8601 timestamp of when this entry was last updated

customerKycVerificationRecordEntity

Each entry represents one KYC requirement assigned to the customer.

Field	Type	Description
`id`	String	The KYC record ID — this is the `associatedRuleId` to pass when uploading documents
`actionType`	String	Type of requirement, e.g. `VERIFY_ACCOUNT_VIA_EKYC`, `ADDRESS_PROOF`, `VERIFY_ACCOUNT_VIA_PHONE_NUMBER`
`idType`	String	Document type required, if applicable (e.g. `ADDRESS_PROOF`)
`complianceDecision`	String	Compliance decision for this specific rule: `APPROVED`, `UNDER_REVIEW`, `REJECTED`
`restriction`	String	Action taken if this rule is outstanding: `BLOCK`
`executed`	Boolean	`true` if this requirement has been completed
`expired`	Boolean	`true` if this requirement has expired
`executionDate`	String	ISO 8601 timestamp of when the requirement was completed
`creationDate`	String	ISO 8601 timestamp of when the requirement was assigned
`ruleExpiredDate`	String	ISO 8601 timestamp of when this rule expired, if applicable
`idRequired`	Boolean	`true` if an identity document is required for this rule
`idRequiredCompleted`	Boolean	`true` if the identity document requirement has been fulfilled
`addressProofRequired`	Boolean	`true` if proof of address is required for this rule
`addressProofRequiredCompleted`	Boolean	`true` if the proof of address requirement has been fulfilled
`sourceOfIncomeRequired`	Boolean	`true` if proof of source of income is required for this rule
`sourceOfIncomeRequiredCompleted`	Boolean	`true` if the source of income requirement has been fulfilled

complianceDecision Values

Value	Meaning
`APPROVED`	Customer has passed all required checks and is cleared to transact
`UNDER_REVIEW`	One or more checks returned a partial or uncertain result — manual review is pending
`REJECTED`	Customer has failed one or more checks and is blocked from transacting

Example Payload

{
  "eventType": "COMPLIANCE_RISK_PROFILE_UPDATED",
  "userId": "00000000-0000-0000-0000-000000000001",
  "firstName": "John",
  "lastName": "Smith",
  "email": "john.smith@example.com",
  "phone": "447000000000",
  "complianceDecision": "UNDER_REVIEW",
  "riskLevel": "HIGH",
  "currentRiskScore": 18,
  "maximumPotentialRiskScore": 154,
  "currentRiskScoreRatio": 0.12,
  "currentTrustScore": 170,
  "relativeMaximumRisk": -16,
  "sanctionsMatch": false,
  "pepMatch": false,
  "adverseMediaMatch": false,
  "adverseMediaCount": 0,
  "documentVerificationStatus": "VERIFIED",
  "fullNameMatch": true,
  "partialNameMatch": false,
  "nameMatchPercentage": 85.0,
  "didNotMatchSignUpName": false,
  "sourceOfFundsVerified": false,
  "status": "PENDING",
  "kycLastUpdateDate": "2026-01-15T10:30:00.000+00:00",
  "defaultIdentificationDocument": {
    "documentNumber": "AB123456",
    "identificationType": "PASSPORT"
  },
  "complianceApprovalHistories": [
    {
      "checkCategory": "Sanctions",
      "scoreType": "TRUST",
      "complianceScore": 25,
      "complianceStatus": "APPROVED",
      "riskLevel": "HIGH",
      "reason": "Sanctions",
      "createdDate": "2026-01-15T10:30:00.000+00:00"
    },
    {
      "checkCategory": "PEP (Politically Exposed Person)",
      "scoreType": "TRUST",
      "complianceScore": 20,
      "complianceStatus": "APPROVED",
      "riskLevel": "HIGH",
      "reason": "PEP (Politically Exposed Person)",
      "createdDate": "2026-01-15T10:30:00.000+00:00"
    },
    {
      "checkCategory": "KYC Rule: 04",
      "scoreType": "RISK",
      "complianceScore": -10,
      "complianceStatus": "UNDER_REVIEW",
      "riskLevel": "HIGH",
      "reason": "New KYC Rule added: 04",
      "createdDate": "2026-01-15T09:00:00.000+00:00"
    }
  ],
  "customerKycVerificationRecordEntity": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "actionType": "VERIFY_ACCOUNT_VIA_EKYC",
      "restriction": "BLOCK",
      "executed": true,
      "expired": false,
      "executionDate": "2026-01-15T10:30:00.000+00:00",
      "creationDate": "2026-01-15T09:00:00.000+00:00"
    },
    {
      "id": "00000000-0000-0000-0000-000000000002",
      "actionType": "ADDRESS_PROOF",
      "idType": "ADDRESS_PROOF",
      "restriction": "BLOCK",
      "executed": false,
      "expired": false,
      "creationDate": "2026-01-15T09:00:00.000+00:00"
    },
    {
      "id": "00000000-0000-0000-0000-000000000003",
      "actionType": "VERIFY_ACCOUNT_VIA_PHONE_NUMBER",
      "restriction": "BLOCK",
      "executed": false,
      "expired": false,
      "creationDate": "2026-01-15T09:00:00.000+00:00"
    }
  ]
}

​Overview

​Webhook Events

​TRANSACTION_STATUS

​How It Works

​Event Structure

​Required Fields

​Transaction Details

​Example Webhook Payload

​Successful Transaction (PAID)

​Failed Transaction

​Cancelled Transaction

​Status Values

​Common msgCode Values

​Retry Strategy

​Handling Webhooks

Respond quickly

Be idempotent

Verify the source

Handle all statuses

​Example Implementation (Node.js)

​Example Implementation (Java / Spring Boot)

​COMPLIANCE_RISK_PROFILE_UPDATED

​Payload Fields

​defaultIdentificationDocument

​complianceApprovalHistories

​customerKycVerificationRecordEntity

​complianceDecision Values

​Example Payload

Overview

Webhook Events

TRANSACTION_STATUS

How It Works

Event Structure

Required Fields

Transaction Details

Example Webhook Payload

Successful Transaction (PAID)

Failed Transaction

Cancelled Transaction

Status Values

Common msgCode Values

Retry Strategy

Handling Webhooks

Example Implementation (Node.js)

Example Implementation (Java / Spring Boot)

COMPLIANCE_RISK_PROFILE_UPDATED

Payload Fields

defaultIdentificationDocument

complianceApprovalHistories

customerKycVerificationRecordEntity

complianceDecision Values

Example Payload