💳 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).

Special rule: You cannot reuse the same partnerEntityId across different pay runs or payables—unless they’re still in draft mode. Reusing across final runs or payables would result in validation errors or duplication issues.

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