Single immediate payment

All Open Banking flows, whether AIS or PIS, UK or EU banks, use the concept of consent - whereby bank account holders provide permission for authorised third-party providers (fin-tech companies, for example) to have access to their financial data (AIS role) or initiate payments (PIS role) on their behalf. The flow for Single Immediate Payments is no exception.

UK BANKS

UK banks have a more or less standardised way of handling the payment flow. Basically it consists of 2 stages - payment consent authorisation by the end-user/bank account holder, and the start of payment settlement.

From the integration side it looks like this: first of all you're requesting our consent URI generation endpoint - for UK banks it's POST /payment/single-immediate-payment-initiation-requests submitting all the data we need to identify the specifics of the payment you want to initiate. Details of the payload can be found here. If everything is fine and all validations pass we return constructed transaction data (under result.single_payment key) and redirect URI (under result.auth_flow) on which the end-user can authorise the consent. After getting this data from our API you send your end-user to the redirect URI present in auth_flow.

In any case, whether the user authorises consent at this stage or not, they'll be redirected back to Fena. If authorisation was successful the settlement of payment will be started and the user will be redirected back to your app using the redirect_uri you've submitted when starting the flow or redirect_uri you've configured on your account while registering with Fena. id, customerPaymentId and status will be passed back to you as query parameters. If something went wrong or authorisation was cancelled by the user you will still be redirected back with one additional parameter in the query string - error.

EU BANKS

EU banks, compared with UK banks, have less standardised ways of handling different cases/flows. We at Fena try to abstract away all the confusions that developers can have by integrating directly with the bank's Open Banking API, providing as standardised a solution as possible.

Here we have a general overview of what it looks like to be integrated with our API and initiate a transaction through it with one of the EU banks. You can find our API docs / spec here.

So first of all client POST’s to consent/payment generation URI: /payment/eu-single-payment-initiation-requests, supplying all the necessary data that helps us to identify what type of transaction they want to create and with which bank. If everything is fine and all validations pass we return constructed transaction data (under result.single_payment key) and redirect URI (under result.auth_flow) on which the end-user of the client can authorise the consent/payment. After getting this data from our API the client redirects their end-user to redirect URI present in auth_flow.

From here, depending on the bank you are interacting with, end-user can be sent to one of these pages:

1. Payment authorisation page,
2. Payment consent authorisation page,
3. Authorisation code generation page.

The first option is relatively straightforward - after authorising the payment on this page, settlement of the transaction will be started. The end-user will be redirected back to the client's app with id, customerPaymentId and status as query parameters. If anything goes wrong one additional error query parameter will be added. Redirect URI of the client's app is submitted while initiating the flow or is configured when the client registers with Fena.

The next two options have one additional intermediary page where the end-user should give additional permission for us to be able to start the settlement process. All redirects are handled by us and partnered banks so our clients will get the same end result regardless of what option the bank uses for getting permissions - we will redirect end-users back to our client’s app (using his/her redirect URI) with above mentioned query parameters.

WEBHOOKS

We will continue to track the statuses for all pending transactions of our clients and send webhook events once any single status is updated. The webhook URI is configured the same way as app redirect URI - submitted on payment initiation request or configured upon registration with Fena. The payload will have following content:

{
    type: ‘single-immediate-payment-initiation_update-status’,
    status: // new detected status of payment,
    comment: ‘detected payment status update’,
    data: { … } // payment details
}

or

{
    type: ‘eu-single-payment-initiation_update-status’,
    status: // new detected status of payment,
    comment: ‘detected payment status update’,
    data: { … } // payment details
}

We are tracking all our transactions until they get successfully settled or run into unrecoverable errors.

Critical: after receiving a webhook event for a transaction's status update, always call our GET payment endpoint to double-check whether the webhook event originated from Fena. For UK banks GET endpoint is /payment/single-immediate-payment-initiation-requests/{paymentId}. And for EU banks GET endpoint is /payment/eu-single-payment-initiation-requests/{paymentId}. If the webhook originated from us then this endpoint will return the same status as was stated in the webhook event. Otherwise status returned from GET request takes precedence.