Menu

Pay by Bank app (PbBa)

Pay by Bank (PbBa) is a real-time payment method that allows your customers to pay through their existing and trusted bank app.

Prerequisite: You must be setup with PbBa, if you want to use it with Worldpay. For more information, contact your Relationship Manager.
You must also ensure you integrate the web merchant button. Seeherefor instructions provided by Mastercard.

Note: This guide covers both Direct and Hosted integrations. Our Hosted Payment Pages (HPP) handle the request and response messages. For details, go straight to theHosted Paymentssection.

On this page:

Best Practice: We recommend that you provide the values necessary for thePayConnect journeyto simplify the shopper experience. Details are available in theorder elements table.
PayConnect is not applicable to hosted payments.

Integrate

Order Elements

ElementAttribute/ Child ElementM/C/ODescription
<delivery>MandatoryThis indicates how the shopper will receive their goods/services. The delivery address will be shown in the shopper's bank app (dependent on bank)
typeMandatoryPossible values:
  • collect
  • digital
  • ship
<date>OptionalThe intended delivery date of the order as a year, month and dayOfMonth
<returnURL>MandatoryThe URL to which the shopper returns after completing their order in their bank app. This must be encoded. The length of the string must not exceed 512 characters. We recommend to keep the string as short as possible
<browser>MandatoryThe type and operating system of the shopper's device. This is used to form the "fingerprint" to issue aPayConnectcookie
deviceTypeMandatoryPossible values: 0 (Desktop), 1 (Mobile), 2 (Console) or 3 (Tablet)
deviceOSMandatoryPossible values: iOs, Android, Windows, Linux, Osx or other
<userAgentHeader>OptionalThe HTTP User-Agent request header sent by your shopper's browser. If not provided, a PayConnect cookie is not issued in the notification
<activeHeaders>OptionalThe active HTTP request headers (excluding the User-Agent header) sent by the shopper's browser. If not provided, a PayConnect cookie is not issued in the notification
<timezone>OptionalThe timezone setting of the shopper's browser. If not provided, a PayConnect cookie is not issued in the notification
<resolution>OptionalThe dimensions of the shopper's screen. If not provided, a PayConnect cookie is not issued in the notification
<shippingAddress>OptionalThe shipping/collection address of the purchased product. This is shown to the shopper in their bank app (depending on the bank) for <delivery type="ship"> and <delivery type="collect">
<firstName>MandatoryThe first name of the shopper, or the shopper’s title and full name (you can pass the title and full name if the entire length of the string does not exceed 100 characters)
<lastName>OptionalThe last name of the shopper. You can omit this if you decide to supply the shopper’s full name in the <firstName> field
<address1>MandatoryThe first line of the shopper’s delivery address
<address2>OptionalThe second line of the shopper’s delivery address
<address3>OptionalThe third line of the shopper’s delivery address
<postalCode>MandatoryThe postcode of the shopper’s delivery address
<city>MandatoryThe city of the shopper’s delivery address
<country>MandatoryThe country of the shopper’s delivery address
<shopperEmailAddress>OptionalAn email address associated with the digital delivery. Must be supplied when submitting <delivery type="digital">
<session>MandatoryThe shopper's browser session
shopperIPAddressMandatoryThe shopper's IP address

Initial XML Request

You will find full XML examples for each delivery type below

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <submit>
        <order orderCode="ORDER_CODE">
            <description>Pbba test order - digital delivery</description>
            <amount value="100" currencyCode="GBP" exponent="2"/>
            <paymentDetails>
                <PBBA-SSL>
                    <returnURL>http://pbbamerchant.com/shopping/confirmation</returnURL>
                    <delivery type="digital">
                        <date year="2100" month="03" dayOfMonth="01"/>
                    </delivery>
                    <cookieId>76fc8a875db63</cookieId>
                </PBBA-SSL>
                <session shopperIPAddress="127.0.0.1" id="ssn141590295"/>
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper@isp4u.com</shopperEmailAddress>
                <browser deviceType="3" deviceOS="ios">
                    <userAgentHeader>Mozilla/5.0</userAgentHeader>
                    <activeHeaders>test_active_header</activeHeaders>
                    <timeZone>GMT+2</timeZone>
                    <resolution>1920*1210</resolution>
                </browser>
            </shopper>
        </order>
    </submit>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <submit>
        <order orderCode="ORDER_CODE">
            <description>Pbba test order - collect from store</description>
            <amount value="100" currencyCode="GBP" exponent="2"/>
            <paymentDetails>
                <PBBA-SSL>
                    <returnURL>http://pbbamerchant.com/shopping/confirmation</returnURL>
                    <delivery type="collect">
                        <date year="2100" month="03" dayOfMonth="01"/>
                    </delivery>
                    <cookieId>76fc8a875db63</cookieId>
                </PBBA-SSL>
                <session shopperIPAddress="127.0.0.1" id="ssn566631664"/>
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper@isp4u.com</shopperEmailAddress>
                <browser deviceType="3" deviceOS="android">
                    <acceptHeader>text/html</acceptHeader>
                    <userAgentHeader>Mozilla/5.0</userAgentHeader>
                    <activeHeaders>test_active_header</activeHeaders>
                    <timeZone>GMT+2</timeZone>
                    <resolution>1920*1210</resolution>
                </browser>
            </shopper>
            <shippingAddress>
                <address>
                    <firstName>Fred</firstName>
                    <lastName>Bloggs</lastName>
                    <address1>1 Street Rd</address1>
                    <address2>Smallton</address2>
                    <address3>Bigton</address3>
                    <postalCode>AB1 2CD</postalCode>
                    <city>Cambridge</city>
                    <countryCode>GB</countryCode>
                </address>
            </shippingAddress>
        </order>
    </submit>
</paymentService>
Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <submit>
        <order orderCode="ORDER_CODE">
            <description>Pbba test order - ship to address</description>
            <amount value="100" currencyCode="GBP" exponent="2"/>
            <paymentDetails>
                <PBBA-SSL>
                    <returnURL>http://pbbamerchant.com/shopping/confirmation</returnURL>
                    <delivery type="ship">
                        <date year="2100" month="03" dayOfMonth="01"/>
                    </delivery>
                    <cookieId>76fc8a875db63</cookieId>
                </PBBA-SSL>
                <session shopperIPAddress="127.0.0.1" id="ssn601018296"/>
            </paymentDetails>
            <shopper>
                <shopperEmailAddress>shopper@isp4u.com</shopperEmailAddress>
                <browser deviceType="3" deviceOS="other">
                    <userAgentHeader>Mozilla/5.0</userAgentHeader>
                    <activeHeaders>test_active_header</activeHeaders>
                    <timeZone>GMT+2</timeZone>
                    <resolution>1920*1210</resolution>
                </browser>
            </shopper>
            <shippingAddress>
                <address>
                    <firstName>Fred</firstName>
                    <lastName>Bloggs</lastName>
                    <address1>1 Street Rd</address1>
                    <address2>Smallton</address2>
                    <address3>Bigton</address3>
                    <postalCode>AB1 2CD</postalCode>
                    <city>Cambridge</city>
                    <countryCode>GB</countryCode>
                </address>
            </shippingAddress>
        </order>
    </submit>
</paymentService>

Synchronous response

You must extract the below values from the synchronous XML response. Use them in the equivalent element (see table) to submit to the PbBa library as per theseinstructions.

ElementDescription

<pbbaRTP>

retrievalExpiry attribute= merchantRequestToPayResponseObject.retrievalTimeOutPeriod

confirmExpiry attribute = merchantRequestToPayResponseObject.confirmationTimeOutPeriod

cookieStatus attribute = merchantRequestToPayResponseObject.cookieStatus

retrievalExpiry is the number of seconds the shopper has to enter the BRN code in their bank app before the code expires for the two-device journey. For the one-device journey this is the number of seconds you have to invoke the shopper's bank app.

confirmExpiry is the number of seconds the shopper has to complete payment after entering the BRN code in their bank app for the two-device journey. For the one-device journey it is the number of seconds the shopper has to complete the payment after invoking the bank app.

cookieStatus:
Y - send as true when calling the merchant button.
You submitted a valid PayConnect token. The token exists and has not expired. The shopper has confirmed they want to accept PayConnect and the bank participates in the PayConnect service.
N- send as false when calling the merchant button.
You did not submit a PayConnect token, or the token you submitted is invalid
<BRN> = merchantRequestToPayResponseObject.pbbacodeA unique six character alpha code you have to extract and send to the merchant library. Show this code to the shopper for a two-device journey
<ApTransactionId>Unique identifier used by PbBa to locate the transaction
<ApTRId> = merchantRequestToPayResponseObject.secureTokenUnique transaction retrieval identifier used by PbBa. This field is shown on your shopper's bank statement (dependent on bank)
<CFI> = merchantRequestToPayResponseObject.bankNameThe short name of the shopper's bank. This is only returned when cookieStatus="Y"

Full XML synchronous response:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd" >
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
  <reply>
     <orderStatus orderCode="ORDER_CODE">
        <payment>
           <paymentMethod>PBBA-SSL</paymentMethod>
           <amount value="100" currencyCode="GBP" exponent="2" debitCreditIndicator="credit" />
           <lastEvent>SENT_FOR_AUTHORISATION</lastEvent>
        </payment>
        <pbbaRTP confirmExpiry="1800" retrievalExpiry="2500" cookieStatus="Y">
           <BRN>TESTCR</BRN>
           <ApTransactionId>7VJ848L6THA7PP2AERL602PM7C6GGGFL6LC</ApTransactionId>
           <ApTRId>292039112649699262</ApTRId>
           <CFI>Pingit</CFI>
        </pbbaRTP>
     </orderStatus>
  </reply>
</paymentService>

Invoke the merchant button applicable to the shopper journey

Add the button for either one device or two device payment.

One Device Flow (M-COMM journey)

The shopper is checking out on the device their bank app is installed on. Below are the two possible scenarios:

  1. The shopper has one bank app installed on the device they use to make the payment.
  2. The shopper has multiple bank apps installed on the device. The following occurs:

    • iOS loads the first bank app that is found
    • Android launches an app switcher where the shopper can choose the bank app they prefer

Two Device Flow (E-COMM journey)

The shopper is using a browser on a device other than the one where the bank app is installed.

The shopper has to manually launch the bank app. They enter a six-digit code (BRN) into the PbBa part of the bank app to retrieve the transaction details. You must display this code through the merchant library on your merchant UI.

Asynchronous Response

The asynchronous response tells you the outcome of a payment.

Ensure that you are updating your system usingorder notifications.

Possible outcomes are:

Payment StatusDescription
AUTHORISEDThe shopper has successfully completed the payment in-app. The order notification includes optionalPayConnect-related payload in the PbBa PayConnect block.

Note: You can expect authorisation within five - seven minutes of payment initiation. If you don’t receive authorisation within this time period, payments are usually not authorised. In some rare edge cases, the bank authorises this after a period of time (including the next day). You must have processes in place to handle this

REFUSEDThe payment has been refused by the bank, or the shopper has cancelled the order in-app
SENT_FOR_AUTHORISATIONThe shopper has abandoned the payment. You do not receive an order notification

Example asynchronous response:

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"
                                "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
    <notify>
        <orderStatusEvent orderCode="ORDER_CODE">
            <payment>
                <paymentMethod>PBBA-SSL</paymentMethod>
                <amount value="6" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
                <lastEvent>AUTHORISED</lastEvent>
                <balance accountType="IN_PROCESS_AUTHORISED">
                    <amount value="6" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
                </balance>
                <pbbaPayConnect setCookie="Y">
                    <cookieId>141d2e89-5df0-4e0c-8152-52937eecea3e</cookieId>
                    <cookieExpiryDays>180</cookieExpiryDays>
                </pbbaPayConnect>
            </payment>
            <journal journalType="AUTHORISED">
                <bookingDate>
                    <date dayOfMonth="04" month="09" year="2019"/>
                </bookingDate>
                <accountTx accountType="IN_PROCESS_AUTHORISED">
                    <amount value="6" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/>
                </accountTx>
            </journal>
        </orderStatusEvent>
    </notify>
</paymentService>

Additional elements in the asynchronous response:

ElementDescription
<cookieId>A cookie you can submit to invoke aPayConnecttransaction on a later payment for this shopper. This is valid as long as:
  • The number of days in <cookieExpiryDays> has not elapsed.
  • It has not already been used for an authorised transaction. A cookie is only valid for one authorisation. A new cookie is returned on each asynchronous response where the payment is authorised.
This element will not be included in the payload if a cookie is not issued
<cookieExpiryDays>The number of days that this cookie is valid for. If you submit an authorisation request with an expired cookie, the corresponding payment will not be completed with PayConnect.

This element will not be included in the payload if a cookie is not issued

Note: The setCookie attribute can be ignored and will be removed at a future release.

PayConnect (Two device flow with PayConnect)

Note: Only Barclays PingIT supports PayConnect. Other banks will support PayConnect in the future.

We recommend you support PayConnect as it reduces friction for returning shoppers.

PayConnect means the bank app opens automatically for returning shoppers using a two-device journey, without the need for the shopper to key in the six-digit code (BRN).

PayConnect works as follows:

  1. Supply the mandatory and optional sub-elements in the <browser> element on the shopper’s first transaction (we recommend you supply all these as standard on every request).
  2. On completion of their first payment, the shopper is prompted to accept the use of a cookie to make future payments easier.
  3. If they accept, we return the cookieId in theorder notificationof the AUTHORISED payment.
  4. Submit the cookie in the <cookieId> element in the next payment request. We will recognise the shopper’s device and automatically invoke their bank app for them to authenticate the payment.

Full XML example with cookieId (using <delivery type="digital">):

Copied!
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
   <submit>
       <order orderCode="ORDER_CODE">
           <description>PbBa test order - digital delivery</description>
           <amount value="100" currencyCode="GBP" exponent="2"/>
           <paymentDetails>
               <PBBA-SSL><returnURL>http://pbbamerchant.com/shopping/confirmation</returnURL>
               <delivery type="digital">
                       <date year="2100" month="03" dayOfMonth="01"/>
                   </delivery>
                   <!-- Mandatory for PayConnect -->
                   <cookieId>76fc8a875db63</cookieId>
               </PBBA-SSL>
               <session shopperIPAddress="127.0.0.1" id="ssn601018296"/>
           </paymentDetails>
           <shopper>
               <shopperEmailAddress>jshopper@myprovider.com</shopperEmailAddress>
               <!-- acceptHeader & userAgentHeader are optional and not neccessary, deviceType & deviceOS are required -->
               <browser deviceType="3" deviceOS="android">
                  <acceptHeader>text/html</acceptHeader>
                  <userAgentHeader>Mozilla/5.0</userAgentHeader>
                  <activeHeaders>test_active_header</activeHeaders>
                  <timeZone>GMT+2</timeZone>
                  <resolution>1920*1210</resolution>
              </browser>
           </shopper>
       </order>
   </submit>
</paymentService>

Once the payment is complete you will receive a new cookieId in yourorder notifications. This will replace the previous cookieId.

Hosted Payments

PbBa is compatible with our Hosted Payment Pages (HPP).

Get started

PbBa hosted uses the standardHPP (Hosted Payment Page) integration.

Payments for PbBa have the payment method mask: PBBA-SSL.

HPP Request

See ourstandard HPP order.

HPP Response

See ourstandard HPP response.

See also

Refunds

Return funds to your shopper without handling sensitive data. Go to ourrefunding APMs guidefor instructions to use the functionality.

In exceptional circumstances, your refund attempt may fail. In all such cases, a REFUND_FAILED journal is created. Where the information is known to us, we inform you of the reason for failure in the merchant interface and order notification. The following reason descriptions are possible:

Journal entryDescriptionNext Steps
ACCTSUSPThe CFI's account used to pay the original transaction is in a suspended status and unable to accept funds to the accountRetry at a later date, or work with the shopper to agree another method of reimbursement
ACCTCLSDThe CFI's account used to pay the original transaction is in a closed status and unable to accept funds to the accountDo not retry the payment. Work with the shopper to agree another method of reimbursement
ACCTNTVLDThe CFI's account no longer existsDo not retry the payment. Work with the shopper to agree another method of reimbursement
ACCTRETFAILUREA technical error has occurred and therefore no account details can be provided to the distributorRetry the refund after a set period (e.g. one hour)
OTHERRetry the refund after a set period (e.g. one hour)

Note: Do not exceed three refund attempts. If you are unable to refund after the third attempt please contact your Corporate Support Manager.
The term CFI in the description refers to the shopper's bank account. The term "distributor" refers to Worldpay.

Other Notes and Considerations

Warning: Do not use capture order modifications or inline captureDelay with PbBa, this causes reconciliation issues.