Testing and Scenarios

Overview

Before you start processing live refunds through the Refunds API, test your integration to make sure everything works as expected. The sandbox environment allows you to simulate refund scenarios without needing real transaction data. The sandbox uses the refund amount you submit in your request to determine which type of response is returned. This lets you validate success cases, error conditions, and edge cases in a controlled environment. Using your sandbox credentials, you can:

Verify that your integration correctly handles successful refund responses.
Test how your system behaves when refunds are declined or fail validations.
Explore boundary conditions, such as attempting to refund more than the original payment. This ensures your integration is ready for production.

Test Scenarios

Use the following refund amounts to simulate different refund scenarios. The sandbox will return predefined responses based on the amount specified in your refund request.

Full refunds

Validate that your integration correctly processes a refund for the total amount of the original transaction. Full refunds will return amountAvailableForRefund as 0.

Refund Amount	Scenario	Response	Notes
1600	RRN Required in Request	Success or Error (404)	Returns success if `rrn` is provided, error if `rrn` is missing
1605	Success Without RRN in Response	Success	Returns successful response but without `refundTransactionRrn` field
1700	Delayed Success	Success	Returns successful response after a 15-second delay to simulate slow processing
1800	Success	Success	Returns successful response with all fields populated

Note: The sandbox does not track previous refunds for each transaction. Every refund request is treated as if the full transaction amount is still available to be refunded for that transaction.

Partial refunds

Test refunds for less than the original transaction amount, including multiple partial refunds against the same transaction.

Refund Amount	Scenario	Response	Notes
600	RRN Required in Request	Success or Error (404)	Returns success if `rrn` is provided, error if `rrn` is missing
605	Success Without RRN in Response	Success	Returns successful response but without `refundTransactionRrn` field
700	Delayed Success	Success	Returns successful response after a 15-second delay to simulate slow processing
Any other amount	Standard Success	Success	Returns successful response with all fields populated

Special Amount Rules - Amounts Ending in 6

When testing with refund amounts that end in 6 (e.g. 96, 506, 1006), the sandbox simulates a transaction with a maximum refundable amount of $10.00 ("refundAmount": 1000).

Note: The sandbox does not track previously refunded amounts for each transaction. Every refund request is treated as if the full $10.00 is still available to be refunded for that transaction, allowing you to test multiple refund scenarios against the same transaction reference.

Refund Amount	Behavior	Response
≤ 1000 (ending in 6)	Success	Returns `amountAvailableForRefund: 1000 - refundAmount`
> 1000 (ending in 6)	Error	Returns 422 Error with `REFUND_AMOUNT_EXCEEDS_TRANSACTION_AMOUNT`

Examples:

Amount 96 → Success with amountAvailableForRefund: 904
Amount 506 → Success with amountAvailableForRefund: 494
Amount 1006 → Error (exceeds maximum refundable amount)

Error handling

Simulate declined or invalid refund attempts to ensure your system handles failures and edge cases.

Refund Amount	Scenario	Response	Notes
700	Slow Network Simulation	Success after 15s	Introduces artificial latency to test how your integration handles slow responses.
1404	Transaction Not Found	Error (404)	Simulates when the original transaction cannot be found
1422	Refund Exceeds Transaction	Error (422)	Returns error code `REFUND_AMOUNT_EXCEEDS_TRANSACTION_AMOUNT`
2422	Transaction Already Refunded	Error (422)	Returns error code `TRANSACTION_ALREADY_REFUNDED`
3422	Refund Transaction Declined	Error (422)	Returns error code `REFUND_REJECTED`
1500	Server Error	Error (500)	Simulates a generic internal server error from the payments service.

Response Fields

Successful Responses

All successful responses include the following fields:

{
  "refundTransactionReference": "uuid-v4-string",
  "refundTransactionRrn": "12-digit-number",           // Optional, may be omitted
  "refundAmount": "number",                            // as provided when making the call
  "amountAvailableForRefund": "number"
}

Testing Tips

Required vs Optional Fields

RRN Testing: Use amount 600 to test scenarios where a transaction can only be found when RRN is provided (simulates cases where your transactionId may not be unique enough for accurate transaction lookup)
Optional RRN: Use amount 605 to test responses without refundTransactionRrn
Performance Testing: Use amount 700 to test timeout handling (15-second delay)

Important Notes

The sandbox generates a unique UUID for refundTransactionReference on each successful call
The refundTransactionRrn is a randomly generated 12-digit number when present
The amountAvailableForRefund varies based on the test scenario:
- For amounts ending in 6: 1000 - refundAmount (if ≤ 1000)
- For other amounts: Random value between $0.10-$20.10
Optional fields in requests (rrn, refundReason, partnerReference) are accepted but don't affect the response unless specifically tested (e.g., amount 600)