# Authorisation Source: https://docs.rocka.live/api-reference/authorisation You can find your personal API credentials on the **Integration** tab in your Rocka Hub. For more details on where to get your API key, see [Get your API key](https://docs.rocka.live/manage-your-account/account-settings/get-your-api-key). ## Authorise your API calls In Rocka, you'll have two pairs of keys for both the sandbox and production environments. | Key | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | | API key | Your main API key. Always include it in the request header as `x-api-key`. | | Sign key | Your unique signature key. For more details, see [Security checks](/api-reference/security-checks). | To make API calls to `stage.api.rocka.live`, use your sandbox (test) credentials. To make API calls to `api.rocka.live`, the production environment, use your live credentials. **Sample request:** ```curl theme={null} curl --request POST \ --url https://api.stage.rocka.live/api/payments/logo \ --header 'Accept: application/json, text/json, text/plain' \ --header 'Content-Type: application/*+json' \ --header 'x-api-key: your-api-key-goes-here' \ --data '{ "currency": "EUR" }' ``` # Callbacks Source: https://docs.rocka.live/api-reference/callbacks Rocka will send you payment and payout callbacks to the `webhookUrl` you provided. ## Open banking payments ### Regular webhooks ```json expandable lines theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"M816254739082 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` ```json expandable lines theme={null} { "PaymentId": "192142e8-e723-47a4-8db1-27690ac37a28", "Status": "Done", "Signature": "3b0aeedd56acca8fd574d54b89982aac15f033052f4a2f01024a32d47c537d0a", "MerchantPaymentId": "order123", "Reference": "P264739851096 IN", "Amount": 50.0, "Currency": "EUR", "CardId": null, "Remitter": { "Name": "Max Mustermann", "Iban": "DE17500105179569697752", "SortCode": null, "AccountNumber": null }, "AdditionalData": null, "DetailedInfo": null, "Method": "open-banking", "BankId": "sparkasse_de", "IsSenderBank": false, "BankTransactionId": null, "Settled": "No", "SettlementDate": null, "CardNumberLast4": null } ``` ```json expandable lines theme={null} { "PaymentId":"fa315e4d-bc55-4671-88ff-ece52a801690", "Status":"Failed", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"Q583961274085 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":null, "Settled":"No", "SettlementDate":null } ``` ### Extended webhooks Extended webhooks include additional metadata, such as the decline reason for failed payments. For more information on how to set up extended webhooks, see [Set up extended webhooks](/webhooks/set-up-extended-webhooks). For more information on payment decline reasons, see [Payment decline reasons](/manage-your-account/your-balance-and-transactions/payment-decline-reasons). ```json expandable lines theme={null} { "PaymentId": "034225e4-faf0-48ca-a9d2-78eb05162cd2", "Status": "Awaiting confirmation", "Signature": "19841111afb86adadc41c57ef5b54850711814905232e503c4514fee23a35cd7", "MerchantPaymentId": "515ede8d-7ebd-4f0b-8608-6f6a0effd88a", "Reference": "7U8QO73D PAYMENT", "Amount": 123, "Currency": "EUR", "CardId": null, "Remitter": { "Name": "Max Mustermann", "Iban": "DE17500105179569697752", "SortCode": null, "AccountNumber": null }, "AdditionalData": null, "DetailedInfo": { "RejectReason": null, "ProcessingStatus": "ApprovedByBank" }, "Method": "open-banking", "BankId": "sparkasse_de", "IsSenderBank": true, "BankTransactionId": null, "Settled": "No", "SettlementDate": null } ``` ```json expandable lines theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":null, "ProcessingStatus":"Settled" }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` ```json expandable lines theme={null} { "PaymentId":"4f8b1e6c-9a3d-475e-b2c7-6d9a3f1e8c47", "Status":"Failed", "Signature":"a2f9c6e3d8b7104ea9f6c3e8d1b704ea7c9f2d5b8e1a4c7f9d2b6e3a8c5f1d9b", "MerchantPaymentId":"89012345-8901-8901-8901-89012345678b", "Reference":"M816254739082 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"BLOCKED BY RISK", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-09T15:07:43.451926Z" } ``` ```json expandable lines theme={null} { "PaymentId": "a749684c-0a26-48bc-a9a3-388bc22f94b7", "Status": "Failed", "Signature": "4d49b0ce1309d6caf7257b85d5cb71a85c0c11ab646baad49bab41c193a2e67d", "MerchantPaymentId": "48295013-7592-3841-9204-58301928475", "Reference": "E394856880734 IN", "Amount": 20000, "Currency": "EUR", "CardId": null, "Remitter": { "Name": "Not Provided", "Iban": null, "SortCode": null, "AccountNumber": null }, "AdditionalData": null, "DetailedInfo": { "RejectReason": "BLOCKED VALIDATION", "ProcessingStatus": null }, "Method": "open-banking", "BankId": "erste_bankaustria_at1", "IsSenderBank": false, "BankTransactionId": null, "Settled": "No", "SettlementDate": null, "CardNumberLast4": null } ``` ```json expandable lines theme={null} { "PaymentId":"7a3e9c1f-4d8b-462a-9f5c-1e7d4a9c3b68", "Status":"Failed", "Signature":"d9b4a7c1f5e2036da7c1f4e9b6203da8c4f7e1a9d6b3c8f2a5d9e1c4b7a3f6d0", "MerchantPaymentId":"78901234-7890-7890-7890-78901234567a", "Reference":"L462987315204 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FORM EXPIRED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-07-25T22:16:04.983271Z" } ``` ```json expandable lines theme={null} { "PaymentId":"2d6f9c4a-7e1b-483d-a659-8c3f7e1a9d52", "Status":"Failed", "Signature":"f1a8c4e7d2b9053fa8c2e6d9b4107fc3a7e9d2c8b5f1a4e8c9d3b6f2a5e8c1d4", "MerchantPaymentId":"67890123-6789-6789-6789-67890123456f", "Reference":"K857293641075 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: INITIATION FAILED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-12T04:38:51.129467Z" } ``` ```json expandable lines theme={null} { "PaymentId":"9e4c7a1f-3b6d-489a-8c2e-5f9d3a7b1e64", "Status":"Failed", "Signature":"c8a3f7e1d4b9026ca7f3e9c2d6b5108ec4a8f1d7b3e6a9c2f5d8b1e4a7c9f3d6", "MerchantPaymentId":"56789012-5678-5678-5678-56789012345e", "Reference":"J394857261048 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: INITIATION REJECTED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-05T20:41:16.702384Z" } ``` ```json expandable lines theme={null} { "PaymentId":"6b9d4f2a-1e8c-47a3-9d5b-3f8a1c6e9d24", "Status":"Failed", "Signature":"b4e9c2a7f5d81036e4a9c7f2d5b8106e3a9f4c8d1b7e2a5f9c3d6b1e8a4f7c2d", "MerchantPaymentId":"45678901-4567-4567-4567-45678901234d", "Reference":"H720384951627 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: INITIATION ABANDONED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-10T11:27:38.564923Z" } ``` ```json expandable lines theme={null} { "PaymentId":"a1f7d3e9-6c2b-4890-b5a1-8d3e7f9c2a41", "Status":"Failed", "Signature":"e7c4a1f8d5b2946ce1a7f4d8b5926c3ea9f1d4b7c2a8e5f9c1d4b7a2e8f5c9d1", "MerchantPaymentId":"34567890-3456-3456-3456-34567890123c", "Reference":"G581926473058 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FORM ABANDONED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-07-28T16:53:07.291645Z" } ``` ```json expandable lines theme={null} { "PaymentId":"3c8e1f4a-9b27-4d6c-a851-2e7f9c4d8b36", "Status":"Failed", "Signature":"5d2a8f7e1c4b9036a7f2e8c1d5b4a907f3e6c9d2a8f7e1c4b9036a7f2e8c1d5b", "MerchantPaymentId":"23456789-2345-2345-2345-23456789012b", "Reference":"F193847265091 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: PAYMENT REJECTED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-03T09:14:22.837451Z" } ``` ```json expandable lines theme={null} { "PaymentId":"7f3a92b1-5e6d-4c8a-9f21-8b6d3e4a71c9", "Status":"Failed", "Signature":"a91f3c8d6e2b47a9f5c1d8e3b6a2f947c1e8d3b6a294f7c1e8d3b6a2f947c1e8", "MerchantPaymentId":"87654321-4321-4321-4321-09876543210a", "Reference":"E827461950382 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: PAYMENT EXPIRED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2026-08-14T13:42:29.104857Z" } ``` ## Payouts ```json expandable lines theme={null} { "Id":"12345678test123456789", "Status":"Done", "CreatedAt":"2024-10-07T06:13:51.0834821Z", "ExecutedAt":"2024-10-07T06:15:04.4400235Z", "Amount":1000, "Fee":12, "Currency":"EUR", "RequestId":null, "RejectReason":null, "Type":"OpenBanking", "CardNumber":null, "CardHolderReference":null, "Iban":"TT123456789HFE112345", "BeneficiaryName":"John Doe", "BeneficiaryRef":"12345678 PAYOUT", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", } ``` ```json expandable lines theme={null} { "Id":"12345678test123456789", "Status":"Failed", "CreatedAt":"2024-10-07T06:13:51.0834821Z", "ExecutedAt":"2024-10-07T06:15:04.4400235Z", "Amount":1000, "Fee":12, "Currency":"EUR", "RequestId":null, "RejectReason":null, "Type":"OpenBanking", "CardNumber":null, "CardHolderReference":null, "Iban":"TT123456789HFE112345", "BeneficiaryName":"User Testing", "BeneficiaryRef":"12345678 PAYOUT", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", } ``` ```json expandable lines theme={null} { "Id": "e00d0e92bcee43dea15efb65fc597509", "Status": "Rejected", "CreatedAt": "2026-03-30T11:19:33.0866336Z", "ExecutedAt": "2026-03-30T11:19:47.5517654Z", "Amount": 11, "Fee": 0, "Currency": "EUR", "RequestId": "392uj9joiq", "RejectReason": null, "Type": "OpenBanking", "CardNumber": null, "CardHolderReference": null, "Iban": "FI1410093000123458", "BeneficiaryName": "John Doe", "BeneficiaryRef": "9ZMT1TTK PAYOUT", "Signature": "0396e7e4dd5167ece4cd37b2611c5d13102ab75fa7943ac05995d06cd6fe31e8" } ``` # Create a payment Source: https://docs.rocka.live/api-reference/create-open-banking-payments POST /api/payments At least one of `customerId` or `email` is required. ### About `providerId` and `iban` * To pre-select a bank for your customer, include `providerId`. * To skip the payment form entirely and navigate the customer straight to their bank's payment form, include the `iban` parameter. * If you include both parameters but the `iban` does not match the `providerId` bank, your customer will still be prompted for their IBAN on the payment form (with the bank pre-selected). # Error codes Source: https://docs.rocka.live/api-reference/error-codes You can test your integration against these error codes. ## Authorisation | Error code | Description | Solution | | ------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 - Unauthorized | The API key you entered couldn't be verified. | Use a valid API key. To find your API key, go to the Integration tab of your [Rocka Hub](https://hub.rocka.live).

For API requests to `api.stage.rocka.live` (including through the playground on this docs site), use your sandbox key. For API requests to `api.rocka.live`, use your production API key. | ## Payouts | Error code | Description | Solution | | --------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------- | | `Currency is incorrect` | This payout currency is currently not supported for payouts. | Use `EUR`. | | `Payout already exists` | A payout with this `requestId` has already been created. | Send the request with a unique `requestId`. | | `Invalid IBAN format` | The IBAN does not match the required format. | Check the IBAN and submit it in a valid format. | | `Invalid IBAN` | The IBAN is valid in format but couldn't be verified. | Use a valid, existing IBAN. | | `Beneficiary name is invalid, name should contain first name and last name` | The beneficiary name must include both a first name and a last name. | Enter the beneficiary’s full name. | | `Amount must be positive` | The payout amount is zero or below zero. | Enter an amount greater than zero. | | `Amount must have at most 2 decimal places` | The payout amount has more than two decimal places. | Enter an amount with no more than two decimal places. | | `Requested amount exceeds limit` | The payout amount exceeds the maximum allowed limit of 9000 EUR. | Enter an amount of 9000 EUR or less. | | `Not enough balance` | Your payout balance is too low to complete this payout. | Top up your payout balance or enter a lower amount. | ## Payment links | Error code | Description | Solution | | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `PaymentId is required` | The `PaymentId` parameter in your request is empty. | Resend the request with a `PaymentId` included. | | `PaymentId has incorrect format` | The `PaymentId` parameter in your request does not match the required format. | The `PaymentId` should match this regex format: `^[0-9a-zA-Z._-]+$`. | | `Amount is required` | The `amount` parameter in your request is empty or missing. | Resend the request with the `amount` parameter included. | | `Amount should be greater than or equal to 0.01.` | The value of the `amount` parameter in your request is too low. | Resend the request with the `amount` parameter set to a value of at least 0.01. | | `Amount should be less than or equal to 30000.` | The value of the `amount` parameter in your request is too high. | Resend the request with the `amount` parameter set to a value of up to 30000. | | `Currency is required.` | The `currency` parameter in your request is empty or missing. | Resend the request with the `currency` parameter. | | `Currency has incorrect value for this merchant.` | The currency you included is not supported by Rocka. | Resend the request with a valid currency (EUR). | | `Name is required.` | The `name` parameter in your request is empty or missing. | Resend the request with the `name` parameter. | | `Name length should be less than or equal to 100.` | The value of the `name` parameter in your request is too long. | Resend the request with the `name` parameter set to a string of a length of 100 characters or less. | | `Payment description is required.` | The `paymentDescription` parameter in your request is empty or missing. | Resend the request with the `paymentDescription` parameter. | | `Payment description length should be less than or equal to 255.` | The `paymentDescription` in your request is too long. | Resend the request with a valid `paymentDescription`. | | `ReturnUrl has incorrect format.` | The `returnUrl` parameter in your request does not match the required format. It should be an absolute URL that includes the protocol (http or https). For example, `https://example.com/returlUrl`. | Resend the request with a valid `returnUrl`. | | `WebhookUrl has incorrect format.` | The `webhookUrl` parameter in your request does not match the required format. It should be an absolute URL that includes the protocol (http or https). For example, `https://example.com/webhookUrl`. | Resend the request with a valid `webhookUrl`. | | `Expiry date should be in UTC format.` | The`expiryDate` parameter in your request does not match the required format. It should include the date and time in the UTC timezone. For example, `2026-02-27T16:11:51.2863657Z` (with Z for the UTC timezone). | Resend the request with a valid `expiryDate`. | | `Expiry date should be greater than current date.` | The`expiryDate` should be a point in the future. | Resend the request with a valid `expiryDate`. | # Getting started Source: https://docs.rocka.live/api-reference/getting-started Our API is designed to help you smoothly process payments and provide your customers with the best user experience. ### API environments | Environment | URL | | :---------- | :----------------------------- | | Sandbox | `https://api.stage.rocka.live` | | Live | `https://api.rocka.live` | ### API endpoints | Request method | Endpoint | | :------------- | :------------------------------------------------------------------------------------------------------------ | | POST | [Display customised payment buttons](/api-reference/open-banking-payments/display-customised-payment-buttons) | | POST | [Create a payment](/api-reference/open-banking-payments/create-a-payment) | | GET | [Check payment status](/api-reference/open-banking-payments/check-payment-status) | | GET | [Get the list of top banks](/api-reference/open-banking-payments/get-the-list-of-top-banks) | | POST | [Create payment links](/api-reference/open-banking-payments/create-payment-links) | | POST | [Create a payout](/api-reference/payouts/create-a-payout) | | GET | [Check payout status](api-reference/payouts/check-payout-status) | | GET | [Export payments](/api-reference/manage-your-data/export-payments) | | GET | [Export payouts](/api-reference/manage-your-data/export-payouts) | If you need any help, please feel free to send us an email at [support@rocka.live](mailto:support@rocka.live).
# Check your balance Source: https://docs.rocka.live/api-reference/manage-your-data/check-your-balance /api-reference/openapi.yaml get /balances/api/balance Check your balance for any currency. If you're getting the 'Balances are not configured' error message, contact us at [support@rocka.live](mailto:support@rocka.live). # Export payments Source: https://docs.rocka.live/api-reference/manage-your-data/export-payments /api-reference/openapi.yaml get /api/payments # Export payouts Source: https://docs.rocka.live/api-reference/manage-your-data/export-payouts /api-reference/openapi.yaml get /api/payouts # Check payment status Source: https://docs.rocka.live/api-reference/open-banking-payments/check-payment-status /api-reference/openapi.yaml get /api/payments/{id} # Display customised payment buttons Source: https://docs.rocka.live/api-reference/open-banking-payments/display-customised-payment-buttons /api-reference/openapi.yaml post /api/payments/logo # Get the list of top banks Source: https://docs.rocka.live/api-reference/open-banking-payments/get-the-list-of-top-banks /api-reference/openapi.yaml get /api/providers/top # Check payout status Source: https://docs.rocka.live/api-reference/payouts/check-payout-status /api-reference/openapi.yaml get /api/payouts/{id} # Create a payout Source: https://docs.rocka.live/api-reference/payouts/create-a-payout /api-reference/openapi.yaml post /api/payouts # Retrieve payment details Source: https://docs.rocka.live/api-reference/retrieve-payment-details There are three ways to retrieve payment data: 1. **returnUrl**. Once the payment is completed, the customer is redirected to the `returnUrl` you specified in the request, passing key details such as the payment status and ID. 2. **Check payment status**. You can request data about the payment using its `PaymentId`. For more details, see [Check payment status](ref:checking-the-payment-status). 3. **webhookUrl**. If you provided a `webhookUrl`, you can listen for events and receive notifications when the payment's status changes. Sample webhook URL: [https://test.example.com/api/notification/valuehere?key=your-key-value-here](https://test.webhook.url/api/notification/valuehere?key=your-key-value-here) ### Sample webhook body (successful payment) ```json theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"User Testing", "Iban":"TT123456789HFE112345", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` ### Sample webhook body (failed payment) ```json theme={null} { "PaymentId":"fa315e4d-bc55-4671-88ff-ece52a801690", "Status":"Failed", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"User Testing", "Iban":"TT123456789HFE112345", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":null, "Settled":"No", "SettlementDate":null } ``` ### Extended webhook features If you enabled extended webhook features, you'll receive additional data in the webhook body, including the `rejectReason` and `processingStatus` from the sender's bank. You can activate this in your Rocka Hub [account settings](https://hub.rocka.live/account/settings). ### Sample extended webhook body (successful payment) ```json theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"User Testing", "Iban":"TT123456789HFE112345", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":null, "ProcessingStatus":"Settled" }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` ### Sample extended webhook body (failed payment) ```json theme={null} { "PaymentId":"49798514-dc44-4c7e-bce3-47778a3a91da", "Status":"Failed", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"User Testing", "Iban":"TT123456789HFE112345", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":{ "RejectReason":"FINANCIAL INSTITUTION: INITIATION ABANDONED", "ProcessingStatus":null }, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"No", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` # Retrieve payout details Source: https://docs.rocka.live/api-reference/retrieve-payout-details There are two ways to retrieve payout data: * **Check payout status**. Pass the payout ID to the` GET /api/payouts/{id}` endpoint to retrieve detailed data, including its status. For more details, see [Check payout status](/api-reference/check-payout-status). * **Webhook notification**. If you provided a `webhookUrl`, you can listen for events and receive notifications when the payout's status changes. ## Sample webhook body for a successful payout ```json theme={null} { "Id":"12345678test123456789", "Status":"Done", "CreatedAt":"2024-10-07T06:13:51.0834821Z", "ExecutedAt":"2024-10-07T06:15:04.4400235Z", "Amount":1000, "Fee":12, "Currency":"EUR", "RequestId":null, "RejectReason":null, "Type":"OpenBanking", "CardNumber":null, "CardHolderReference":null, "Iban":"TT123456789HFE112345", "BeneficiaryName":"User Testing", "BeneficiaryRef":"12345678 PAYOUT", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", } ``` ## Sample webhook body (failed payout) ```json theme={null} { "Id":"12345678test123456789", "Status":"Failed", "CreatedAt":"2024-10-07T06:13:51.0834821Z", "ExecutedAt":"2024-10-07T06:15:04.4400235Z", "Amount":1000, "Fee":12, "Currency":"EUR", "RequestId":null, "RejectReason":null, "Type":"OpenBanking", "CardNumber":null, "CardHolderReference":null, "Iban":"TT123456789HFE112345", "BeneficiaryName":"User Testing", "BeneficiaryRef":"12345678 PAYOUT", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", } ``` If you're using `webhookUrl` to retrieve payout data, make sure to include security checks to prevent bank fraud. For more details, see [Security checks](/api-reference/security-checks). # Security checks Source: https://docs.rocka.live/api-reference/security-checks If you're using `returnUrl` and/or `webhookUrl` to handle payment or payout results, add quick security checks to prevent bank fraud. ## Anti-fraud security checks 1. **Verify the payment signature:** Use this formula to verify the payment signature: ```text theme={null} signature = sha256(paymentId + status + signatureKey) ``` The `signatureKey`is unique to your account and ensures the payment result data is authentic. 2. **Prevent duplicate signatures:** This makes sure the payment result isn't duplicated. Fraudsters can't create a valid signature without your `signatureKey`, but they can intercept a legitimate result and try to resend it. To prevent this, implement duplicate detection: * Compare the `paymentId` of the current order with the one in the payment result. * Store every `paymentId` that has been processed and reject any repeated submissions with the same ID. # Create a payment link Source: https://docs.rocka.live/api-reference/shortlinks/create-a-payment-link /api-reference/openapi.yaml post /api/payments/short-links If you can't create payment links, reach out to us at support@rocka.live. # Integrate direct bank payments Source: https://docs.rocka.live/integration-guide/api/custom-layout Custom Layout Small 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 three 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 (if you include their `customerId` or `email`). Alternatively, you can store the customer's bank (`BankId`) and IBAN (`Iban`) that you received through payment webhooks and use this data for their next payment. * **Offer open banking payments to customers who pay with card**. If you have a custom card payment form on your site, you can offer direct open banking payments as an alternative. To do so, send Rocka the first 6 digits of the customer's credit card number when creating the payment. This will generate a payment link that will redirect the customer directly to their bank's payment form. ## Set up a custom bank layout Complete your onboarding in Rocka Hub and get your API keys. For more details, see [Get your API key](/manage-your-account/account-settings/get-your-api-key) and [Authorisation](/api-reference/authorisation). 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). 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: ```curl theme={null} curl --request GET \ --url 'https://api.rocka.live/api/providers/top?country=FR&count=3' \ --header 'accept: application/json' \ --header 'x-api-key:' ``` ```json theme={null} [ { "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 } ] ``` You can use either the bank logos returned by `GET /providers/top` or your own custom assets.  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 their`customerId `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: ```curl theme={null} 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", // include the providerId parameter "email": "test@example.com" } ' ``` ```json theme={null} { "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" } ``` ### Offer open banking payments to customers who pay by card Offer open banking payments to customers who pay by card If you have a custom card payment form on your website, you can offer open banking payments to customers who chose to pay by card. This will generate a payment link that detects the customer's bank and redirects them straight to their bank's payment form, skipping Rocka's payment page. To do so, when you create a payment, pass the first 6 digits of the credit card number the customer entered as `iin`: ```curl theme={null} 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" } ' ``` ## 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: ```curl theme={null} { "webhookUrl": "https://example.com/hookurl", "returnUrl": "https://example.com/returnurl" } ``` For more details, see [Retrieve payment details](/api-reference/retrieve-payment-details). # Integrate hosted checkout Source: https://docs.rocka.live/integration-guide/api/default-layout Start Desktop Rocka's hosted checkout page lists all banks supported by Rocka in every locale. Once your customer chooses their country and payment method, they will be able to place a payment directly through their bank app. ## Set up hosted checkout Complete your onboarding in Rocka Hub and get your API key. For more details, see [Get your API key](/manage-your-account/account-settings/get-your-api-key) and [Authorisation](/api-reference/authorisation). Use the `POST /payments` endpoint to create a payment. At the very least, you will need to include these parameters: * payment `amount` and `currency` * `returnUrl`, which is the address your customer will be redirected to once they complete the payment. * `paymentId`, which is the payment's unique identifier in your system. This will only be visible to you. Rocka will return this paymentId in every callback. * `description`, which is a short payment description your customer will see.  You can include other optional parameters to personalise the payment experience for your customer. For more details, see [POST Create a payment](/api-reference/open-banking-payments/create-a-payment). `POST /payments` returns the payment's ID and payment URL. We recommend that you direct the customer to the payment URL. This can be either in the same tab or a new tab. Once the customer completes the payment, they will be redirected to the `returnUrl` you specified. You can also embed the payment URL as an iFrame for on-page checkout. If you choose this option, make sure the iFrame embed's size allows the customer to comfortably use their bank's web interface. ## What your customer will see The hosted checkout page displays a selection of banks available in the customer's country. If you include the customer's `ipAddress` in your request, their country will be preselected on the payment page and they will see their local banks straight away. If you don't, Rocka will get the customer's IP address and suggest the country automatically. Overview Payment Once the customer chooses their bank, they will be either asked for their IBAN or prompted to scan a QR code to confirm the payment in their bank app. This depends on their bank and locale. If you provide the `providerId`parameter, the bank will be preselected for your customer, but they will still need to enter their IBAN or scan the bank QR code. If you provide their`iban`in the request, they will be redirected straight to their bank app, skipping Rocka's hosted checkout page. For more information, see [Integrate direct bank payments](/integration-guide/api/custom-layout). Most banks will need your customer's IBAN to process the payment. If your customer can't find it, they'll be able to simply log in with their bank through the mobile app or the web version Some payment methods and banks will generate QR codes your customer can scan to complete the payment in the mobile app. They can also log in to the web version # Getting started with your integration Source: https://docs.rocka.live/integration-guide/api/overview Use Rocka's hosted checkout page or integrate direct bank payments Rocka supports two ways to accept open banking payments: 1. **Hosted checkout**: use Rocka’s hosted payment page to show customers the available banks for their country. 2. **Direct bank payments**: show your own bank buttons and send customers directly to their selected bank using Rocka's API methods. Before you start, get your API keys (for more information, see [Get your API key](/manage-your-account/account-settings/get-your-api-key)). You can build and test your integration in the sandbox before your merchant account is approved. To accept real payments, complete your onboarding in Rocka Hub. ## Choose your payment flow ### Hosted checkout Use hosted checkout if you want Rocka to show the available banks to your customer. With hosted checkout, you add Rocka’s payment button to your website or checkout page. When the customer clicks it, they open Rocka’s hosted payment page, choose their bank, and complete the payment through their banking app or online banking. Overview Payment Hosted checkout is best if: * you want the fastest way to start accepting open banking payments; * you serve customers in several countries; * you want Rocka to manage the bank selection page for you; * you do not need to build a custom bank selection interface. To integrate hosted checkout, create a payment using the `POST /payments` endpoint. You can include the customer’s IP address in the request so Rocka can show the relevant country’s bank list by default. [Integrate hosted checkout →](/integration-guide/api/default-layout) ### Direct bank payments Pay With Ing Use direct bank payments if you want to show your own bank buttons in your checkout. With direct bank payments, you choose which banks to show on your website. When the customer clicks a bank button, Rocka sends them directly to that bank’s payment form. This can skip Rocka’s hosted bank selection page. Direct bank payments are best if: * you want full control over the checkout experience; * you want to show specific banks or payment methods; * you want to optimise checkout for specific countries; * you want to make checkout faster for returning customers. To integrate direct bank payments, create a payment using the `POST /payments` endpoint and include the `iban` parameter for the selected bank. [Integrate direct bank payments →](/integration-guide/api/custom-layout) ## What happens after the customer pays After the customer confirms the payment with their bank, Rocka sends you a callback with the payment status. You can use those callbacks to update the payment in your system and show the correct status to the customer. For more details on callbacks, see [Callbacks](/api-reference/callbacks). By default, payments are confirmed when your bank sends Rocka a callback verifying that the funds were deposited into your account. You can enable trusted payments for returning customers. In this case, the payment will be confirmed once the customer's bank sends a callback confirming that a transaction has been sent out of their account. For more details, see [Enable trusted payments](/manage-your-account/account-settings/enable-trusted-payments). # Test your payment integration Source: https://docs.rocka.live/integration-guide/api/test-your-integration Before you start accepting payments, test your Rocka integration to make sure everything's working as intended. ## Test your integration 1. Go to your [Rocka Hub](https://hub.rocka.live/) > **Integration**. You'll find your test API key under **Test credentials**. 2. To verify your site is connected to Rocka, make a test API call with your sandbox key. For example, you can try the Get the list of top banks endpoint. Try creating your first payment with your test API key using the [POST /api/payments endpoint](/api-reference/create-open-banking-payments). The response will include the `url` parameter, which is the payment link: ```json Sample response theme={null} { "id": "d620b186-f3fd-41cf-afa2-35d290002c87", "url": "https://stage.checkout.rocka.live/?id=d620b186-f3fd-41cf-afa2-35d290002c87&country=EU&info_isNew=true", "qrCode": null, "token": "v4.local.nfh1xPxnY6ekBQYmMaEOF7_sivOdy6WPrXW1eZJGVEeIiL8BXZep_P7lJS02KAjRqOWVabXvebTK8hVccovmxQ6SFLttc80lPvEjN2hvOgjAx20bJxQD07I5gp8X-EHoiIrit4ANEEvSM5iYOhnkobrB6yLC-tD8YQO8K_pCmOTyTPjx261JwZ5BNLoB_Klg27nPRRpJE400_9VQIbWR95s4dnH2NM2NRFJQ83LZCDJ07gTimjEHkpfDYXrU1F7-9Jb9JhylqETRTevCwOlWBUex-agzobgMLxG4dNU6frGM6uMI0RpKZcYjbWcp5lwdqiLhtBJ4ZTPicDDm0tNh_JCA5UbXyxx1GxPe76Eh1RYHhP3S-BOJ-yk1EI0eHkC0bPQw-IMQ_AHohhZR2-Qu8nk2lQ", "threeDsData": null, "status": "New" } ``` To make a test payment, follow the steps below. This payment flow will be the same for your customers. 1. Open the link in the `url` parameter. If you're located in one of the supported locales, Rocka will automatically detect your country and offer local banks. You can also change the country using the dropdown list in the top-right. 2. For most locales, you will be prompted for a local IBAN. You can use one of the test IBANs provided below. Once you enter the IBAN, click **Proceed to payment** → **Go to bank**. | Country | Test IBAN | | ----------- | ------------------------------ | | Austria | `AT442060462969882667` | | Belgium | `BE86548395218350` | | Bulgaria | `BG11UNCR70002357555869` | | Czechia | `CZ3950512253883481546422` | | Denmark | `DK0350517819194565` | | Estonia | `EE241288345534195171` | | Finland | `FI6096556523142496` | | France | `FR2017569000305334518641U14` | | Germany | `DE28500105175177352381` | | Greece | `GR8001017482782598767712723` | | Hungary | `HU47109180019139163433933895` | | Ireland | `IE13BOFI900017196892` | | Italy | `IT41G0300203280631633853611` | | Latvia | `LV47BFTO78HL1E44S557U` | | Lithuania | `LT531333837574574518` | | Luxembourg | `LU970101299639351982` | | Netherlands | `NL06RABO3605998615` | | Norway | `NO4643439454116` | | Poland | `PL92109024024223477881477127` | | Portugal | `PT36003506517684676992475` | | Romania | `RO48PORL2287771354415982` | | Slovakia | `SK8937262781847381589252` | | Slovenia | `SI37131411574212932` | | Spain | `ES6221001524961942163622` | | Sweden | `SE6131639725357863517336` | \ For some banks, you can also ignore the prompt and click **Don't remember your IBAN?** at the bottom of the form. Next, click **Connect to your bank account** → **Go to Bank Europe**, which will send you directly to the test bank website. 3. On the test bank login form, you can enter these usernames to trigger a specific payment status. Once you enter the username, click **Continue** → **Yes, I agree**. | **Username** | Payment status | | ------------ | --------------------------------------------------------------------------------------------------------------------- | | `done` | Done. You will also receive [callbacks](/api-reference/callbacks) from the sender and recipient banks. | | `failed` | Failed. You will receive a callback from the sender bank. | | `processing` | Awaiting confirmation. You will not receive any callbacks. | 4. Select any of the test bank accounts. Click Go to bank and log in to the test bank website again. For real payments, your customers will be redirected to their bank app to confirm the payment on this step. Once the payment goes through, you will receive a callback to the `webhookUrl` you specified in your request. You will also see the payment in the **Transactions** section in your Rocka Hub. To see other callbacks you can potentially receive for other payment statuses, see [Callbacks](/api-reference/callbacks). ```json theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"12345678 PAYMENT", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"User Testing", "Iban":"TT123456789HFE112345", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` # Integrate with Rocka Source: https://docs.rocka.live/integration-guide/overview Get started with open banking payments You can start accepting open banking payments in just a few steps. To set up your integration and start accepting payments, complete your onboarding in [Rocka Hub](https://hub.rocka.live). If you have any questions, please reach out to your personal manager. You can start working on your integration using your test API key while we're reviewing your application. You'll be able to generate live payments once your application is approved. To start accepting payments, get your personal API keys. You can find them on the **Integration** tab on the left-hand sidebar in your Rocka Hub. You'll need your keys to make every call to the API. For more information, see [Get your API key](/manage-your-account/account-settings/get-your-api-key). Decide whether you want to direct your customers to Rocka's bank selection page or integrate payments through specific banks. Integrate with Rocka's API and accept open banking payments on your site Test your integration on the sandbox server (`https://stage.api.rocka.live`) to make sure everything works as expected. Make sure your integration is processing everything correctly throughout the entire payment flow Once you've tested your integration and completed your onboarding in Rocka Hub, you're ready to start accepting real payments. To go live, 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](/webhooks/enable-webhook-notifications)). You can also set up extended webhooks with additional payment metadata ([Set up extended webhooks](/webhooks/set-up-extended-webhooks)). Your first live transactions may be flagged by Rocka's antifraud system. If your test transactions aren't going through, please contact us at [support@rocka.live](mailto:support@rocka.live). # Create a payout Source: https://docs.rocka.live/integration-guide/payouts/create-a-payout Payouts are transactions you send from your balance to your customers' bank accounts. For example, if you need to issue a refund to a payment method other than the original one your customer used, you can issue a payout instead. To issue a payout, you need to have enough funds on your payout balance. You can find your payout balance on the Payouts tab. ## Create a payout To make API requests, you'll need your API key. For more details, see [Authorisation](/api-reference/authorisation). To create a payout, use the [/api/payouts](https://docs.rocka.live/api-reference/payouts/create-a-payout) API endpoint. ```curl theme={null} curl --request POST \ --url https://api.stage.rocka.live/api/payouts \ --header 'Content-Type: application/json' \ --header 'x-api-key: ' \ --data ' { "amount": 50, "currency": "EUR", "iban": "DE75512108001245126199", "beneficiaryName": "Mark Schmidt", "webhookUrl": "https://example.com/webhookUrl", "requestId": "payout1794" } ' ``` ```json theme={null} { "iban": "DE75512108001245126199", "beneficiaryName": "Mark Schmidt", "beneficiaryRef": "BC83DF4B0A634 OU", "id": "e01186ef9a1442afb924a8ad60d24390", "status": "Processing", "createdAt": "2026-05-08T11:26:10.455Z", "amount": 50, "currency": "EUR", "requestId": "payout1794" } ``` # Test your payouts Source: https://docs.rocka.live/integration-guide/payouts/test-your-payouts Before you start issuing payouts to your customers, make sure your integration works as expected. You can create test payouts, implement additional security checks and verify you're correctly handling all payout statuses. ## Create a test payout To create a test payout: 1. Go to your [Rocka Hub](https://hub.rocka.live/) > **Integration**. You'll find your test API key under **Test credentials**. 2. To verify your site is connected to Rocka, make a test API call with your sandbox key. For example, you can try the Get the list of top banks endpoint. Try creating your first payment with your test API key using the [POST /api/payouts endpoint](/api-reference/create-open-banking-payments). To trigger specific payout statuses, use these IBANs: | Status | IBAN | | --------- | ----------------------------- | | Executing | `FR7630006000011234567890189` | | Done | `GB33BUKB20201555555555` | | Failed | `DE75512108001245126199` | | Rejected | `FI1410093000123458` | Once your payout is processed, you will receive a callback. For more information, see [Callbacks](https://docs.rocka.live/api-reference/callbacks#payouts). ## Before you go live We recommend that you double-check everything works as expected on sandbox before your payouts go live: ### 1. Security checks If you're using the `webhookUrl` parameter to receive payout status updates, implement security checks to protect yourself against bank fraud. [Security checks → ](/api-reference/security-checks) ### 2. Error handling Verify you're properly validating all input data. [Error codes → ](https://docs.rocka.live/api-reference/error-codes) ### 3. Status handling Make sure you're processing all payout status callbacks (`Done`, `Rejected` and `Failed`). [Payout callbacks → ](/api-reference/callbacks#payouts) # Download llms-full.txt Source: https://docs.rocka.live/llms-full # Add new users Source: https://docs.rocka.live/manage-your-account/account-settings/add-new-users You can give members of your team limited access to your Rocka Hub. To add new users to your Hub, reach out to us at [support@rocka.live](mailto:support@rocka.live). Your employees will be able to: * see the Transactions, Payouts and Reports tabs * generate reports. They will not be able to see any other tabs or issue refunds on your behalf. They also will not be able to access your API keys, bank account details or any other data. # Change your password Source: https://docs.rocka.live/manage-your-account/account-settings/change-your-password To change your password: Go to the [Rocka Hub log in page](https://hub.rocka.live/). If you’re logged in to your Rocka Hub, you will need to click **Log out** at the bottom-right corner first. Click **Forgot your password?** under the password field. Enter your account email and click **Get code**. Check your email. If the email you entered is associated with a Rocka account, you will get a verification code. Go back to the log in form. Enter the verification code you received and click **Verify code**. Click **Create password**. Enter and confirm your new password. Click **Confirm** to confirm your changes. # Enable trusted payments Source: https://docs.rocka.live/manage-your-account/account-settings/enable-trusted-payments When a customer makes a payment through Rocka, their bank sends us callbacks with transaction status updates. Once the receiving bank (either yours, or Rocka’s if you use our accounts) confirms that the funds have been received, the payment is considered complete. If trusted payments are enabled, payments from returning customers are considered complete as soon as their bank confirms that the transaction has been initiated from their account. This helps ensure a smooth payment experience, even if there are processing delays. ## Enable trusted payments  To enable trusted payments, contact your account manager. # Get your API key Source: https://docs.rocka.live/manage-your-account/account-settings/get-your-api-key To start accepting payments, get your personal API keys. You can find them in the Integration tab on the left-hand sidebar in your Rocka Hub. Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **Integration**. Copy your sandbox and production API keys. Api Keys # Use Rocka Hub Source: https://docs.rocka.live/manage-your-account/index Manage your account and bank details Rocka Hub is your merchant dashboard for managing payments, refunds, reports and account settings. Use it to track activity, update account details and access key tools for your business. ## Manage your finances Add or remove business bank accounts used for collecting payments from your customers Issue refunds to your customers Generate payment and payout reports ## Manage your account settings Change your company details and manage your websites Create Rocka Hub accounts for your employees and manage your account settings # About refunds Source: https://docs.rocka.live/manage-your-account/refunds/about-refunds You can issue full or partial refunds for your customers for any reason. ## What to expect * Refunds use your active (payout) balance, so you will not be able to initiate a refund if your current balance cannot cover it. * Refunds can only be sent to the customer's original payment method. To issue a refund to a different destination (such as another card or bank account), [create a payout](/integration-guide/payouts/create-a-payout) instead. # Check refund status Source: https://docs.rocka.live/manage-your-account/refunds/check-refund-status To check the status of a refund: Go to your [Rocka Hub](https://hub.rocka.live/). On the left-hand sidebar, click [**Transactions**](https://hub.rocka.live/transactions).  Find and click the transaction you issued a refund for. Scroll down until you see the Refunds section. You will see the full refund metadata, including its current status. For more information on refund statuses, see [Refund statuses and timelines](/manage-your-account/refunds/refund-statuses-and-timelines). # Issue a refund Source: https://docs.rocka.live/manage-your-account/refunds/issue-a-refund Issue A Refund To issue a refund:  Go to your [Rocka Hub](https://hub.rocka.live/). On the left-hand sidebar, click [**Transactions**](https://hub.rocka.live/transactions).  Find and click the transaction you want to issue a refund for.  Scroll down until you see the Refunds section. Click **Make Refund**. Enter the refund amount. You can also include a comment explaining the reason for this refund. Click **Submit refund**.  # Refund statuses and timelines Source: https://docs.rocka.live/manage-your-account/refunds/refund-statuses-and-timelines Refunds are generally processed within 5 to 10 business days, but it can sometimes take longer. For example, this can be the case for reversals or partial reversals. If you have any questions regarding a refund you issued, reach out to us at [support@rocka.live](mailto:support@rocka.live). Refunds can have these statuses: | Status | Description | | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Sent` | Temporary status. Rocka has successfully initiated the refund. This doesn't guarantee the customer has already received it. | | `Done` | Final status. The customer's bank has notified Rocka that the customer received the refund. | | `Failed` | Final status. The refund could not be processed and failed. For example, this can happen if there is an insufficient balance on your account to issue the refund. | # Check your balance Source: https://docs.rocka.live/manage-your-account/reports/check-your-balance You can see your balance in your Rocka Hub:  1. **Current balance** on the Payouts tab. This is the balance you can use to send payouts to your customers. It consists of balance top-ups (both in fiat and crypto), as well as settlement nettings. Current Balance   2. **Income balance** on the sidebar. Your Current week balance is the sum of your incoming pay-in transactions over this week. Your Last week balance is the sum of your incoming pay-in transactions over the past week. Income Balance   All balances are estimated based on the most recent currency conversion rates. This means that if you are accepting payments in currencies other than EUR, Rocka will use the EUR equivalent of each amount to calculate and display your balance.  At this time, you can only see your income balance in your Rocka Hub. Your total revenue balance will not be displayed.  # Create a payment report Source: https://docs.rocka.live/manage-your-account/reports/create-a-payment-report Reports are limited to the latest 100,000 transactions matching the filters. Transactions over this limit will not be part of the report. To create a payment (transaction) report: In your [Rocka Hub](https://hub.rocka.live), click **Transactions** on the left-hand sidebar. If you want to only include specific columns or payouts in your report, apply filters before you generate it. * To filter columns, click   and toggle columns either on or off. * To filter transactions by payment method, amount and other fields, set the filter in the table. For example, to only include failed payouts, click the Status dropdown and select Failed. Click the **Generate report** button at the top-right corner. Once your report is ready, you will find it on the **Reports** tab on the left-hand sidebar. It will be available for download as a .csv file. # Create a payout report Source: https://docs.rocka.live/manage-your-account/reports/create-a-payout-report To create a payout report: In your [Rocka Hub](https://hub.rocka.live), click **Payouts** on the left-hand sidebar. If you want to only include specific columns or payouts in your report, apply filters before you generate it. * To filter columns, click   and toggle columns either on or off. * To filter payouts by payment method, amount and other fields, set the filter in the table. For example, to only include failed payouts, click the Status dropdown and select Failed. Click the **Generate report** button at the top-right corner. Once your report is ready, you will find it on the **Reports** tab on the left-hand sidebar. It will be available for download as a .csv file. # Download a report Source: https://docs.rocka.live/manage-your-account/reports/download-a-report All successfully generated reports are always available for download as .csv files. To find a report you have previously generated: Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **Reports**. You will see every report you have ever generated. To download a report, scroll down, find the report you need and click the **Download** icon next to it. # Add a website Source: https://docs.rocka.live/manage-your-account/your-account-details/add-a-website To add a website:  Go to your [Rocka Hub](https://hub.rocka.live/).  On the left-hand sidebar, click **My account**.  Switch to the **Websites** tab.  Enter or paste the URL of the website you want to add and click **Add website**.  When you add a website, it will be automatically submitted for review. Once it’s reviewed and verified by our team, its status will change to *Approved*.  Add Website # Edit your company details Source: https://docs.rocka.live/manage-your-account/your-account-details/edit-your-company-details Edit Company Details To edit your company details before your profile is approved:  Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **My account**.  On the Company details tab, click **Edit**.  You can edit: * Company legal name: Your company's legal name. This should match your company's incorporation certificate. * Country of incorporation: The country where your company was registered. * Company registration number: Your company's unique number in Rocka's records. It was assigned to your company when you registered your account. * Date of incorporation: The date your company was registrered. * Industry sector: Your company's industry.  Enter your new details and click **Save**. If you want to edit your company details after your profile was approved, your changes will be reviewed by Rocka before they are applied. Your changes are sent for review once you click Save. # Remove a website Source: https://docs.rocka.live/manage-your-account/your-account-details/remove-a-website If you want to remove one of the websites you added to your account, you can do so in your Rocka Hub. You can only accept payments on websites that are added to your Rocka Hub and have the Approved status. If you remove a website, all new payments with that website's `ShopID` will fail. ### Remove a website Go to your [Rocka Hub](https://hub.rocka.live/).  On the left-hand sidebar, click **My account**.  Switch to the **Websites** tab.  Find the website you want to delete in the **Your websites** section.   Hover over the website and click the **Remove**  icon.  Click **Remove** in the pop-up window to confirm your action. # Understand blocked countries Source: https://docs.rocka.live/manage-your-account/your-account-details/understand-blocked-countries Blocked countries By default, customers from all countries can place payments on all your websites. However, sometimes certain countries can be blocked for all your websites or a specific website. For some websites, country-based restrictions are applied to comply with laws, regulations, sanctions and licensing requirements. You can find lists of blocked countries on the Websites tab (**My account** → **Websites**) in your Rocka Hub. ### Countries blocked by default This is the list of countries that are blocked for all your websites. You can find it on top of the page under Countries blocked by default. If a website has a custom list of blocked countries, the default list will not be applied. ### Custom blocked countries On the Websites table, you can see which country restrictions are applied for every website: * List of blocked countries: This is the list of countries that are blocked for this specific website. The default list will not be applied. * *Inherited*: This website uses the default list of blocked countries. No other countries are blocked specifically for this website. * *No countries are blocked*: The default list of blocked countries is not applied to this website and there are no custom restrictions. Customers from all countries will be able to place payments on this website. # Payment decline reasons Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/payment-decline-reasons There are several reasons payments can get the Failed status. If a payment failed, you will find the reason on the Transactions tab in your Rocka Hub. You can also enable extended webhooks and receive callbacks that include decline reasons. To receive extended callbacks that include payment decline reasons, enable them in your Rocka Hub. For more information, see [Set up extended webhooks](/webhooks/set-up-extended-webhooks). ## Payment decline reasons You can find the exact reason why a payment was declined in your Rocka Hub (Transactions > the Decline Reason field on the payment's entry). If you enabled extended webhooks, you will also receive the decline reason in the payment callback. For more information, see [Set up extended webhooks](/webhooks/set-up-extended-webhooks). | Decline reason | Rocka Hub | Description | Callback | | --------------------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `BLOCKED BY RISK` | Blocked by risk | The customer was blocked by the risk scoring system. | See full callback: [Failed (Blocked by risk)](/api-reference/callbacks#failed-payment-blocked-by-risk) | | `BLOCKED VALIDATION` | - | The payment you created was over the maximum payment limit (EUR 8,500). | See full callback: [Failed (Blocked validation)](/api-reference/callbacks#failed-payment-blocked-validation) | | `FORM EXPIRED` | Form expired | The customer did not complete the payment in time. | See full callback: [Failed (Form expired)](/api-reference/callbacks#failed-payment-form-expired) | | `FINANCIAL INSTITUTION: INITIATION FAILED` | Initiation failed | The customer couldn't open the payment link. There could also be a problem on their bank's side. | See full callback: [Failed (Initiation failed)](/api-reference/callbacks#failed-payment-initiation-failed) | | `FINANCIAL INSTITUTION: INITIATION REJECTED` | Initiation rejected | The bank declined the payment initiation. | See full callback: [Failed (Initiation rejected)](/api-reference/callbacks#failed-payment-initiation-rejected) | | `FINANCIAL INSTITUTION: INITIATION ABANDONED` | Initiation abandoned | The customer did not click the link to complete the payment in their bank app. | See full callback: [Failed (Initiation abandoned)](/api-reference/callbacks#failed-payment-initiation-abandoned) | | `FORM ABANDONED` | Form abandoned | The customer did not complete the payment in their bank app. | See full callback: [Failed (Form abandoned)](/api-reference/callbacks#failed-payment-form-abandoned) | | `FINANCIAL INSTITUTION: PAYMENT REJECTED` | Payment rejected | The bank declined the payment the customer placed. For example, this can happen when the customer does not have enough funds on their balance. | See full callback: [Failed (Payment rejected)](/api-reference/callbacks#failed-payment-payment-rejected) | | `FINANCIAL INSTITUTION: PAYMENT EXPIRED` | Payment expired | The customer's bank did not confirm the payment was successful within 9 days after the customer had placed the payment. | See full callback: [Failed (Payment expired)](/api-reference/callbacks#failed-payment-payment-expired) | # Resend payment callbacks Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/resend-payment-callbacks If you didn't receive a payment callback, you can resend it in your Rocka Hub. This is only available for payments (not refunds). Make sure you've properly configured transaction callbacks. For more information, see [Enable webhook notifications](/webhooks/enable-webhook-notifications). ## Resend payment callbacks Add Website To resend a callback: Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **Transactions**. Find and click the payment you want to resend a callback for. Under Timeline, click **Resend callback**. # Transaction statuses Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/transaction-statuses ## Payment statuses All newly created payments get the `New` status. Once a payment is processed, its status will change to either `Done` or `Failed`. Current Balance | Status | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `New` | Temporary status. You have just created this payment. It won't appear in your Rocka Hub until its status changes to Processing. | | `Processing` | Temporary status. If you're using our [hosted checkout](/integration-guide/api/default-layout), this status means the customer clicked the payment link and chose their country and bank. If you're using [direct payments](/integration-guide/api/custom-layout), this status means the customer clicked the payment link (with their bank pre-selected). | | `Awaiting confirmation` | Temporary status. Your customer has placed the payment. Rocka is waiting for a callback from your bank confirming that the payment has been received. | | `Done` | Final status. The payment has been completed. | | `Failed` | Final status. The payment couldn't be completed. For the list of possible decline reasons, see [Payment decline reasons](/manage-your-account/your-balance-and-transactions/payment-decline-reasons). | ## Refund statuses All newly created payments get the `Sent` status. Once a refund is processed, its status will change to either `Done` or `Failed`. For more details, see [Refund statuses and timelines](/manage-your-account/refunds/refund-statuses-and-timelines). # View payout details Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/view-payout-details To view payout details: Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **Payouts**. Find the payout you want to see more details on. You will be able to see detailed payout metadata in the table. If you want to add or hide columns, click the **Columns** button. Filter Payout Columns # View transaction details Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/view-transaction-details To view transaction details:  Go to your [Rocka Hub](https://hub.rocka.live/).  On the left-hand sidebar, click **Transactions**.  Click the transaction you want to see more details on.  You will see the payment amount, bank, order ID and other data, as well as the full status history and current status (or final status, if the payment is completed or failed).  Transaction Info New If you scroll down, you will also be able to issue a refund for this payment and view previous refund data. For more information, see [Issue a refund](/manage-your-account/refunds/issue-a-refund) and [Check refund status](/manage-your-account/refunds/check-refund-status). Issue A Refund # Add a bank account Source: https://docs.rocka.live/manage-your-account/your-bank-accounts/add-a-bank-account Add A Bank Account To add a new bank account:  Go to your [Rocka Hub](https://hub.rocka.live/).  On the left-hand sidebar, click **My account**.  Switch to the **Bank account** tab.  Click **Change C2B account preferences**.  If you want to use a new account for a currency you have previously added, simply replace the IBAN in the form. \ \ To add an account in a new currency, click the **Choose currency** dropdown and check the box next to the currency you want to add. Enter your bank account details in the form that will appear.   Click **Verify** to verify your new bank account. # Remove a bank account Source: https://docs.rocka.live/manage-your-account/your-bank-accounts/remove-a-bank-account To remove a bank account:  Go to your [Rocka Hub](https://hub.rocka.live). On the left-hand sidebar, click **My account**.  Switch to the **Bank account** tab.  Click **Change C2B account preferences**.  Click the **Choose currency** dropdown and uncheck the box next to the currency you want to remove.   Remove Bank Account You always need to have at least one active bank account in your profile. If you have only one remaining, you will not be able to remove it.  # Understand bank accounts Source: https://docs.rocka.live/manage-your-account/your-bank-accounts/understand-bank-accounts You can manage your bank account details on the Bank account tab.  Bank Accounts There are two ways you can collect payments from your customers:  * **Segregated account**. All payments your customers place are deposited to Rocka’s dedicated C2B account. We transfer it to your bank through regular settlements. * **Direct account**. All payments your customers place are deposited straight to your own C2B account.  ## About segregated and direct bank accounts | | Segregated account | Direct account | | ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Acceptance rate | Typically higher acceptance rate | May have a lower acceptance rate | | Fees | Additional fees apply | No extra fees | | Payment timelines | Payments are collected into a dedicated account and settled to you on a regular schedule | Payments are deposited directly into your account after the customer completes the payment | | Reconciliation | Easier to handle using Rocka’s settlement calculations | You may need to reconcile incoming transfers in your own bank account | | Auditing | Centralised records can streamline auditing | Auditing may require checking your own bank records | # Enable webhook notifications Source: https://docs.rocka.live/webhooks/enable-webhook-notifications To receive notifications about payment status changes and other events, set up webhooks. You can use extended webhooks to receive extra metadata. For more details, see [Set up extended webhooks](/webhooks/set-up-extended-webhooks). ## Set up webhook notifications Webhook notifications are available for three endpoints: [Create a payment](/api-reference/create-open-banking-payments), [Create a payout](/api-reference/payouts/create-a-payout) and [Create a payment link](/api-reference/shortlinks/create-a-payment-link). To enable webhook notifications, pass `webhookUrl` in the request parameters. ```curl theme={null} { "webhookUrl": "https://example.com/exampleURL" } ``` ```json expandable lines theme={null} { "PaymentId":"bc973098-3dfb-4700-af20-28ca4fdb583a", "Status":"Done", "Signature":"b2e286bfc7b94ab2342342341881c85b50f286b23462436432d7dfc5fcd05ca2r234r231", "MerchantPaymentId":"12345678-1234-1234-1234-12345678910", "Reference":"M816254739082 IN", "Amount":50.0, "Currency":"EUR", "CardId":null, "Remitter":{ "Name":"Max Mustermann", "Iban":"DE17500105179569697752", "SortCode":null, "AccountNumber":null }, "AdditionalData":null, "DetailedInfo":null, "Method":"open-banking", "BankId":"sparkasse_de", "IsSenderBank":false, "BankTransactionId":"BANKTRANSACTIONID", "Settled":"Yes", "SettlementDate":"2024-10-01T07:18:56.316302Z" } ``` ## Alternative options Apart from setting up webhook notifications, you can also receive up-to-date payment and payout data via `returnUrl` and status check endpoints. For more details, see [Retrieve payment details](/api-reference/retrieve-payment-details) and [Retrieve a payout](/api-reference/retrieve-payment-details/). # Set up extended webhooks Source: https://docs.rocka.live/webhooks/set-up-extended-webhooks ### About extended webhooks Extended webhooks provide you with extra metadata. You'll be notified if: 1. the sending bank approves the transaction (you'll receive a notification with `ApprovedByBank` as the payment status) 2. the payment is credited to the beneficiary's bank account (you'll receive a notification with `Settled` as the payment status) 3. the payment fails (you'll receive a notification with the detailed reason). ## Set up extended webhooks To enable extended webhooks: Go to your [Rocka Hub](https://hub.rocka.live/).  On the left-hand sidebar, click **My account**.  Switch to the **Settings** tab.  Toggle **Allow extended webhooks** on.   For the list of possible reasons why a payment can fail, see [Payment decline reasons](/manage-your-account/your-balance-and-transactions/payment-decline-reasons). If you have any qustions or need help with your payment, contact us at [support@rocka.live](mailto:support@rocka.live).