Integrate direct bank payments

You can design your own payment UI using Rocka’s API endpoints and offer a custom selection of banks. This approach can skip the Rocka payment form entirely. Instead of a link to a Rocka’s hosted payment form, you will get a Rocka Buffet link (https://checkout.rocka.live/buffet?...) which will send the customer directly to their bank’s payment form. There are two ways to integrate direct payments. You can implement either of these or both:

Add bank buttons to your site. You can decide which banks you want to offer and add their buttons to the checkout page. Your customer will be redirected straight to their bank app or website.
Add a button for a bank your customer has already paid through. For returning customers that have already paid through Rocka, you can add a button that will automatically offer their most recent payment method.

Set up a custom bank layout

Step 1. Complete your onboarding

Complete your onboarding in Rocka Hub and get your API keys. For more details, see Get your API key and Authorisation.

Step 2. Get the data

Collect all the required data, some of which might be from your customer. At the very least, you will need to provide the payment amount and currency, as well as your customer’s country (for personalised checkout).

Step 3. Retrieve major banks in your customer's country

Use the GET /providers/top endpoint to retrieve a list of the major banks in your customer’s country. You will need to provide the ISO 3166 code of the country and optionally, the number of banks you want to retrieve. You will get a list of banks with all the required metadata, including each bank’s id and logoUrl. Sample request and response retrieving the list of France’s top banks:

Sample request

curl --request GET \
  --url 'https://api.rocka.live/api/providers/top?country=FR&count=3' \
  --header 'accept: application/json' \
  --header 'x-api-key:'

Sample response

[
{
  "id": "caisse_d_epargne_fr",
  "name": "Caisse d'Epargne",
  "logoUrl": "https://cdn.rocka.live/storage/shared/bank-logo/circle/caisse-d-epargne.svg",
  "iin": 487840,
  "isInstant": true
},
{
  "id": "bnp_paribas_fr",
  "name": "BNP Paribas",
  "logoUrl": "https://cdn.rocka.live/storage/shared/bank-logo/circle/bnp-paribas.svg",
  "iin": 265401,
  "isInstant": true
},
{
  "id": "la_banque_postale_fr",
  "name": "La Banque Postale",
  "logoUrl": "https://cdn.rocka.live/storage/shared/bank-logo/circle/la-banque-postale.svg",
  "iin": 415059,
  "isInstant": true
}
]

Step 4. Add payment buttons

You can use either the bank logos returned by GET /providers/top or your own custom assets.

Step 5. Initiate payments

Design a payment form on your site (using either Rocka’s buttons or your own layout).

To initiate a payment, you will need to pass the bank’s providerId (which was returned as id by the GET /providers/top method). You can also include the customer’s IBAN to streamline the checkout process for them. If you don’t include the IBAN, most providers will ask the customer for it on the payment form.
For returning customers, include theircustomerId or email. Rocka will preselect their bank automatically.

For EUR payments, at least one of customerId or email parameters is required. Sample request and response generating a new payment through La Banque Postale:

Sample request

curl --request POST \
  --url https://api.stage.rocka.live/api/payments \
  --header 'accept: application/json' \
  --header 'content-type: text/json' \
  --header 'x-api-key: 24d0034-5a83-47d5-afa0-cca47298c516' \
  --data '
{
"amount": 1.45,
"currency": "EUR",
"returnUrl": "https://example.com/returnurl",
"paymentId": "9318-123-test-1423",
"description": "Order 1234-DS-1234",
"providerId": "la_banque_postale_fr", // include the providerId parameter
"email": "test@example.com"
}
'

Sample response

{
"id": "4aa4db5c-cc7e-4e93-8742-673c5086e2d3",
"url": "https://checkout.rocka.live/buffet?id=4aa4db5c-cc7e-4e93-8742-673c5086e2d3&token=v4.local.Q1Q1YG9hBPj4dJKSEHtVolAGmsPosmSAmIO_Vpot-mrReibibUtSmuTt0yGryC7F8tRYI3t4c5FVJ-iHp1laliPfW0M5IVPG5zraxmlBoF66AI3PWlIGY3drhFySNTmxfoqrpDsxfS3tLRI4n7cJXQ3RzTAhZPaf3WmVewU9OOZcYPHhjsItR8AgxgVLIijegxwPyrXTPAvBulJjkM3yjsWYkvHK8A1YPDheCnsq06dlEMNqHWACiTtDCyfK_0ir8VTzU1k_SpQikGehrcQmn4u8v0tr4xL36yWj7Be-AVx8GbJ-mIazaD7x4uKbrUmODuaoW6uy_QI6HeWJSsMH4ui-VL7LRTi91hgXJTc8966sTwRsU6S--bsi_ifOiCsm50Cq5HFLmejcxh92yJenOJIxLCx1MRscmWznBMI",
"qrCode": null,
"token": "v4.local.Q1Q1YG9hBPj4dJKSEHtVolAGmsPosmSAmIO_Vpot-mrReibibUtSmuTt0yGryC7F8tRYI3t4c5FVJ-iHp1laliPfW0M5IVPG5zraxmlBoF66AI3PWlIGY3drhFySNTmxfoqrpDsxfS3tLRI4n7cJXQ3RzTAhZPaf3WmVewU9OOZcYPHhjsItR8AgxgVLIijegxwPyrXTPAvBulJjkM3yjsWYkvHK8A1YPDheCnsq06dlEMNqHWACiTtDCyfK_0ir8VTzU1k_SpQikGehrcQmn4u8v0tr4xL36yWj7Be-AVx8GbJ-mIazaD7x4uKbrUmODuaoW6uy_QI6HeWJSsMH4ui-VL7LRTi91hgXJTc8966sTwRsU6S--bsi_ifOiCsm50Cq5HFLmejcxh92yJenOJIxLCx1MRscmWznBMI",
"threeDsData": null,
"status": "New"
}

Retrieve payment status

When creating the payment, you can specify the returnUrl the customer will be redirected to once the payment is completed or the webhookUrl for payment status updates:

{
  "webhookUrl": "https://example.com/hookurl",
  "returnUrl": "https://example.com/returnurl"
}

For more details, see Retrieve payment details.

​Set up a custom bank layout

​Retrieve payment status

Set up a custom bank layout

Retrieve payment status