PayToBankAccountV3

Everything you need to know about the payment request.

About the payToBankAccountV3 request

payToBankAccountV3 request schema and elements
payToBankAccountV3 response schema and elements
Example request and response

payToBankAccountV3 request schema

Each <paymentInstructions> parent can contain multiple <paymentInstructionV3> children – one for each payment, up to 500.

If failure occurs in a <paymentInstructionV3> child, then all transactions within the <payToBankAccountV3> request fail with an error -800. The <paymentInstructionV3> children have individual success or failure codes, showing which transactions failed, and why. Though some of these children may show success status codes, they are not processed if they are part of a failed batch.

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<auth>

<username>string</username>

<password>string</password>

</auth>

<requestReference>string</requestReference>

<paymentInstructionV3>

<countryCode>string</countryCode>

<sourceCurrency>string</sourceCurrency>

<sourceAmount>double</sourceAmount>

<targetCurrency>string</targetCurrency>

<targetAmount>double</targetAmount>

<sourceOrTarget>string</sourceOrTarget>

<merchantReference>string</merchantReference>

<paymentReference>string</paymentReference>

<email>string</email>

<mobile>string</mobile>

<fastPayment>string</fastPayment>

<forexReference>string</forexReference>

<paymentDescription>string</paymentDescription>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

</paymentAdditionalData>

</paymentDetails>

</paymentTemplate>

<paymentItemId>guide</paymentItemId>

</paymentInstructionV3>

</paymentInstructions>

</payToBankAccountV3>

</soap:Body>

</soap:Envelope>

payToBankAccountV3 elements

Lvl	Element	Description	Values / Limitations
1	auth	Contains the elements related to the authorisation of a request.	Complex Type Mandatory
2	username	Username for this merchant (or API user).	6 to 50 alpha-numeric characters Mandatory
2	password	Password for this merchant.	6 to 50 alpha-numeric characters Mandatory
1	requestReference	Unique field used if a valid response is not received to this request. The request can be called again with the same requestReference, returning the original response.	6 to 50 alpha-numeric characters Mandatory
1	paymentInstructions	Contains the elements relating to paymentInstructionV3. Up to 500 paymentInstructionV3 can be included.	Complex Type Mandatory
2	paymentInstructionV3	Contains the elements related to a single payment instruction.	Complex Type Mandatory
3	paymentDetails	Contains the below child elements.	Complex Type Mandatory
4	countryCode	The country the payment is being made to, there are additional country codes for some specific routes.	2 alpha characters as per the ISO 3166-1 English country code standard Mandatory
4	sourceCurrency	The currency code of your Worldpay AP account that should be debited.	3 alpha characters as per the ISO 4217 currency code standard Mandatory
4	sourceAmount	The amount of the funds to be debited from your Worldpay AP account.	Numeric that can contain two decimal places. Optional
4	targetCurrency	Specifies the currency of the payment if the payment currency is different to the source currency.	3 alpha characters as per the ISO 4217 currency code standard Mandatory
4	targetAmount	The amount of target currency that should be made to the beneficiary.	Numeric that can contain two decimal places Optional
4	sourceOrTarget	Whether the beneficiary should be paid the source (S) or target (T) amount. See payToBankAccountV3 for further details.	‘S’ or ‘T’, representing Source or Target (‘S’ is assumed if no parameter specified)
4	merchantReference	Your own reference for the payment which may appear on the beneficiary bank account statement.	1 to 50 alpha-numeric characters. Does not need to be unique Optional
4	paymentReference	Your unique identifier for this transaction, typically used for internal transaction IDs. This reference may appear on the beneficiary bank account statement.	1 to 50 alpha-numeric characters. should be unique Mandatory
4	email	Beneficiary’s email address. If populated the beneficiary will receive an email notification once the payment has been made (if set up).	1 to 255 alpha-numeric characters. Optional
4	mobile	For future use.	1 to 50 alpha-numeric characters. Optional
4	fastPayment	Indicates if the payment should go through a fast or normal payment route.	“Y” or “N” Optional
4	forexReference	For future use.	Optional
3	paymentDescription	Description for the payment, known as the purpose of payment.	Optional
3	paymentAdditionalData	For future use.	Complex Type Optional
4	AdditionalData	For future use.	Complex Type Optional
5	KeyName	For future use.	String Optional
5	KeyValue	For future use.	String Optional
3	paymentTemplate	You have three options on how to provide a paymentTemplate, explained in payToBankAccountV3	Complex Type Mandatory if paymentItemId is not provided
3	paymentItemId	The paymentItemId value can be returned from the OneClick BankDetailsCapture service, explained in Collecting the beneficiary’s bank details on page 6	GUID, 36 alpha-numeric characters. Mandatory if paymentTemplate is not provided

payToBankAccountV3Response schema

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<requestReference>string</requestReference>

<receivedDate>dateTime</receivedDate>

<statusMessage>string</statusMessage>

<epacsReference>string</epacsReference>

<merchantReference>string</merchantReference>

<paymentReference>string</paymentReference>

<countryCode>string</countryCode>

<sourceCurrency>string</sourceCurrency>

<sourceAmount>double</sourceAmount>

<targetCurrency>string</targetCurrency>

<targetAmount>double</targetAmount>

<sourceOrTarget>string</sourceOrTarget>

<merchantReference>string</merchantReference>

<paymentReference>string</paymentReference>

<email>string</email>

<mobile>string</mobile>

<fastPayment>string</fastPayment>

<forexReference>string</forexReference>

<paymentDescription>string</paymentDescription>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

</paymentAdditionalData>

</paymentDetails>

<payee>string</payee>

<accountNumber>string</accountNumber>

<bankName>string</bankName>

<bankCode>string</bankCode>

<branchCode>string</branchCode>

<branchAddress>string</branchAddress>

<accountType>string</accountType>

<iban>string</iban>

<swift>string</swift>

<ffc>string</ffc>

<fastPayment>string</fastPayment>

<bankAccountCurrency>string</bankAccountCurrency>

<additionalInfo1>string</additionalInfo1>

<additionalInfo2>string</additionalInfo2>

<additionalInfo3>string</additionalInfo3>

</bankDetails>

</Row>

</paymentTemplate>

<paymentStatusMessage>string</paymentStatusMessage>

</paymentResultV3>

<epacsReference>string</epacsReference>

<merchantReference>string</merchantReference>

<paymentReference>string</paymentReference>

<countryCode>string</countryCode>

<sourceCurrency>string</sourceCurrency>

<sourceAmount>double</sourceAmount>

<targetCurrency>string</targetCurrency>

<targetAmount>double</targetAmount>

<sourceOrTarget>string</sourceOrTarget>

<merchantReference>string</merchantReference>

<paymentReference>string</paymentReference>

<email>string</email>

<mobile>string</mobile>

<fastPayment>string</fastPayment>

<forexReference>string</forexReference>

<paymentDescription>string</paymentDescription>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

<KeyName>string</KeyName>

<KeyValue>string</KeyValue>

</AdditionalData>

</paymentAdditionalData>

</paymentDetails>

<payee>string</payee>

<accountNumber>string</accountNumber>

<bankName>string</bankName>

<bankCode>string</bankCode>

<branchCode>string</branchCode>

<branchAddress>string</branchAddress>

<accountType>string</accountType>

<iban>string</iban>

<swift>string</swift>

<ffc>string</ffc>

<fastPayment>string</fastPayment>

<bankAccountCurrency>string</bankAccountCurrency>

<additionalInfo1>string</additionalInfo1>

<additionalInfo2>string</additionalInfo2>

<additionalInfo3>string</additionalInfo3>

</bankDetails>

</Row>

</paymentTemplate>

<paymentStatusMessage>string</paymentStatusMessage>

</paymentResultV3>

</paymentInstructions>

</payToBankAccountV3Result>

</payToBankAccountV3Response>

</soap:Body>

</soap:Envelope>

payToBankAccountV3Response elements

Lvl

Element

Description

Values / Limitations

payToBankAccountV3Result

Contains elements related to the request.

Complex Type

requestReference

This is the requestReference supplied by the merchant when they made the request.

6 to 50 alpha-numeric characters

Mandatory

receivedDate

The date and time transactions are received by the Worldpay API, configured for GMT/UTC.

yyyy-mm-ddThh:mm:ss.nn
(the ‘T’ remains in the string and does not get replaced by a value. ‘nn’ represents hundredths of a second)

Mandatory

statusCode

Shows the result of the request.

This is an integer value and mandatory.

Status Code	Result
Zero and other positive values (except 2)	Success
Two (2)	Processing
Negative values	Failure

statusMessage

The outcome of the request, containing reason for failure if applicable.

1 to 255 alpha-numeric characters

Mandatory

paymentInstructions

Contains a collection of responses to the payment requests.

Complex Type

paymentResultV3

Contains the status and transaction related information related to the original payment request.

Complex Type

epacsReference

The Worldpay reference code for this transaction.

36 alpha-numeric characters

Mandatory

merchantReference

Returns the merchantReference field passed as part of the request.

1 to 50 alpha-numeric characters.

Non-unique and optional

paymentReference

Returns the unique paymentReference passed as part of the request. If no value was supplied then a unique value is returned.

1 to 50 alpha-numeric characters

Mandatory

paymentDetails

Returns the entire contents of the paymentDetails passed into the request.

Complex Type

Mandatory

countryCode

The country the payment is being made to.

2 alpha characters as per the ISO 3166-1 English country code standard

Mandatory

sourceCurrency

The currency code of your Worldpay AP account that should be debited.

3 alpha characters as per the ISO 4217 currency code standard

Mandatory

sourceAmount

The amount of the funds to be debited from your Worldpay AP account.

Numeric that can contain two decimal places

Optional

targetCurrency

Currency you asked for Worldpay to pay to the beneficiary.

3 alpha characters as per the ISO 4217 currency code standard

Mandatory

targetAmount

The amount of target currency that should be made to the beneficiary.

Numeric that can contain two decimal places

Optional

sourceOrTarget

Whether the beneficiary should be paid the source (S) or target (T) amount. See payToBankAccountV3 payToBankAccountV3 for further details.

‘S’ or ‘T’, representing Source or Target

merchantReference

Your own reference for the payment which may appear on the beneficiary bank account statement.

1 to 50 alpha-numeric characters

Optional

paymentReference

Your unique identifier for this transaction, typically used for internal transaction IDs. This reference may appear on the beneficiary bank account statement.

1 to 50 alpha-numeric characters

Mandatory

Beneficiary’s email address.

1 to 255 alpha-numeric characters

Optional

Mobile

For future use.

1 to 50 alpha-numeric characters

Optional

fastPayment

A flag indicating whether the payment should go through a fast or normal payment route.

String 1 character, “Y” or “N”

Optional

forexReference

For future use.

Optional

paymentDescription

A description for the payment, known as the purpose of payment.

Optional

paymentAdditionalData

For future use.

Complex Type

Optional

AdditionalData

For future use.

Complex Type

Optional

KeyName

For future use.

String

Optional

KeyValue

For future use.

String

Optional

bankDetails

Returns the beneficiary bank details

Complex Type

Mandatory

Payee

Beneficiary name

String, up to 50 characters

Optional

accountNumber

Beneficiary Bank Account Number

String, up to 35 characters

Optional

bankName

Beneficiary Bank Name

String, up to 50 characters

Optional

bankCode

Beneficiary Bank Code

String, up to 50 characters

Optional

branchCode

Beneficiary Branch Code

String, up to 50 characters

Optional

branchAddress

Beneficiary Branch Address

String, up to 50 characters

Optional

accountType

Beneficiary Account Type

String, 1 character

Optional

checkDigits

Beneficiary Account Check Digits

String, up to 2 characters

Optional

Iban

Beneficiary IBAN

String, up to 34 characters

Optional

Swift

Beneficiary SWIFT Code

String up to 11 characters

Conditional

Ffc

For Further Credit to

String up to 35 characters

Optional

fastPayment

Defines whether the payment should be sent through a Fast Payment route.

String 1 character, “Y” or “N”

Optional

bankAccountCurrency

Currency of the beneficiary bank account

3 alpha characters as per the ISO 4217 currency code standard.

Mandatory

additionalInfo1

Additional information you provide when requesting the Push to Account.

String, up to 50 characters

Optional

additionalInfo2

Additional information you provide when requesting the Push to Account.

String up to 50 characters

Optional

additionalInfo3

Additional information you provide when requesting the Push to Account.

String up to 50 characters

Optional

paymentTemplate

Extracted from the paymentTemplate contents passed into the request, or from the associated bank details captured in OneClick if the paymentItemId is passed into the request.

Complex Type

Optional

paymentItemId

The paymentItemId value returned from the OneClick BankDetailsCapture service, as explained in Collecting the beneficiary’s bank details.

GUID, 36 alpha-numeric characters.

Optional

paymentStatusCode

Returns a numeric code specific to the transaction in question.

Numeric between -32000 and 32000.

Mandatory

paymentStatusMessage

Returns the reason for a specific transaction.

1 to 255 alpha-numeric characters.

Mandatory

Example request and response

Request

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<statusMessage>Success</statusMessage>

<merchantReference>lecompte205</merchantReference>

<merchantReference>lecompte205</merchantReference>

</paymentDetails>

<payee>Monsieur Examinez LeCompte</payee>

<bankName>Banque Francais</bankName>

<branchAddress>1 Rue de Victor Hugo, Rouen</branchAddress>

</bankDetails>

<paymentItemId>da1553c5-567f-e211-90b2-0026b9792fb4</paymentItemId>a

<paymentStatusMessage>Success</paymentStatusMessage>

</paymentResultV3>

</paymentInstructions>

</payToBankAccountV3Result>

</payToBankAccountV3Response>

</soap:Body>

</soap:Envelope>

Response

<?xml version="1.0" encoding="UTF-8"?>

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

<soap:Body>

<statusMessage>Success</statusMessage>

<merchantReference>lecompte205</merchantReference>

<merchantReference>lecompte205</merchantReference>

</paymentDetails>

<payee>Monsieur Examinez LeCompte</payee>

<bankName>Banque Francais</bankName>

<branchAddress>1 Rue de Victor Hugo, Rouen</branchAddress>

</bankDetails>

</paymentTemplate>

<paymentStatusMessage>Success</paymentStatusMessage>

</paymentResultV3>

</paymentInstructions>

</payToBankAccountV3Result>

</payToBankAccountV3Response>

</soap:Body>

</soap:Envelope>