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.
Payment source
Every pay run needs to specify which payment source it will be funded from, by providing one of:
paymentSourceId- The ID of a connected payment source (bank account or card), from Get payment sources.payerBankAccountId- Still supported for backwards compatibility, and is equivalent topaymentSourceIdfor a bank account. New integrations should usepaymentSourceIdinstead.paymentSourceTypeset toCard, with nopaymentSourceId- the user will be asked to add their card details during the payment flow, rather than paying with an already-connected card.
See the Pay by card guide for more on paying with a card.
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 eitherIndividualorOrganisationdepending on whether the beneficiary is a person or a company/organisation.
$type is JSON metadata and must be the top propertyThis 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 -$typeis valid,typeis 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.companyNameif$typeisOrganisation,firstNameandlastNameif$typeisIndividual.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 paymentsaccountCurrency- 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"
}
}
]
}Card Payments
{
"partnerEntityId": "e3f1a3a1-9a7a-4c2f-8e3f-1a2b3c4d5e6f",
"paymentSourceType": "Card",
"payables": [
{
"partnerEntityId": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
"recipientAmount": {
"amountInMinorUnits": 2000,
"currencyCode": "GBP"
},
"reference": "testcard123",
"beneficiary": {
"bankAccount": {
"accountCurrency": "GBP",
"accountRoutingName": "John Doe",
"country": "GB",
"gbSortCode": "123456",
"gbAccountNumber": "12345678"
}
}
}
]
}paymentSourceId is omitted here, so the user will be prompted to enter new card details when they check out the pay run. To pay with a previously connected card instead, add paymentSourceId with the card's ID from Get payment sources.
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.
keyandvaluecan be strings up to 100 characters in length- Maximum of 10 metadata items per pay run
keymust conform to regular expression^[A-Za-z0-9,.-_ ]+$
For example:
"metadata": [
{ "key": "productType", "value": "payroll" }
]