---
title: "Void or refund payin"
method: POST
path: "/v1/payins/{payin_id}/void_or_refund"
tags: ["Payins"]
---

# Void or refund payin

`POST /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.

## Parameters

- `#/paths/~1v1~1payins/get/parameters/0` — unresolved $ref
- `#/paths/~1v1~1payins~1%7Bpayin_id%7D/get/parameters/1` — unresolved $ref

## Request body

- object
  - `idempotency_key` IdempotencyKey, required — unresolved $ref
  - `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).
    - `rate` integer — Rate, in percent mille (1 PCM = 0.001%). For example, 3000 is 3%.
    - `rate_cap` integer — Rate cap, in minor units. Used to cap the rate to a specified amount. For example, 1000 is 10.00 USD. The following validation must be met: - If the `rate` is greater than 0%, then the `rate_cap` must be greater than $0. For example, to bill a rate of 1% up to $100 set the value to `10000`. - If the `rate` is less than 0%, then the `rate_cap` must be less than $0. For example, to bill a rate of -1% up to -$100 set the value to `-10000`. - If the `rate` is 0%, then the `rate_cap` must be $0.
    - `fee` integer — Fee, in minor units. For example, 1000 is 10.00 USD. The absolute value of the fee can be up to $10, regardless of the amount of the refund. However, if the absolute value of the fee is greater than $10, then the absolute value of the fee cannot be greater than the `amount` field. Valid requests: - Fee of $10 on a $5 refund. - Fee of -$10 on a $5 refund. - Fee of $11 on a $20 refund. - Fee of -$11 on a $20 refund. Invalid requests: - Fee of $11 on a $5 refund. - Fee of -$11 on a $5 refund.
    - `currency_code` CurrencyCode — unresolved $ref
  - `reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT', required — The reason to void or refund this payin.
  - `metadata` Schema — unresolved $ref
  - `amount_splits` object[] — Represents how the refund amount should be allocated between the originating merchant, the platform, and one or more other merchants. This configuration overrides the amount_split_reversal_config defined on the payin config.<br/><br/> The sum of all amount splits must be less than or equal to the amount on the refund request.<br/><br/> A `PLATFORM` split defines the amount to debit from the platform. A maximum of one `PLATFORM` split is permitted per refund.<br/><br/> A `MERCHANT` split defines the amount to debit from the specified merchant. Multiple `MERCHANT` splits are permitted. Each `MERCHANT` split must specify a unique merchant_id.<br/><br/> Any remaining amount not specified by the amount splits will be debited from the originating merchant.<br/><br/> If no amount splits are provided, then the configuration provided on the payin config amount_split_reversal_config will be respected for full refunds. For partial refunds without amount_splits, the originating merchant will be debited the full partial refund amount and all split receivers retain their allocations.<br/><br/> The amount split is defined as a rate and amount.<br/><br/> For example, to assess a split of 1% + $5.00, specify 1000 in the rate and 500 in the amount.
    - `rate` integer — The amount split defined as a rate, in percent mille (1 PCM = 0.001%). For example, 3000 is 3%.
    - `rate_cap` integer — The amount split rate cap, in minor units. Used to cap the rate to a specified amount. For example, 1000 is 10.00 USD.
    - `amount` integer, required — The amount to debit from this split receiver, in minor units. For example, 1000 is 10.00 USD.
    - `currency_code` 'USD', required — Three-letter ISO currency code, in uppercase. Currently, only USD is supported.
    - `type` 'PLATFORM' | 'MERCHANT', required — The type of receiver for this split.<br/><br/> `PLATFORM` allocates the split amount to the platform. `MERCHANT` allocates the split amount to the merchant specified by merchant_id.
    - `merchant_id` string — Required when type is `MERCHANT`.<br/><br/> The unique identifier of the merchant to debit from.<br/><br/> Not valid when type is `PLATFORM`.
  - `payin_billing_fees_reversal_config` object — Controls whether the billing fees from the original payin are returned to the originating merchant. This configuration overrides the billing_fees_reversal_config defined on the payin config or the merchant's default configuration.
    - `on_full_refund` boolean — Determines whether the billing fees for the original payin are returned to the originating merchant when a refund for the full amount is processed.<br/><br/> When `true`, the billing fee is credited back to the merchant and included in the refund's computed billing fee.

## Response `200`

OK

- object
  - `status` Status — unresolved $ref
  - `data` object
    - `type` 'VOID' | 'REFUND' — Indicates if a void or a refund was attempted. Set to VOID if the payin processing was not completed and a void was attempted. Set to REFUND is the payin processing was completed and a refund was attempted.
    - `merchant_id` MerchantId — unresolved $ref
    - `refund_id` RefundId — unresolved $ref
    - `refund_status` 'PROCESSING' | 'FAILED' | 'IN_REVIEW' — The status of the refund. This field will only be set if the `type` is `REFUND`.
    - `payin_id` PayinId — unresolved $ref
    - `payin_status` 'CANCELED' | 'SUCCEEDED' — The status of the payin.
    - `amount` integer — The amount voided or refunded, in minor units. For example, 1000 is 10.00 USD.
    - `currency_code` CurrencyCode — unresolved $ref
    - `merchant_billing` MerchantBilling — unresolved $ref
    - `amount_splits` AmountSplits — unresolved $ref
    - `payin_billing_fees_reversal_config` object — Controls whether the billing fees from the original payin are returned to the originating merchant. This configuration overrides the `billing_fees_reversal_config` defined on the payin config or the merchant's default configuration.<br/><br/> This is only applicable if the `type` is `REFUND`.
      - `on_full_refund` boolean — Determines whether the billing fees for the original payin are returned to the originating merchant when a refund for the full amount is processed.<br/><br/> When `true`, the billing fee is credited back to the merchant and included in the refund's computed billing fee.
    - `reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' — The reason to void or refund this payin.
    - `refusal_code` RefusalCode — unresolved $ref
    - `refusal_desc` RefusalDesc — unresolved $ref
    - `auth_code` string — The authorization code if the refund was approved. This field will only be set if the `type` is `REFUND`.
    - `metadata` Schema — unresolved $ref
    - `source` 'API_DIRECT' | 'COMPONENT' | 'EXTERNAL', nullable — The source of the refund.
    - `created_at` string, date-time — Date and time void or refund was created at in UTC RFC 3339 format.
  - `errors` Errors — unresolved $ref

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `404` — unresolved $ref
- `409` — unresolved $ref
- `5XX` — unresolved $ref

---

[API](https://skmtc.dev/rainforestpay/apis/authentication.md) · [All operations](https://skmtc.dev/rainforestpay/apis/authentication/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rainforestpay/authentication/revisions/529a0dab0f90/schema)