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" |