Pay By Bank

Pay By Bank

Pay By Bank (also known as Instant EFT or iEFT) is a payment method that allows customers to pay directly from their bank accounts in real-time, providing an immediate, secure, and seamless checkout experience. This method is particularly popular in South Africa, enabling customers to make instant electronic funds transfers without using traditional card payments.

Introduction

Pay By Bank is a widely used alternative payment method in South Africa, offering customers a convenient way to pay for goods and services directly from their bank accounts. Integrating Pay By Bank with PayOS enables you to provide a fast, user-friendly payment option while leveraging PayOS to route payments to your chosen Payment Service Provider (PSP). This guide explains how to integrate Pay By Bank (Instant EFT) into your application or website using PayOS.

Pre-requisites

Before accepting Pay By Bank payments through PayOS, ensure you meet the following requirements:

• PayOS integration:
  You have integrated with PayOS, either using our hosted checkout, SDK, or server-to-server API.

• Payment processor configuration:
  You have set up an integration account for Pay By Bank with a supported Payment Service Provider (PSP) in PayOS. Pay By Bank services in South Africa are typically supported through PSPs that facilitate instant EFT, such as Stitch, Cellulant, PayU, or Ozow. Ensure that the commercial relationships with these PSPs are in place or can be utilised through PayOS.

• Enable Pay By Bank:
  You have enabled Pay By Bank as a payment option in your PayOS configuration through the PayOS Portal.

• Meta fields setup:
  If Pay By Bank requires specific meta fields (such as bank selection fields or reference details), ensure these fields are correctly configured under Merchant configurations -> Meta fields on your PayOS dashboard and included in your requests.

Ways to integrate Pay By Bank with PayOS

PayOS supports multiple integration methods for offering Pay By Bank at checkout:

1. PayOS hosted checkout
   Using PayOS’s hosted checkout is the simplest way to accept Pay By Bank payments. With this option:

   • There’s minimal development required on your end.
   • PayOS automatically displays the Pay By Bank method during checkout.
   • You can control the payment methods offered through the session creation API call, specifying Pay By Bank as a restricted method if desired.

2. PayOS SDK
   If you prefer more control over your checkout experience, you can integrate with the PayOS SDK:

   • The SDK provides UI components to include Pay By Bank as a payment method seamlessly.
   • It simplifies capturing any required inputs (like selecting a bank from a list) and initiating transactions, without extensive server-side coding.
   • Consult the PayOS SDK documentation for detailed steps on integrating Pay By Bank.

3. Server-to-server integration
   For complete control over your payment process and checkout flow, you can integrate Pay By Bank using PayOS’s server-to-server APIs:

   • This approach offers greater flexibility in implementing the payment flow and handling customer data.
   • You will be responsible for capturing necessary inputs (e.g., bank selection) and forwarding them to PayOS.

Let’s explore the server-to-server approach in more detail.

Retrieving available payment methods

Using the PayOS API, you can retrieve a list of available payment methods for a given checkout session by calling the GET /v1/payment/available-methods endpoint with a sessionId. For Pay By Bank, the method type is typically returned as payByBank.

Request:

$
curl -G https://api.payos.money/api/v1/payment/available-methods \
>
     -d sessionId={sessionId}

Response:

1
{
2
  "success": true,
3
  "availableMethods": [
4
    {
5
      "type": "payByBank",
6
      "name": "Pay by Bank (Instant EFT)",
7
      "requiredInput": [
8
        {
9
          "name": "bankName",
10
          "type": "select",
11
          "label": "Select Bank",
12
          "options": [
13
            "Bank A",
14
            "Bank B",
15
            "Bank C"
16
          ]
17
        }
18
      ]
19
    },
20
    ...other methods...
21
  ]
22
}

In this response:

• The Pay By Bank payment method is listed with "type": "payByBank".
• The requiredInput field indicates that the customer must select their bank from a list of available banks.

Creating a checkout session

To create a checkout session that includes Pay By Bank as a payment option, make a POST request to the /v1/checkout/session endpoint. You can specify which payment methods to offer in the paymentMethods array. For Pay By Bank, set "type": "payByBank".

$
curl -X POST https://api.payos.money/api/v1/checkout/session \
>
     -H "Content-Type: application/json" \
>
     -d '{
>
  "amount": 20000,
>
  "currency": "ZAR",
>
  "integrationType": "hosted",
>
  "merchantReference": "ORDER67890",
>
  "redirectUrl": "https://merchant.com/redirect",
>
  "brand": "merchant-brand-key",
>
  "payerToken": "TOKEN_abcdef123456",
>
  "payerDetails": {
>
    "payerName": "Siyanda Mthembu",
>
    "payerEmailAddress": "siyanda.mthembu@example.com",
>
    "payerMobileNumber": "0723456789",
>
    "payerLocation": "ZMB"
>
  },
>
  "paymentMethods": [
>
    {
>
      "type": "payByBank",
>
      "restrict": true
>
    }
>
  ]
>
}'

Response:

1
{
2
  "sessionId": "SESSION_abcdef123456",
3
  "paymentLink": "https://payos.money/checkout/SESSION_abcdef123456"
4
}

In this example:

• The paymentMethods array restricts the session to only the Pay By Bank payment method ("type": "payByBank").
• restrict set to true ensures that this session provides only Pay By Bank as the available payment method.
• The sessionId in the response references this specific checkout session, which can be used to retrieve available methods, complete the payment, or make further adjustments before checkout completion.

Handling the payment

After creating a session, your application can direct customers to the paymentLink if using the hosted checkout. If you’re using the PayOS SDK or a server-to-server integration, you’ll use the session details to process the Pay By Bank payment. This involves:

• Displaying a list of banks (retrieved from the availableMethods API response) for the customer to select.
• Collecting necessary customer inputs (like bank selection) and passing them to PayOS through the appropriate API calls.

Supported regions / countries

Pay By Bank through PayOS is currently supported in the following regions and countries:

(Note: Support for additional regions and countries may be added in the future. Check PayOS documentation or contact support for updates.)

Supported workflows and services

The following table outlines the workflows and services supported when using Pay By Bank with PayOS:

Ensuring a seamless and secure payment experience

To optimise your integration and ensure customer satisfaction, consider the following best practices:

• Prioritise security and compliance:
  Protecting customer data is paramount. PayOS adheres to PCI DSS standards and other relevant regulations. Ensure you also follow any additional region-specific compliance requirements, especially when handling sensitive financial information across different countries.

• Focus on a smooth user experience:
  Present payment methods clearly and intuitively. When customers reach the checkout stage, they should easily recognise and trust the payment options available. For example, highlight local payment methods prominently in regions where they are popular.

• Monitor performance and reliability:
  Keep an eye on transaction success rates and processing times. PayOS’s dashboard provides insights into each payment method’s performance, enabling you to resolve any latency or downtime issues quickly to maintain customer trust.

• Scale with your business growth:
  As your business expands, your payment needs may evolve. PayOS’s flexible infrastructure makes it easy to add new payment methods, integrate with additional PSPs, or adjust your configurations to handle increased transaction volumes without compromising performance.

Additional resources and next steps

With PayOS, managing and enabling diverse payment methods becomes more efficient and manageable. For detailed integration instructions, coding examples, and advanced customisation options, explore these resources:

• PayOS API documentation
  Dive deeper into PayOS’s API endpoints and discover how to implement server-to-server integrations, handle advanced payment flows, and manage transactions programmatically.

• Integration Guides
  Review step-by-step guides for integrating PayOS’s SDKs or connecting to popular PSPs, ensuring a smooth setup experience regardless of your technical background or business model.

By configuring payment methods with PayOS, you can offer your customers a streamlined and secure checkout experience tailored to their preferences and regional payment norms. Continuously refine your payment configurations and leverage PayOS’s robust features to stay agile in an ever-evolving e-commerce landscape.