Documentation

ERROR_ADDING_REFUND

Message: The request tried to create a refund, but the payment was not found. The request was rejected. Corrective action: Use the ID of a valid payment that is in closed status.

Explanation: You provided a payment ID that does not exist or belongs to a different environment. Ensure that the payment ID is correct and the underlying payment transaction is closed.

Error Example: post /v1/refunds {"payment": "payment_aaaaaaaaaaaa"}, when the payment is active or in error status.

Correct Example:

post /v1/refunds {
    "payment": "payment_d31d3ca850419ab5e2f9f1a33f9c6eea",
    "amount": 100
}

ERROR_CREATE_PARTIAL_REFUND_NOT_READY

Message: The request tried to create a partial refund of a card payment, but this service is temporarily unavailable. The request was rejected. Corrective action: Try again after 24 hours. If the issue persists, contact Rapyd Client Support.

Explanation: The card acquirer has not yet processed the transaction. Try again later. If the error persists, contact Rapyd Client Support.

ERROR_CREATE_REFUND

Message: The request tried to create a refund against a payment, but the operation failed. Corrective action: Verify that the payment exists and is not closed, and check all input parameters.

Explanation: This error can occur for several reasons. If the payment ID is not valid, correct the error and try again. When the status of the payment is ACT, you can cancel the payment if the payment method supports it, or capture the payment and try to create the refund. If the status of the payment is ERR, contact Rapyd Client Support. Otherwise, check all input parameters and try again.

Error Example: post /v1/refunds {"payment": "payment_12345abcd"}, when the payment is still active (status = ACT)

Correct Example: Capture the payment, then run the following:

post /v1/refunds {
    "payment": "payment_d31d3ca850419ab5e2f9f1a33f9c6eea"
}

ERROR_CREATE_REFUND_CURRENCY_NOT_VALID

Message: The request tried to create a refund, but the currency was not recognized. The request was rejected. Corrective action: Set currency to the value of merchant_requested_currency or currency_code from the response to Create Payment.

Explanation: The currency in the request does not match the currency that was originally paid by the customer. You must refund the amount using the currency of the original payment.

Error Example: {"currency": "EUR"}, where the original payment specified that the customer was paying in USD.

Correct Example where the original payment specified that the customer was paying in USD.

{
    "currency": "USD"
}

ERROR_CREATE_REFUND_DUPLICATE_EWALLET

Message: The request tried to refund a split payment, but the same wallet was specified more than once. The request was rejected. Corrective action: In the ewallets array, specify each wallet only one time.

Explanation: In split payments, each destination wallet must be mentioned only one time. Your request errroneously used one wallet ID more than once in the request. Verify the IDs in the request or consolidate amounts as needed.

Error Example: {"ewallets": [{"ewallet": "ewallet_12345abcd", "amount": 30}, {"ewallet": "ewallet_12345abcd", "amount": 20}]}

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "amount": 50
        }
    ]
}

ERROR_CREATE_REFUND_EWALLET_ALREADY_FULLY_REFUNDED

Message: The request tried to create a refund of a payment, but the payment was already fully refunded. The request was rejected. Corrective action: None. To transfer money to the payer, use Create Payout or Transfer Funds Between Wallets.

Explanation: The transaction has no remaining balance to refund. If you need to send more money to the customer, use a payout instead. If the customer has a Rapyd Wallet and you are authorized to use this feature, you can transfer funds directly.

ERROR_CREATE_REFUND_EWALLET_NOT_FOUND_IN_PAYMENT

Message: The request tried to refund a payment, but the wallet was not found in the payment. The request was rejected. Corrective action: In the ewallets array, specify wallets that appear in the payment.

Explanation: You tried to refund from an ewallet that was not part of the original split payment. Check the original payment response for the correct wallet IDs.

Error Example: {"ewallets": [{"ewallet": "ewallet_2468aabbcc"}]}, where the original payment was to ewallet_c1943cfeda5f98247ab117e5d2648861.

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861"
        }
    ]
}

ERROR_CREATE_REFUND_EWALLETS_INCONSISTENCY

Message: The request tried to refund a split payment, but the refund split was not defined correctly. The request was rejected. Corrective action: In the ewallets array, specify the amount field for all wallets or the percent field for all wallets.

Explanation: You mixed amount and percent fields in the ewallets array. Choose one calculation method for all wallets in the request.

Error Example: {"ewallets": [{"ewallet": "ewallet_1", "amount": 10}, {"ewallet": "ewallet_2", "percent": 75}]}

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "amount": 10
        },
        {
            "ewallet": "ewallet_7ab117e5d264886c1943cfeda5f98241",
            "amount": 30
        }
    ]
}

ERROR_CREATE_REFUND_INVALID_EWALLETS_AMOUNT

Message: The request tried to create a refund, but the amount from one wallet was not valid. The request was rejected. Corrective action: In the ewallets array, set the amount field for all wallets to a positive decimal number.

Explanation: The amount specified for a wallet is zero, negative, or improperly formatted. Provide a valid positive number.

Error Example: {"ewallets": [{"amount": -5}]}

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "amount": 5.00
        }
    ]
}

ERROR_CREATE_REFUND_INVALID_EWALLETS_PERCENTAGE

Message: The request tried to create a refund, but the percentage from one wallet was not valid. The request was rejected. Corrective action: In the ewallets array, set the percentage field for all wallets to a decimal number between 0 and 100.

Explanation: You provided a percentage value for a wallet that is zero, negative, or greater than 100. Ensure that the value is within the allowed range for the entire transaction and for each individual wallet.

Error Example: {"ewallets": [{"percentage": 110}]}

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "percentage": 50
        }
    ]
}

ERROR_CREATE_REFUND_MISSING_EWALLET_ID

Message: The request tried to refund a payment, but the ID of one of the wallets was missing. The request was rejected. Corrective action: In the ewallet field, provide the ID of the wallet that the refund will be taken from.

Explanation: You forgot to specify the IDs of one or more wallets in your request. Provide the wallet IDs starting with the prefix ewallet_.

Error Example: {"ewallets": [{"amount": 10}]}

Correct Example:

{
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "amount": 10
        }
    ]
}

ERROR_CREATE_REFUND_PAYMENT_NOT_REFUNDABLE

Message: The request tried to create a refund, but the payment method does not allow this operation. The request was rejected. Corrective action: Send the funds to the payer using Create Payout or Transfer Funds Between Wallets, or contact Client Support.

Explanation: The chosen payment method does not support refunds. You must return the funds to the customer using an alternative method that you are authorized to use.

ERROR_GET_EWALLET_NOT_ENOUGH_FUNDS

Message: The request tried to create a refund of a payment to one or more wallets, but one of the wallets did not have enough funds to complete the refund. The request was rejected. Corrective action: Fund the wallet with Create Payment or transfer funds from another wallet using Transfer Funds Between Wallets.

Explanation: The ewallet you are trying to refund from has a balance lower than the refund amount. Increase the amount in the wallet's available balance before retrying.

ERROR_PREVIOUS_REFUND_WAS_NOT_PROPORTIONATE

Message: The request tried to create a refund to two or more wallets, but the previous refund was not proportionate and the current request did not specifically state the amount to return to each wallet. The request was rejected. Corrective action: Specify an ewallets array. For each ewallet, specify the amount that it will receive from the refund.

Explanation: The default behavior for a refund from multiple wallets is proportional - the amount refunded from each wallet is determined in proportion to its share of the payment. You can change this ratio by specifying the amounts. You can also make multiple refunds, but if you create a non-proportionate refund, any subsequent refunds must also be non-proportionate. In that event, you must manually define the amount for each wallet.

Error Example: post /v1/refunds {"payment": "payment_1", "amount": 50}

Correct Example:

{
    "payment": "payment_12345abcd",
    "ewallets": [
        {
            "ewallet": "ewallet_c1943cfeda5f98247ab117e5d2648861",
            "amount": 25
        },
        {
            "ewallet": "ewallet_5f98247ab117e5d2648861c1943cfeda",
            "amount": 25
        }
    ]
}

ERROR_QUERY_DATE_RANGE_EXCEEDS_90_DAYS

Message: The request included temporal query parameters for defining a date range, but the date range defined via the IDs of the objects exceeds 90 days. Corrective action: Create a query where the date range does not exceed 90 days.

Explanation: Your search filter covers a period longer than the allowed 90-day limit. Adjust the starting_after and ending_before parameters.

Error Example: get /v1/refunds?starting_after=refund_100aaabbbddd&ending_before=refund_1000abcde

Correct Example:

get /v1/refunds?starting_after=refund_34d395388fd0bd22f65f74b130fd58b5&ending_before=refund_3d22f65f74b130fd58b54d395388fd0b

ERROR_REFUND_AMOUNT_EXCEEDS_PAYMENT_AMOUNT

Message: The request tried to create a refund of payment that was collected to one or more wallets, but the amount of all refunds against this payment exceeded the amount of the payment. The request was rejected. Corrective action: None. Determine why an attempt was made to refund more money than was collected originally.

Explanation: The amount you are trying to refund is greater than the remaining un-refunded balance of the payment. Reduce the refund amount.

Error Example: {"amount": 500} where the payment was for 100.

{
    "amount": 100
}

where the payment was for 100.

ERROR_REFUND_REQUEST_FOR_PAYMENT_IN_DISPUTE

Message: A refund request for a payment that is already in dispute was rejected. Corrective action: None.

Explanation: You cannot issue a refund while a bank dispute is active. You must wait for the dispute process to resolve or challenge it through the Client Portal. See Challenging a Dispute.

ERROR_UPDATE_REFUND

Message: The request tried to update a refund, but the refund was not found, or the operation failed. The request was rejected. Corrective action: Check all input fields, and verify that the refund exists and was not already closed.

Explanation: The refund ID in the request is invalid, the refund is in a status that does not allow updates, or you are trying to update a field that cannot be updated. Verify the refund ID and status.

Error Example: post /v1/refunds/refund_2468aabbcc

Correct Example:

post /v1/refunds/refund_12345abcd

INVALID_REFUND

Message: The request attempted an operation that requires a refund, but the refund was not found. The request was rejected. Corrective action: Use the ID of a valid refund.

Explanation: The refund ID provided does not exist in the system. Check for typos and ensure that you are in the correct environment.

Error Example: get /v1/refunds/refund_2468aabbcc

Correct Example:

get /v1/refunds/refund_34d395388fd0bd22f65f74b130fd58b5

INVALID_REFUND_STATUS

Message: The request tried to complete a refund, but the refund was already completed and closed. The request was rejected. Corrective action: Determine why multiple attempts were made to complete the same refund.

Explanation: You are trying to process a refund that has already reached a final closed status. No further action is required for this refund. If you need to send funds to the customer, use Create Payout.

INVALID_REFUND_TOKEN

Message: The request tried to update a refund, but the refund was not found. The request was rejected. Corrective action: Use the ID of a valid refund.

Explanation: The refund token or ID is missing or incorrect. Ensure that you are passing the correct ID and ensure that you are in the correct environment.

Error Example: post /v1/refunds/refund2468aabbcc

Correct Example:

post /v1/refunds/refund_34d395388fd0bd22f65f74b130fd58b5

PAYMENT_NOT_COMPLETED

Message: The request tried to create a refund, but the payment object on which the refund is based is not in closed status. The request was rejected. Corrective action: Wait until the payment is closed, and then create the refund.

Explanation: You cannot refund a payment that is in any status other than CLO. If the payment is a card payment, you can try Capture Payment. For other payment method categories, wait for the status to become CLO before initiating a refund.

Error Example: Attempting a refund on a payment with "status": "ACT".

{
    "payment": "payment_4594996f3e0e752e0de819545c6561ac",
    "merchant_reference_id": "2025-11-19a",
    "reason": "Merchandise returned"
}

when the status of the payment is CLO.