Implementing a Callback Page

The callback page, or the Redirect URL is a webpage to where the user is redirected after the payment process is concluded.

Usualy, it is a returning page of an ecommerce or a mobile app screen with a success/failure message.

This link is configured through administration portal. At the side menu, click on “Editar Aplicação“ and after insert the redirect URL link at the field below.

The page itself

The Redirect Page is a normal link that receives 3 parameters by query string at the end of the payment flow.

ticket=eyJhbGciO… (contains information about the token used in the payment process)
state=HVLeXYgP6… (is the consent ID)

To confirm that the payment was processed successfully (and the payment status) you may check the payment status through the Webhook on Payment Initiation or using the Pooling API using some AJAX request to some backend that generates a Token with the API and calls some API to retrieve the payment information.

For example, the state parameter brings the consent ID, so you may use the Get Pix by ConsentId API, like below:

curl --location 'https://api-openkeys.8429y94d.dev.fsapps.app/open-keys-itp/api/payment-consumer/v1/pix/consents/HVLeXYgP6…' \
--header 'Authorization: Bearer <PUT_HERE_THE_ACCESS_TOKEN>' \

The response is something like below:

{
    "data": {
        "paymentId": "9be63638-3ef9-4427...",
        "endToEndId": "E139358932023091...",
        "consentId": "urn:celcoin:1e308e7f-b705-...",
        "creationDateTime": "2023-09-12T19:11:38Z",
        "statusUpdateDateTime": "2023-09-12T19:11:42Z",
        "proxy": "55155...",
        "status": "ACSC",
        "localInstrument": "DICT",
        "cnpjInitiator": "1393589...",
        "payment": {
            "amount": "1.15",
            "currency": "BRL"
        },
        "remittanceInformation": "Pagamento Pix",
        "creditorAccount": {
            "accountType": "CACC",
            "ispb": "9289...",
            "issuer": "0...",
            "number": "101..."
        },
        "debtorAccount": {
            "ispb": "12345678",
            "issuer": "1774",
            "number": "1234567890",
            "accountType": "CACC"
        }
    },
    "links": {
        "self": "https://api.opb.celcoin.dev.fsapps.io/open-banking/payments/v2/pix/payments/9be63638-3ef9-..."
    },
    "meta": {
        "requestDateTime": "2023-09-12T19:11:56Z"
    }
}

It is important not to call these APIs from a public page, as to generate a token you need to use your API ID and secret and it can be exposed if used on a public customer website.

You now have all the payment information you need to create a success page like the one shown below, or a failure screen indicating the reason for the failure. Open Keys contracting companies are responsible for creating and presenting the Journey Completion screen, according to the models presented as suggestions below.

Effectiveness screen templates by Open Finance definition

Payment Initiation

Example screen available in the Open Finance UX Guide

Information that needs to be contained in the execution screen

Payment method (in accordance with current payment arrangements and BCB Resolution No. 109 ;
Value of the payment transaction (optional for successive transactions whose agreed value varies);
Information regarding the Receiver of the Payment Transaction;
Amount of the payment transaction initiation service fee, if any;
payment date (e.g.: payment day, every 5th, every 17th);
Periodicity of transactions and deadline. viii. payment description/purpose information.

Data Sharing

The customer must be notified as Consent Effective (successful return).
In the case of effective consent, present a summary of the request with the following information:

Client ID;
Date and time of confirmation;
Validity of consent: term and end date;
Purpose of use of shared data;
Scope of sharing data (e.g.: registration, account, credit cards, credit operations).