Base URL:
https://{domain}.fincode.software/api/v6/services/Replace {domain} with the subdomain assigned to your organisation.Before You Begin
1
Your agent account is created
Once your commercial agreement is signed, our support team creates an agent account for your organisation and emails you the login credentials.
2
Log in to the agent portal
Use the credentials from that email to log in. From here you can configure plugins, view transactions, and manage your integration.
- Non-interactive mode
- Interactive mode
Use this mode for system-to-system integration where your backend books transactions directly on behalf of senders, without the sender being present.A cashier user authenticates on your backend, then calls
Set Up Your Cashier Account
1
Create a cashier (teller) account
From within your agent portal, create an automated cashier account. Some teams call this a teller account, it’s the same thing. This is separate from your own agent login.
2
Authenticate as the cashier to get your token
Call
PUT securitymanagement/login with the cashier account’s credentials, not your agent login, to obtain the token used for every call in this section. See Authentication.create-transaction in a single request with the sender, beneficiary, and any required KYC documents all embedded in the payload.Step 1 - Get Organisation Compliance Policy
Before booking, call this endpoint to retrieve your organisation’s KYC and AML requirements. The compliance policy tells you which documents and fields you must embed in thecreate-transaction request for the sender. The policy includes:- Document verification requirements (passport, national ID, proof of address)
- Transaction limits and thresholds
- Identity verification methods
- AML/KYC screening requirements
- Geographic and delivery method restrictions
Step 2 - Book Transfer with Embedded KYC
Authenticate as a cashier user and callcreate-transaction with everything embedded. This endpoint reduces the number of API calls required from sign-up to booking. It allows you to combine sender creation, beneficiary creation, and KYC document submission into a single call.We recommend calling customer-compliance-checklist before create-transaction so you can identify and submit any outstanding compliance requirements inline.Sender options
Include exactly one of the following in your request:- New sender - include the sender’s personal details (name, email, phone, address, etc.) in
newSenderKyc. The platform creates the customer record. To reuse this sender in later bookings, pass their customer code aspreExistingSenderCustomerCode. - Existing sender - include
preExistingSenderCustomerCodewith the sender’s previously assigned code. All sender fields are resolved from the existing record.
Beneficiary options
Include exactly one of the following:- New beneficiary - include the recipient’s details in
newRecipientKyc(name, phone, address, destination country, etc.). - Existing beneficiary - include the beneficiary’s previously assigned code in
preExistingRecipientCustomerCodeto reuse an existing record.
creditParty as lowercase key-value pairs. See Create Transaction for the full field reference.Embedding KYC documents
Use theeligibleDocumentList field to attach any KYC documents required by the compliance policy. Each entry includes the document type and the base64-encoded file. Pass associatedRuleId for each document to link it to the correct compliance rule.The response returns a serverCorrelationId (the transaction UUID) and an objectReference (the payment reference number, or PCN) for use in subsequent payment and status calls. It also returns preExistingSenderCustomerCode and preExistingRecipientCustomerCode. Store these codes and reuse them for later transactions with the same customers.Recovering a customer with a correlation ID
When you create a new sender or recipient, send your own unique ID innewSenderKyc.correlationId or newRecipientKyc.correlationId. If the create transaction call times out or the network fails before you receive the response, look the customer up with that ID instead of creating them again.Headers:
X-Auth-Token, uuid, platform. Allowed roles: AGENTS, CASHIER, MANAGER. To look up several customers at once, separate the IDs with commas.Each customer in the response includes code, userProfileId, firstName, middleName, lastName, email, phone and correlationId. Use code as preExistingSenderCustomerCode or preExistingRecipientCustomerCode in your next create transaction call.Only customers created with a
correlationId can be found this way.Step 3 - Process Payment (Optional)
If the transaction requires a payment link (for example, open banking or card), call this endpoint with the PCN from Step 2 (theobjectReference value) to retrieve available payment methods and generate a hosted payment URL.Call this endpoint once per transaction. Each call returns a new
paymentIntentId. Pass the objectReference value from the create-transaction response as the pcn.Step 4 - Check Transfer Status
Pass the
objectReference value from the create-transaction response as the {pcn} path parameter. Subscribe to webhook notifications to receive automatic status updates without polling.Summary
1
Get compliance policy
GET compliance/list-organisation-compliance-policy2
Book transfer with embedded KYC
POST transactionmanagement/create-transaction - include sender (new or existing), beneficiary (new or existing), and any required documents in a single call using a cashier token.3
Process payment (if required)
POST paymentmanagement/supported-payment-methods4
Track status
Poll
checktransactionstatus or subscribe to webhooksSupported 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.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.
