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"
        }
    ]
}