API Guide
Log In
API Guide
Start typing to search…

Quickstart guide

Follow the steps to get started and make your first payment with Crezco!

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 Sandbox API key. To get this you can submit a request to [email protected].

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 [email protected] 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.

Request URL

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

Example request

{
  "companyName": "organisation-name",
  "partnerClientId": "your-reference-id",
  "users": [
    {
      "userId": "example-user-id",
      "email": "[email protected]",
      "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.

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 sandbox environment would be as follows

GET https://api.partners.sandbox.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"
}

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.

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.

Request URL

POST https://api.partners.sandbox.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:

  1. Listening to the statuses through webhook events
  2. 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 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 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.

Example request url

POST https://api.partners.sandbox.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