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

Create balance account for existing party of a person (modular)

{
  "currency": "EUR",
  "scheduledPayoutDay": "friday",
  "payoutInstrumentReference": "MyPayoutInstrument1"
}
Response
application/json

Balance account for a party of an existing person (modular)

{
  "currency": "EUR",
  "payoutInstrumentReference": "MyPayoutInstrument1",
  "scheduledPayoutDay": "friday",
  "balanceAccountId": "pareBH4YMkUx7MA2X7bnS4750",
  "dateTimeCreated": "2025-04-16T20:46:26.727Z",
  "version": 0
}

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: "MyPayoutInstrument1"
scheduledPayoutDaystring

The scheduled payout day for this balanceAccount.

Enum"monday""tuesday""wednesday""thursday""friday"
balanceAccountIdstringread-only

Unique ID created by us to identify a balance account. This 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-onlyrequired

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
Response
application/json

Balance account for a party of type company (modular)

{
  "currency": "CHF",
  "payoutInstrumentReference": "MyPayoutInstrument1",
  "scheduledPayoutDay": "thursday",
  "balanceAccountId": "parGWfE__Xr1F-AmY0v72fwR0",
  "dateTimeCreated": "2025-04-16T20:46:27.014Z",
  "version": 1
}

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 schedules

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

Coming Soon - Additional schedules and FX functionality

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

Update balance account for existing party of a sole trader (modular)

{
  "currency": "CHF",
  "payoutInstrumentReference": "MyPayoutInstrument1",
  "scheduledPayoutDay": "wednesday"
}
Response
application/json

Update balance account for existing party of a sole trader (modular)

{
  "currency": "CHF",
  "payoutInstrumentReference": "MyPayoutInstrument1",
  "scheduledPayoutDay": "wednesday",
  "balanceAccountId": "parApcraCq1bmBuCotAMoyss0",
  "dateTimeCreated": "2025-04-16T20:46:26.852Z",
  "dateTimeUpdated": "2025-04-16T20:46:29.901Z",
  "version": 1
}

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