Open Banking - Purchase 1: with request for customer's consent and redirection

General information

To perform a purchase by using Payment Page with the Open Banking payment method:

1. Send a request with all the required parameters and signature to the Benker URL.
2. Accept the callback with the purchase result from the payment platform.

The following figure shows the complete purchase processing flow in the Open Banking payment method.

Request

The following table lists the parameters that you have to include in the request for purchase through the checkout page with the Open Banking payment method.

Here is an example of the data from a request to open the checkout page by using EPayWidget:

EPayWidget.run(
	{
		project_id: 1234,
		payment_id: 'payment_47',
		customer_id: 'customer_123',
		customer_first_name: 'John',
		customer_last_name: 'Doe',
		customer_email: 'johndoe@example.com',
		customer_account_number: 'DE89370400440532013000',
		payment_currency: 'EUR',
		payment_amount: 10000,
		force_payment_method: 'open-banking',
		merchant_return_url: 'http://example.com/return',
		signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=='
	}
)

Displaying bank icons on the checkout page

In the Open Banking payment method, the payments are performed through specific banks. When making a purchase on the checkout page, the customer first chooses a payment method and then selects the bank.

The Open Banking payment method offers several options to display bank icons on the checkout page:

• Choosing the bank in two steps First, the customer chooses Open Banking among other payment methods, and then selects the bank from the list by entering either the name of the bank or the International Bank Account Number (IBAN). This is the default behavior.
• Displaying only banks of the Open Banking payment method For the customer to see only banks available in the Open Banking payment method (without other payment methods), add the force_payment_method parameter to the request and set it to open-banking.
• Enforcing only one bank If you want the customer to go directly to their bank service to complete the payment (without choosing a payment method and bank on the checkout page), use the force_payment_method parameter with the open-banking value in the request, add the payment_extra_param parameter, as well as account_bank_id parameter containing the ID of the required bank. More information about bank IDs can be found at Banks available for purchase.
  Note: Please contact the Benker support team to set the value of payment_extra_param parameter.

  Here is an example of the data from a request to open the checkout page with one preselected bank by using EPayWidget.

  EPayWidget.run(
  	{
  		project_id: 1234,
  		payment_id: 'payment_47',
  		customer_id: 'customer_123',
  		customer_first_name: 'John',
  		customer_last_name: 'Doe',
  		customer_email: 'johndoe@example.com',
  		payment_currency: 'EUR',
  		payment_amount: 10000,
  		force_payment_method: 'open-banking',
  		payment_extra_param: 'deeplink', 
  		account_bank_id: '12345',
  		signature: 'kUi2x9dKHA5VNU0FY...vySO/RLCv1htT4DqtVUkDJrOcZzUCwX6Rek7pZhkIQg=='
  	}
  )

Callback

In the Open Banking payment method, the payment platform returns the purchase result in a callback. For the information about the callback structure, see Callbacks.

The following is an example of a callback body with information about a successfully completed purchase.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of a callback for a declined purchase.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

• Interaction concepts
• Payment models and statuses
• Signature generation and verification
• Operation statuses and response codes

General information

To perform a purchase by using Gate with the Open Banking payment method:

1. Send a request with all the required parameters and signature to the Benker URL.
2. Receive a callback with the data you're required to submit.
3. Send a request with the data to the Benker payment platform.
4. Accept the callback with the purchase result from the payment platform.

The following figure provides the details of the purchase processing flow in the Open Banking payment method.

Request

This section provides the instructions on how to build the request for purchase with the Open Banking payment method.

Here is an example of the data from a request to initiate a purchase with the Open Banking payment method:

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "language": "EN"
    },
    "account": {
        "number": "DE89370400440532013000",
        "bank_id": "593123456789",
        "bank_code": "1234567890"
    },
    "payment": {
        "currency": "EUR",
        "amount": 10000,
        "description": "Description"
    },
    "return_url": {
        "success": "https://example.com/success/",
        "decline": "https://example.com/decline/",
        "return": "https://example.com/return/"
    }
}

Intermediate callbacks

Formats for intermediate callbacks and requests for obtaining consent and additional information

In cases where it is necessary to obtain additional consent from the customer and, if relevant, additional information, an intermediate callback containing the clarification_fields object is sent from the payment platform to your system each time. The nested objects of that object describe the specified objects and parameters necessary to process the payment. Such a callback may include:

The following is a fragment of a callback informing about the necessity of obtaining customer's consent.

{
  "clarification_fields": {
	"customer": {
	  "type": "object",
	  "description": "",
	  "properties": {
		"psu_consent": {
		  "type": "string",
		  "description": "Need to request the customer's consent to make a payment"
		},
		"psu_consent_text": {
		  "type": "string",
		  "description": "The text to be displayed on the payment form",
		  "default": "The consent text to be displayed to the customer"
		}
	  }
	}
  }
}

After you received information about customer's consent for purchase processing from the customer, send it to the payment platform in a new request. Listed below are the instructions on how to build the request with information about customer's consent for purchase processing.

Here is an example of the data from the request with information about customer's consent for purchase processing:

{
	"general": {
		"project_id": 1234,
		"payment_id": "payment_47",
		"signature": "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO/RLUkDJrOcZzUCwX6R/ekpZhkIQg=="
	},
	"additional_data": {
		"customer": {
			"psu_consent": "1",
			"psu_consent_text": "The consent text displayed to the customer"
		}
	}
}

Customer redirection

After receiving and processing your purchase request, the payment platform sends you the callback with the data for redirecting the customer to the provider service.

To redirect the customer, use the values of the following parameters in the redirect_data object:

• url—the URL to redirect the customer to
• body—the data to send in the request body
• method—the HTTP method for retrieving the website page (for example, POST or GET)
• encrypted—this is the service parameter. Ignore it.

Here is an example of the callback snippet with the data to redirect the customer.

"redirect_data": {
    "method": "GET",
    "body": [],
    "encrypted": [],
    "url": "https://example.com/redirect"
}

Callback

In the Open Banking payment method, the payment platform returns the purchase result in a callback. For the information about the callback structure, see Callbacks.

The following is an example of a callback body with the information about a successfully completed purchase.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "success",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

The following is an example of a callback for a declined purchase.

{
    "project_id": 1234,
    "payment": {
        "id": "payment_47",
        "type": "purchase",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "method": "open-banking",
        "sum": {
            "amount": 10000,
            "currency": "EUR"
        },
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 47,
        "type": "sale",
        "status": "decline",
        "date": "2024-12-07T19:08:45+0000",
        "created_date": "2024-12-07T19:08:05+0000",
        "request_id": "1a23456bc7890de",
        "sum_initial": {
            "amount": 10000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "EUR"
        },
        "code": "20000",
        "message": "General decline",
        "provider": {
            "id": 12345,
            "payment_id": "123abc123-123",
            "auth_code": ""
        }
    },
    "signature": "U7HQO7ToISZhMPKdM4XrUKQtoYzFvoB3cs9CRd4xeYG2Q=="
}

Related topics

• Interaction models
• Payment models and statuses
• Signature generation and verification
• Operation statuses and response codes

Banks available for purchase

When making payments using any of the Open Banking group methods, various banks that support this method may be involved. The request must contain the project and payment identifiers, signature, currency code, and payment amount, as shown in the example. Specify real payment data if possible. However, random values are also allowed.

If you have any questions about working with banks supported by the Open Banking methods, refer to your Benker account manager.

Request for the list of available banks

This section provides the instructions on how to build the request for the list of banks supported in the Open Banking payment method.

Here is an example of the data from the request for the list of banks available in the Open Banking payment method.

{
	"general": {
		"project_id": 200,
		"payment_id": "ORDER_155860015",
		"signature": "K6jll2ym+PtOb3ocZtr345st...=="
	},
	"payment": {
		"amount": 10000,
		"currency": "EUR"
	},
	"account": {
		"country":"GB"
	}
}

[
	{
		"minAmount": 100, // Minimum payment amount allowed for the payment (in minor currency units)
		"maxAmount": 1000, // Maximum payment amount allowed for the payment (in minor currency units)
		"limitCurrency": "EUR", // Code of the currency used for the payment limits (minAmount and maxAmount) in the ISO-4217 alpha-3 format
		"id": 123, // Bank ID
		"abbr": "EXB", // Bank shortcut name (for internal use)
		"name": "Example Bank", // General bank name
		"nativeName": "Example Bank", // Native bank name
		"currencies": [ // Array with currencies supported by the bank
			{
				"id": 123, // Currency ID in the payment platform
				"alpha_3_4217": "EUR", // Alphabetic code of the payment currency in the ISO-4217 alpha-3 format
				"number_3_4217": "123", // Numeric code of the payment currency in the ISO-4217 alpha-3 format
				"currency_type": "fiat", // Type of the currency
				"exponent": 2 // Number of decimal places after decimal point
			}
		]
	}
]

Payment confirmation procedure

The workflow of processing purchases made with Open Banking methods implies participation of banks, and in certain cases, processing payments on the side of these banks and the provider service may take up considerable time (in some cases up to seven or more days). As a result, there can be situations when the earlier information about the payment's completion or decline contradicts the final result (for example, following a notification about a declined payment, the funds are credited to the recipient's account, or vice versa).

To ensure timely and correct notification of merchants regarding the status of payments in these cases, the Benker payment platform uses a payment confirmation procedure. When you integrate the Open Banking payment methods, discuss with your account manager the use of this procedure as well as switching of statuses of the payments with the confirmed declines to the reversed or decline status (to make monitoring and analysing payments more convenient).

The payment confirmation procedure can be performed in different ways. One of the possibilities is the following:

1. After the customer completes all required steps, the payment is processed on the provider and bank services side while the customer is redirected to the payment interface (Payment Page or your system) where they receive the information about payment processing.
2. A number of actions are performed on the payment platform side:
   1. The sale operation status is set to success.
   2. A callback is sent to your system about changes in the status of the operation.
   3. The payment confirmation operation is formed.
   4. The payment is assigned the awaiting confirmation status—until the provider receives information about the crediting of funds.
   5. A callback is sent to your system about changes in payment status.
3. On the provider’s side, the final status of funds being credited is determined, after which the information about this status is sent to the payment platform.
4. On the payment platform side, the received information is processed, as a result of which the payment confirmation operation and the payment are assigned final statuses and the corresponding callbacks are sent to your system.

The payment confirmation operation can have one of the following final statuses:

• success—when the information about the crediting of funds to the recipient is received from a service provider side. In this case the payment status is set to success and the final callback containing the payment information is sent to your system.
• decline—when the information regarding the funds not being credited to the recipient is received from a service provider upon expiration of the specified period (which is 7 days by default and can be changed by contacting Benker technical support).

  In such cases depending on the project settings, that were configured during integration, the following scenarios are available:

  • The reversal operation is formed automatically and the payment platform sends the following callbacks successively: an intermediate callback, containing information about the funds not being credited and the final callback, containing the information about the purchase refund and the reversed payment status.
  • The payment status is set to decline and the final callback with information that purchase was declined is sent from the payment platform to your system.

When using this procedure, you can also monitor payment and operation statuses by using the Gate API (by receiving responses to payment status requests), as well as the Dashboard interface.

Using payment confirmation via Payment Page and Gate is described in the corresponding section of this article. If you have any additional questions regarding this procedure, contact the Benker specialists.