Bulk payments

Further information on how to create bulk payments with Yapily.

Bulk payment request

To create a bulk payment with the Yapily API, you specify an array of Single Payments and provide them to the payments object in the the BulkPaymentRequest when executing any of the bulk payment endpoints.

Depending on the restrictions of each Institution, you may have to make specific adjustments to the payments array. More information on these types of restrictions are listed below.

Account beneficiaries

For each Institution in the UK that has the limitation where each Payee must be a trusted beneficiary for the execution of the bulk payment to occur successfully, Yapily has introduced the ACCOUNT_BENEFICIARIES feature to allow TPPs to get all the beneficiaries for the Payer account to cross check that each Payee is a trusted beneficiary.

To access the beneficiaries of an account, you must obtain a valid AIS consent using [Create Account Authorisation] (/api/#create-account-authorisation) and then use the resultant consentToken to execute [Get Account Beneficiaries] (/api/#get-account-beneficiaries).

Unfortunately, it is not in scope for Open Banking to allow the dynamic adding of beneficiaries through Open Banking APIs so the payments service user must do this manually through their bank.

IdempotencyId

Unique identifier for bulk payment file requests. Ensures idempotency, preventing duplicate processing of files and transactions due to retries or timeouts.

Requirements for idempotencyId:

• Uniqueness: Each idempotencyId should be unique per bulk payment consent. Reusing the same idempotencyId with different consents (bulk payment files) can result in duplicate payments, as each consent is treated as a separate transaction.
• Validity Period: An idempotencyId is valid for 24 hours. Resubmitting a bulk payment file with the same idempotencyId and consent after 24 hours may lead to the payment being processed again.

• Correct Usage: When resending a bulk payment file due to issues like timeouts, use the same idempotencyId (for the same consent) within 24 hours to ensure the file is processed only once.
• Format: The idempotencydD must be an alphanumeric string between 1 and 40 characters with no spaces (e.g., igeRtFGgIk351ImM3rtd ).

Execution

Once the bank is instructed to execute the payment, the bank will decide whether or not they execute the bulk as a whole, meaning that if one payment fails, the entire bulk may fail.

Known restrictions

Barclays

• Only immediate domestic payments are supported
• Maximum 50 payments per request
• Minimum 5 payments per request
• Maximum total payments amount is £50,000
• Minimum payment amount is £0.05
• The reference field is mandatory for every payment in the bulk transaction
• The character field length for Debtor Account Name and Creditor Account Name is <140 characters
• Please avoid using special characters (such as '.', '#', or ' [ ] ') in contact names and references, as this can prevent you from completing bulk payment

HSBC

• Only immediate domestic and scheduled domestic payments are supported
• Maximum 25 payments per request
• For HSBC Business customers cannot exceed a single payment limit, which is setup by the client
• Domestic scheduled payments must have a payment execution date that is 2-45 days in the future

Lloyds

• Only immediate domestic and scheduled domestic payments are supported
• Maximum 25 payments per request
• Maximum total payments amount is £100,000
• Bulk payment daily limit is £250,000
• The reference for every payment is required
• Payer object must be specified in the bulk payment
• Maximum 18 characters for payee.name
• Maximum 18 characters for paymentIdempotencyId

Natwest

• Only immediate domestic and scheduled domestic payments are supported
• Maximum 50 payments per request
• Bankline customers have a maximum limit of:
  • 3000 payments to multiple payees at once from a single debit account
  • 4000 payments to multiple payees at once from multiple debit accounts
• The maximum payment amount will be driven by the customer’s daily payment limits on their account
• Customer’s daily payment limits are shared across bulk payments and individual payments. For example, if a customer has a daily limit of £1000, the value of bulk and individual payments they make collectively on one day can't exceed £1000
• Each payment in the bulk must have the same payment type
• Bulk payments are only accepted where all the creditors are trusted beneficiaries
• Each payment in the bulk must have maximum of 16 characters for reference
• A bulk payment can consist uniquely of either Single immediate Payments or Future Dated Payments
• Maximum 18 characters for payee.name
• Payer object must be specified in the bulk payment
• Two-factor authentication is always required for bulk payments. Customers will be asked to authenticate themselves using MFA in their mobile app or via card and reader
• Multi-authorisation journey is supported in Bankline. The secondary authoriser(s) would need to approve the payments by logging into Bankline and completing the authorisation

RBS

• Only immediate domestic and scheduled domestic payments are supported
• Maximum 50 payments per request
• Bankline customers have a maximum limit of:
  • 3000 payments to multiple payees at once from a single debit account
  • 4000 payments to multiple payees at once from multiple debit accounts
• The maximum payment amount will be driven by the customer’s daily payment limits on their account
• Customer’s daily payment limits are shared across bulk payments and individual payments
• Each payment in the bulk must have the same payment type
• Bulk payments are only accepted where all the creditors are trusted beneficiaries
• Each payment in the bulk must have maximum of 16 characters for reference
• Multi-authorisation journey is supported in Bankline. The secondary authoriser(s) would need to approve the payments by logging into Bankline and completing the authorisation

Santander

• Only immediate domestic payments are supported
• Maximum 3,500 payments per request
• The maximum payment amount:
  • Business accounts - £100,000
  • Corporate accounts - £250,000
• Bulk payments are only accepted where all the creditors are trusted beneficiaries
• Payer object must be specified in the bulk payment

Revolut

• Only immediate domestic payments are supported
• Maximum 1,000 payments per request
• Maximum total payments amount is £1,000,000
• Payees must be set up as trusted beneficiaries on the payer account before a bulk payment is attempted
• Payee names must be more than one word
• For bulk payments, payee.address.country , payee.address.postCode and payee.address.townName are mandatory for each payment in the bulk payment request
• Revolut Business users can only authorise bulk payments via the web application and not the mobile app
• If the payee for a payment in a bulk payment file is a business, paymentRequest.payee.merchantCategoryCode should be provided
• Faster Payments Scheme can accept only 18 characters for the reference field
• The reference field is mandatory for every payment in the bulk transaction

Ulster

• Only immediate domestic and scheduled domestic payments are supported
• Maximum 50 payments per request
• Bankline customers have a maximum limit of:
  • 3000 payments to multiple payees at once from a single debit account
  • 4000 payments to multiple payees at once from multiple debit accounts
• The maximum payment amount will be driven by the customer’s daily payment limits on their account
• Customer’s daily payment limits are shared across bulk payments and individual payments
• Each payment in the bulk must have the same payment type
• Bulk payments are only accepted where all the creditors are trusted beneficiaries
• Each payment in the bulk must have maximum of 16 characters for reference
• Multi-authorisation journey is supported in Bankline. The secondary authoriser(s) would need to approve the payments by logging into Bankline and completing the authorisation

Virgin Money

• Only immediate domestic payments are supported
• The bank can accept:
  • 750 payments in a single file if they are all from the same debtor account and are all being remitted on the same day (e.g. payroll)
  • 150 payments in a single file if they are coming from different debtor accounts and/or are being remitted on different days
• Payment limits for business accounts vary per account and can be set by the customers
• The bank limit for faster payments is £250,000
• The payments with no date would be immediate payments
• Payer object must be specified in the bulk payment
• Aggregated value of batch payments must be within the company/user's approval limit
• Virgin Money will usually schedule the payment request immediately, but delays may occur during busy periods or if additional approvals are required
• The initiation section of the payment must match the corresponding sections of the payment consent resource; discrepancies will generate an error response and the request will not be processed
• Bulk payment request response times can be slower than those for other integrations due to a deficiency in the bank's system

Solaris

• The requested execution date should not be passed in the requests as it will be skipped in the request to institution
• PSU-IP-ADDRESS is required for bulk payments