Skip to content

New service | Last updated: 14 May 2025

Important

This documentation is for preview purposes only.

Manage balance accounts

Create and manage balance accounts which represent a virtual currency account within Worldpay. We use this to store the party's funds ahead of a payout.


You can add a balanceAccount in two ways. Either during or after the creation of a party. This guide focuses on adding a balanceAccount after the party creation call.

To add a balanceAccount during orchestrated party creation call, you can use the https://access.worldpay.com/parties endpoint.

Create a balance account

After a party is created, you can create and add a balance account.

POST https://access.worldpay.com/parties/{partyId}/balanceAccount


Note

You can only request creation of one balance account per one currency.

Request example

POST https://access.worldpay.com/parties/parTH82wexHglhnBbzd6iJ7P0/balanceAccount

application/json
{
  "currency": "EUR",
  "payoutInstrumentReference": "personalCheckingAccount2",
  "scheduledPayoutDay": "friday",
  "frequency": "weekly"
}

Request/ response schema

currencystring= 3 characters^[A-Z]*$required
Example: "GBP"
payoutInstrumentReferencestring

A reference of the payoutInstrument created by you. This field holds the beneficiary bank details. Use this to direct payouts to the relevant beneficiary. This must be unique within an entity.

Example: "primaryBusinessAccount"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount. You must provide this for "weekly" and "monthly" frequency.

Enum"monday""tuesday""wednesday""thursday""friday"
Example: "friday"
frequencystring

Scheduled payout frequency for this balanceAccount:
daily - payouts are processed every business day
weekly - you must include scheduledPayoutDay
monthly - you must include scheduledPayoutDay and recurrence

Enum"daily""weekly""monthly"
Example: "weekly"
recurrencestring

The week of the month the payout is paid out. You must provide this for "monthly" frequency.

Enum"first""second""third""fourth"
Example: "first"
nextPayoutDatestringread-only

The next scheduled payout date for this balance account.

Example: "2025-02-14"
balanceAccountIdstringread-only

Unique ID created by us to identify a balance account. This is sent in the response after balanceAccount creation.

accountNumberstringread-only

The number of your balanceAccount.

dateTimeCreatedstringread-only

The date and time that the balance account was created, as an ISO 8601 zoned date time.

Example: "2025-01-23T12:23:445.222Z"
dateTimeUpdatedstringread-only

The date and time that the balance account was last updated, as an ISO 8601 zoned date time.

Example: "2025-01-25T02:43:499.202Z"
versioninteger(int32)read-only

View a balance account

View information about a balance account, previously created.

GET https://access.worldpay.com/parties/{partyId}/balanceAccount/{balanceAccountId

You can see the full schema above or in our API reference.

Assigning a payout schedule

Assign a payout schedule to a balance account, to ensure regular payouts to a specified payout instrument.

Important

Some regions require you to assign a regular schedule to their balance accounts. Please speak to your Worldpay Implementation Manager for further details.

Schedule support

  • daily

    • for every workday of the week (Monday-Friday)

  • weekly

    • for any workday of the week (Monday-Friday), using scheduledPayoutDay

  • monthly

    • set the day of the week (Monday-Friday), using scheduledPayoutDay
    • define which week of the month (first, second, third, fourth), using recurrence

Update a balance account

You can change:

  • the payoutInstrument
  • the day the payouts are scheduled for
Requirements
  • When updating a balance account, you must provide the nextPayoutDate. This is the date of the upcoming payout of the existing schedule for this balanceAccountId. You can make a GET request against this balanceAccountId to retrieve this.
  • The payoutInstrument currency must match the currency of the balance account.

Request example

PUT https://access.worldpay.com/parties/{partyId}/balanceAccount/{balanceAccountId}

application/json
{
  "currency": "USD",
  "payoutInstrumentReference": "primaryBusinessAccount",
  "scheduledPayoutDay": "thursday",
  "frequency": "weekly",
  "balanceAccountId": "parApcraCq1bmBuCotAMoyss0",
  "dateTimeCreated": "2025-04-16T20:46:26.852Z",
  "dateTimeUpdated": "2025-04-16T20:46:29.901Z",
  "version": 1,
  "accountNumber": "12345678",
  "nextPayoutDate": "2026-03-19"
}

You can see the full schema above or in our API reference.

Delete a balance account

Coming soon

Next steps

Add a payout instrument
Manage beneficial owners or
Verify a party