Integrate custom checkout

You can design your own payment UI using Rocka’s API and let customers choose their bank directly from your checkout. In some cases, you can skip Rocka’s payment form entirely. Instead of sending the customer to Rocka’s hosted payment form, POST /payments returns a Rocka Buffet URL that directs them to their selected bank’s payment form.

Set up custom checkout

You can start working on your checkout before you complete your onboarding in Rocka Hub. To set up and test your integration, use your test API key. Follow the steps below to get started.

Configure your integration

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. Retrieve popular banks

Use the GET /providers/top endpoint to retrieve a list of the popular banks in your customer’s country. Provide the ISO 3166 code of the country and optionally, the number of banks you want to retrieve. The response includes the required bank metadata, such as each bank’s id and logoUrl. Sample request and response retrieving the list of the popular banks in France:

Sample request

curl --request GET \
  --url 'https://api.stage.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 3. Add payment buttons

Use the bank information returned by GET /providers/top to create your bank selection. For the button images, you can use Rocka’s logoUrl values or your own custom assets.

Step 4. Create a payment

Use the POST /payments endpoint to create a payment. At a minimum, include these parameters:

payment amount and currency
returnUrl, where the customer is redirected after they complete the payment
paymentId, your unique identifier for the payment. This is only be visible to you. Rocka returns this paymentId in every callback.
description, a short description of the payment shown to the customer on the payment form
customerId or email, the customer’s unique identifiers in your system

To streamline the checkout process, you can:

Include the customer’s IBAN as iban. This will pre-select their country and bank, and in most cases the customer will be redirected to their bank’s payment form.
Include the bank’s providerId (returned as id by GET /providers/top). This will pre-select the customer’s country and bank, but they will still be prompted for their IBAN.
Include the first 6 digits of the customer’s card number as iin. This will pre-select their bank automatically. For more information, see Offer open banking to card payers.

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: ' \
  --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",
"email": "test@example.com"
}
'

Sample response

{
"id": "4aa4db5c-cc7e-4e93-8742-673c5086e2d3",
"url": "https://checkout.rocka.live/buffet?id=4a...MI",
"qrCode": null,
"token": "v4.local.Q1Q1YG9h...MI",
"threeDsData": null,
"status": "New"
}

Step 5. Direct the customer to the payment link

POST /payments returns the payment’s ID (id) and a Rocka Buffet URL (url). Direct the customer to this URL to send them to their selected bank’s payment form. This can be in a new tab or the same tab.Once the customer places the payment, they are redirected to the returnUrl you provided in your payment creation request.

Step 6. Handle payment completion and status updates

When you create a payment, you can provide a webhook URL (webhookUrl) where sends send callbacks with payment status updates.Rocka notifies you when the payment is completed (the Done status) or fails (the Failed status). For more information on callbacks and statuses, see Callbacks and Transaction statuses.

You can enable extended webhooks to receive additional payment metadata (for example, the exact decline reason for failed payments). For more details, see Set up extended webhooks.

Test your integration and go live

Before you start accepting live payments, make sure your integration works as expected. For more information on how to test payments using Rocka’s mock bank, see Test your integration. Once you’ve tested your integration and completed your onboarding in Rocka Hub, you’re ready to go live. To do so, switch to the live server (https://api.rocka.live) and use your live API keys. Make sure you’ve properly configured webhook notifications (Enable webhook notifications). You can also set up extended webhooks with additional payment metadata (Set up extended webhooks).

Improve the payment experience

There are three ways you can use custom checkout to improve your customers’ payment experience. You can implement any combination of these options, or all three.

Highlight popular banks

For example, you can list a bank that’s highly popular in your target region separately for more visibility.

Offer returning customers their last-used bank

For returning customers who have already paid through Rocka, you can add a dynamic button that automatically offers their last used bank.

Offer open banking to card payers

If you have a custom card payment form on your site, you can offer open banking as an alternative when they enter their card number.

Highlight popular banks

If a bank is especially popular with customers in your target region, you can list it as its own button instead of grouping it with the rest. To add a separate button for a popular bank:

Send a request to the GET /providers/top endpoint. This will return a list of popular banks, each with its unique id and iin.
Add a payment button to your checkout form. You can either use your own assets or request a button from Rocka. To use a Rocka button, make a request to POST /payments/logo and include the bank’s iin in your request.
Every time you create a payment initiated from this button, include the bank’s id as providerId in your request to POST /payments. This will generate a payment with the country and bank pre-selected on the form.

Offer returning customers their last-used bank

If a customer has previously paid through Rocka, you can use their customerId or email to dynamically retrieve a payment button for their last-used bank. To do so:

Pass the customer’s customerId or email to the POST /payments/logo endpoint.The response includes a link to a custom payment button tailored to the customer’s bank. Use this link to display the dynamic payment button.

Sample response

{
"country": "fr",
"type": "bank",
"id": "revolut_fr",
"displayName": "Revolut",
"theme": null,
"url": "https://cdn.rocka.live/logo-button/revolut_fr.svg"
}

When you create the payment, pass the same customerId or email to POST /payments as well. This skips the bank selection stage and directs the customer to their bank’s payment form.

Sample request

   curl --request POST \
      --url https://api.stage.rocka.live/api/payments \
      --header 'Content-Type: application/*+json' \
      --header 'x-api-key: ' \
      --data '
    {
      "amount": 100,
      "currency": "EUR",
      "returnUrl": "https://example.com",
      "paymentId": "Order_173921",
      "description": "Payment for order 173921",
      "customerId": "xCID-012453739"
    }
    '

Sample response

{
"id": "f719ab50-56f3-4dd8-82bf-0e97fd147b41",
"url": "https://checkout.rocka.live/buffet?id=f719ab...aw",
"threeDsData": null,
"status": "New"
}

Offer open banking payments to customers who pay by card

If you have a custom card payment form, you can offer open banking as an alternative after the customer enters their card number. When you create the payment (using the POST /payments endpoint), pass the first six digits of the card number as iin. Rocka will identify the customer’s bank and generate a payment link that directs them to that bank’s payment form. You can also generate a custom payment button on the fly. To do so, send a request to the POST /payments/logo endpoint and include the first six digits of the card number as iin. The endpoint will return a link to the payment button that you can display on your payment form.

Create a payment
Generate a custom payment button

      curl --request POST \
        --url https://api.stage.rocka.live/api/payments \
        --header 'accept: application/json' \
        --header 'content-type: text/json' \
        --header 'x-api-key: ' \
        --data '
      {
      "amount": 19.45,
      "currency": "EUR",
      "returnUrl": "https://example.com/returnurl",
      "paymentId": "9318-123-test-1423",
      "description": "Order 1234-DS-1234",
      "iin": "492942", 
      "email": "test@example.com"
      }
      '

Sample request:

      curl --request POST \
        --url https://api.rocka.live/api/payments/logo \
        --header 'Content-Type: application/*+json' \
        --header 'x-api-key: ' \
        --data '
      {
        "currency": "EUR",
        "country": "DE",
        "iin": "403649"
      }
      '

Sample response:

      {
      "country": "de",
      "type": "bank",
      "id": "sparkasse_de",
      "displayName": "Sparkasse",
      "theme": null,
      "url": "https://cdn.rocka.live/logo-button/sparkasse_de.svg"
      }

Quickstart

Integrate with Rocka

Payouts

Webhooks

Open banking payments

Your account details

Your bank accounts

Reports and reconciliation

Refunds

Account settings

Integrate custom checkout

Set up custom checkout

Configure your integration

Test your integration and go live

Improve the payment experience

Highlight popular banks

Offer returning customers their last-used bank

Offer open banking to card payers

Highlight popular banks

Offer returning customers their last-used bank

Offer open banking payments to customers who pay by card

​Set up custom checkout

​Configure your integration

​Test your integration and go live

​Improve the payment experience

Highlight popular banks

Offer returning customers their last-used bank

Offer open banking to card payers

​Highlight popular banks

​Offer returning customers their last-used bank

​Offer open banking payments to customers who pay by card

Set up custom checkout

Configure your integration

Test your integration and go live

Improve the payment experience

Highlight popular banks

Offer returning customers their last-used bank

Offer open banking payments to customers who pay by card