Entities

While building to Crezco’s API, there are a set of core objects you’ll interact with:

🏢 Organisation

Represents your customer’s business within Crezco. Each organisation gets a unique OrganisationId, which you’ll use to track payments and activity.

👤 User

These are the users associated with each organisation.

💳 Payable

An individual payment that the customer would like to make. Each payable has a unique payableId, allowing for easy tracking and reconciliation.

📦 Pay Run

A group of payments your customer (an organisation) would like to make at a single point in time. Grouping payables together allows your customers to minimise the amount of times they need to authorise the payments, ideal for payroll, supplier payouts and bulk disbursements

🔔 Webhooks

Real-time notifications to keep your platform updated on payment events, ensuring your system always has the latest information.

Key concepts

There are a number of other essential concepts that are represented in the API, that we use specific language for in order to be as clear as possible:

💻 Hosted flows

Hosted flows are secure, Crezco-managed user interfaces for essential interactions like bank connections, verification, and payment approvals. By redirecting users to Crezco-hosted pages, you simplify integration, enhance security, and maintain regulatory compliance.

Each flow can be fully themed to match your branding, ensuring a cohesive and professional user experience.

Benefits of hosted flows

Easy integration: Minimal development effort, as Crezco manages the UI and compliance complexities.
Secure and compliant: Meets regulatory standards like Strong Customer Authentication (SCA) and Open Banking.
Consistent experience: Provides users with reliable, frictionless interactions across your platform.

Typical use cases

Hosted flows are particularly suited for:

Quickly connecting users' bank accounts during onboarding.
Efficiently verifying user identities for KYC purposes.
Securely approving individual or bulk payments.

Available flows

Bank connection flow: Users securely link their bank accounts to enable seamless transactions.
Verification flow: Streamlined identity verification to enhance trust and compliance.
Payment flow: Secure and simple authorisation of payments via Crezco’s hosted checkout.

🛍️ Checkout

The checkout process allows users to approve payments securely through Crezco's hosted payment flow. This uses the strong customer authentication facilitated by your customer's bank to ensures compliance, security, and ease of use, reducing friction in the payment experience for end-users.

🧾 Beneficiaries

A beneficiary is the recipient of a payment. In Crezco's API, each payable specifies a beneficiary, including their bank account details and other necessary information to ensure accurate and secure transactions.

💱 Major units vs minor units

When specifying payment amounts, it's crucial to distinguish between major units and minor units:

Major units: These represent the standard denomination of a currency (e.g., pounds in GBP, euros in EUR).
Minor units: These represent the fractional denomination of a currency (e.g., pence in GBP, cents in EUR).

For example, £10.99 consists of 10 major units and 99 minor units. In the API, amounts are typically represented in minor units to avoid rounding errors. Therefore, £10.99 would be represented as 1099 minor units. Not all currencies have a 100 unit based minor currency and some don't have a minor currency at all. You can find out more about variations between currencies on our International Payments Guide.

💸 Fees

Crezco offers a transparent fee structure to keep your costs predictable. We also allow you to configure your own fee structure on top. While domestic payments may have minimal or no fees, cross-border transactions could incur additional charges. You can configure your application to either absorb these fees or pass them on to the end-users, depending on your business model.

For detailed information on fees and how to manage them within the API, refer to our Collecting Fees Guide

Idempotency

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide the following header:

Idempotency-Key: {KEY}

An idempotency key is a unique value generated by the client which the server uses to recognise subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys can be up to 255 characters long.

Keys are eligible to be removed from the system automatically after they're at least 24 hours old. All POST requests accept idempotency keys. Sending idempotency keys in GET and DELETE requests has no effect and should be avoided, as these requests are idempotent by definition.