Request to pay

We offer you the CreateRequestToPay endpoint to initiate an open-banking verified credit transfer from the consumer's bank account to your bank account. This payment method needs a consumer verification for every transaction.

There is no mandate required and the payment will be initiated immediately. After successful initiation you will receive an immediate response about the acceptance (“technical OK”). If you are using our reconciliation service you will also get an additional feedback when the funds are settled (“financial OK”).

In the CreateRequestToPay response, We will return a requestToPayId. This Id is used to transfer the payment to the bank and it also appears on the account statements of all banks involved in clearing the payment.

Workflow

Creating a RequestToPay request

To initiate a RequestToPay, the BC Connect API offers you the CreateRequestToPay endpoint. The following JSON shows an example post request:

{
    "connectorId": "{{connectorId}}",
    "bankAccount": {
        "customer": {
            "merchantId": "{{merchantId}}",
            "givenName": "Max",
            "familyName": "Mustermann",
            "emailAddress": "[email protected]",
            "languageCode": "de"
        },
        "iban": "DE73567139321459454946"
    },
    "currencyCode": "EUR",
    "amount": 201
}

Processing the RequestToPay response

The response contains a hostedPageId that is used in the next step when building the hostedPageView link. At this point, the RequestToPay entity is in the pendingApproval state. The following shows an example response:

{
    "requestToPay": {
        "id": "ad9e7ab018178077c201e44a5ebe8539",
        "merchantId": "7de36158df05015e0de8c3a00b20e1bb",
        "connectorId": "db59637141634e756f18e903104c1e63",
        "customerId": "8fabc8559d3594946f80bbfaf8667d5b",
        "customer": {
            "id": "8fabc8559d3594946f80bbfaf8667d5b",
            "merchantId": "7de36158df05015e0de8c3a00b20e1bb",
            "createdAt": "2023-05-04T12:15:34.6125834Z",
            "state": "active",
            "givenName": "Max",
            "familyName": "Mustermann",
            "countryCode": "DE",
            "languageCode": "de",
            "emailAddress": "[email protected]"
        },
        "bankAccountId": "7ea98b75a10806c117e5a56d17ed5623",
        "bankAccount": {
            "id": "7ea98b75a10806c117e5a56d17ed5623",
            "merchantId": "7de36158df05015e0de8c3a00b20e1bb",
            "customerId": "8fabc8559d3594946f80bbfaf8667d5b",
            "createdAt": "2023-05-04T12:15:34.5341314Z",
            "state": "active",
            "accountHolder": "Max Mustermann",
            "iban": "DE73567139321459454946",
            "currencyCode": "EUR",
            "countryCode": "DE"
        },
        "hostedPageId": "70697283afee5919caf848445c9a521b",
        "createdAt": "2023-05-04T12:15:34.526958Z",
        "state": "pendingApproval",
        "currencyCode": "EUR",
        "amount": 201,
        "reference": "a158c8f1998a6e5d23f5a733e27e550d",
        "softDescriptor": "Thank you for shopping at TestMerchant!."
    }
}

Creating the HostedPage view

As previously mentioned the hostedPageId will now be used to create the hostedPageView link. You can find more about this endpoint under the view endpoint of the hostedPage entity. As described there, you need to specify a success- and a fail-URL as query parameters.

Starting the PIS-Journey

After successfully sending the hostedPageId to the view endpoint, together with a success- and fail-URL, the user will be redirected based on the configured PIS routing.

The PIS-journey

The PIS provider, to whom the user is redirected, takes care of all the steps of the journey. These steps include:

• the selection of the country
• the selection of the customer's bank
• the authentication at the customer's bank
• the selection of the correct bank account
• and finally the initiation of the payment at the selected bank, provided that the customer has sufficient funds

Redirection to the success- (or fail-) URL

Based on the result of the PIS-journey, BC Connect redirects the customer to either the pre-configured success- or fail-URL.

The following query strings will be appended to the merchant callback URLs.

• success = true | false
• requestToPayId = ad9e7ab018178077c201e44a5ebe8539
• reasonCode (← info about the reason of failure)

The following two examples show how the return callback URLs would look like, depending on whether the payment was successful or not:

{{successurl}}?requestToPayId=ad9e7ab018178077c201e44a5ebe8539&success=true

{{failurl}}?requestToPayId=ad9e7ab018178077c201e44a5ebe8539&success=false&reasonCode=SPX 999