Last Updated: 27 July 2023 | Change Log

Transfer API

Transfer funds between your currency accounts.

Get started

Request

POST https://try.access.worldpay.com/accounts/transfer/

Request example

{
"sourceAccountNumber":"0000550000000001",
"targetAccountNumber":"0000550000000002",
"amount":123.45,
"narrative":"CurrencyTransfer12",
"quoteID":"Q0000000BV"
}

Mandatory parameters

Field Name	Description	Data Type/Format	Min-Max Length	Validation Criteria
`sourceAccountNumber`	Source Account Number from where the funds will be taken from. The first 6 characters indicate the domainID of the merchant. The rest determines the specific account number.	String	16-16	Alphanumeric only. Special characters are restricted.
`targetAccountNumber`	Target Account Number to which the funds will be transferred. The first 6 characters indicate the domainID of the merchant. The rest determines the specific account number.	String	16-16	Alphanumeric only. Special characters are restricted.
`amount`	Numeric only (must be grater than 0). Use dot (.) as decimal point. Up to 7 digits before decimal point and up to 2 decimal places.
`narrative`	A unique value supplied by your customer for the transfer. Must be unique for the domain the source account belongs to.	String	6-34	Alphanumeric only. Special characters allowed: List of allowed special chars: ** \|+=%!£$^&*()-_<>@[]~#:;',.?/¬`\ Only double backslash is allowed. Spaces are allowed.

Optional parameter

Field Name	Description	Data Type/Format	Min-Max Length	Validation Criteria
`quoteId`	A value that represents a unique FX quote that is pre-lodged with the treasury.	String	1-50	Alphanumeric only. NO special characters.

Response

Successful response fields

Body of the response

There is no body for a successful response. Only HTTP status 202 will be returned.

Error response examples

Example 1:

{
  "validationErrors": [
    {
      "errorName": "fieldHasInvalidValue",
      "message": "Source account number must be 16 characters",
      "jsonPath": "$.SourceAccountNumber"
    }
  ],
  "errorName": "bodyDoesNotMatchSchema",
  "message": "The json body provided does not match the expected schema"
}

Example 2:

{
  "errorName": "FieldHasInvalidValue",
  "message": "Amount to transfer cannot be greater than the remaining balance of -0.54 GBP"
}

Error response codes

Scenario	HTTP code	Custom code	Error name	Error message	Comments/Help/Examples
JWT not present, or invalid	401	TRAU06	"unauthorizedRequest"	The request is unauthorized
Authorization Failed - incorrect or no domain entitlements	403	TRAF18	"Forbidden"
JWT entitlements incorrect	403	TRAF18	"Forbidden"
sourceAccount is child to targetAccount	403	TRAF18	"Forbidden"
Account resource not found	404	TRAN15	"notFound"
Account number not found	404	TRAN15	"Could not find details for accountNumber"
Correlation ID not valid	400	TAP01	"headerHasInvalidValue"	"WP-CorrelationId must be a GUID"
Caller ID invalid	400	TAP01	"headerHasInvalidValue"	"WP-CallerId must contain only alphanumeric, dot (.) and hyphen (-) characters"
Source account number not present	400	TRAB05	"Schema validation failed"	"Source account number is mandatory"
Target account number not present	400	TRAB05	"Schema validation failed"	"Target account number is mandatory"
Source account number more or less than 16 chars	400	TRAB05	"Schema validation failed"	"Source account number must be 16 characters"
Target account number more or less of 16 chars	400	TRAB05	"Schema validation failed"	"Target account number must be 16 characters"
Narrative not present	400	TRAB05	"Schema validation failed"	"Narrative is mandatory"
Narrative less than 6 or more than 34	400	TRAB05	"Schema validation failed"	"Narrative must be at least 6 and no more than 34 characters"
Amount not present	400	TRAB05	"Schema validation failed"	"Empty value for amount"
Amount is invalid - not numerical	400	TRAB05	"Schema validation failed"	"Invalid value for amount. It should be numerical"
Amount is invalid - more than 2 decimal places	400	TRAB05	"Schema validation failed"	"Amount should have a maximum of 2 decimal places"
Amount is invalid - negative value or less than 1 digit	400	TRAB05	"Schema validation failed"	"Amount should be grater than 0"
Account resource not found	404	TRAN15	"not found"	"Resource not found"
Account number not found	404	TRAN15	"not found"	"Could not find details for accountNumber {accountNumber}"
A downstream service is down	500	TRAE11	"internalErrorOccurred"	"Something went wrong"
Balance in source account is less than the value in amount field of the request	402	TRAU08	"FiledHasInvalidValue"	"Amount to transfer cannot be grater than the remaining balance of {clearedBalance} {currency}"	"Amount to transfer cannot be grater than the remaining balance of 1258.25 USD"
EPACS - 409 idempotency	409	TRAX12	"Duplicate Entry"	"Duplicate request detected: Narrative - {narrative}"	"Duplicate request detected: Narrative - CurrencyTransfer12"