This guide explains how to simulate refund behavior using the sandbox Merchant Service API. All examples use fixed test IDs and return predefined responses. No real money is moved.
Retrieve refundable details
Use this step to verify that the sandbox transaction supports refunds and to see the maximum refundable amount and expiry time.
Trigger: transaction ID 22b36073-57a3-4c3d-9585-87f2e55275a5
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refundable-details>Response
{
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"refundable_money": {
"amount": 230,
"currency": "EUR"
},
"expiry_datetime": "2020-06-01T13:00:00+02:00"
}Create en retrieve refund details
Refunds in the sandbox are processed asynchronously. First, you send a Create Refund (POST) request; this only confirms that the refund request was accepted and returns the refund with status PENDING. You must then retrieve the refund details using the refund_id to determine the final status, which will be PENDING, SUCCEEDED, or FAILED depending on the sandbox scenario.
Successful iDEAL refund transaction
1. Request - Create Refund
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 30
}
}2. Response - Create Refund
{
"refund_id": "ecabb344-1f2c-4ca5-970a-3ec2649c817f",
"refund_transaction_id": "c2ede5c0-a03f-4f00-a5f5-05aaa6d397af",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"updated_at": "2020-01-01T14:00:00+01:00",
"refund_money": {
"amount": 30,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "PENDING",
"description": "Customer request for refund"
}3. Request - Refund transaction information
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds/ecabb344-1f2c-4ca5-970a-3ec2649c817f>4. Response - Refund transaction information
{
"refund_id": "ecabb344-1f2c-4ca5-970a-3ec2649c817f",
"refund_transaction_id": "c2ede5c0-a03f-4f00-a5f5-05aaa6d397af",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"updated_at": "2020-01-01T14:00:00+01:00",
"refund_money": {
"amount": 30,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "SUCCEEDED",
"description": "Customer request for refund"
}Pending iDEAL refund transaction
User attempts an iDeal refund and it is still pending.
1. Request - Create Refund
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 230
}
}2. Response - Create Refund
{
"refund_id": "cc094aeb-89f7-4123-b60b-ccf83a16320d",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"refund_money": {
"amount": 230,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "PENDING",
"description": "Customer request for refund"
}3. Request - Refund transaction information
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds/cc094aeb-89f7-4123-b60b-ccf83a16320d>4. Response - Refund transaction information
{
"refund_id": "cc094aeb-89f7-4123-b60b-ccf83a16320d",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"refund_money": {
"amount": 230,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "PENDING",
"description": "Customer request for refund"
}Failed iDEAL refund transaction
User attempts an iDeal refund but it fails.
1. Request - Create Refund
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 20
}
}2. Response - Create Refund
{
"refund_id": "96436fe3-caef-4af8-9cb5-dacc0d5e8907",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"updated_at": "2020-01-01T14:00:00+01:00",
"refund_money": {
"amount": 20,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "PENDING",
"description": "Customer request for refund"
}3. Request - Refund transaction information
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds/96436fe3-caef-4af8-9cb5-dacc0d5e8907>4. Response - Refund transaction information
{
"refund_id": "96436fe3-caef-4af8-9cb5-dacc0d5e8907",
"transaction_id": "22b36073-57a3-4c3d-9585-87f2e55275a5",
"created_at": "2020-01-01T13:00:00+01:00",
"updated_at": "2020-01-01T14:00:00+01:00",
"refund_money": {
"amount": 20,
"currency": "EUR"
},
"vat_category": "HIGH",
"payment_brand": "IDEAL",
"status": "FAILED",
"description": "Customer request for refund"Error Scenarios
The sandbox allows you to simulate error conditions so you can verify that your integration handles failure scenarios correctly. Each error is triggered by using a specific test transaction ID or refund request, and returns a deterministic response.
Refundable details of a transaction
INTERNAL_SERVER_ERROR
Description: A network connection failure occurs while requesting refundable details.
Trigger: transaction ID 172f0295-daca-4783-971b-34f89847e69e
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/172f0295-daca-4783-971b-34f89847e69e/refundable-details>Response
{
"errors": [
{
"error_message": "Request to Refund Service failed with internal error for omnikassa contractId 1",
"error_code": "INTERNAL_SERVER_ERROR"
}
]
}NOT_FOUND
Description: Transaction is not known.
Trigger: transaction ID 184f0213-bafa-4794-321b-12f89787e70a
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/184f0213-bafa-4794-321b-12f89787e70a/refundable-details>Response
{
"errors": [
{
"error_message": "Request to Refund Service failed with internal error for omnikassa contractId 1",
"error_code": "NOT FOUND"
}
]
}Create refund
MAXIMUM_REFUNDABLE_AMOUNT_EXCEEDED
The refund request is rejected because the requested amount is higher than what is still refundable for the transaction.
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 2
}
}Response
{
"errors": [
{
"error_message": "Refund amount is too large",
"error_code": "MAXIMUM_REFUNDABLE_AMOUNT_EXCEEDED"
}
]
}REFUND_PERIOD_EXPIRED
The transaction can no longer be refunded because the allowed refund period has passed.
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 3
}
}Response
{
"errors": [
{
"error_message": "Transaction is not refundable any more",
"error_code": "REFUND_PERIOD_EXPIRED"
}
]
}UNKNOWN_TRANSACTION_OR_REFUND_NOT_SUPPORTED
A refund is requested using a transaction ID that does not exist or refers to a transaction type that does not support refunds.
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 4
}
}Response
{
"errors": [
{
"error_message": "Transaction 22b36073-57a3-4c3d-9585-87f2e55275a5 is not found",
"error_code": "UNKNOWN_TRANSACTION_OR_REFUND_NOT_SUPPORTED"
}
]
}INTERNAL_SERVER_ERROR
User attempts a refund but a network connection failure occurs.
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds>
{
"money": {
"currency": "EUR",
"amount": 5
}
}Response
{
"errors": [
{
"error_message": "Request to Refund Service failed with internal error for omnikassa contractId 1",
"error_code": "INTERNAL_SERVER_ERROR"
}
]
}Refund transaction information
NOT_FOUND
Trigger: refund ID aa024aeb-89f7-4123-a23b-ccf83a16450d
Request
<https://api-sandbox.rabobank.nl/openapi/sandbox/omnikassa/merchant/transactions/22b36073-57a3-4c3d-9585-87f2e55275a5/refunds/aa024aeb-89f7-4123-a23b-ccf83a16450d>Response
{
"errors": [
{
"error_code": "NOT_FOUND",
"error_message": "Refund for id 'aa024aeb-89f7-4123-a23b-ccf83a16450d', contract '1' and transaction '22b36073-57a3-4c3d-9585-87f2e55275a5' not found"
}
]
}