Build your integration
Connect your bank's systems to Quant Flow, track settlement and reconcile the outcome.
Start with the system you are connecting
Quant Flow provides the token operations and controls behind your bank's deposit and payment workflows. Your integration connects those capabilities to your existing systems; your core banking system remains the book of record. Your bank decides when a booked deposit should be represented by tokens and when tokens should be redeemed.
The platform architecture shows the gateway, token engine, policy engine, custody service and ledger. For implementation, organise your adapter around three responsibilities:
| Responsibility | Your integration does | Quant Flow provides |
|---|---|---|
| Submit instructions | Complete bank-side checks, choose customer and account references, retain a business reference and send an idempotent request. | Customer and account registries, token operations and configured control checks. |
| Track outcomes | Retain the returned identifiers, process signed events and read progress when needed. | Operation states, settlement outcomes, webhook delivery and audit evidence. |
| Reconcile | Compare confirmed operations and settled balances with the bank's records; investigate exceptions. | Transaction history, balances, outstanding breaks and delivery history. |
Keep gateway credentials and custody configuration in backend services. For roles, permissions and key ownership, read Identities and entitlements and Security and key management.
Choose the workflows your adapter will own
A useful first integration is one currency, one customer, two token accounts and a complete issuance-to-redemption cycle. This exercises provisioning, supply changes, payments and reconciliation without making PayScript a prerequisite.
For example, your bank books a 100.00 GBP deposit and issues the matching tokens to account A. A confirmed transfer of 25.00 GBP credits account B without changing token supply. Redeeming 10.00 GBP from B burns those tokens; only after that burn confirms does your bank pay out the corresponding cash. Your adapter must retain the bank instruction and the platform operation for each step so it can explain both the customer position and the outstanding token liability.
Add controls around that flow in stages. Configure independent users and approval groups, test the policy-enabled path, then connect signed outcome events. Add PayScript when you need the platform to decide when an instruction should run. It uses the token-operation capabilities; it does not take over your bank's deposit ledger or cash postings.
| Decision before implementation | Why it matters |
|---|---|
| Which currencies and accounts will be supported? | Each account holds one asset; each asset needs an active contract and configured custody. |
| Which system initiates each instruction? | Your backend needs a durable business reference and idempotency key before submission. |
| Which actions require a person? | API permissions, business-policy approval and custody signing are separate controls. |
| When does your application show a payment as complete? | Acceptance, approval and signing are intermediate facts; settlement requires the final operation outcome. |
| Who investigates an uncertain outcome? | A lost response or delayed event must enter recovery and reconciliation rather than create another instruction. |
The sections below implement this sequence. For feature-specific details, use the feature index.
Establish the environment and access
Arrange your organisation, gateway, users, machine credentials, network and custody configuration through Get access and Before you begin. Use the organisation assigned to that environment; an account reference from a different organisation is not interchangeable.
For the user-based Quickstart, use POST /api/auth/login and follow Authenticate. A response can contain tokens or a first-sign-in challenge. Complete a challenge before making protected requests. For a bank backend, follow the machine-client flow in Authentication; its token endpoint belongs to the deployment's identity provider, and the deployment-specific details still need confirmation during onboarding.
Every protected request carries a bearer access token and API-Version: 1.0.0. Keep refresh credentials and machine secrets out of browser code and source control. Begin with a read such as GET /api/users/me to check the calling identity. A successful login proves authentication; it does not prove entitlement to every operation or readiness of the settlement infrastructure.
Prepare the asset, customer and account
| Step | Guide | API connection | Ready when |
|---|---|---|---|
| Check the asset's contract | Instruments and tokenised deposits | GET /api/contracts | The intended asset has an ACTIVE contract. |
| Deploy if required | Before you begin | POST /api/contracts | Deployment is confirmed and the contract is ACTIVE. |
| Register the customer | Create a customer and an account | POST /api/customers | The customer reference is registered and usable. |
| Register the token account | Create a customer and an account | POST /api/accounts | Provisioning completes; GET /api/accounts/{accountRef} reports ACTIVE. |
Use your own stable customerRef and accountRef values and retain their mapping to the bank's records. A customer can have multiple accounts, so a token operation names an account rather than a customer. Account provisioning is asynchronous: its initial 202 and PENDING status are not readiness to transact.
Before token submission, have the platform operator confirm the active signing-key registration for your organisation and asset, custody readiness and the required contract roles. These are operational prerequisites; account provisioning alone does not verify them. See Security and key management.
Contract deployment needs the administrator address and configured custody and network infrastructure. It is a setup operation, not something to repeat before each mint. Read the endpoint's duplicate-asset and idempotency rules before deploying.
Submit a token operation and retain its identity
Follow Issue tokens for a mint or Make a transfer for a movement between accounts. Both use POST /api/transactions. Use Request examples for cURL, JavaScript and Python, and the linked API Reference for request schemas and generated samples.
Before submission, retain the business instruction and a unique idempotency key in durable storage. Send amounts as decimal strings in currency units, with the currency's supported precision. Keep the same key and request when retrying after a connection failure; creating a new key can create another operation. See Amounts, currencies and precision and Idempotency and retries.
When the call returns, retain its transactionId alongside your business reference. A 202 is acceptance. It does not prove approval, signing or settlement. Contract deployment and account controls also return operation identifiers, but use their own endpoints: POST /api/contracts and POST /api/accounts/{accountRef}/controls.
Follow settlement and handle approval
Read GET /api/transactions/{transactionId} until the operation reaches a terminal state, or use signed events to learn its outcome. Implement the full state handling described in Operations and their lifecycle: an operation may be awaiting policy, approval, signing or ledger confirmation.
| Outcome | Your integration's next action |
|---|---|
CONFIRMED | Record the settled outcome, retain any reported transaction hash and block number, and reconcile. |
FAILED | Retain failureCode and any reasonCode, then follow Handle failures. |
CANCELLED | Record the cancelled outcome and stop waiting for settlement. |
| Any non-terminal state | Continue tracking. Alert on a prolonged wait; a timeout in your client is not a failed operation. |
Policy behaviour depends on the environment's configuration. Do not infer that an approval rule is enforced just because a demo mint succeeded. Confirm policy enablement and the judged operation types, then test the intended approval and rejection paths with authorised users. Policy, approvals and audit explains the controls; GET /api/approvals/tasks and POST /api/approvals/tasks/{taskId}/approve connect them to the API. The approver acts with their own user token and cannot approve their own initiation.
Receive events and recover missed deliveries
Follow Receive your first webhook to register a publicly routable HTTPS destination with POST /api/webhooks. Test delivery using POST /api/webhooks/{id}/test. Verify the signature against the exact request bytes before processing an event, and handle duplicate deliveries as described in Webhooks.
Persist the event before acknowledging it and keep your handler separate from slow business processing. Use GET /api/webhook-events to investigate delivery, and POST /api/webhook-events/{id}/redeliver to request a redelivery. If a notification is missing, read the operation's current state; do not submit a replacement instruction merely because an event did not arrive.
Reconcile and operate the integration
After confirmation, read settled balances with GET /api/accounts/{accountRef}/balances. Reconcile operation history from GET /api/transactions against your bank's records using Reconcile against your core banking. Reconciliation must account for operations still in flight, rather than treating every submission as settled value.
Use GET /api/transactions/breaks for exceptions and GET /api/audit/events for activity evidence. Preserve the correlation between business reference, idempotency key, operation identifier and any ledger identifiers. See Audit and evidence for retention and export considerations.
Check readiness before going live
Use the Quickstart as a first integration exercise, then test the paths your application relies on: lost-response retries, token expiry, insufficient permissions, provisioning delays, policy approval and rejection, failed settlement, duplicate webhook delivery and missed-event recovery. Record the request, status and resulting state for each test without retaining credentials in the report.
The API Reference is the published contract; an example response is not evidence that an environment has passed that test. A successful balance read is not a complete mint test, and a confirmed mint does not prove transfer, redemption or an enabled approval policy. Confirm your environment's capabilities and the unresolved deployment details in Limitations before agreeing production readiness.
Hand over the integration to operations
Use Production readiness to record the environment, signing/access checks, workflow tests and operating agreement. Give the support team the durable instruction journal and sanitised escalation format.
Use Daily operations and monitoring for exceptions, Maintenance and recovery for preserving pending work, and Access changes and offboarding for retirement. Recovery targets and missing action/signing specifications need owner confirmation before independent production implementation.
Implement and maintain the adapter
Implement a backend client turns this integration sequence into server-side JavaScript: identity check, customer/account provisioning, token submission, bounded outcome reads, balance reads and administrative changes. Persist each business instruction and its idempotency key before submission, then store the returned transaction ID. Keep submission, outcome processing and reconciliation as separate jobs so a restart or delayed webhook does not submit the same intent twice.
Your application owns its durable store and business-side authorization. Quant Flow owns the operation state reported by its API. Process signed webhook deliveries idempotently and use API reads to recover missing events; make bank-side booking decisions from confirmed outcomes and reconciliation evidence.
Use the developer integration coverage map to find the guide and contract-derived code for every API area. Treat team administration, automation and policy authoring as capabilities to select for your integration, rather than compulsory steps for every payment.
When your integration changes, review the published endpoint contract and its workflow guide together. Repeat affected acceptance tests, preserve existing instruction identifiers and confirm deployment-specific configuration and operating responsibilities before production sign-off.
Updated 2 days ago