Get started in 4 simple steps

This guide takes you through the basics of making payments in 4 steps. For more specific use cases you can read our guides and recipes below:

Domestic payments
International payments
Bill payments
Payroll
Single payments
Bulk payments

1. Get access and authorise 🔐

To use the Crezco API you will initially need a API key to our test environment (UAT). To get this you can submit a request to support@crezco.com.

Once you have been issued with your API key you can start testing the API safely without interacting with real banks or risk sending real money.

Authentication to the Crezco API is performed via HTTP Bearer Auth. Provide your API key as the token value: Authorization: Bearer YOUR_API_KEY

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Once you are ready to make utilise the Crezco API on production you can reach out to support@crezco.com and we will issue you with a production API key.

2. Create an organisation 🏢

This is the resource that represents your customer. You will reference them in Crezco's product using an OrganisationId it's worth storing this in your own system mapped to the ID for your customer.

Organisations are foundational to managing your users and pay-runs. To create an organisation call our POST /organisations endpoint. Create Organisation

Request URL

POST https://api.partners.uat.crezco.com/organisations

Example request

{
  "companyName": "organisation-name",
  "partnerClientId": "your-reference-id",
  "users": [
    {
      "userId": "example-user-id",
      "email": "user-email@crezco.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "Admin"
    }
  ]
}

For more information see our guide on creating an organisation.

3. Connect a bank account 🏦

After creating an organisation you’ll need to connect a bank account to them. This allows the organisation to make payments from this bank accounts to beneficiaries.

To improve the developer experience and speed up integrations Crezco provide a hosted user flow that allows the user to connect their bank account.

To access the URL for this hosted flow you can call the GET /organisations/{organisationId}/connect endpoint. Connect

Return URLs

Add a returnURL to redirect the user back to your application after completing the flow.

Request URL

The following GET request will respond with a link to the bank connection flow. At the end of the bank connection flow the user will be redirected to the returnUrl you specified in the request. For example to send users to https://your-application-url.com your request on the UAT environment would be as follows

GET https://api.partners.uat.crezco.com/organisations/{some-organisation-id}/connect?returnUrl=https://your-application-url.com

Example response

{
  "url": "https://your-platform-name.flows.crezco.com/connections/1234"
}

📘
In Crezco's test environment, select Crezco Sandbox GB simulated bank for testing without a real bank account.

4. Create a pay run 💰

Once an organisation has successfully connected a bank account, they can create a pay run. This is a collection of payments the user that is acting on behalf of that organisation would like to make at that point in time. Create pay run

A pay run needs to contain a valid payerBankAccountId corresponding to one of the bank accounts available via GET - Organisation Bank Accounts. Pay runs should also contain beneficiary bank account details for each constituent payable.

📘
In Crezco's test environment, select the bank account ID belonging to the Crezco Sandbox GB simulated bank account that you connected earlier, to test payments without moving real money.

Request URL

POST https://api.partners.uat.crezco.com/organisations/{some-organisation-id}/pay-run

Example request

{
  "partnerEntityId": "Your-PayRun-ID1",
  "partnerClientId": "Your-Unique-ID",
  "scheduledExecutionDate": "2023-02-01",
  "payerBankAccountId": "Bank-Account-ID",
  "payables": [
    {
      "partnerEntityId": "Your-Payable-ID1",
      "amount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 1275
      },
      "reference": "My-Ref-1234",
      "beneficiary": {
        "bankAccount": {
          "accountRoutingName": "Test Company 1 LTD",
          "country": "GB",
          "gbSortCode": "12-34-56",
          "gbAccountNumber": "12345678"
        }
      }
    },
    {
      "partnerEntityId": "Your-Payable-ID2",
      "amount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 2005
      },
      "reference": "My-Ref-1235",
      "beneficiary": {
        "bankAccount": {
          "accountRoutingName": "Test Company 1 LTD",
          "country": "GB",
          "gbSortCode": "12-34-56",
          "gbAccountNumber": "12345678"
        }
      }
    },
    {
      "partnerEntityId": "Your-Payable-ID3",
      "amount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 1050
      },
      "reference": "My-Ref-1235",
      "beneficiary": {
        "bankAccount": {
          "accountRoutingName": "Test Company 2 LTD",
          "country": "GB",
          "gbSortCode": "65-43-21",
          "gbAccountNumber": "87654321"
        }
      }
    }
  ]
}

Example response

You will receive back a 201 response with a PayRunId. You'll need this for checking out the pay run to initiate the payment(s) and track payable statuses.

{
  "payRunId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organisationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "partnerEntityId": "Your-Unique-ID",
  "scheduledExecutionDate": "2023-07-17",
  "payerBankAccountId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "payables": [
    {
      "$type": "Payable",
      "payableId": "abd61eb8-a6fc-4251-949e-da62732e1f12",
      "partnerEntityId": "payable-5",
      "recipientAmount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 1
      },
      "endUserTotalCostAmount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 1,
        "isEstimated": false
      },
      "currencyConversion": null,
      "fees": null,
      "beneficiary": {
        "address": null,
        "bankAccount": {
          "country": "GB",
          "accountCurrency": "GBP",
          "accountRoutingName": "Crezco",
          "gbSortCode": "123456",
          "gbAccountNumber": "12345679"
        }
      },
      "promotion": null,
      "fundingAmount": {
        "currencyCode": "GBP",
        "amountInMinorUnits": 1,
        "isEstimated": false
      },
      "reference": "ref-1",
      "isLowPriority": false,
      "failureInsights": null,
      "reversedAmount": null,
      "status": "Draft"
    }
  ],
  "groups": [
    {
      "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "status": "Unknown",
      "partnerEntityId": "Your-Unique-ID",
      "partnerPayableIds": [
        {
          "payableId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "partnerEntityId": "Your-Unique-ID"
        }
      ],
      "reference": "My-Ref-1234"
    }
  ],
  "batches": [
    {
      "batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "paymentOrder": 0,
      "status": "Unknown",
      "groups": [
        {
          "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "partnerEntityId": "Your-Unique-ID"
        }
      ],
      "payables": [
        {
          "payableId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "partnerEntityId": "Your-Unique-ID"
        }
      ]
    }
  ],
  "status": "Unknown",
  "checkoutUri": "string"
}

A note on statuses

Pay runs and payables have different statuses that they can go through. These can be accessed and tracked by either:

Listening to the statuses through webhook events
Fetching the statuses of the pay run

5) Checkout a pay run 🛍️

To initiate the payment of a pay run you must call the GET Checkout endpoint Checkout with the PayRunId returned above. This will initialise a new payment workflow and return the final checkout URL to which the user must be redirected, allowing the payer to begin the payment workflow

A completeUrl must be set which specifies where the user will be sent following confirmed successful completion of the pay run.

Additionally, an incompleteUrl must be set which specifies where the user will be sent following unsuccessful completion of the pay run, or when the payer's bank takes more than a few seconds to process the payments.

Example request url

POST https://api.partners.uat.crezco.com/organisations/{some-organisation-id}/pay-run/{some-pay-run-id}/checkout?completeUrl=https://some-success-url.com&incompleteUrl=https://some-unsuccessful-url.com

Example response

{
  "url": "https://some-pay-run-checkout-url.com"
}

Once the user has completed the payment flow then congratulations, your users have made their first embedded payment on your platform!