Create and maintain balance accounts.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/worldpay-balance-accounts-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: 3DS 3DS actions Balance accounts API
description: "Protect your business and meet regulatory requirements by verifying your customer's identity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to your by your Worldpay Implementation Manager.\n<br /> <br />\n\nYou **must** use the `Authorization` header for any request you send to our 3DS API.\n\n__Accept/Content-Type header__\n ```\n Content-Type: application/vnd.worldpay.verifications.customers-v3.hal+json\n Accept: application/vnd.worldpay.verifications.customers-v3.hal+json\n ```\nWe use the Accept header to identify which version of our API you are using. You must use the Accept header for any request you send to our 3DS API.\n\nWe require the Content-Type header if the request you're sending includes a request body, and if the HTTP method is a `POST` or a `PUT`.\n<br /><br />\n\n\n__DNS whitelisting__ \nWhitelist the following URLs:\n* `https://try.access.worldpay.com/`\n* `https://access.worldpay.com/`\n\nPlease ensure you use DNS whitelisting, not explicit IP whitelisting."
version: '3'
x-metadata:
category:
- 3DS
- SCA Exemptions
business:
- Enterprise
catalog-list: true
generated: false
servers:
- url: https://try.access.worldpay.com
description: Test (Try)
- url: https://access.worldpay.com
description: Live
security:
- BasicAuth: []
tags:
- name: Balance accounts
description: Create and maintain balance accounts.
paths:
/parties/{partyId}/balanceAccounts:
post:
tags:
- Balance accounts
summary: Create a balance account
operationId: createBalanceAccount
parameters:
- name: partyId
in: path
description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
- name: WP-Api-Version
in: header
description: The API version.
required: true
schema:
type: string
format: date
example: '2025-01-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAccount'
examples:
Create a balance account for existing party of person (modular with a weekly payout):
$ref: '#/components/examples/Create_BalanceAccount_Person_modular'
Create a balance account for existing party of sole trader (modular with a monthly payout):
$ref: '#/components/examples/Create_BalanceAccount_SoleTrader_modular'
Create a balance account for existing party of company (modular with a daily payout):
$ref: '#/components/examples/Create_BalanceAccount_Company_modular'
required: true
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAccount'
examples:
Create a balance account for existing party of person (modular with a weekly payout):
$ref: '#/components/examples/BalanceAccount_Person_created_201_modular'
Create a balance account for existing party of sole trader (modular with a monthly payout):
$ref: '#/components/examples/BalanceAccount_SoleTrader_created_201_modular'
Create a balance account for existing party of company (modular with a daily payout):
$ref: '#/components/examples/BalanceAccount_Company_created_201_modular'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Bad request:
$ref: '#/components/examples/400'
URL with invalid value:
$ref: '#/components/examples/400_Invalid_Url'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal error occurred:
$ref: '#/components/examples/500'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Service Unavailable:
$ref: '#/components/examples/503'
/parties/{partyId}/balanceAccounts/{balanceAccountId}:
get:
tags:
- Balance accounts
summary: View a balance account
operationId: getBalanceAccount
parameters:
- name: partyId
in: path
description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
- name: balanceAccountId
in: path
description: A unique identifier for the balanceAccount generated by us. This is sent in the response of your balanceAccount creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: par.*0$
- name: WP-Api-Version
in: header
description: The API version.
required: true
schema:
type: string
format: date
example: '2025-01-01'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAccount'
examples:
Get a balance account for existing party of company (modular with a daily payout):
$ref: '#/components/examples/Get_BalanceAccount_Company_200_modular'
Get a balance account for existing party of person (modular with a weekly payout):
$ref: '#/components/examples/Get_BalanceAccount_Person_200_modular'
Get a balance account for existing party of sole trader (modular with a monthly payout):
$ref: '#/components/examples/Get_BalanceAccount_SoleTrader_200_modular'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Bad request:
$ref: '#/components/examples/400'
URL with invalid value:
$ref: '#/components/examples/400_Invalid_Url'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal error occurred:
$ref: '#/components/examples/500'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Service Unavailable:
$ref: '#/components/examples/503'
put:
tags:
- Balance accounts
summary: Update a balance account
operationId: updateBalanceAccount
parameters:
- name: partyId
in: path
description: A unique identifier for the party generated by us. This is sent in the response of your party creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: ^par[a-zA-Z0-9-_]*0$
- name: balanceAccountId
in: path
description: A unique identifier for the balanceAccount generated by us. This is sent in the response of your balanceAccount creation call.
required: true
schema:
type: string
maxLength: 25
minLength: 25
pattern: par.*0$
- name: WP-Api-Version
in: header
description: The API version.
required: true
schema:
type: string
format: date
example: '2025-01-01'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBalanceAccountRequest'
examples:
Update a balance account:
$ref: '#/components/examples/Update_Balance_Account_SoleTrader_modular'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceAccount'
examples:
Update balance account:
$ref: '#/components/examples/Update_Balance_Account_SoleTrader_200_modular'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Bad request:
$ref: '#/components/examples/400'
URL with invalid value:
$ref: '#/components/examples/400_Invalid_Url'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Internal error occurred:
$ref: '#/components/examples/500'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
Service Unavailable:
$ref: '#/components/examples/503'
components:
schemas:
UpdateBalanceAccountRequest:
type: object
description: Request payload for updating a balance account.
properties:
currency:
type: string
description: The currency in [ISO 4217 currency format](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
maxLength: 3
minLength: 3
pattern: ^[A-Z]*$
payoutInstrumentReference:
type: string
description: '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
scheduledPayoutDay:
type: string
description: The scheduled payout day for this `balanceAccount`. You must provide this for "weekly" and "monthly" `frequency`.
enum:
- monday
- tuesday
- wednesday
- thursday
- friday
example: friday
frequency:
type: string
description: '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
recurrence:
type: string
description: The week of the month the payout is paid out. You must provide this for "monthly" `frequency`.
enum:
- first
- second
- third
- fourth
example: first
balanceAccountId:
type: string
description: Unique ID created by us to identify a balance account. This is sent in the response after `balanceAccount` creation.
dateTimeCreated:
type: string
description: The date and time that the balance account was created, as an ISO 8601 zoned date time.
example: 2025-01-23T12:23:445.222Z
dateTimeUpdated:
type: string
description: 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
version:
type: integer
format: int32
accountNumber:
type: string
description: The number of your balanceAccount.
nextPayoutDate:
type: string
format: date
description: The upcoming payout date of the existing schedule for this `balanceAccountId`. You can retrieve this via our GET endpoint.
example: '2025-02-14'
required:
- currency
- nextPayoutDate
- payoutInstrumentReference
ErrorResponseItem:
type: object
properties:
errorName:
type: string
message:
type: string
path:
type: string
jsonPath:
type: string
queryParameter:
type: string
pathParameter:
type: string
BalanceAccount:
type: object
properties:
currency:
type: string
description: The currency in [ISO 4217 currency format](/products/reference/supported-countries-currencies#iso-currency-codes).
example: GBP
maxLength: 3
minLength: 3
pattern: ^[A-Z]*$
payoutInstrumentReference:
type: string
description: '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
scheduledPayoutDay:
type: string
description: The scheduled payout day for this `balanceAccount`. You must provide this for "weekly" and "monthly" `frequency`.
enum:
- monday
- tuesday
- wednesday
- thursday
- friday
example: friday
frequency:
type: string
description: '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
recurrence:
type: string
description: The week of the month the payout is paid out. You must provide this for "monthly" `frequency`.
enum:
- first
- second
- third
- fourth
example: first
nextPayoutDate:
type: string
description: The next scheduled payout date for this balance account.
example: '2025-02-14'
readOnly: true
balanceAccountId:
type: string
description: Unique ID created by us to identify a balance account. This is sent in the response after `balanceAccount` creation.
readOnly: true
accountNumber:
type: string
description: The number of your balanceAccount.
readOnly: true
dateTimeCreated:
type: string
description: The date and time that the balance account was created, as an ISO 8601 zoned date time.
example: 2025-01-23T12:23:445.222Z
readOnly: true
dateTimeUpdated:
type: string
description: 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
readOnly: true
version:
type: integer
format: int32
readOnly: true
required:
- currency
ErrorResponse:
type: object
properties:
errorName:
type: string
description: An ordinal error type that is part of the API contract. It is machine readable, but also human readable for clarity and semantic understanding of the error.
example: bodyDoesNotMatchSchema
message:
type: string
description: A human readable message giving a corrective action for the error. THIS IS NOT FOR MACHINE CONSUMPTION.
validationErrors:
type: array
items:
$ref: '#/components/schemas/ErrorResponseItem'
pathParameter:
type: string
queryParameter:
type: string
jsonPath:
type: string
readOnly: true
title: Error Response
examples:
'503':
value:
errorName: serviceUnavailable
message: Service cannot fulfil the request even though service functions witout internal errors.
Get_BalanceAccount_Person_200_modular:
description: Balance account for a party of type person (modular)
value:
currency: EUR
payoutInstrumentReference: personalCheckingAccount
scheduledPayoutDay: friday
frequency: weekly
balanceAccountId: pareBH4YMkUx7MA2X7bnS4750
dateTimeCreated: '2025-04-16T20:46:26.727Z'
version: 0
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
'400':
value:
errorName: bodyDoesNotMatchSchema
message: There were field validation errors. The errors that occurred are within the validationErrors array.
validationErrors:
- errorName: fieldIsNotAllowed
message: The identified field is present when it is explicitly not allowed in the request.
jsonPath: $.additionalData
Create_BalanceAccount_Person_modular:
value:
currency: EUR
payoutInstrumentReference: personalCheckingAccount2
scheduledPayoutDay: friday
frequency: weekly
Create_BalanceAccount_Company_modular:
value:
currency: USD
frequency: daily
payoutInstrumentReference: primaryBusinessAccount
BalanceAccount_Company_created_201_modular:
description: Balance account for a party of an existing company (modular)
value:
currency: USD
payoutInstrumentReference: primaryBusinessAccount
frequency: daily
balanceAccountId: parGWfE__Xr1F-AmY0v72fwR0
dateTimeCreated: '2025-04-16T20:46:27.014Z'
version: 0
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
Get_BalanceAccount_SoleTrader_200_modular:
description: Balance account for a party of type sole trader (modular)
value:
currency: USD
payoutInstrumentReference: primaryBusinessAccount
scheduledPayoutDay: friday
frequency: monthly
recurrence: first
balanceAccountId: parApcraCq1bmBuCotAMoyss0
dateTimeCreated: '2025-04-16T20:46:26.852Z'
version: 0
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
Create_BalanceAccount_SoleTrader_modular:
value:
currency: USD
scheduledPayoutDay: friday
frequency: monthly
recurrence: first
payoutInstrumentReference: primaryBusinessAccount
Update_Balance_Account_SoleTrader_200_modular:
description: Update balance account for existing party of a sole trader (modular)
value:
currency: USD
payoutInstrumentReference: primaryBusinessAccount
scheduledPayoutDay: thursday
frequency: weekly
balanceAccountId: parApcraCq1bmBuCotAMoyss0
dateTimeCreated: '2025-04-16T20:46:26.852Z'
dateTimeUpdated: '2025-04-18T20:46:29.901Z'
version: 2
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
Update_Balance_Account_SoleTrader_modular:
value:
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'
Get_BalanceAccount_Company_200_modular:
description: Balance account for a party of type company (modular)
value:
currency: USD
payoutInstrumentReference: primaryBusinessAccount
frequency: daily
balanceAccountId: parGWfE__Xr1F-AmY0v72fwR0
dateTimeCreated: '2025-04-16T20:46:27.014Z'
dateTimeUpdated: '2025-04-17T20:46:27.014Z'
version: 1
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
400_Invalid_Url:
value:
errorName: urlContainsInvalidValue
message: The URL contains a value or values that are invalid.
validationErrors:
- errorName: fieldHasInvalidValue
message: Party 'parDgfhD9O5lWVjWiUOo3Cdf0' was not found.
jsonPath: $.partyId
BalanceAccount_SoleTrader_created_201_modular:
description: Balance account for a party of an existing soleTrader (modular)
value:
currency: USD
payoutInstrumentReference: primaryBusinessAccount
scheduledPayoutDay: friday
frequency: monthly
recurrence: first
balanceAccountId: parApcraCq1bmBuCotAMoyss0
dateTimeCreated: '2025-04-16T20:46:26.852Z'
version: 0
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
BalanceAccount_Person_created_201_modular:
description: Balance account for a party of an existing person (modular)
value:
currency: EUR
payoutInstrumentReference: personalCheckingAccount2
scheduledPayoutDay: friday
frequency: weekly
balanceAccountId: pareBH4YMkUx7MA2X7bnS4750
dateTimeCreated: '2025-04-16T20:46:26.727Z'
version: 0
accountNumber: '12345678'
nextPayoutDate: '2026-03-19'
'500':
value:
errorName: internalErrorOccurred
message: An error occurred within the service (potentially due to an interaction with a downstream service).
securitySchemes:
BasicAuth:
type: http
scheme: basic