Void or refund payin

post

https://api.sandbox.rainforestpay.com/v1/payins/{payin_id}/void_or_refund

Void or refund a payin by the payin ID.

If the payin status is Processing, then the full payin amount can be voided. A payin cannot be partially voided. If the payin status is Succeeded, then the payin can be fully or partially refunded. See the payin refundable_amount and non_refundable_reason_code for details on if the payin is eligible for a void or refund.

Path Params

payin_id

string

required

The unique payin identifier.

Prefix is "pyi" in production and "sbx_pyi" in sandbox.

Body Params

idempotency_key

string

required

length between 1 and 255

A unique identifier provided by the platform. This key will be used to detect subsequent retries of the same request. Subsequent requests with the same key will return the result of the first request, regardless if the first request succeeded or failed. This identifier should be generated by the platform and can be max 255 characters.

amount

integer

The amount to void or refund, in minor units. Must be equal or less than the amount originally processed. If omitted or set to 0, the full amount of the payin will be voided or refunded.

For example, 1000 is 10.00 USD.

merchant_billing

object

The billing rate and fee to calculate the merchant's billing fee for the amount of the refund. If set, then this rate and fee will be used to determine the billing fee for the refund and will override the merchant's billing profile.

This is only applicable if the payin results in a refund instead of a void.

Negative values for the rate and fee can be utilized to return billing fees to the merchant (e.g. to give the fees from the payin back to the merchant upon refund).

reason

string

enum

required

The reason to void or refund this payin.

Allowed:

metadata

object

Valid JSON key-value object specified by the platform to store additional information. Keys are queryable in list endpoints. Do not use the metadata field to store sensitive or confidential data.

This metadata will be merged with the metadata stored on the payin by the top-level key. If the same top-level key is passed in this request, it will overwrite the value stored on the payin. The merged metadata will be saved on the payin metadata field for a VOID and on the refund metadata field for a REFUND.

Metadata must be less than 8 KB in size.

Headers

Rainforest-Api-Version

string

enum

Defaults to 2024-10-16

Allowed:

Responses

200OK

400Bad request, check for validation errors.

401Authorization missing or invalid.

403Authorization insufficient for requested action.

404Resource not found.

409Conflict on the requested resource.

5XXUnexpected error.