API Guide
Log In
API Guide

Create pay run

post
https://api.partners.uat.crezco.com/organisations//pay-runs

Creates a single pay run containing one or more payables scheduled for a given date. All payables within a a pay run are paid from a single payer account. Each payable can be for a different recipient.

This endpoint creates a single pay run containing one or more payables scheduled for a given date. All payables within a pay run are paid from a single payer account. Each payable can be for a different recipient.

📘

Up to 500 payables are supported per pay run.

If you think you will hit this limit, let us know, and we will look to raise it.

Beneficiaries

Every Payable requires a beneficiary object describing the recipient of the payment.

  • $type - Required for international payments, optional for domestic payments. Value should be either Individual or Organisation depending on whether the beneficiary is a person or a company/organisation.
🚧

$type is JSON metadata and must be the top property

This property describes the type of the beneficiary object, which in turn affects the required properties of the object. Metadata naming convention is to begin with $ (which is mandatory - $type is valid, type is not valid), and metadata properties must be the first properties in the object.

Be mindful of how your code objects are serialised to JSON in this regard.

  • companyName / firstName + lastName - Required for international payments, optional for domestic payments. companyName if $type is Organisation, firstName and lastName if $type is Individual.
  • address - Postal address. Required for most international payments, optional for domestic payments. Country must be an ISO 3166-1 alpha-2 code.
  • bankAccount - Required for all payments
    • accountCurrency - Required for all payments. Must be an ISO 4217 code.
    • accountRoutingName - Required for all payments.
    • country - Required for all payments. Must be an ISO 3166-1 alpha-2 code.
    • Bank account routing address components e.g. gbSortCode, iban: Enough of these must be supplied to satisfy at least one of the groups returned by Get Beneficiary Bank Account Fields.

Examples

Domestic Payments

{
  "partnerEntityId": "4b0e3c3e-43dc-409e-9b84-603fb1885a62",
  "payerBankAccountId": "a5b256c6-d6cc-4465-aa03-0decfff03339",
  "payables": [
    {
      "partnerEntityId": "368e9bdf-ef1f-459a-b005-8e64100f5269",
      "recipientAmount": {
        "amountInMinorUnits": 2000,
        "currencyCode": "GBP"
      },
      "reference": "testdomestic123",
      "beneficiary": {
        "bankAccount": {
          "accountCurrency": "GBP",
          "accountRoutingName": "John Doe",
          "country": "GB",
          "gbSortCode": "123456",
          "gbAccountNumber": "12345678"
        }
      }
    }
  ]
}

International Payments

{
  "partnerEntityId": "32ef0825-f17b-4204-9395-f62382a3729e",
  "payerBankAccountId": "a5b256c6-d6cc-4465-aa03-0decfff03339",
  "payables": [
    {
      "partnerEntityId": "75aa8041-5839-4c86-b37e-ba58c21192a3",
      "recipientAmount": {
        "amountInMinorUnits": 5008,
        "currencyCode": "EUR"
      },
      "reference": "testfxfz3n",
      "beneficiary": {
        "$type": "Organisation",
        "address": {
          "street": "42 Rue de la République",
          "city": "Paris",
          "region": "Île-de-France",
          "country": "FR",
          "postalCode": "75001"
        },
        "bankAccount": {
          "accountCurrency": "EUR",
          "accountRoutingName": "Example Co",
          "country": "FR",
          "iban": "FR7630006000011234567890189"
        },
        "companyName": "Example Co. France"
      }
    },
    {
      "partnerEntityId": "26facc73-e3bc-4328-9eab-dd05147fd992",
      "recipientAmount": {
        "amountInMinorUnits": 6006,
        "currencyCode": "EUR"
      },
      "reference": "testfxK695",
      "beneficiary": {
        "$type": "Individual",
        "address": {
          "street": "52 RUE DES FLEURS",
          "city": "Paris",
          "region": "Île-de-France",
          "country": "FR",
          "postalCode": "75001"
        },
        "bankAccount": {
          "accountCurrency": "EUR",
          "accountRoutingName": "John Doe",
          "country": "FR",
          "iban": "FR1420041010050500013M02606"
        },
        "firstName": "John",
        "lastName": "Doe"
      }
    }
  ]
}

Metadata

You are able to attach your own metadata to a pay run in simple key-value pairs. These will be visible in Get pay run subsequently.

  • key and value can be strings up to 100 characters in length
  • Maximum of 10 metadata items per pay run
  • key must conform to regular expression ^[A-Za-z0-9,.-_ ]+$

For example:

"metadata": [
  { "key": "productType", "value": "payroll" }
]

Path Params
uuid
required

The unique Crezco ID for an organisation

Body Params

Model for creating a pay run

string
required
length between 1 and 50

Globally Unique Id of this pay run in the partner system

date | null

The date that this pay run is scheduled to be paid represented in ISO 8601 complete date delimited format (e.g. 2022-05-12 would be 12th May 2022)

If omitted, payment will be instructed as soon as it is authorised

uuid | null

The bank account to pay from. For backwards compatibility, this field is still supported.
New integrations should use PaymentSourceType and PaymentSourceId instead.

string
enum
Allowed:
uuid | null

ID of the payment source. The type is derived automatically when PaymentSourceType is omitted.
Required for Bank payment sources. Optional if PaymentSourceType is Card (for stored cards).

payables
array
required
length ≥ 1

Collection of individual payable items that form this pay run

payables*

Details for a single payment being made from a Payer to a Recipient

string
required
length between 1 and 50

Globally Unique Id of this payment in the partner system

recipientAmount
object
required
endUserTotalCostAmount
object
currencyConversion
object

Details of the rates for a currency conversion

fees
object
beneficiary
required

Details of the beneficiary receiving this payment

string
enum
invoice
object
timeline
object

Timeline information for this payment, including cutoff and estimated processed times.

fundingAmount
object
string

Customer reference for this payment

boolean

Sets the payment to be processed last in the batch

reversedAmount
object
string
enum

Mapping for https://crezco.readme.io/reference/statuses so we don't expose internal statuses

string
enum
Allowed:
uuid | null

ID of the payment source, if known

groups
array of objects | null

Optional collection of payable groups within this pay run

Payables can be grouped by beneficiary. Grouped payables to the same beneficiary will, once paid, appear as a single line item on the payer's bank statements.

Attempts to group payments with different beneficiaries will cause pay run creation to fail.

groups
string
enum

Mapping for https://crezco.readme.io/reference/statuses so we don't expose internal statuses

metadata
array of objects

Partner-defined metadata for this pay run

metadata
Headers
string
Defaults to 2025-01-31

The requested API version

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated about 2 months ago

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json

Updated about 2 months ago