PayByBank

Introduction

PayByBank, PBB from now on, is a bank account payment solution that provides access to an open banking payment network.

Addon Payments’ payments solution PayByBank is built on Truelayer, which is an open banking payments network that connects banks, merchants and customers in Europe and the UK.

With Truelayer (PayByBank in Addon Payments) you can operate in two ways:

1. Open loop: Payments are deposited directly into your merchant’s bank account, unrelated to Truelayer. This modality does not admit refunds or Payouts to customers.

2. Close loop: The payment amount is deposited into your merchant account on the Truelayer platform. You can then transfer these funds to your other accounts manually or automatically through the Truelayer management panel.

Payment type	Bank transfer
Countries available	AUT, BEL, EST, FIN, FRA, DEU, IRL, ITA, LTU, NLD, POL, PRT, ROU, ESP, SWE, GBR
Currencies available	Euro and British pound
Redirection required?	Yes
Two-step payment allowed?	No
Refunds allowed?	Yes, total and partial (only on close loop)

Closed-loop refunds and Payouts are made from your Truelayer account credit. If you do not have credit, you can wait to receive funds or you can make a transfer to your merchant’s Truelayer account.

You can use both operations in your merchant if you set up two products, one for each operation.

Finally, you have a Postman collection where you can test the different PayByBank operations:

Postman.

Operations supported

PayByBank is available in the 3 types of integration. On the other hand, the operations supported are:

Authorization: A standard payment from the customer to your merchant. The capture of the amount is automatic.
Void: Total cancellation of the payment amount. Through the BackOffice or via endpoint. The operation to be voided must be in a specific status. More details in this section.
Refunds: Full or partial refunds. Through the BackOffice or via endpoint.
PayByLink: Sends customers a payment link, via mail, QR, etc. Only for Host2Host integrations.
Payout: Payment from the merchant to the customer. Not to be confused with refunds.

These operations are available depending on the integration:

Operation	Hosted	Host2Host	JavaScript
Authorization	Yes	Yes	Yes
Void (total)	No	Yes	No
Refunds (partial and total)	No	Yes (close loop)	No
PayByLink	No	Yes	No
Payout	Yes (close loop)	Yes (close loop)	Yes (close loop)

PayByBank transaction flow

Here is a diagram illustrating the flow of a PayByBank authorization transaction. A detailed explanation of each point is provided below.

This is the flow that follows a payment transaction made with PayByBank:

1. The customer fills in the payment information.

2. The merchant creates the request.

3. The merchant encrypts, encodes and signs the request.

4. The merchant sends the request to Addon Payments

5. If the request is correctly formed, Addon Payments returns a notification to the merchant with the PayByBank URL and the transaction status is set to “REDIRECTED”.

6. The merchant redirects the customer to the recieved PayByBank (Truelayer) URL.

7. When the customer accesses the URL, Addon Payments sends a notification indicating the “AWAITING_PAYSOL” status of the transaction.

8. The customer performs the transaction on the link recieved.

9. Addon Payments processes the PayByBank payment solution transaction.

10. If the transaction is not authorized, Addon Payments returns a notification with the status “ERROR” to the merchant, and the customer is redirected to the ERROR URL provided in the initial request.

11a. If the transaction is authorized and your merchant operates with open loop, Addon Payments returns a notification to the merchant with the status “SUCCESS”, and the customer is redirected to the SUCCESS URL indicated in the initial request.

11b. If the transaction is authorized and your merchant operates with close loop, Addon Payments returns a notification to the merchant with the status “SUCCESS_WARNING”, and the customer is redirected to the AWAITING URL provided in the original transaction.

12. If your merchant operates with a close loop, Addon Payments settles the transaction.

13. If your merchant operates with close loop, after settling the transaction, Addon Payments will send your merchant a notification with the status “SUCCESS”, and the customer is redirected to the SUCCESS URL indicated in the initial request.

Requirements to use PayByBank

In this section you have the requirements that customers and merchants must meet in order to use PayByBank in your merchant with Addon Payments.

Customer requirements

In order to use PayByBank, customers must:

Have a bank account with one of the banks available on the Truelayer platform.
Have online access to that bank account.

Merchant requirements

Here are the prerequisites your merchant must meet to integrate PayByBank.

Create an account and application for your Truelayer merchant

Yo integrate PayByBank in Addon Payments, you must create a Trulayer account for your merchant. To do so, follow these steps:

Access this page and create an account for your merchant. You must fill in the details of your merchant to create your account.
Once you have created your account, you must create an “aplication” in Trulayer.
Type a name for the application. You can modify the client_id which is used to identify the application.
Confirm the values and click on “Create application”.
A window with the name of the created application, the client identifier and the secret key will be displayed.
Click the “Get started” button. You should now have access to your account.

The newly created account is limited to Truelayer’s testing environment. When PayByBank integration testing is complete, request a Go live to Truelayer.

If you have any questions regarding registration, access to the console or any other issue, please contact Truelayer’s technical support.

Get your Truelayer account information and set up AP return URLs

Access your merchant’s management panel on Truelayer.
Access the created application by clicking on the “Apps” button in the left menu.
Access the configuration section of the application by clicking on “Settings” at the top.
Get and save the following data from the “Identifiers” section:
- Customer Identifier (Client Id.)
- Secret key (Client secret)
Remove the default URLs and add the Addon Payments return URLs as allowed redirect URLs in the Truelayer platform. In the “Allowed redirect URIs” section, click the plus “+” button and add the following URLs:

Environment	URL
Staging	https://checkout.stg-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
Staging	https://checkout.stg-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
Production	https://checkout.prd-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west1-d.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank
	https://checkout.prd-eu-west3-c.epgint.com/EPGCheckout/returnurl/returnUrlPayByBank/paysol/paybybank

Note: Remember that production environment URLs cannot be entered until your merchant is registered in the production environment.

Generate an encryption key for Truelayer, upload it and set up AP notification URLs

Generate a couple encryption keys, public and private, for your merchant in Trulayer.
The process is detailed in this Trulayer guide. At the end of the guide process you will get a public and a private key in .pem text files.
Access the management panel of your Truelayer store.
Access the application created by clicking on the “Apps” button in the left menu.
Access the configuration section of the application by clicking on “Settings” at the top.
Locate the “Payment Settings” section to upload the public signing key. Click the “Upload signing key” button.
A window will open where you can upload the .pem file with the public key. If the file is correct it will appear in the list of signing keys.
Display the key information to obtain the Key identifier (KID), needed later. Save the KID.
On the “Webhook URI” section, enter the following URL:

Environment	URL
Staging	https://checkout-stg.easypaymentgateway.com/EPGCheckout/callback/callbackPayByBank/paysol/paybybank
Production	https://checkout.easypaymentgateway.com/EPGCheckout/callback/callbackPayByBank/paysol/paybybank

Nota: Remember that production environment URLs cannot be entered until your merchant is registered in the production environment.

Choose between open loop or close loop operation

Choose the operation: open loop or close loop. See details in the Introduction.

If you operate in open loop, no further action is required on the Trulayer console.
If you operate in close loop, for the production environment you need to create a funding account in the Truelayer management panel, in which funds from payments received will be deposited, pending manual or automatic withdrawal.
- In the staging environment, you have two accounts for testing in the “Merchant Account” section of the “Payments” section. One account is in Euros and the other in GBP.
- All fund accounts have a unique identifier that you will be able to consult and that you must provide to Support.
- To consult this identifier: Click on “Apps” on the left menu, then “Merchant Account”. Select the account you want to consult. Then, at the bottom of the “Details” tab, the “ID” field.

Request payment solution configuration

As a final step before starting to integrate the PayByBank solution, you must ask the Addon Payments Support team for the activation and configuration of PBB in your Virtual POS.

For this we need all this data that you can get from the Truelayer management panel:

Client identifier (Client Id.)
Secret key (Client secret)
KID (Encryption public key identifier).
.pem file with the encryption private key.

If you operate by close loop:

Identifier of the bank account you have created for your merchant on the Truelayer platform.

If you operate by open loop:

IBAN of your merchant’s bank account outside the Truelayer platform.
Full name of the beneficiary of such bank account.

Environments and endpoints: Staging and Production

Addon Payments has two (2) separate operating environments:

Staging environment:

This is the first environment you will use.
You can test your set-up with the credentials in the previous section.
This will allow you to make sure that the different situations are handled properly by your integration.
Real cards and accounts don’t work.

Production Environment:

In this environment, transactions are real.
You can only use real, operational cards and accounts.

Below are the endpoints by type of integration:

Environment	Hosted	Host2Host
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/tokenize	https://checkout.addonpayments.com/EPGCheckout/rest/online/pay

Request	Environment	URL
Request /auth	Staging	https://epgjs-mep-stg.addonpayments.com/auth
Request /charge	Staging	https://epgjs-mep-stg.addonpayments.com/charge/v2
Request /auth	Production	https://epgjs-mep.addonpayments.com/auth
Request /charge	Production	https://epgjs-mep.addonpayments.com/charge/v2

Required and optional data PayByBank

Below is a table with the parameters required to send a request with PayByBank. These data are common in the 3 types of integration: Hosted, Host2Host and JavaScript. The type indicates that the parameter if required/mandatory (R).

Field	Format	Type	Description	Example
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
merchantTransactionId	Alphanumeric Max. 18 characters No special characters (accents, punctuation marks, etc.) No duplicate numbers	R	This is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order.	order_91684
productId	Whole number Max. 20 characters	R	Product ID created on your AP merchant. You’ll find it in the welcome email.	149830
operationType	Alphanumeric Max. 45 characters	R	Shows type of operation to carry out. Permitted values: – debit (default): Payment transaction. That is, cash travels from the customer’s account to the merchant. – credit: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.	debit
customerId	Alphanumeric Max. 80 characters	R	Customer ID in your e-commerce platform.	A34623
amount	Numerical with decimals 0~1000000.00	R	Amount of the transaction. If the amount has decimals, the separator is a dot (.). The separator cannot be included in the thousands.	127.5
currency	Alphabetical – EUR – GBP	R	Currency of the transaction. Limited to EUR and GBP.	EUR
country	Alphabetical 2 characters ISO 3166-1 alfa-2 EU countries and UK	R	Country from which the transaction is sent	ES
firstName	Alphabetical Max. 50 characters	R	Customer’s name. If more than one, use spaces between them.	John
lastName	Alphabetical Max. 50 characters	R	Customer’s surname(s) If more than one, they are separated by spaces.	Doe
telephone	Alphanumeric Max. 45 characters	R (optional if customerEmail is sent)	Telephone number. With the country prefix. It is required “telephone” or “customerEmail”, you can choose which one.	+34600600600
customerEmail	Alphanumeric Max. 100 characters	R (optional if telephone is sent)	Email of the customer. It is required “telephone” or “customerEmail”, you can choose which one.	correo@mail.com
customerCountry	ISO 3166-2 code	R	Customer’s country.	ES
addressLine1	Alphanumeric Max. 50 characters	R	Customer’s address.	Tower street 2
postCode	Alphanumeric Max. 16 characters	R	Customer’s address postal code.	08003
city	Alphabetic Max. 50 characters	R	Customer’s city.	Barcelona
statusURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your e-commerce platform where AP will send the notification with the status of the transaction. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/status
successURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is authorized. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/success
errorURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is declined. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/error
cancelURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is cancelled during the payment process. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/cancel
awaitingURL	Alphanumeric (characters allowed in URL) Max. 2048 characters	R	URL of your platform to which the customer is redirected if the transaction is pending processing. If it is sent in the request, it will take priority over the one configured in the Addon Payments BackOffice Portal. If it is not sent in the request, the customer will be redirected to the URL configured in the administration module.	https://www.example.com/awaiting
paymentSolution	Alphanumeric Max. 45 characters	O	Name of the payment solution to process the transaction. IMPORTANT: If you don’t want all the payment solutions you have available to be shown, do NOT send this parameter.	PayByBank
addressLine2	Alphanumeric Max. 50 characters	O	Customer’s address. Optional, in case the complete address doesn’t fit in addressLine1.	Ramos street 23
dob	Alphanumeric Max. 10 characters YYYY-MM-DD	O	Customer date of birth.	1999-12-31
state	Alphanumeric Max. 50 characters	O	State or province of the customer.	Barcelona
merchantParams	Alphanumeric Max. 500 characters key1:value1;key2:value2;keyN:valueN	O	Parameter where extra transaction details are sent, as in PayByLink. More details in the specific section.	N/A
bankCountry	ISO 3166-2 2 characters	O	Country of the bank of the customer’s bank account. When this field is empty, a drop-down list of available countries will appear. If this parameter is set to a country, the indicated country will be checked by default and the drop-down will not be displayed.	ES
bankHolder	Alphabetic Max. 70 characters	O	First and last name(s) of the customer’s bank account holder. Separate with spaces.	John Doe
bankAccountType	Permitted values: – iban – sort_code_account_number	O	Type of the customer’s bank account. Depending on the value you send, you will also have to send “bankIban” or “bankCode” and “bankAccountNum”.	iban
bankIban	Alphanumeric Max. 30 characters	O (send if: “bankAccountType: iban”)	IBAN bank code of the customer’s account.	ES1212341234121234567890
bankCode	6 digits numeric	O (send if: “bankAccountType: sort_code_account_number)	Bank code of the customer’s account.	123456
bankAccountNum	8 digits numeric	O (send if: “bankAccountType: sort_code_account_number)	Customer account number.	12345678

Host2Host integration

With Addon Payments you can use PayByBank payment solution with your Host2Host integration. We recommend you to visit Host2Host documentation for more details about this type of integration.

Authorization

The authorization is a payment transaction from the customer to the merchant. The amount capture is automatic. It sends the request to the corresponding Host2Host endpoint.

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of authorization through PayByBank by Host2Host. Remember that the string request must pass the encryption process.

				
					merchantId=12345&productId=14983&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Authorization request parameters

See the parameters to send in a PayByBank authorization via Host2Host in the table of common parameters.

Response

Visit our section on Managing notifications to learn more about its structure.

This is a code example of the response recived to a PayByBank authorization request:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Void

In Addon Payments you can reverse (cancel) the amount of a PayByBank transaction in favor of the customer. To do so, the previous transaction must be pre-authorized. See the documentation for more details.You can cancel operations by:

The BackOffice Portal.
By petition, as we will see below.

These are the endpoints where void requests are sent:

Environment	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/void
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/void

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of a request for void of a PayByBank transaction by Host2Host. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=27258897&paymentSolution=paybybank&transactionId=7556056

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/void' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: Z7VA6TpG9B84X9x9qqXoWQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwcLTAURzz4IiJ26kBlQpYVnedKEVhevNJNZ88z6m50W2THtDR70pQq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Parameters of the void request

These are the parameters to send for a void request of a PayByBank transaction. The type column indicates whether the item is Required/Mandatory (R) or Optional (O).

Field	Format	Type	Description	Example
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
transactionId	Whole number Max. 100 digits	R	ID for the original transaction the secondary operation applies to, such as capture, release or refund.	76543210
paymentSolution	Alphanumeric Max. 45 characters	R	Name of the payment solution for which the initial transaction has been processed. It is indicated in the original transaction response.	paybybank
merchantTransactionId	Alphanumeric Max. 18 characters No special characters (accents, punctuation marks, etc.) No duplicate numbers	R	This is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order. Can’t be the same between transactions.	order_91684
description	Max 1000 characters Page of Latin-1 codes (ISO-8859-1)	O	Description of the transaction. Saved in the transaction details and returned in the notification. Doesn’t affect the transaction. Helps you identify it more easily.	Void after demo

Response

Visit our section on Managing notifications to learn more about its structure.

This is a code example of a response received to a request to cancel a PayByBank transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228298</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_failed","event_version":1,"event_id":"565218dd-767c-4313-a907-1c65faa2b2ef","payment_id":"4519ec74-193a-4005-8539-6ed6703337ae","metadata":{"txnId":"228297","operationType":"Payin"},"payment_method":{"type":"bank_transfer"},"failed_at":"2024-06-09T14:58:13.923Z","failure_stage":"authorizing","failure_reason":"canceled"}</details>
            <merchantTransactionId>0806105</merchantTransactionId>
            <message>Payment operation fail on stage: authorizing. Failure reason: canceled</message>
            <operationType>DEBIT</operationType>
            <paySolTransactionId>4519ec74-193a-4005-8539-6ed6703337ae</paySolTransactionId>
            <paymentDetails>
                <extraDetails/>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>CANCELLED</status>
            <transactionId>228297</transactionId>
            <respCode>
                <code>1542</code>
                <message>Transaction was manually cancelled or declined by the merchant</message>
                <uuid>67073f7b_c157_40a3_8e64_5a918133df13</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
</response>

Refunds

You can make partial or total refunds of the amount of a PayByBank transaction, as long as the transaction is authorized and settled and you operate by close loop. You can make refunds through:

The BackOffice Portal.
The Truelayer management panel.
By request.

Refunds via Truelayer management panel

To make a full or partial refund in the Truelayer management panel follow these steps:

In the left menu click on “Payments”, then “Payments”.
You will see a list of your merchant’s transactions. Find and click on the operation you want to return.
A drop-down will open with transaction details. Click on “Authenticate & refund payment” in the Refunds section.
You will need to authenticate yourself, either with a one-time code or other methods.
Once you have authenticated, a window will open with the details of the refund.
Enter the amount of the refund, total or partial, in the “Amount” field.
When the refund is successfully completed, a new refund transaction will be created in the transaction list referring to the original payment ID.

Refund by request

These are the endpoints where the refund requests are sent.

Entorno	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/rebate

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of a refund request for a PayByBank transaction by Host2Host. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=61565574&amount=5&paymentSolution=paybybank&transactionId=7556056

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/rebate' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: Z7VA6TpG9B84X9x9qqXoWQ==' \
--form 'merchantId="12345"' \
--form 'encrypted="4xUYxJxLc/ABCyqJfwttTalkds3YeijsJe6MlTnC6mgmbm0aXKq6qjF37NCfOeq/UDCg0RB/MPfYUJRUIsfPk=' \
--form 'integrityCheck="1c256f5b834e5db6d5f453043a8a3830859b308f297cc2cf423064510c5c9b72"'

Parameters of the refund request

These are the parameters to send for a refund request for a PayByBank transaction. The type column indicates whether the parameter is Required/Mandatory (R) or Optional (O).

Field	Format	Type	Description	Example
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
transactionId	Whole number Max. 100 digits	R	ID for the original transaction the secondary operation applies to, such as capture, release or refund.	76543210
paymentSolution	Alphanumeric Max. 45 characters	R	Name of the payment solution for which the initial transaction has been processed. It is indicated in the original transaction response.	paybybank
amount	Numérico decimal 0~1000000.00	R	Amount of refund. If it is less than the total, the return will be partial. If the amount contains decimals, you must use the period (.) as a separator. Thousands separator cannot be included.	10.50
merchantTransactionId	Alphanumeric Max. 18 characters No special characters (accents, punctuation marks, etc.) No duplicate numbers	R	This is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order. Can’t be the same between transactions.	order_91684
description	Max 1000 characters Page of Latin-1 codes (ISO-8859-1)	O	Description of the transaction. Saved in the transaction details and returned in the notification. Doesn’t affect the transaction. Helps you identify it more easily.	Refund after returning product

Response

Visit our section on Managing notifications to learn more about its structure.

This is an example of a refund notification for a PayByBank transaction. This is the final notification, indicating that it has been successful. Previously, it goes through another validation state with status: “AWAITING_PAYSOL”.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payfrex-response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228219</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"refund_executed","event_version":1,"event_id":"e3f4afba-dc64-ac52-63f8-11e21ac87790","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","executed_at":"2024-06-06T06:53:31.293Z","refund_id":"5469f084-a74e-4bb7-bd76-37c44d68c5d0"}</details>
            <merchantTransactionId>0606005</merchantTransactionId>
            <message>PayByBank refund has been successfully executed.</message>
            <operationType>REFUND</operationType>
            <payFrexTransactionId>228219</payFrexTransactionId>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>69443</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</payfrex-response>

PayByLink (payment link)

PayByLink (PBL) is an operation that generates a payment link that is sent to the customer. With PayByBank, your merchant can use these payment links.

This is a diagram of the flow of a PayByLink transaction with PayByBank. Below is a detailed explanation of each point.

1. The merchant creates the request.

2. The merchant encrypts, encodes and signs the request.

3. The merchant sends the request to Addon Payments.

4. Addon Payments processes the transaction.

5a. If the request is not correctly formed, Addon Payments returns a notification to the merchant with the transaction status “ERROR”.

5b. If the request is correctly formed, Addon Payments returns a notification to the merchant with the payment URL and the transaction status changes to “PENDING_CONFIRMATION”.

6. The merchant sends the customer the payment link received.

7. The customer opens the link.

8a. If the link is expired, Addon Payments sends the merchant a notification with the status “CANCELLED”.

8b. If the link is correct, Addon Payments returns a notification to the merchant with the status “AWAITING_PAYSOL”, and the customer is redirected to PayByBank (Trulayer) for further processing.

9. The customer pays in the link.

10. Addon Payments processes the PayByBank payment solution transaction.

11. If the transaction is not authorized or the customer leaves the process, Addon Payments returns a notification to the merchant with the status “AWAITING_PAYSOL”.

12a. If the transaction is authorized and your merchant operates with open loop, Addon Payments returns a notification to the merchant with the status “SUCCESS”, and the customer is redirected to the SUCCESS URL indicated in the initial request.

12b. If the transaction is authorized and your merchant operates with close loop, Addon Payments returns a notification to the merchant with the status “SUCCESS_WARNING”, and the customer is redirected to the AWAITING URL indicated in the initial request.

13. If your merchant operates with close loop, Addon Payments settles the transaction.

14. If your merchant operates with close loop, after settling the transaction, Addon Payments will send a notification to your merchant with the status “SUCCESS”, and the customer is redirected to the SUCCESS URL indicated in the initial transaction.

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of PayByLink request in PayByBank by Host2Host. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php
&state=barcelona&merchantParams=payByLink:true

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

PayByLink request parameters

Below is a table with the required data for PayByLink through PayByBank.

In addition to the data from this table, you must send the required data from the general table. The type indicates whether the field is required/mandatory (R) or optional (O):

Field	Format	Type	Description	Example
state	Alphanumeric Max. 50 characters	O	State or province of the customer.	Barcelona
merchantParams	Alphanumeric Max. 500 characters key1:value1;key2:value2;keyN:valueN	O	Extra parameters of the request. To operate with PayByLink it is required to send the following in this field “payByLink:true”. You can also include other parameters, such as the expiration date of the link.	merchantParams=payByLink:true
− payByLink	Boolean – true – false	R	Indicates if the operation is PayByLink.	true
− pblExpirationUnit	Permitted values: – minutes – hours	O	Unit (hours or minutes) in which the expiration is to be measured. This value is imposed against the value configured in the BackOffice. If this value is not sent and is not configured by default, the expiration of the payment link is 24 hours.	minutes
− pblExpirationValue	Positive integer	O	Number of units (hours or minutes) until the link expires. This value is imposed against the value configured in the BackOffice. If this value is not sent and is not configured by default, the expiration of the payment link is 24 hours.	15
paysolExtendedData	JSON with no limit	O	JSON object to include extra information required by some payment solutions. In PayByLink, it can be sent to show the cart to the customer in the payment gateway. In the dropdown below you have the fields and how to form the JSON.	N/A

Some considerations to take into account in PayByLink:

The expiration of the links is 24 hours by default. It can be modified in the BackOffice or in the requests. The expiration indicated in the request has priority over the one configured in the BackOffice.
You can ask Support to change the default expiration on all links in the BackOffice.
There is no maximum link expiration, the minimum is 1 minute.
Here is an example of how to form the JSON of the paysolExtendedData and its fields:

JSON of the paysolExtendedData

				
					{
    "product_items": [
        {
            "name": "Producto 1", //product name
            "price": 5, //product price
            "quantity": 1, //product quantity
            "url": "https://micomercio.com/producto1" //your merchant url for the product
        },
        {
            "name": "Producto 2",
            "price": 2.5,
            "quantity": 2,
            "url": "https://micomercio.com/producto2"
        }
    ]
}

Response

Visit our section on Managing notifications to learn more about its structure.

Here are some examples of the notifications received upon a PayByLink request. First, you will receive a notification with the payment link to send to the customer. When the customer clicks it, you will receive another notification. Finally, you will receive a notification with the status of the transaction.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5</amount>
            <currency>GBP</currency>
            <details>{"id":"jTfUD3fguG8","uri":"https://payment.truelayer-sandbox.com/links/jTfUD3fguG8"}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank PayByLink uri successfully created.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>jTfUD3fguG8</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>uri</key>
                        <value>https://payment.truelayer-sandbox.com/links/jTfUD3fguG8lt;</value>
                    </entry>
                    <entry>
                        <key>id</key>
                        <value>jTfUD3fguG8</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>PENDING_CONFIRMATION</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>3eb6e394_21a2_49c7_a124_113d3d3ce77c</uuid>
            </respCode>
        </operation>
    </operations>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_link_payment_created","event_version":1,"event_id":"986ab71a-847f-4fa3-b417-4f88c2aed9b2","payment_link_id":"jTfUD3fguG8","payment":{"id":"4fd99d1c-845b-450b-99fc-783e5e73e676","created_at":"2024-06-06T17:30:13.732Z"}}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank PayByLink payment successfully initiated. Waiting for Truelayer's response.</message>
            <operationType>DEBIT</operationType>
            <paymentSolution>paybybank</paymentSolution>
            <status>AWAITING_PAYSOL</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>354d82bc_61b7_4b89_af82_24b1ea3f0529</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>AWAITING_PAYSOL</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228284</message>
    <operations>
        <operation sorted-order="1">
            <amount>5.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"da83166d-caa8-4d40-bae9-f97ad01fe342","payment_id":"4fd99d1c-845b-450b-99fc-783e5e73e676","metadata":{"txnId":"228284","operationType":"payByLink"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T17:30:35.45Z","payment_source":{"id":"b277e24b-7b18-4e22-9d98-c47a43bd5faa","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"16de2aa3-ec88-4f09-bd35-7b7d2794a289"}</details>
            <merchantTransactionId>0606306</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228284</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>354d82bc_61b7_4b89_af82_24b1ea3f0529</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Payout

Payouts are a payment transaction from the merchant to the customer’s account. Not to be confused with refunds. The purpose of this operation is the payment of prizes, for example. You must request this operation to Support for its activation.

You can operate with Payouts in PayByBank in any of the 3 integrations with CLOSE LOOP and with the same parameters as in this example, which will be with Host2Host. The request is very similar to a normal authorization, but with “operationType: credit”. Also, if you operate by open loop, you will need to add some specific parameters.

Payout according to customer account

The parameters to be sent in the Payout change depending on whether the customer has a Truelayer account or not:

Customer with a Truelayer account, this Payout will be by closed circuit.
Customer with an external bank account, this Payout will be by open circuit and you will have to add some parameters.

Important: Regardless of whether the customer has a Truelayer or non-Truelayer account, the merchant must have a Truelayer account and operate with close loop to make Payouts.

Payout according to flow

The type of Payout depends on the flow that your merchant has active, it is not possible to choose the type of Payout (direct or in 2 steps) with the parameters of the request. There are 2 types of Payouts:

Direct Payout: The customer receives the amount when the request is successfully completed.
Payout in 2 stages: The customer initiates the Payout process but this is pending approval or reject by the merchant.

In addition, for security reasons, to perform a Payout there must be a previous authorized payment (from the customer to the merchant). The Payout will be made with the same payment solution and to the same card with which the previous payment was made. However, there are exceptions where a Payout can be made without prior deposit, depending on the nature of the merchant.

You must request the Payout operation to Support for its activation.

Requirements for Payouts in PayByBank

You must add the AIS service URLs to the authorized return URLs in the Truelayer platform. Follow this process and add the following URLs:

Environment	URL
Staging	https://checkout.stg-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
Staging	https://checkout.stg-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
Production	https://checkout.prd-eu-west1.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west1-d.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west3.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais
	https://checkout.prd-eu-west3-c.epgint.com/EPGCheckout/returnurl/returnUrlAIS/paysol/ais

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

These are some examples of Payout request in PayByBank by close loop via Host2Host. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10&currency
=EUR&country=ES&customerId=000001&productId=123450001&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php
&successURL=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko.php
&cancelURL=https://micomercio.com/url-cancelacion.php&awaitingURL=https://micomercio.com/url-espera.php
&operationType=credit&dob=1990-01-01

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/pay' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="YhkE2nrG1vmWRxNnMxWtbqDHsi/+FQs2AfPJBBHwIYOG3JCagem6DSb+R+63D5+NT/FQzI0Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInomL4o17lyYZds2eQ48hNGO8O8EmnDzTfveqZUASpII=”' \
--form 'integrityCheck="06c928531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Payout request parameters in Paybybank

The required parameters (R) for a Payout request in PayByBank are those in this table.

Depending on whether you operate by close loop or open loop, you will have to add/modify some data, as you can see in the following sections:

Close loop

These are the parameters to be added/modified for close loop payout requests:

Field	Format	Type	Description	Example
operationType	Alphanumeric Max. 45 characters	R	Shows type of operation to carry out. Permitted values: – debit – credit: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.	debit
dob	Alphanumeric Max. 10 characters YYYY-MM-DD	R	Customer date of birth.	1999-12-31

Open loop

These are the parameters to be added/modified for open loop payout requests:

Field	Format	Type	Description	Example
operationType	Alphanumeric Max. 45 characters	R	Shows type of operation to carry out. Permitted values: – debit – credit: Deposit transaction to the customer’s account. That is, cash travels from the merchant to the customer’s account. For example, in the payment of a prize. Not to be confused with returns. These have their own type of transaction.	debit
dob	Alphanumeric Max. 10 characters YYYY-MM-DD	R	Customer date of birth.	1999-12-31
bankCountry	ISO 3166-2 2 characters	O	Country of the bank of the customer’s bank account. When this field is empty, a drop-down list of available countries will appear. If this parameter is set to a country, the indicated country will be checked by default and the drop-down will not be displayed.	ES
bankHolder	Alphabetic Max. 70 characters	O	First and last name(s) of the customer’s bank account holder. Separate with spaces.	John Doe
bankAccountType	Permitted values: – iban – sort_code_account_number	O	Type of the customer’s bank account. Depending on the value you send, you will also have to send “bankIban” or “bankCode” and “bankAccountNum”.	iban
bankIban	Alphanumeric Max. 30 characters	O (send if: “bankAccountType: iban”)	IBAN bank code of the customer’s account.	ES1212341234121234567890
bankCode	6 digits numeric	O (send if: “bankAccountType: sort_code_account_number)	Bank code of the customer’s account.	123456
bankAccountNum	8 digits numeric	O (send if: “bankAccountType: sort_code_account_number)	Customer account number.	12345678

Response

Visit our section on Managing notifications to learn more about its structure.

This is an example of the notification you get from a Payout transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>PayByBank callback response has finished successfully, for the transaction Id: 228220</message>
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>GBP</currency>
            <details>{"type":"payout_executed","event_version":1,"event_id":"b4a6b795-c03d-e52b-405b-c895832fd743","metadata":{"operationType":"Payout","txnId":"228220"},"executed_at":"2024-06-06T07:30:34.107Z","payout_id":"19b3eb94-5837-4340-bd50-fa42bf259647","beneficiary":{"type":"external_account"}}</details>
            <merchantTransactionId>0606006</merchantTransactionId>
            <message>PayByBank payout has been successfully executed.</message>
            <operationType>CREDIT</operationType>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228220</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>b1cc4210_b008_4ed9_8ce7_19bc4bb22033</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Payouts pending to be approved or rejected

If the Workflow that your merchant has configured for Payouts indicates so, the operation will be “pending” to “credit” and you will have to approve or reject the payout. Follow the steps in this guide to do so.

Check transaction status

You can check the status of a PayByBank transaction that is not in final status (SUCCESS, ERROR or CANCELLED). This request allows us to retrieve the last status of the transaction. These are the endpoints where the status query request is sent:

Environment	URL
Staging	https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/checkTxn
Production	https://checkout.addonpayments.com/EPGCheckout/rest/online/checkTxn

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of a PayByBank check transaction status request by H2H. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&paymentSolution=paybybank&transactionId=12345

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/checkTxn' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 3eRDEm73YvekNKUJctyu==' \
--form 'merchantId="12345"' \
--form 'encrypted="Agb69XWtT8WJ9qAdyNFHE6Hn+Hya57BBcOfx1ylrhg53nG2evwuAborzvFSQO3IslRCtBAuJVaSzRavzdNBtZXjzS2D5hF1TUlut+p3/9WUaInom”' \
--form 'integrityCheck="28531469eb314c609e9a565567afecae69e644ba0e8cc49c612b6bf35e83"'

Parameters of the check transaction status request

These are the parameters you must send for a check transaction status in PayByBank. The type column indicates whether the item is required/required (R):

Field	Format	Type	Description	Example
merchantId	Whole number 4~7 digits	R	Your merchant’s ID on the AP platform. Provided by Support in the welcome email. It is the same for both environments	14983
transactionId	Whole number Max. 100 digits	R	ID for the original transaction the secondary operation applies to, such as capture, release or refund.	76543210
paymentSolution	Alphanumeric Max. 45 characters	R	Name of the payment solution for which the initial transaction has been processed. It is indicated in the original transaction response.	paybybank
merchantTransactionId	Alphanumeric Max. 18 characters No special characters (accents, punctuation marks, etc.) No duplicate numbers	R	This is the unique identifier of the merchant’s transaction. It is used by your platform to link the notifications received with the customer’s order. Can’t be the same between transactions.	order_91684

Response

Visit our section on Managing notifications to learn more about its structure.

This is an example of a notification to a PayByBank check transaction status.

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <operations>
        <operation sorted-order="1">
            <amount>10.0</amount>
            <currency>EUR</currency>
            <details>{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","amount_in_minor":1000,"currency":"EUR","user":{"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"payment_method":{"type":"bank_transfer","beneficiary":{"type":"merchant_account","reference":"xxxxxxx","merchant_account_id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},"provider_selection":{"type":"user_selected","filter":{},"provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"}},"created_at":"2024-01-01T00:00:00.000000Z","status":"settled","authorization_flow":{"configuration":{"provider_selection":{},"redirect":{"return_uri":"https://payment.truelayer-sandbox.com/payments/completed"},"form":{"input_types":["text","select","text_with_image"]},"consent":{"action_type":"adjacent","requirements":{"pis":{},"ais":{"scopes":["accounts","balance"]}}},"user_account_selection":{},"scheme_selection":{}}},"executed_at":"2024-01-01T00:00:00.000000Z","payment_source":{"account_identifiers":[{"type":"sort_code_account_number","sort_code":"123456","account_number":"12345678"},{"type":"iban","iban":"GB75CLRB04066800000871"}],"id":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","account_holder_name":"Nombre Apellido"},"settled_at":"2024-01-01T00:00:00.00Z","metadata":{"txnId":"xxxxxx","operationType":"Payin"},"creditable_at":"2024-01-01T00:00:00.000000Z"}</details>
            <merchantTransactionId>123456789</merchantTransactionId>
            <message>Check Transaction operation Success. Transaction status on Truelayer: settled</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</paySolTransactionId>
            <paymentDetails>
                <extraDetails/>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>xxxxxx</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</uuid>
            </respCode>
        </operation>
    </operations>
</response>

Hosted Integration

The PayByBank payment solution is available in Hosted integrations. You can choose whether to show the complete cashier with all the payment solutions your merchant has active, or only PayByBank. We recomend that you visit the Hosted documentation for more details about this type of integration.

Authorization

The authorization is a payment transaction from the customer to the merchant. The capture of the amount is automatic. Send the request to the corresponding Hosted endpoint.

Request

Remember that requests sent to Addon Payments must be encrypted. Visit our Encryption, signature and sending the request for more information.

Here are some examples of authorization through PayByBank by Hosted. Remember that the string request must pass the encryption process.

				
					merchantId=12345&merchantTransactionId=00000001&amount=10.00&currency=EUR&country
=ES&operationType=debit&firstName=Pablo&lastName=Ferrer&telephone=+34600600600
&customerCountry=ES&addressLine1=Calle Canales 4&postCode=08003&city=barcelona
&statusURL=https://micomercio.com/recepcion_notificacion.php&successURL
=https://micomercio.com/url-ok.php&errorURL=https://micomercio.com/url-ko
.php&cancelURL=https://micomercio.com/url-cancelacion.php

				
					curl --location --request POST 'https://checkout-stg.addonpayments.com/EPGCheckout/rest/online/tokenize' \
--header 'apiVersion: 5' \
--header 'encryptionMode: CBC' \
--header 'iv: 0Pn6pDEm73YvekNKUJcvwg==' \
--form 'merchantId="12345"' \
--form 'encrypted="jULXEtDfSVYIgfV29GBTcibe+ED+IvnfI2ssayrpqoJRzmI+SVst1SV3LRjt7DHlU5+0FoBPZy8K1wiPaTPYrMvCuxRAMYF+sk6ZPENAipntbetAbXHDVs6KKbjyCjDLRwGX7rrIlPi0TTIH9nGfPTq4DL1CDxivnjd1eOGOnHzQRr”' \
--form 'integrityCheck="0bc22b4408a6a2bf135fd2eb3832775f44b02f96d7e10d940b81c5069763685f"'

You will receive a response to this request with the link to the Hosted cashier to which you should redirect the customer.

Authorization request parameters

You can see in the common table the parameters required to send for a PayByBank authorization request via Hosted.

Response

Visit our section on Managing notifications to learn more about its structure.

This is an example of a response received to a PayByBank transaction authorization request:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

JavaScript Integration

With Addon Payments you can use the PayByBank payment solution with your JavaScript integration. This integration has some extra steps different from the other integrations, so we recommend you to visit the JavaScript documentation for more details.

Authorization

The authorization is a payment operation from the customer to the merchant. The capture of the amount is automatic. Send the request to the corresponding JavaScript endpoint.

Getting the authToken and rendering the cashier

The first step is to request the authToken and render the cashier. This step is the same as in the JavaScript card integration. See the documentation:

Charge

By obtaining the “prepayToken”, you will be able to send the payment/charge request. Here is an example of a PayByBank request via JavaScript.

				
					{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "firstName": "Pablo",
    "lastName": "Ferrer",
    "telephone": "+34600600600",
    "customerCountry": "ES",
    "addressLine1": "calle canales 2",
    "postCode": "08003",
    "city": "Barcelona",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType"= "debit"
}

				
					curl --location --request POST 'https://epgjs-mep-stg.addonpayments.com/charge/v2' \
--header 'Content-Type: application/json' \
--header 'prepayToken: 8862abf9-ca5a-49da-9527-1e3163e64954' \
--data-raw '{
    "merchantId": "12345",
    "merchantTransactionId": "00000001",
    "amount": "10.00",
    "currency": "EUR",
    "country": "ES",
    "firstName": "Pablo",
    "lastName": "Ferrer",
    "telephone": "+34600600600",
    "customerCountry": "ES",
    "addressLine1": "calle canales 2",
    "postCode": "08003",
    "city": "Barcelona",
    "statusURL": "https://micomercio.com/recepcion_notificacion.php?tipo=redireccion",
    "successURL": "https:// micomercio.com/url-ok.php",
    "errorURL": "https:// micomercio.com/url-ko.php",
    "cancelURL": "https:// micomercio.com/url-cancelacion.php",
    "awaitingURL": "https:// micomercio.com/url-espera.php",
    "operationType"= "debit"
}'

Parameters of the charge request

You can see in the common table the required parameters to send for a PayByBank authorization charge request via JavaScript. In addition, you must send this parameter that you have previously obtained:

prepayToken: Sent in the request header. AP returns this reference after the customer enters his data in the JS payment form. It is the reference that links to the customer’s card or account data for JavaScript integration.

Response

Visit our section on Managing notifications to learn more about its structure.

This is an example of a PayByBank transaction notification with the result of the transaction:

				
					<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response operation-size="1">
    <message>WorkFlow has finished successfully, for transaction Id: 228214</message>
    <operations>
        <operation sorted-order="1">
            <amount>10</amount>
            <currency>EUR</currency>
            <details>{"type":"payment_settled","event_version":1,"event_id":"895883e0-b972-4480-a0f3-215a8db8606c","payment_id":"9374a22a-3281-491d-8e5e-ee7c080601ef","metadata":{"txnId":"228214","operationType":"Payin"},"payment_method":{"type":"bank_transfer","provider_id":"mock-payments-gb-redirect","scheme_id":"faster_payments_service"},"settled_at":"2024-06-06T06:39:32.673Z","payment_source":{"id":"671a41aa-3196-48fd-8b88-ed23fe8e978d","account_holder_name":"JOHN SANDBRIDGE","account_identifiers":[{"type":"sort_code_account_number","sort_code":"040668","account_number":"00000871"},{"type":"iban","iban":"GB75CLRB04066800000871"}]},"user_id":"40097f84-d022-4f94-928c-d47ba5552c6a"}</details>
            <merchantTransactionId>0606001</merchantTransactionId>
            <message>PayByBank payment has been successfully settled.</message>
            <operationType>DEBIT</operationType>
            <optionalTransactionParams/>
            <paySolTransactionId>9374a22a-3281-491d-8e5e-ee7c080601ef</paySolTransactionId>
            <paymentDetails>
                <extraDetails>
                    <entry>
                        <key>paybybankStatus</key>
                        <value>settled</value>
                    </entry>
                </extraDetails>
            </paymentDetails>
            <paymentSolution>paybybank</paymentSolution>
            <status>SUCCESS</status>
            <transactionId>228214</transactionId>
            <respCode>
                <code>0000</code>
                <message>Successful</message>
                <uuid>8bcac545_9f4d_43f7_a28b_82e5b8ee35ca</uuid>
            </respCode>
        </operation>
    </operations>
    <optionalTransactionParams/>
    <status>SUCCESS</status>
    <workFlowResponse>
        <id>14267</id>
        <name>PayByBank Full</name>
        <version>42</version>
    </workFlowResponse>
</response>

Error codes

These are the error codes you may receive in PayByBank transaction notifications. You can find them in the lines “code”, “paymentCode”, “paymentMessage”.

< code > Addon Payments Code	Addon Payments Message	< paymentCode >Payment solution code	< paymentMessage >Payment solution message
1502	Insufficient funds	insufficient_funds	The PSU did not have the required balance in their account to complete this payment.
1508	A parameter on the payment call is invalid, check the Payment Solution Response	HttpStatus.BAD_REQUEST	INVALID_PARAMETERS
1509	The transaction was blocked by the Payment Solution.	blocked	The payment has been blocked due to a regulatory requirement. This may happen if the PSU fails a sanctions check.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_beneficiary_account	The payment failed because an invalid beneficiary account reference was provided.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_credentials	The banking credentials provided by the PSU to log into their bank were incorrect.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_iban	The IBAN that your user provided at the creation of the pay-in this closed-loop payout is for was invalid.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_mandate_state	The mandate was not in a valid status to create a recurring payment.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_otp	The PSU submitted an incorrect one-time password during the authorisation of the payment.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_remitter_account	The account details of the remitter bank account provided during the payment flow were incorrect.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_request	The payment failed due to invalid data in the request.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_scan	We could not convert the beneficiary’s sort code and account number to an IBAN.
1509	The transaction could not be processed. Check the Payment Solution Response	invalid_sort_code	The payment failed due to an invalid sort code being provided.
1509	The transaction could not be processed. Check the Payment Solution Response	mandate_revoked	The mandate for a recurring payment is revoked.
1509	The transaction could not be processed. Check the Payment Solution Response	server_error	TrueLayer encountered an error while processing the payment.
1511	The refund was unable to be processed. Check Payment Solution Response	returned	The payout was blocked or rejected by the beneficiary bank after it had entered the executed status.
1524	The provided transaction reference has already been used for another transaction. You must provide a unique value for each request	HttpStatus.CONFLICT	IDEMPOTENCY_KEY_CONCURRENCY_CONFLICT
1524	The provided transaction reference has already been used for another transaction. You must provide a unique value for each request	HttpStatus.UNPROCESSABLE_ENTITY	IDEMPOTENCY_KEY_REUSE
1526	The specified accountId or email is invalid	invalid_account_details	The payment failed because either the creditor’s or debtor’s account details were invalid.
1526	The specified accountId or email is invalid	invalid_account_holder_name	The payment failed because the account holder’s name details were invalid.
1540	The transaction exceeds allowed account limits	constraint_violation	The constraints set up for the mandate were breached by this recurring payment.
1542	Transaction was manually cancelled or declined by the merchant	canceled	The PSU cancelled the payment on the hosted payment page or the payment was cancelled using Cancel Payment API.
1542	Transaction was manually cancelled or declined by the merchant	user_canceled_at_provider	The payment failed because the user cancelled the authorisation during the payment flow.
1548	The third party processor has declined the transaction	provider_rejected	The payment was rejected by the provider for an unspecified reason.
1548	The third party processor has declined the transaction	rejected	The payment was rejected for an unspecified reason.
1600	Payment solution general input error, please check payment solution respond	provider_error	The provider has unexpectedly failed when creating the payment.
1605	The amount specified for this operation is incorrect please check the Payment Solution Respons	payment_limit_exceeded	The PSU’s payment limit amount with their bank was breached.
1607	Unknown error by the Payment Solution.	unknown	The payout failed for an unknown reason that does not belong to any of the other reasons.
1607	Unknown error by the Payment Solution.	unknown_error	The payment failed for an unknown reason.
1613	Unable to process this operation please check the Payment Solution Response	verification_declined	The payment did not satisfy the requested verification check.
1617	Payment Stopped by the Scheme	scheme_error	There was an issue with the selected payment provider or payment scheme.
1619	Not Authorized please check the Payment Solution Response	authorization_failed	The PSU failed to authorise the payment successfully.
1631	Token Error, please check payment solution respond	expired	The token of the payment expired before the payment got authorised, thus it won’t be possible to execute the payment.
1631	Token Error, please check payment solution respond	provider_expired	The payment failed because the token or exchange code used to communicate with the bank expired.
1632	Unknown payment solution error code	HttpStatus.INTERNAL_SERVER_ERROR	UNKOWN_ERROR
1658	Unable to auth	not_authorized	The PSU cancelled the payment or wasn’t able to successfully authenticate on the provider’s UI.
1663	Unsupported card scheme	scheme_unavailable	There is no scheme available given the provider selection configuration.
1692	No payment details were provided	HttpStatus.NOT_FOUND	PAYMENT_NOT_FOUND
2002	Unauthorized communication error	HttpStatus.UNAUTHORIZED	UNAUTHENTICATED
3099	Unidentified error	HttpStatus.NOT_IMPLEMENTED	NA
5042	The payment solution is not available	HttpStatus.FORBIDDEN	FORBIDDEN
8013	Exceed limits. Check Service Response	HttpStatus.TOO_MANY_REQUESTS	RATE_LIMIT_EXCEED
8025	Connection Error.Check Service Response	internal_server_error	An error has occurred within TrueLayer when processing the payment.

PayByBank

Introduction

Operations supported

PayByBank transaction flow

Requirements to use PayByBank

Customer requirements

Merchant requirements

Create an account and application for your Truelayer merchant

Get your Truelayer account information and set up AP return URLs

Generate an encryption key for Truelayer, upload it and set up AP notification URLs

Choose between open loop or close loop operation

Request payment solution configuration

Environments and endpoints: Staging and Production

Required and optional data PayByBank

Host2Host integration

Authorization

Request

Authorization request parameters

Response

Void

Request

Parameters of the void request

Response

Refunds

Refunds via Truelayer management panel

Refund by request

Request

Parameters of the refund request

Response

PayByLink (payment link)

Request

PayByLink request parameters

Response

Payout

Requirements for Payouts in PayByBank

Request

Payout request parameters in Paybybank

Close loop

Open loop

Response

Payouts pending to be approved or rejected

Check transaction status

Request

Parameters of the check transaction status request

Response

Hosted Integration

Authorization

Request

Authorization request parameters

Response

JavaScript Integration

Authorization

Getting the authToken and rendering the cashier

Charge

Parameters of the charge request

Response

Error codes

visto recientemente

Products

Sales

Technical Support

Partners

SmartWiki, Powered by AI

Consulta la documentación de las distintas secciones de integraciones:

Addon Payments

Cyberpac

POS integrated Payments

Addon Payments

Consult the documentation of the different integrations sections:​

Consult the documentation of the different integrations sections: