Capture bank details with payment templates

How to capture bank details with payment templates. Useful for specific country/currency combinations:

getPaymentTemplatesV2 request schema and elements
getPaymentTemplatesV2 response schema and elements
Example request and response, including a multiple options response

getPaymentTemplatesV2 request 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>

<auth>

<username>string</username>

<password>string</password>

</auth>

<requestReference>string</requestReference>

<country>string</country>

<currency>string</currency>

<language>string</language>

<templateType>string</templateType>

<extraField>string</extraField>

</criteria>

</getPaymentTemplatesV2>

</soap:Body>

</soap:Envelope>

getPaymentTemplatesV2 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	criteria	Contains further child elements describing the criteria for payment templates to retrieve.	Complex Type Mandatory
2	country	The country of the beneficiary’s bank.	2 alpha characters, as per the ISO 3166-1 English country code standard Mandatory
2	currency	The currency in which the beneficiary will receive funds.	3 alpha characters as per the ISO 4217 currency code standard Mandatory
2	language	The payment template labels and tooltips language, currently only available for “en” (English).	ISO 2-char language code Optional
2	paymentType	The payment type for which this template will be used	“Push to Account” Optional
2	extraField	For future use	Optional

getPaymentTemplatesV2Response schema

If no template is available for a combination, we provide a default International template.

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

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

<soap:Body>

<receivedDate>dateTime</receivedDate>

<statusMessage>string</statusMessage>

<requestReference>string</requestReference>

</paymentTemplate>

</paymentTemplates>

</getPaymentTemplatesV2Result>

</getPaymentTemplatesV2Response>

</soap:Body>

</soap:Envelope>

getPaymentTemplatesV2Response elements

Lvl	Element	Attribute	Description	Values / Limitations
1	getPaymentTemplatesV2Result		Contains elements related to the status of the request and paymentTemplates returned for successful requests	Complex Type Mandatory
2	receivedDate		The date and time the request was 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
2	statusCode		Shows the result of the request. Zero and positive values signify success, negative values represent failure. A full list of status codes and their meanings is shown in Status Codes.	Numeric between -32000 and 32000. Mandatory
2	statusMessage		The outcome of the request, containing reason for failure if applicable.	1 to 255 alpha-numeric characters. Mandatory
2	requestReference		The requestReference passed in the getPaymentTemplates request.	6 to 50 alpha-numeric characters Mandatory
2	paymentTemplates		Contains paymentTemplate children.	Complex Type Optional
3	paymentTemplate		A number of Row elements representing the bank data that needs to be captured. A Row element can contain further child Row elements and various attributes.	Complex Type Mandatory
		TemplateID	A unique identifier associated with the given template.	Mandatory
		Name	The country name the template suits.	Up to 50 characters. Mandatory
		TransferTypeDesc	The bank transfer type the template suits.	Up to 50 characters. Examples are “International Payment”, “Local Payment” Mandatory
		TemplateType	An enumeration for the template type.	Integer Optional
		TemplateCurrency	The currency the template suits.	3 alpha characters as per the ISO 4217 currency code standard Optional
		TemplateCountry	The country code the template suits.	2 alpha characters, as per the ISO 3166-1 English country code standard Mandatory
		ErrorCode	Whether a submitted template contains invalid data (Not used in getPaymentTemplates request).	Integer Optional
		ErrorMsg	A descriptive error message related to the ErrorCode attribute value (Not used in getPaymentTemplates request).	String Optional
4	Row		Defines a field or row in a payment template. The properties of each field are defined as attributes in the Row element.	Complex Type Mandatory
		Section	If provided, can be a header for a subset of bank details when the payment template is rendered on the merchant’s side. If not provided, the row can be expected to refer to the beneficiary.	String For example, “Beneficiary Details”, “Beneficiary Bank Details”. Optional
		SectionTag	If provided, indicates the type of entity the row references. If not provided, the row can be expected to refer to the beneficiary.	String For example, “R” for remitter, “B” for beneficiary Optional
		Title	The label of the bank data field that the row represents.	String Mandatory
		FieldType	The type of UI control that should be used to capture this data.	String For example, “Input”, “Select” Mandatory
		Id	The Id that should be assigned to the control capturing the data.	String All possible values are listed in Payment template fields. Mandatory
		InputType	Specifies whether the data captured can be numeric.	String For example: “n” for numeric, “na” for alpha-numeric Mandatory
		Required	Indicates if the bank data field is mandatory.	Boolean String Mandatory
		Visibility	Indicates if the row should be displayed to the customer. If not provided, the row should be displayed.	Boolean String Mandatory
		LabelTooltip	Used where an explanation is added about the bank data being captured.	String Mandatory
		Tooltip	Instructs the user about restrictions for particular bank data fields.	String Mandatory
		MinLength	The minimum length accepted.	Integer Mandatory
		MaxLength	The maximum length accepted.	Integer Mandatory
		MaxLengthIncludesNonAlpha	Indicating whether non-alpha characters should contribute to length restrictions.	Boolean String Mandatory
		OptionText	Used in child rows of Rows where the InputType indicates a selection, usually a dropdown list. The attribute value specifies the text that should appear in the dropdown list.	String Optional
		OptionValue	Used in child rows of Rows where the InputType indicates a selection, usually a dropdown list. The attribute value specifies the value that should be associated with this option when selected.	String Optional
		Spacer	Used to indicate what separator character should be used when multiple child Rows exist under a parent Row.	String Optional
		ErrorCode	Indicates if the specific row of a submitted payment template contains invalid data. (Not used in getPaymentTemplates request).	Integer Optional
		ErrorMsg	A descriptive error message related to the ErrorCode attribute value.	String Optional
		Value	The captured value for the given bank data field. Not used in getPaymentTemplates request.	String Optional

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>

<auth>

<username>amerchant25</username>

<password>s23dLjdf</password>

</auth>

<requestReference>Request01</requestReference>

</criteria>

</getPaymentTemplatesV2>

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

<requestReference>Request01</requestReference>

</Row>

</PaymentTemplate>

</paymentTemplates>

</getPaymentTemplatesV2Result>

</getPaymentTemplatesV2Response>

</soap:Body>

</soap:Envelope>

Multiple options example response

When multiple options are available for a field, all the available options for that field will be returned in the response. This should be used for rendering drop down lists. An example response containing a field with multiple options is:

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

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

<soap:Body>

<statusMessage>Success</statusMessage>

<requestReference>Request01</requestReference>

</Row>

</Row>

</paymentTemplate>

</paymentTemplates>

</getPaymentTemplatesV2Result>

</getPaymentTemplatesV2Response>

</soap:Body>

</soap:Envelope>

Payment template fields

Beneficiary Details

Id	Content	Value / Limitations
CustomerName	If the beneficiary (payee) is an individual, this should be their full name, including first and last name (no initials) with a space in-between. If the beneficiary (payee) is a company, this should be the full company name.	String up to 50 characters Mandatory
Title	Title of the beneficiary, e.g. Mr/Ms/Mrs etc. "Company" can be used to indicate the beneficiary is not an individual.	String up to 15 characters Optional
PlaceOfBirth	Beneficiary city/state of birth. Only applicable to an individual beneficiary type.	String up to 50 characters Optional
CountryOfBirth	Beneficiary Country of birth in the ISO 2-character format. Only applicable to an individual beneficiary type.	String 2 characters Optional
DateOfBirth	Beneficiary date of birth. Only applicable to an individual beneficiary type.	Date in the format DD-MM-YYYY Optional
AddressLine1	First part of the beneficiary residential address.	String up to 100 characters Optional
AddressLine2	Second part of the beneficiary residential address.	String up to 100 characters Optional
AddressLine3	Third part of the beneficiary residential address.	String up to 100 characters Optional
City	City of the beneficiary residential address.	String up to 50 characters Optional
State	Full name, not 2 character, of the State or County or Province of the beneficiary residential address.	String up to 50 characters Optional
CountryCode	Country code of the beneficiary residential address.	String 2 characters ISO 3166-1 English country code standard Optional
Postcode	Postcode of the beneficiary residential address.	String up to 20 characters Optional

Identification

Id	Content	Value / Limitations
IdType	Type of beneficiary identification being captured: 0 = Unknown 2 = NationalID (Only applicable to an individual beneficiary type) 3 = DriverLicence (Only applicable to an individual beneficiary type)	String 1 character Optional
IdValue	Value of the beneficiary identification being captured.	String up to 50 characters Optional

Content

Value / Limitations

IdType

Type of beneficiary identification being captured:

0 = Unknown
2 = NationalID (Only applicable to an individual beneficiary type)
3 = DriverLicence (Only applicable to an individual beneficiary type)

String 1 character

Optional

IdValue

Value of the beneficiary identification being captured.

String up to 50 characters

Optional

Beneficiary Bank Details

Id	Content	Value / Limitations
BankAccountNumber	Bank account number of the beneficiary (payee). If not provided then the IBAN is mandatory.	String up to 35 characters Conditional
IBAN	The International Bank Account Number is the account number of the beneficiary (payee). If not being provided then the BankAccountNumber is mandatory.	String up to 34 characters Conditional
SWIFT	The Bank Identification Code of the beneficiary (payee) bank.	String either 8 or 11 characters Optional
AccountType	The type of account held by the beneficiary e.g. Checking or Savings: 0 = Checking 1 = Savings 2 = Cheque	String 1 character Optional
BankName	Name of the beneficiary (payee) bank.	String up to 50 characters Optional
BankCode	Bank code (sometimes known as Sort Code or Routing Code) of the beneficiary bank.	String up to 50 characters Optional
BranchCode	Branch code of the beneficiary bank.	String up to 50 characters Optional
AdditionalInfo1	Additional data which doesn’t fit into any other field.	String up to 50 characters Optional
AdditionalInfo2	Additional data which doesn’t fit into any other field.	String up to 50 characters Optional
AdditionalInfo3	Additional data which doesn’t fit into any other field.	String up to 50 characters Optional
BranchAddress	Location of the beneficiary (payee) bank. The general location is acceptable e.g. “London”.	String up to 50 characters Optional

Remitter Details

Id	Content	Value / Limitations
R_FirstName	If the remitter (payee) is an individual, supply their first name (no initials). For entities, provide the full legal name.	String up to 30 characters Conditional Mandatory for Payment Service Provider merchants. Optional for all others.
R_LastName	If the remitter (payee) is an individual, supply their last name (no initials). For entities, provide the full legal name.	String up to 30 characters Conditional Mandatory for Payment Service Provider merchants. Optional for all others.
R_Title	Title of the remitter, e.g. Mr/Ms/Mrs etc. "Company" can be used to indicate the remitter is not an individual.	String up to 15 characters Optional
R_PlaceOfBirth	Remitter city/state of birth. Only applicable to an individual remitter type.	String up to 50 characters Optional
R_CountryOfBirth	Remitter Country of birth in the ISO 2-character format. Only applicable to an individual remitter type.	String 2 characters Optional
R_DateOfBirth	Remitter date of birth in format DD-MM-YYYY. Only applicable to an individual remitter type.	Date in the format DD-MM-YYYY Optional
R_AddressLine1	First part of the remitter residential address.	String up to 100 characters Conditional Mandatory for Payment Service Provider merchants. Optional for all others.
R_AddressLine2	Second part of the remitter residential address.	String up to 100 characters Optional
R_AddressLine3	Third part of the remitter residential address.	String up to 100 characters Optional
R_City	City of the remitter residential address.	String up to 30 characters Conditional Mandatory for Payment Service Provider merchants. Optional for all others.
R_State	Full name, not 2 character, of the State or County or Province of the remitter residential address.	String up to 35 characters Conditional Mandatory for Payment Service Provider merchants for countries with notion of states. Optional for all others.
R_CountryCode	2-character ISO country code of the remitter residential address.	String 2 characters ISO 3166-1 English country code standard Conditional Mandatory for Payment Service Provider merchants. Optional for all others.
R_Postcode	Postcode of the remitter residential address.	String up to 10 characters Conditional Mandatory for Payment Service Provider merchants. Optional for all others.

Remitter Identification

Id	Content	Value / Limitations
R_IDType	Type of remitter identification being captured: 0 = Unknown 2 = NationalID (Only applicable to an individual remitter type) 3 = DriverLicence (Only applicable to an individual remitter type)	String 1 character Optional
R_IDValue	Value of the remitter identification being captured.	String up to 50 characters Optional

Content

Value / Limitations

R_IDType

Type of remitter identification being captured:

0 = Unknown
2 = NationalID (Only applicable to an individual remitter type)
3 = DriverLicence (Only applicable to an individual remitter type)

String 1 character

Optional

R_IDValue

Value of the remitter identification being captured.

String up to 50 characters

Optional

Request the payment