Pay by Bank App

Pay by Bank App (PbBA) is a payment method available to payers in the United Kingdom that allows them to use their banking app on their smartphone to pay for goods and services without them having to download any applications. Payers have complete visibility to their bank balance during transactions and the peace of mind that their transaction(s) will be authorized and completed in a secure and trusted environment of their mobile banking app. By utilizing the Faster Payment Service, PbBA offers almost real-time payments and settlement along with the following benefits:

  • Reduced friction and abandonment that may help increase revenue
  • Reduced customer disputes that could lead to reduction in costs
  • Potential to reduce fraud
  • Ready for PSD2, SCS, and other regulatory requirements

PbBA currently supports transactions and settlements in GBP currency only.

Prerequisites

Before you begin integrating PbBA in your environment, ensure that you have:

  • Registered your merchant account with your local payment method aggregator.
  • Linked a bank account in GBP currency with your merchant account that is registered with your local payment aggregator.
  • Configured your gateway merchant profile using the account details provided by your local payment method aggregator.

Pay by Bank App Integration

Pay by Bank App is supported in API version 54 and later, and only by using the Pay operation.

To integrate to the gateway to use PbBA, initiate a Pay request and provide the following fields:

Request field Required Type Description
sourceOfFunds.type
No String Set the value to PBBA.
sourceOfFunds.provided.pbba
No String Additional details for Pay by Bank App payment method.
sourceOfFunds.provided.pbba.returnUrl
No String The URL of your app to which the payer is redirected from their mobile banking app.
WS API PAY example
  {
    "apiOperation": "PAY",
    "order": {
      "amount": "45.46",
      "currency": "GBP"             },
    "sourceOfFunds": {
      "provided": {
        "pbba": {
          "returnUrl": "<URL_of_merchant_app>"
        }
      },
      "type": "PBBA"
      },
    "transaction": {
      "source": "INTERNET"
    }
  }
 

Response Parameters

Response parameter Description
sourceOfFunds.provided.pbba.paymentRequestId A unique 18 character payment request identifier, which is also known as the Pay by Bank app secure token. It is used when the payer's banking app is invoked on their mobile device during the shopping experience.
sourceOfFunds.provided.pbba.paymentRequestInputCode A one-time 6 character code that identifies the payment request, which is also known as the Pay by Bank app Basket Reference Number. This code may be used by the payer to confirm the payment within their mobile banking app.
WS API response example
{
 "gatewayEntryPoint": "WEB_SERVICES_API",
 "merchant": "PBBA_MER_2",
 "order": {
   "amount": 45.46,
   "chargeback": {
       "amount": 0,
       "currency": "GBP"
   },
   "creationTime": "2019-09-17T11:19:34.813Z",
   "currency": "GBP",
   "fundingStatus": "IN_PROGRESS",
   "id": "13347",
   "status": "INITIATED",
   "totalAuthorizedAmount": 0,
   "totalCapturedAmount": 0,
   "totalRefundedAmount": 0
 },
 "response": {
   "acquirerCode": "PENDING",
   "gatewayCode": "SUBMITTED"
 },
 "result": "SUCCESS",
   "sourceOfFunds": {
     "provided": {
         "pbba": {
           "paymentRequestId": "120191291357676444",
           "paymentRequestInputCode": "PLJGLW"
         }
     },
     "type": "PBBA"
   },
   "timeOfRecord": "2019-09-17T11:19:34.813Z",
   "transaction": {
     "acquirer": {
       "id": "PBBA_PPRO",
       "merchantId": "MPGTESTCONTRACT",
       "timeZone": "+0000",
       "transactionId": "509260333"
     },
     "amount": 45.46,
     "currency": "GBP",
     "funding": {
       "status": "IN_PROGRESS"
     },
     "id": "1",
     "source": "INTERNET",
     "type": "PAYMENT"
   },
 "version": "54"
} 

Transaction Response Codes

The table below shows the transaction response codes for the possible scenarios you may encounter after initiating a PbBA payment.

Retrieve transaction response What this means...
response.gatewayCode=APPROVED
result=SUCCESS
The payment is successful.
response.gatewayCode=PENDING
result=PENDING
The gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen to notifications from the gateway.
response.gatewayCode=DECLINED or ACQUIRER_SYSTEM_ERROR
result=FAILURE
The payment was declined. Offer the payer the option to try another payment method.
In the case of an ACQUIRER_SYSTEM_ERROR you may want to inquire with the acquirer the reason for payment failure, or you can try RETRIEVE_TRANSACTION again.
response.gatewayCode=TIMED_OUT
result=FAILURE
Treat this as a declined payment. The gateway will make any attempt to ensure the transaction was not successful or will revert the transaction.

Refunds

PbBA supports full or partial refund payments. You must be configured for refunds on the Suncorp Gateway and on your merchant account with your local payment method aggregator.

Standalone refunds are not supported for PbBA transactions.

Testing Your PbBA Integration

You must have access to the Bank3 app and it must be integrated with the Suncorp Gateway to test your PbBA integration. Contact Mastercard to request access to the Bank3 app for testing purposes, after which you will receive an email notification when access has been granted.

When you are granted access to the Bank3 app and it is integrated with the Suncorp Gateway, use your non test prefix merchant ID and test your integration using one of the following options.

To test your PbBA integration where the Bank3 app and your app are on the same mobile device, follow these steps:

  1. Tap the zapp://paymentRequestId URL either in a mobile browser or within the mobile app.
  2. Follow the prompts to log in to the Bank3 app using your PIN or TouchID.
  3. Complete the payment by selecting a dummy account and you will automatically be redirected to the merchantredirecturl in a browser.

To test your PbBA integration where the Bank3 app and your app are on different mobile devices, follow these steps:

  1. In the Bank3 app tap the PbBA logo in the bottom right of your screen and enter the six character code returned in paymentRequestInputCode.
  2. Select a dummy bank account, tap Confirm payment and the local payment method aggregator hosted page will automatically redirect to the URL set in merchantredirecturl.

Copyright © 2021 Suncorp