# 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). |
> [!NOTE]
>
> 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
**Successful payment (fully settled)**
```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"
}
```
**Successful payment (awaiting settlement)**
```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
}
```
**Failed payment**
```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).
**Awaiting confirmation**
```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
}
```
**Successful payment**
```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"
}
```
**Failed payment (Blocked by risk)**
```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"
}
```
**Failed payment (Blocked validation)**
```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
}
```
**Failed payment (Form expired)**
```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"
}
```
**Failed payment (Initiation failed)**
```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"
}
```
**Failed payment (Initiation rejected)**
```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"
}
```
**Failed payment (Initiation abandoned)**
```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"
}
```
**Failed payment (Form abandoned)**
```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"
}
```
**Failed payment (Payment rejected)**
```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"
}
```
**Failed payment (Payment expired)**
```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
**Successful payout**
```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",
}
```
**Failed payout**
```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",
}
```
**Rejected payout**
```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
> [!NOTE]
>
> 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).
For more information, see [Integrate custom checkout](/integration-guide/api/custom-layout).
# 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.
> **More on webhooks**
>
> 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).
> **More on extended webhooks**
>
> ### 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.
> **More on webhooks**
>
> ## 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",
> }
> ```
> [!NOTE]
>
> 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 custom checkout
Source: https://docs.rocka.live/integration-guide/api/custom-layout
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
**1. Step 1. Complete your onboarding**
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).
**2. 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 theme={null}
> 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**
>
> ```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
> }
> ]
> ```
**3. 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.
**4. 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](#offer-open-banking-payments-to-customers-who-pay-by-card).
Sample request and response generating a new payment through La Banque Postale:
> **Sample request**
>
> ```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",
> "email": "test@example.com"
> }
> '
> ```
> **Sample response**
>
> ```json theme={null}
> {
> "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"
> }
> ```
**5. 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.
**6. 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](/api-reference/callbacks) and [Transaction statuses](/manage-your-account/your-balance-and-transactions/transaction-statuses).
> [!TIP]
>
> 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](/webhooks/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](/integration-guide/api/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](/webhooks/enable-webhook-notifications)). You can also set up extended webhooks with additional payment metadata ([Set up extended webhooks](/webhooks/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](#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](#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](#offer-open-banking-payments-to-customers-who-pay-by-card)**
>
> 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:
1. Send a request to the [GET /providers/top](/api-reference/open-banking-payments/get-the-list-of-top-banks) endpoint. This will return a list of popular banks, each with its unique `id` and `iin`.
2. 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](/api-reference/open-banking-payments/display-customised-payment-buttons) and include the bank's `iin` in your request.
3. Every time you create a payment initiated from this button, include the bank's `id` as `providerId` in your request to [POST /payments](/api-reference/create-open-banking-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:
**Step 1**
Pass the customer's `customerId` or `email` to the [POST /payments/logo](/api-reference/open-banking-payments/display-customised-payment-buttons) 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**
>
> ```json theme={null}
> {
> "country": "fr",
> "type": "bank",
> "id": "revolut_fr",
> "displayName": "Revolut",
> "theme": null,
> "url": "https://cdn.rocka.live/logo-button/revolut_fr.svg"
> }
> ```
**Step 2**
When you create the payment, pass the same `customerId` or `email` to [POST /payments](/api-reference/create-open-banking-payments) as well. This skips the bank selection stage and directs the customer to their bank's payment form.
> **Sample request**
>
> ```curl theme={null}
> 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**
>
> ```json theme={null}
> {
> "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](/api-reference/create-open-banking-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](/api-reference/open-banking-payments/display-customised-payment-buttons) 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**
```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"
}
'
```
**Generate a custom payment button**
Sample request:
```curl theme={null}
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:
```json theme={null}
{
"country": "de",
"type": "bank",
"id": "sparkasse_de",
"displayName": "Sparkasse",
"theme": null,
"url": "https://cdn.rocka.live/logo-button/sparkasse_de.svg"
}
```
# Integrate hosted checkout
Source: https://docs.rocka.live/integration-guide/api/default-layout
Rocka's hosted checkout page lists all banks supported by Rocka in every locale. Once your customer chooses their country and payment method, they can place a payment directly through their bank app.
## Set up hosted 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
**1. Step 1. Get your API key**
Create a 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).
To set up and test your integration, use your test (sandbox) API key.
**2. Step 2. Create a payment and configure webhooks**
Use the [POST /payments](\(/api-reference/open-banking-payments/create-a-payment\)) 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
We also recommend that you provide a `webhookUrl` address where Rocka can send payment callbacks.
**3. Step 3. Direct the customer to the payment link**
`POST /payments` returns the payment's ID and a payment URL. Add a payment button to your checkout that directs the customer to this URL. 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.
**4. Step 4. 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). Both these statuses are final, and it's safe to fulfil the customer's order when the payment has the Done status. For more information on callbacks and statuses, see [Callbacks](/api-reference/callbacks) and [Transaction statuses](/manage-your-account/your-balance-and-transactions/transaction-statuses).
> [!TIP]
>
> 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](/webhooks/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](/integration-guide/api/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](/webhooks/enable-webhook-notifications)). You can also set up extended webhooks with additional payment metadata ([Set up extended webhooks](/webhooks/set-up-extended-webhooks)).
## What your customer sees
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 is preselected on the payment page and they see their local banks straight away. If you don't provide `ipAddress`, Rocka detects the customer's IP address automatically and uses it to suggest a country. The customer also sees the payment description (that you provided as `description`).
Once the customer chooses their bank, they 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 is preselected for your customer, but they 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).
> **IBAN prompt step**
>
> Most banks need your customer's IBAN to process the payment. If your customer can't find it, they'll be able to log in with their bank through the mobile app or the web version.
> **QR scan step**
>
> Some payment methods and banks 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. **Custom checkout**: show your own bank buttons and send customers directly to their selected bank using Rocka's API methods.
> [!TIP]
>
> You can integrate both options. For example, you can add a generic Pay by bank button that directs the customer to Rocka's bank selection page, as well as several separate buttons for popular banks in your target region.
### 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.
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
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. Make a test API call**
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.
**2. Create your first payment in sandbox mode**
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"
}
```
**3. Place the test payment**
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**.
> **Test IBANs for each country**
>
> | Country | Test IBAN |
> | - | - |
> | Austria | `AT442060462969882667` |
> | Belgium | `BE86548395218350` |
> | Bulgaria | `BG11UNCR70002357555869` |
> | Croatia | `HR0325000097881796116` |
> | Czechia | `CZ3950512253883481546422` |
> | Denmark | `DK0350517819194565` |
> | Estonia | `EE241288345534195171` |
> | Finland | `FI6096556523142496` |
> | France | `FR2017569000305334518641U14` |
> | Germany | `DE28500105175177352381` |
> | Greece | `GR8001017482782598767712723` |
> | Hungary | `HU47109180019139163433933895` |
> | Iceland | `IS197628766334454111135952` |
> | Ireland | `IE13BOFI900017196892` |
> | Italy | `IT41G0300203280631633853611` |
> | Latvia | `LV47BFTO78HL1E44S557U` |
> | Liechtenstein | `LI2608800294479732234` |
> | Lithuania | `LT531333837574574518` |
> | Luxembourg | `LU970101299639351982` |
> | Netherlands | `NL06RABO3605998615` |
> | Norway | `NO4643439454116` |
> | Poland | `PL92109024024223477881477127` |
> | Portugal | `PT36003506517684676992475` |
> | Romania | `RO48PORL2287771354415982` |
> | Slovakia | `SK8937262781847381589252` |
> | Slovenia | `SI37131411574212932` |
> | Spain | `ES6221001524961942163622` |
> | Sweden | `SE6131639725357863517336` |
> | Switzerland | `CH8389144537329983673` |
\
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.
**4. Process the callback**
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 and payouts
You can start accepting open banking payments and sending payouts in just a few steps.
**1. Create your account**
To set up your integration, create a [Rocka Hub](https://hub.rocka.live) account and get your API keys. For more information, see [Get your API key](/manage-your-account/account-settings/get-your-api-key).
You can start working on your integration using your sandbox API key while we're reviewing your application. You'll be able to generate live payments and payouts once your application is approved.
**2. Set up your integration**
Decide what you want to implement: accept open banking payments from your customers, send payouts to them or both.
> **[Accept payments](/integration-guide/api/overview)**
>
> Integrate with Rocka's API and accept open banking payments on your site
> **[Send payouts](/integration-guide/payouts/create-a-payout)**
>
> Integrate with Rocka's API and send payouts directly to your customers' bank accounts
**3. Test your integration**
Test your integration on the sandbox server (`https://api.stage.rocka.live`) to make sure everything works as expected.
> **[Test your payments](/integration-guide/api/test-your-integration)**
>
> Make sure your integration is processing everything correctly throughout the entire payment flow
> **[Test your payouts](/integration-guide/payouts/test-your-payouts)**
>
> Make sure your integration is processing everything correctly throughout the entire payout flow
**4. Go live**
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](/webhooks/enable-webhook-notifications)). You can also set up extended webhooks with additional payment metadata ([Set up extended webhooks](/webhooks/set-up-extended-webhooks)).
> [!NOTE]
>
> 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
> [!NOTE]
>
> 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.
**Sample request**
```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"
}
'
```
**Sample response**
```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. Make a test API call**
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.
**2. Create your first payout in sandbox mode**
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` |
**3. Process the callback**
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:
**Step 1**
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.
**Step 2**
Click **Forgot your password?** under the password field.
**Step 3**
Enter your account email and click **Get code**.
**Step 4**
Check your email. If the email you entered is associated with a Rocka account, you will get a verification code.
**Step 5**
Go back to the log in form. Enter the verification code you received and click **Verify code**.
**Step 6**
Click **Create password**.
**Step 7**
Enter and confirm your new password. Click **Confirm** to confirm your changes.
# Enable multi-factor authentication
Source: https://docs.rocka.live/manage-your-account/account-settings/enable-mfa
To protect your account, you can enable multi-factor authentication for your account. To do so, contact your account manager or reach out to us at [support@rocka.live](mailto:support@rocka.live).
If you enable multi-factor authentication, you will receive an email with a one-time verification code every time you log in to your Rocka Hub. You will not be able to log in without entering this code. The code will be sent to the email address you use to log in.
# 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.
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live).
**Step 2**
On the left-hand sidebar, click **Integration**.
**Step 3**
Copy your sandbox and production API keys.
# Use Rocka Hub
Source: https://docs.rocka.live/manage-your-account/index
Manage your bank details, payments and payouts
Rocka Hub is your merchant dashboard for managing payments, payouts, refunds, reports and account settings. Use it to track activity, send payouts, update account details and access key tools for your business.
## Getting started
If you're new to Rocka, complete your onboarding in [Rocka Hub](https://hub.rocka.live).
Once your application is approved, you'll be able to accept live payments and send live payouts. If you have any questions, reach out to your account manager or contact us at [support@rocka.live](mailto:support@rocka.live).
## Manage your finances
> **[Understand bank accounts](/your-bank-accounts/understand-bank-accounts/)**
>
> Learn more about how to collect and settle payments through Rocka
> **[Issue refunds](/manage-your-account/refunds)**
>
> Issue refunds to your customers
> **[Create reports](/manage-your-account/reports)**
>
> Generate payment and payout reports
## Manage your account settings
> **[Edit your account details](/manage-your-account/your-account-details)**
>
> Change your company details and manage your websites
> **[Modify your account settings](/manage-your-account/account-settings)**
>
> 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:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click [**Transactions**](https://hub.rocka.live/transactions).
**Step 3**
Find and click the transaction you issued a refund for.
**Step 4**
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
To issue a refund:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click [**Transactions**](https://hub.rocka.live/transactions).
**Step 3**
Find and click the transaction you want to issue a refund for.
**Step 4**
Scroll down until you see the Refunds section. Click **Make Refund**.
**Step 5**
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.
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.
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.
> [!NOTE]
>
> 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
> [!NOTE]
>
> 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:
**Step 1**
In your [Rocka Hub](https://hub.rocka.live), click **Transactions** on the left-hand sidebar.
**Step 2**
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.
**Step 3**
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:
**Step 1**
In your [Rocka Hub](https://hub.rocka.live), click **Payouts** on the left-hand sidebar.
**Step 2**
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.
**Step 3**
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:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live).
**Step 2**
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:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click **My account**.
**Step 3**
Switch to the **Websites** tab.
**Step 4**
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*.
# Edit your company details
Source: https://docs.rocka.live/manage-your-account/your-account-details/edit-your-company-details
To edit your company details before your profile is approved:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live).
**Step 2**
On the left-hand sidebar, click **My account**.
**Step 3**
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.
**Step 4**
Enter your new details and click **Save**.
> [!NOTE]
>
> 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
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click **My account**.
**Step 3**
Switch to the **Websites** tab.
**Step 4**
Find the website you want to delete in the **Your websites** section.
**Step 5**
Hover over the website and click the **Remove** icon.
**Step 6**
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
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.
> [!TIP]
>
> 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).
> [!TIP]
>
> Make sure you've properly configured transaction callbacks. For more information, see [Enable webhook notifications](/webhooks/enable-webhook-notifications).
## Resend payment callbacks
To resend a callback:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live).
**Step 2**
On the left-hand sidebar, click **Transactions**.
**Step 3**
Find and click the payment you want to resend a callback for.
**Step 4**
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`.
| 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:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live).
**Step 2**
On the left-hand sidebar, click **Payouts**.
**Step 3**
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.
# View transaction details
Source: https://docs.rocka.live/manage-your-account/your-balance-and-transactions/view-transaction-details
To view transaction details:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click **Transactions**.
**Step 3**
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).
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).
# Change your bank account details
Source: https://docs.rocka.live/manage-your-account/your-bank-accounts/change-your-bank-account-details
To change your bank account details (for example, add or remove a bank account), contact your account manager.
# Understand bank accounts
Source: https://docs.rocka.live/manage-your-account/your-bank-accounts/understand-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.
> [!TIP]
>
> To change your bank account details, contact your account manager.
## 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.
> [!TIP]
>
> 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"
}
```
> **Sample webhook for a successful payment**
>
> ```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:
**Step 1**
Go to your [Rocka Hub](https://hub.rocka.live/).
**Step 2**
On the left-hand sidebar, click **My account**.
**Step 3**
Switch to the **Settings** tab.
**Step 4**
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).