{
"openapi": "3.0.1",
"info": {
"title": "Balances",
"description": "Request your account details for a single account or all accounts under an entity.\n\n__Authentication header__\n ```\n Authorization: {your_credentials}\n ```\nReplace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Worldpay Implementation Manager.\n
\n\nYou **must** use the `Authorization` header for any request you send to our Balances API.\n\n__Accept header__\n ```\n Accept: application/vnd.worldpay.accounts.balance-v1+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 Balances API.\n
\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": "v1"
},
"servers": [
{
"url": "https://try.access.worldpay.com",
"description": "Test (Try)"
},
{
"url": "https://access.worldpay.com",
"description": "Live"
}
],
"paths": {
"/accounts/balance/{accountNumber}": {
"get": {
"summary": "Get account details",
"description": "Retrieve the details of one specific account.",
"operationId": "getAccount",
"parameters": [
{
"name": "WP-CorrelationId",
"in": "header",
"description": "Optional ID to trace requests, if not provided, it is generated.",
"schema": {
"type": "string"
},
"example": "15cd16b2-7b82-41cb-9b11-21be9dacad88"
},
{
"name": "accountNumber",
"in": "path",
"description": "The account number",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountResponse"
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/AccountResponse"
}
}
}
},
"400": {
"description": "BAD REQUEST response if the request is incorrectly validated",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Bad request": {
"$ref": "#/components/examples/400"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Bad request": {
"$ref": "#/components/examples/400"
}
}
}
}
},
"401": {
"description": "UNAUTHORIZED response if JWT is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"UNAUTHORIZED": {
"$ref": "#/components/examples/401"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"UNAUTHORIZED": {
"$ref": "#/components/examples/401"
}
}
}
}
},
"403": {
"description": "FORBIDDEN response if you are not authorized to access",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"FORBIDDEN": {
"$ref": "#/components/examples/403"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"FORBIDDEN": {
"$ref": "#/components/examples/403"
}
}
}
}
},
"404": {
"description": "NOT FOUND response if the AccountNumber or Page was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"NOT FOUND": {
"$ref": "#/components/examples/404"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"NOT FOUND": {
"$ref": "#/components/examples/404"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"Internal server error": {
"$ref": "#/components/examples/500"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"Internal server error": {
"$ref": "#/components/examples/500"
}
}
}
}
}
}
}
},
"/accounts/balance": {
"get": {
"summary": "Get details for all your accounts",
"description": "Retrieve account details for all your accounts.",
"operationId": "getEntity",
"parameters": [
{
"name": "WP-CorrelationId",
"in": "header",
"description": "Optional ID to trace requests, if not provided, it is generated.",
"schema": {
"type": "string"
},
"example": "15cd16b2-7b82-41cb-9b11-21be9dacad88"
},
{
"name": "entity",
"in": "query",
"description": "Your unique 6-digit ID given during the onboarding process.",
"schema": {
"type": "string",
"example": "11155"
}
}
],
"responses": {
"200": {
"description": "OK response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AccountResponse"
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/AccountResponse"
}
}
}
},
"400": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Bad request": {
"$ref": "#/components/examples/400"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"Bad request": {
"$ref": "#/components/examples/400"
}
}
}
}
},
"401": {
"description": "UNAUTHORIZED response if JWT is not valid",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"UNAUTHORIZED": {
"$ref": "#/components/examples/401"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"UNAUTHORIZED": {
"$ref": "#/components/examples/401"
}
}
}
}
},
"403": {
"description": "FORBIDDEN response if you are not authorized to access",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"FORBIDDEN": {
"$ref": "#/components/examples/403"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"examples": {
"FORBIDDEN": {
"$ref": "#/components/examples/403"
}
}
}
}
},
"404": {
"description": "NOT FOUND response if the AccountNumber or Page was not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"NOT FOUND": {
"$ref": "#/components/examples/404"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"NOT FOUND": {
"$ref": "#/components/examples/404"
}
}
}
}
},
"500": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"Internal server error": {
"$ref": "#/components/examples/500"
}
}
},
"application/vnd.worldpay.accounts.balance-v1+json": {
"schema": {
"$ref": "#/components/schemas/BaseErrorResponse"
},
"examples": {
"Internal server error": {
"$ref": "#/components/examples/500"
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Account": {
"type": "object",
"properties": {
"accountNumber": {
"type": "string",
"description": "The account number.",
"nullable": true,
"example": "1111557890987654"
},
"accountName": {
"type": "string",
"description": "The name of the account. (This is given to you during onboarding and typically consists of your merchant name followed by the currency code.)",
"nullable": true,
"example": "Etsy GBP"
},
"currency": {
"type": "string",
"description": "The [ISO 4217 currency codes](/products/reference/supported-countries-currencies#iso-currency-codes) of the account.",
"nullable": true,
"example": "GBP"
},
"clearedBalance": {
"type": "number",
"description": "The cleared balance.",
"format": "double",
"example": 142.5
},
"unclearedBalance": {
"type": "number",
"description": "The uncleared balance.",
"format": "double",
"example": 100.8
},
"balance": {
"type": "number",
"description": "The total balance.",
"format": "double",
"example": 243.5
},
"accountStatus": {
"type": "string",
"description": "The status of the account.",
"nullable": true,
"example": "ACTIVE"
}
},
"additionalProperties": false
},
"AccountResponse": {
"type": "object",
"properties": {
"entity": {
"type": "string",
"description": "Your unique 6-digit ID given to you during the onboarding process.",
"nullable": true,
"example": "111155"
},
"accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Account"
},
"description": "Collection of account details.",
"nullable": true
}
},
"additionalProperties": false,
"description": "The GET account response."
},
"BaseErrorResponse": {
"type": "object",
"properties": {
"httpStatusCode": {
"type": "integer",
"description": "The HTTP status",
"format": "int32"
},
"customCode": {
"type": "string",
"description": "The unique response code for this endpoint.",
"nullable": true
},
"message": {
"type": "string",
"description": "The error message.",
"nullable": true
}
},
"additionalProperties": false,
"description": "The error response."
},
"ErrorResponse": {
"type": "object",
"properties": {
"httpStatusCode": {
"type": "integer",
"description": "The HTTP status.",
"format": "int32"
},
"customCode": {
"type": "string",
"description": "The unique response code for this endpoint.",
"nullable": true
},
"message": {
"type": "string",
"description": "The error message.",
"nullable": true
},
"errors": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"description": "Collection of error details.",
"nullable": true
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"basicAuth": {
"type": "http",
"scheme": "basic"
}
},
"examples": {
"400": {
"value": {
"httpStatusCode": 400,
"customCode": "ACCB05",
"message": "Schema validation failed",
"errors": {
"AccountNumber": [
"AccountNumber should be 16 digits"
]
}
}
},
"401": {
"value": {
"httpStatusCode": 401,
"customCode": "ACCU06",
"message": "Unauthorized request"
}
},
"403": {
"value": {
"httpStatusCode": 403,
"customCode": "ACCF18",
"message": "Forbidden",
"errors": {
"Domain": [
"Authorisation Failed for this Domain"
]
}
}
},
"404": {
"value": {
"httpStatusCode": 404,
"customCode": "ACCN15",
"message": "Could not find details for accountNumber"
}
},
"500": {
"value": {
"httpStatusCode": 500,
"customCode": "ACCE11",
"message": "Unexpected Issue. Please try again"
}
}
}
},
"security": [
{
"basicAuth": []
}
]
}