Pay by Bank
About
Pay by Bank relies on open banking, which allows third-party providers to access banking data and initiate transactions on behalf of customers (in line with applicable regulations). Your platform can allow users to pay directly from their bank account, via a range of bank wire transfer schemes.
How it works
The Pay by Bank payment method allows you to redirect the user to their bank to initiate and authenticate the bank wire.
User chooses payment method
On your app or website, the user selects Pay by Bank as the payment method.
You present available banks
Optionally, you can present the user with a list of banks for them to select theirs. If you provide the BankName in your API request, the user doesn’t have to choose it on the hosted page on redirection.
You can also invite the user to select the Scheme they wish to use, otherwise the instant one is used by default (if supported by the bank).
To retrieve the supported banks, call the GET View supported banks for Pay by Bank endpoint, filtering on the user’s country. In the response, you can display the Name to the user in the list, while the BankName is the value to send in your payment request. For each bank, the list of Scheme values supported is also returned.
As well as the BankName, you can also invite the user to provide their IBAN and BIC which preselects the account to be debited. Otherwise, the user selects the account to debit on the hosted page.
In Germany (DE), banks impose an additional authentication step that can be avoided if you also obtain and provide the user’s IBAN and BIC up front.
Payment initiation
You initiate the payment request by calling POST Create a Pay by Bank PayIn, specifying the ReturnURL to which the user will be returned after payment (whatever the outcome).
If the ReturnURL redirects to your app, rather than a website, you need to also set the PaymentFlow to APP.
You should also provide the BankName, Scheme and IBAN and BIC if you obtained them from the user.
Caution – Pay-in currency must match account currency
The currency of the pay-in request must correspond to the currency of the account the user selects, otherwise the user is returned an error and the pay-in fails.
Redirection
You redirect the user to the hosted page via the RedirectURL in the API response.
On the hosted page, the user initiates the payment by:
- Selecting their bank (based on
Country), unless specified inBankName - Selecting the account to be debited, which requires authentication to connect to their bank (unless specified by
IBANandBIC) – this is known as the account information service (AIS) that is authenticated in some countries, notably Germany - Authenticating their payment – this is known as the payment initiation service (PIS) which is always authenticated in all countries
Note – Session timeout 9 minutes
The Pay by Bank session lasts for 9 minutes, at which point the pay-in fails automatically if no action has been taken by the user.
Return
After payment, the user is returned on your specified ReturnURL:
- To a website if
PaymentFlowisWEB(default value) - To a mobile app if the
PaymentFlowisAPP
Outcome
If the payment was initiated successfully by the user, then the response parameter ProcessingStatus is returned with its only value PENDING_SUCCEEDED and the Status is CREATED.
ProcessingStatus is only returned if the payment initiation was successful, and it triggers a webhook for the dedicated event type:
PAYIN_NORMAL_PROCESSING_STATUS_PENDING_SUCCEEDED
ProcessingStatus only has one value, PENDING_SUCCEEDED, which is temporarily returned until the final outcome is known. If it is not returned, then the payment was not initiated successfully by the user.
When the bank wire from the user’s account is received on Mangopay’s account, the pay-in’s Status changes from CREATED to SUCCEEDED and the ResultCode changes to 000000. This outcome triggers a webhook for the event type:
PAYIN_NORMAL_SUCCEEDED
Depending on the Scheme that is used, it can take up to 72 hours for the pay-in to succeed.
If the pay-in fails, it’s Status changes to FAILED and a ResultCode and ResultMessage are returned giving the reason (see Functional errors below). This outcome triggers a webhook for the event type:
PAYIN_NORMAL_FAILED
Banks and schemes
Once redirected on the RedirectUrl to the Pay by Bank hosted experience, the user selects their bank (unless sent in BankName) and chooses the account to be debited.
On the hosted Pay by Bank page, however, they are not able to select the scheme used for the payment.
You can send the Scheme in your API request, and we recommend that you present this choice to the user beforehand.
To retrieve the banks supported by Pay by Bank, you can use the GET View supported banks for Pay by Bank endpoint.
Note – Ensure clear communication with the user
Whether you leave the Scheme choice to the user (recommended) or not, you should communicate clearly which scheme is being used.
Furthermore, it is possible for a bank to charge the user additional fees (separately) for an instant scheme, but this will become less common as markets adapt.
By default (with the exception of Denmark) the local instant payment scheme is used for the payment if it is supported by the bank, otherwise the non-local scheme is used. If Country is DK then the Scheme must be specified – there is no default because there are two instant schemes available.
If your API call specifies the instant scheme but the bank doesn’t support it, then the non-instant scheme is used. However, the API returns the value that you sent, even after the funds arrive on Mangopay’s account and the Status becomes SUCCEEDED.
Supported schemes
The following Scheme values are available depending on the Country:
Supported banks
The banks supported by Pay by Bank are available via the GET View supported banks for Pay by Bank endpoint.
For testing data, see Payment methods - Testing.
Refunds
Pay by Bank relies on bank wire schemes which have no native refund functionality. However, you can refund pay-ins by using payouts and specifying the initial transaction ID. See Refunds using payouts for details.
Functional errors
If the Pay by Bank PayIn Status changes to FAILED, the following ResultCode errors may be returned.