Capture bank details with OneClick

To start capturing bank details with OneClick, use an HTTPS Form Post to submit a specific set of parameters to the OneClick API.

Worldpay AP uses a browser redirect to return the shopper to your website, including bank data that has been captured by the service.

Request parameters

To start the Bank Details Capture process, submit this data to the OneClick URL:

Parameter name	Type (Size)	Required	Description
service	String(18)	Mandatory	Value must be ‘BANKDETAILSCAPTURE’
merchantID	String(9)	Mandatory	Your 9-character merchant code. Contact us if you don’t know your code.
country	String(2)	Mandatory	The country where the beneficiary bank account is held.
customerRef	String(12)	Mandatory	Alpha-numeric characters identifying the customer. As we do not process this reference, it can be your own reference.
language	String(2)	Optional	The ISO 639-1 2-character language code for this customer. It defaults to English.
receiveCurrency	String(3)	Optional	The ISO currency code of the beneficiary bank account currency. If unknown, we use the local currency code of the country.

Example request form

This is example HTML form initiating the process to capture bank account details for a Euro payment to Spain:

Returning captured bank details to you

After the beneficiary bank account data has been validated and confirmed it is returned to your website when the customer is redirected.

We can configure three URLs for the user to be redirected to:

• SUCCESS Redirected under normal circumstances

• CANCEL Redirected if they click the Cancel button

• ERROR Redirected if there is an error

You can choose how to receive the captured bank details:

1. Returned as query string parameters appended to your redirect URL (this is the default: contact us if you prefer to use the other formats)

2. Posted back in a paymentTemplate XML structure

3. Returned as a single query string paymentItemId parameter

Returning bank detail query string parameters

You can opt to receive the bank details in a series of query string parameters instead of the captured bank details.

This screen is an example of a French bank details form populated with bank details:

This snippet shows the query string parameters returned if the above form was submitted:

Parameter Name	Value
addressLine1	123 Rue Tisserand
addressLine2	Vaugirard
beneficiaryCountry	FR
City	Paris
Country	FR
Currency	EUR
customerRef	EVTEU1234567
dateOfBirth	1/1/1980
Email	testing@envoyservices.com
Language	EN
postalCode	123456
Status	SUCCESS
targetCurrency	EUR

Returning paymentTemplate XML

If you have opted to receive bank details in an XML string they will be returned in an HTTP Post field called paymentTemplate.

This is the paymentTemplate XML schema:

paymentTemplate schema

Lvl	Element	Attribute	Description	Values/Limitations
1	paymentTemplate		Contains a number of Row elements that represent the captured bank data.	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	Describes the type of bank transfer the template suits. Examples: “International Payment”, “Local Payment”	Up to 50 characters Mandatory
		TemplateType	An enumeration for the template type.	Integer Optional
		TemplateCurrency	The currency for the template suits.	3 alpha characters as per the ISO 4217 currency code standard. Optional
		TemplateCountry	The country code for the template suits.	2 alpha characters, as per the ISO 3166-1 English country code standard Mandatory
		TemplateLanguage	The language presented to the Shopper.	2 alpha characters as per the ISO 639-1 language code standard
2	Row		Defines the Id and value of each captured field.	Complex Type 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
		Value	The captured value for the given bank data field. Not used in getPaymentTemplates request.	String Optional

Example of Returning paymentTemplate XML

This screen is an example of a French bank details form populated with bank details:

The table below shows the fields returned to your website if the above form was submitted.

The paymentTemplate field contains all the bank details that have been collected but in an XML structure.

Parameter	Value
addressLine1	123 Rue Tisserand
addressLine2	Vaugirard
beneficiaryCountry	FR
city	Paris
country	FR
currency	EUR
customerRef	EVTEU1234567
dateOfBirth	1/1/1980
email	something@worldpay.com
language	EN
paymentTemplate	<paymentTemplate Name="France" TransferTypeDesc="Euro Payment" TemplateID="6e189719ecdae011a6740026b9792fb4" TemplateType="3" TemplateCountry="FR" TemplateCurrency="EUR" TemplateLanguage="en"><Row Id="BankName" Value="BNP Paribas" /><Row Id="CustomerName" Value="Olivier Nocher" /><Row Id="IBAN" Pleceholder="Please enter IBAN" Value="FR1420041010050500013M02606" /><Row Id="SWIFT" Value="BNPAFRPP" /><Row Id="AddressLine1" Value="123 Rue Tisserand" /><Row Id="AddressLine2" Value="Vaugirard" /><Row Id="City" Value="Paris" /><Row Id="Postcode" Value="123456" /><Row Id="CountryCode" DataSource="CountryListDataSource" Value="FR" /><Row Id="DateOfBirth" Value="01/01/1980" /></paymentTemplate>
postalCode	123456
status	SUCCESS
targetCurrency	EUR

You can extract and submit paymentTemplate with the payToBankAccountV3 API as described in PayToBankAccountV3.

Returning paymentItemId query string parameter

You can opt to receive a single paymentItemId as a query string parameter instead of the captured bank details. We'll capture and store bank details entered by the Shopper and assign them a paymentItemId.

Use this paymentItemId in the MerchantAPI payToBankAccountV3 call as the paymentItemId element. You won't need to pass actual bank details in the API call, reducing complexity and security risks of storing and submitting bank data.

The paymentItemId can be reused any time you want to make a payment with those bank details.

This screen is an example of a French bank details form populated with bank details:

This snippet shows the query string parameters returned if the above form was submitted:

Parameter name	Value
customerRef	EVTEU1234567
language	en
country	FR
currency	EUR
email	testing@envoyservices.com
targetCurrency	EUR
paymentItemId	7f6f7337-1a80-e611-b795-005056b70383
status	SUCCESS

For further information, see Use the paymentItemId.