💳 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 they contain are provided are created in a draft mode. This allows the same partnerEntityId to 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

1. Create draft pay run with payables and beneficiaries
2. Validate: surface errors/warnings, allow user to update or discard
3. Initiate checkout after validation passed
4. User authorises payment(s) via hosted flow with chaining if needed
5. 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

Idempotency

Use Idempotency-Key headers with POST/PUT to prevent duplicate Pay Run or Payable creation (key valid for 24 hours).

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.

Why this matters

Duplicate payments usually occur when multiple users initiate the same payment at the same time, or when the same invoice is added to several pay runs accidently. To prevent this, Crezco enforces strict rules around how a partnerEntityId can be reused.

How Crezco validates partnerEntityId

Crezco will not allow a payable to be created if:

• the same partnerEntityId already exists for the same organisation, and
• that existing payable is not in a terminal cancelled state.

This prevents multiple active payables referencing the same underlying business entity in your system.

The same rules apply across pay runs. A partnerEntityId cannot appear in two separate non draft pay runs and it cannot appear in multiple active payables that would be paid simultaneously.

Draft mode exception

While a pay run is in draft mode, the partnerEntityId can be reused across multiple draft pay runs and draft payables. This helps you support workflows where users may discard, edit, or rebuild a pay run before finalising it.

Once the pay run is checked out, the draft exception no longer applies and the partnerEntityId becomes locked for that payable until it completes or is cancelled.

Terminal cancelled state

A payable is considered safe to reuse only when it has reached a terminal cancelled state.

If the payable is in any other state, including processing, awaiting authorisation, or completed, then its partnerEntityId cannot be reused.

Recommended implementation pattern

For each payable your system creates, map the partnerEntityId to the underlying business entity in your platform. Typical examples include:

• invoice ID or bill ID
• payroll item ID or employee net payment ID
• supplier payment request ID
• reimbursement or expense ID

By mapping one to one between your internal entity and Crezco’s partnerEntityId, you gain automatic protection against:

• duplicated invoices being sent for payment
• two users paying the same payable at the same time
• concurrent pay runs accidentally paying overlapping items
• retry flows accidentally creating a second payable instead of updating the first

Validation behaviour

If an API request attempts to create a payable using a partnerEntityId that already exists in an active state, Crezco will return a validation error. This should be surfaced to your user so they can correct the duplication at source.

If multiple partner users attempt to create the same payable concurrently, Crezco’s validation ensures that only one payable is accepted and the others are rejected, preventing accidental double payments.

🌍 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.