Agent Integration Guide

This page lists every endpoint your application needs to go live. Work through the sections in order - each section’s output feeds the next.

Base URL: https://{your-domain}.fincode.software/api/v6/services/Replace {your-domain} with the subdomain assigned to your organisation.

Step 1 - Customer Registration

Create a customer record. This is always the first call. The response returns a userId that all subsequent calls depend on.

Method	Path	What it does	Swagger
`POST`	`usermanagement/register-customer` →	Register a new sender	↗
`POST`	`usermanagement/profile` →	Retrieve a sender’s profile	↗

Subscribe to our webhook notifications to receive real-time customer status updates.

Step 2 - Authentication

Obtain a session token. The token is valid for 50 minutes and is shared across all calls within the session.

Method	Path	What it does	Swagger
`PUT`	`securitymanagement/login` →	Obtain a session token	↗
`GET`	`securitymanagement/reset-password/{email}` →	Initiate a password reset	↗
`PUT`	`securitymanagement/change-password` →	Change the authenticated user’s password	↗

Step 3 - KYC & Compliance

When a customer is registered, the platform automatically assigns KYC rules based on their risk profile. Call the checklist endpoint to find out what actions are outstanding before a transaction can be booked.

Method	Path	What it does	Swagger
`GET`	`compliance/list-organisation-compliance-policy` →	Retrieve the KYC and transaction rules configured for the organisation	↗
`PUT`	`compliance/customer-compliance-checklist` →	Retrieve the pre-transaction compliance checklist for a customer	↗

From here, the flow depends on whether you are using the platform’s built-in KYC or your own external KYC provider.

Using built-in KYC
Using your own KYC provider

Initiate each requirement

For each item returned by the compliance checklist, call the initiate endpoint. This triggers the action on the platform side and returns what you need to proceed.

Method	Path	What it does	Swagger
`GET`	`compliance/initiate-awaiting-compliance-action/{customer-kyc-record-id}` →	Trigger a specific pending KYC action	↗

Replace {customer-kyc-record-id} with the ID from the checklist.

Fulfil each requirement

How each action is fulfilled depends on its type.

Email verification

Handled automatically. When you call initiate, the platform sends a branded verification email to the customer. No further API call is needed from your side.

Phone OTP

The platform sends an OTP to the customer via SMS when you call initiate. Your application collects the code from the customer and submits it.

Method	Path	What it does	Swagger
`GET`	`securitymanagement/otp-verification/{email}/{verification-code}` →	Submit the OTP the customer received	↗
`GET`	`securitymanagement/sms-resend-otp/{email}` →	Resend the OTP if the customer did not receive it	↗

Document upload (Proof of Address, ID, Source of Funds)

Your application collects the document from the customer and submits it.

Method	Path	What it does	Swagger
`POST`	`documentmanagement/attach-documents` →	Submit a KYC or AML document	↗

Pass the associatedRuleId from the checklist item in the request body to link the document to the correct rule.

eKYC (electronic identity verification)

The initiation call automatically creates the eKYC session. Follow the flow returned in the initiate response to complete electronic identity verification.

Prerequisites - Plugin setup

Before using your own KYC provider, you must configure it as a plugin on your agent dashboard.

Go to the Plugins section on your dashboard.
Click Create Plugin and enter your provider credentials.
Set the API Type to EXTERNAL KYC PROVIDER.

If your provider handles email and phone verification as part of its identity flow, also enable the following settings to prevent the platform from sending its own verification messages to the customer:

doNotForwardEmailVerification: prevents the platform from sending its own email verification link.
doNotForwardPhoneVerification: prevents the platform from sending its own phone OTP.

Register the eKYC session with the platform

Before initiating verification with your provider, call this endpoint to create a tracking record on the platform side. The platform generates a unique reference and returns it.

Method	Path	What it does	Swagger
`POST`	`compliance/external-provider/initiate` →	Register the eKYC session and obtain a platform reference	↗

Store the reference from the response. Pass it to your KYC provider as the external user identifier so the provider echoes it back in the webhook it sends to the platform.

Configure the webhook callback

Your KYC provider must send its verification result directly to the platform when the customer completes verification. Configure the URL below as the webhook callback in your provider account settings. This is a one-time setup, not per customer.

Method	Path	What it does	Swagger
`POST`	`compliance/external-screening/webhooks/{provider-code}` →	Receives verification results from your KYC provider	↗

Replace {provider-code} with the value that matches your KYC provider (see Supported Providers below).

Initialise verification with your provider

Create the verification session with your KYC provider and embed the reference from the registration step in the field your provider uses for an external reference. The provider will echo this value back in the webhook it sends to the platform on completion.

Listen for the platform webhook

After the platform processes the result, it will POST a webhook to your registered callback URL with:

{
  "eventType": "COMPLIANCE_RISK_PROFILE_UPDATED"
}

Check the customerKycVerificationRecordEntity array in the payload. Any rule with "executed": false is still outstanding and must be fulfilled before the customer can transact.

Fulfil non-eKYC requirements

If your provider also handles email and phone verification, notify the platform after your provider has verified each one:

Method	Path	What it does	Swagger
`POST`	`compliance/external-provider/verify-contact` →	Mark email or phone as verified	↗

Pass userId and type (EMAIL or PHONE_NUMBER). This marks the requirement as fulfilled and triggers the full KYC lifecycle automatically.

When this endpoint is called, the platform also calls your configured KYC provider to independently verify the contact detail. The plugin must be configured before using this endpoint.

If your provider does not handle email and phone verification, fulfil those requirements using the standard flows:

Email verification

Handled automatically. When you call initiate in the registration step, the platform sends a branded verification email to the customer. No further API call is needed.

Phone OTP

The platform sends an OTP via SMS. Your application collects the code and submits it.

Method	Path	What it does	Swagger
`GET`	`securitymanagement/otp-verification/{email}/{verification-code}` →	Submit the OTP the customer received	↗
`GET`	`securitymanagement/sms-resend-otp/{email}` →	Resend the OTP if the customer did not receive it	↗

Document upload

Collect the document and submit it. Pass the associatedRuleId from the checklist item in the request body.

Method	Path	What it does	Swagger
`POST`	`documentmanagement/attach-documents` →	Submit a KYC document	↗

Step 4 - Transaction Quote

Get a live exchange rate and fee breakdown before booking.

Method	Path	What it does	Swagger
`GET`	`services/quote/callQuote` →	Perform a transaction quote	↗

Step 5 - Beneficiary Management

Add and retrieve beneficiaries linked to a sender.

Method	Path	What it does	Swagger
`POST`	`usermanagement/new-beneficiary` →	Add a new beneficiary to a sender’s account	↗
`POST`	`usermanagement/find-all-beneficiery` →	Retrieve all beneficiaries for a sender	↗

Step 6 - Book a Transfer

Both endpoints require an X-Idempotency-Key header to prevent duplicate bookings.

Method	Path	What it does	Swagger
`POST`	`transactionmanagement/create-transaction` →	Book a transfer	↗
`POST`	`transactionmanagement/history-data` →	Look up a booked transfer’s status	↗

The X-Idempotency-Key must be a unique identifier per request. Subscribe to webhook notifications as an alternative to polling the status endpoint.

Step 7 - Pay for a Booked Transfer

Retrieve the available payment methods for a booked transfer and implement the chosen payment flow in your application. Card and Open Banking are both supported.

Method	Path	What it does	Swagger
`POST`	`paymentmanagement/supported-payment-methods` →	List payment methods for a booked transfer	↗

The X-Idempotency-Key must be a unique identifier per request. The pcn must match the one used in the booking call.

Step 8 - Check Transfer Status

Check the current status of a booked transfer by its reference number.

Method	Path	What it does	Swagger
`POST`	`transactionmanagement/checktransactionstatus/{transaction_identification_number}` →	Check the status of a booked transfer	↗

Subscribe to webhook notifications to receive automatic status updates without polling.

AML Compliance

AML checks run at the point of transaction. Any outstanding requirements must be resolved before the transaction can complete. Submit AML-required documents using the same endpoint as KYC documents. Pass the associatedRuleId from the outstanding requirement in the request body.

Method	Path	What it does	Swagger
`POST`	`documentmanagement/attach-documents` →	Submit an AML-required document	↗

Supported KYC Providers

Applies to integrations using your own KYC provider. The following providers are currently supported. Your chosen provider must be configured in your agent plugin settings before use.

Provider	Code
ShuftiPro	`SHUFTI_PRO`
SEON	`SEON_IDV`
SumSub	`SUMSUB`
Didit	`DIDIT`

Technical requirements

Your provider must meet all of the following before we can accept their results:

ID document verification: must be capable of verifying government-issued identity documents (passport, national ID, driving licence).
Liveness check (face match): must perform a biometric face match between the document photo and a live selfie or video capture.
Webhook callback support: must be able to send a webhook to our system when verification is complete.
Correlation ID embedding: must accept and return a reference ID in the webhook payload so the platform can tie the result back to the correct customer record.
Structured result payload: the webhook payload must include verification outcome, document details, and any AML/sanctions/PEP screening results in a structured, parseable format.

Summary

POST usermanagement/register-customer

Authenticate

PUT securitymanagement/login

Complete KYC & compliance

Built-in KYC: initiate each requirement then fulfil it. Your own KYC provider: register the session, configure the webhook, initiate with your provider, and listen for COMPLIANCE_RISK_PROFILE_UPDATED.

Get a quote

GET services/quote/callQuote

Add a beneficiary

POST usermanagement/new-beneficiary

Book the transfer

POST transactionmanagement/create-transaction

Process payment

POST paymentmanagement/supported-payment-methods

Resolve any AML requirements

POST documentmanagement/attach-documents

Track status

Poll checktransactionstatus or subscribe to webhooks

Getting Started

Transaction Core

API Endpoints

Step 1 - Customer Registration

Step 2 - Authentication

Step 3 - KYC & Compliance

Initiate each requirement

Fulfil each requirement

Prerequisites - Plugin setup

Register the eKYC session with the platform

Configure the webhook callback

Initialise verification with your provider

Listen for the platform webhook

Fulfil non-eKYC requirements

Step 4 - Transaction Quote

Step 5 - Beneficiary Management

Step 6 - Book a Transfer

Step 7 - Pay for a Booked Transfer

Step 8 - Check Transfer Status

AML Compliance

Supported KYC Providers

Technical requirements

Summary

​Step 1 - Customer Registration

​Step 2 - Authentication

​Step 3 - KYC & Compliance

​Initiate each requirement

​Fulfil each requirement

​Prerequisites - Plugin setup

​Register the eKYC session with the platform

​Configure the webhook callback

​Initialise verification with your provider

​Listen for the platform webhook

​Fulfil non-eKYC requirements

​Step 4 - Transaction Quote

​Step 5 - Beneficiary Management

​Step 6 - Book a Transfer

​Step 7 - Pay for a Booked Transfer

​Step 8 - Check Transfer Status

​AML Compliance

​Supported KYC Providers

​Technical requirements

​Summary

Step 1 - Customer Registration

Step 2 - Authentication

Step 3 - KYC & Compliance

Initiate each requirement

Fulfil each requirement

Prerequisites - Plugin setup

Register the eKYC session with the platform

Configure the webhook callback

Initialise verification with your provider

Listen for the platform webhook

Fulfil non-eKYC requirements

Step 4 - Transaction Quote

Step 5 - Beneficiary Management

Step 6 - Book a Transfer

Step 7 - Pay for a Booked Transfer

Step 8 - Check Transfer Status

AML Compliance

Supported KYC Providers

Technical requirements

Summary