💳 What is a payment?

A payment is a transfer of funds from one bank account to another, initiated by an organisation. There are two key types:

Payable: represents a single payment request (e.g. “invoice #123”).
Pay Run: batches multiple payables (like payroll or supplier payouts) to be authorised in a single flow.

Each entity has its own unique ID for easy tracking.

🛠️ Pay run creation

You can create a pay run by calling the POST /organisations/organisationId/pay-runs endpoint.

On creation attempt the endpoint returns any validation errors or warnings, which you can display to users for correction. For error the pay run will not be created. For warnings the pay run will be created but with warnings.

Both errors and warnings should be surfaced to the end-user so they can be corrected.

Draft mode

Initially, pay runs and the payables are created in draft mode and contain have a partnerEntityId which must be supplied on creation. In draft mode, the same partnerEntityId can still be re-used across other payables and pay runs. In draft mode, pay runs can be discarded and a new one created to correct any issues.

Checking out a pay run

Once the pay run is ready to be finalised, it can be "checked out" using Crezco's hosted payment flow. This changes the state of the pay run to no longer be in draft mode.

💻 Hosted payment (checkout) flow

Crezco provides a hosted checkout flow for securely authorising payments. This uses the banks native secure authorisation mechanism to ensure security and compliance, while preserving your platform’s UX.

GET /organisations/{organisationId}/pay-runs/{payRunId}/checkout

Returns a url to send your user for payment authorisation
User completes SCA via their bank, then is redirected back to your returnUrl.

Why use it?

Quick integration: No need to build SCA flows yourself
Regulatory compliance: PSD2, Open Banking, SCA handled by Crezco
Chaining payments: For banks that don’t support bulk payments, we automatically chain individual authorisations—allowing users to approve each payable one after the other in a single flow

🔗 Understanding Chaining vs Bulk

Not all banks support submitting multiple payables in a single bulk payment authorisation. For those banks, we enable chaining — securing multiple single-payable authorisations back-to-back within the same hosted flow. This ensures a continuous user experience and simplifies implementation across different bank capabilities.

🔁 Flow overview

Create draft pay run with payables and beneficiaries
Validate: surface errors/warnings, allow user to update or discard
Initiate checkout after validation passed
User authorises payment(s) via hosted flow with chaining if needed
Monitor using webhooks like payment.completed, payable.sent, or payment.failed and update your system accordingly

Amounts in currency units

Specify amounts in minor units:

e.g., £10.99 = 1099 pence

Important: Some currencies, like Japanese yen, don’t have decimal fractions (no minor units). Always convert based on the currency’s structure as defined in ISO 4217.

Using `partnerEntityId` to prevent duplicate payments

The partnerEntityId is a unique reference that your platform assigns to a payable or pay run. It should map directly to the underlying entity in your system, for example an invoice, payroll line item, or bill. Crezco uses this identifier to ensure that the same entity cannot be paid twice by mistake.

See Preventing duplicate payments to understand how to make your payment integration robust.

🌍 International Payments

Crezco supports payments in 35+ currencies across** 100+ countries**, offering competitive FX rates

Use cases for this include:

Paying global suppliers
Supporting multi-country payroll
Settling invoices internationally

💸 Fees & Transparency

As a partner of Crezco, you have the flexibility to charge your customer fees.

There are two kinds of fee:

Fixed: This is a flat value, e.g. £0.20 GBP
Variable: This is a percentage of the payable's value - e.g. 0.5%

There are two parties that may charge a fee:

Provider: This is Crezco, charging for running costs and underlying bank network costs
Partner: This is you, charging using the above kinds of fee however you see fit

Fees can be collected by Crezco system to do this we will add a Payable to the Pay Run that represents the full fee amount.

The Payable for the fees can be distinguished by the property "$type": "FeePayable" . It excludes some unnecessary properties such as beneficiary, but you can track the status of this payable like any other to see if fees were successfully paid.