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/response example

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

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

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.

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

Scheduled payout for this balanceAccount.<br><b>weekly</b> - you must include schedulePayoutDay<br><b>monthly</b> - you must include schedulePayoutDay and recurrence

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

The week of the month the payout is paid out. Used 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.

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

Request/response example

No request payload

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 Implementation Manager for further details

Schedule support

  • weekly

    • for each workday of the week (Monday-Friday)
    • the payoutInstrument currency must match the one of the balance account

  • monthly

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

Modify a balance account

You can:

  • change the payoutInstrument
  • day the schedules are paid out to

Request/response example

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

application/json
{
  "currency": "USD",
  "payoutInstrumentReference": "primaryBusinessAccount",
  "scheduledPayoutDay": "thursday",
  "frequency": "weekly"
}

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