Void or refund payin

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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required

The unique payin identifier.

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

Body Params
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.

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).

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.

amount_splits
array of objects

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.

The sum of all amount splits must be less than or equal to the amount on the refund request.

A PLATFORM split defines the amount to debit from the platform. A maximum of one PLATFORM split is permitted per refund.

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.

Any remaining amount not specified by the amount splits will be debited from the originating merchant.

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.

The amount split is defined as a rate and amount.

For example, to assess a split of 1% + $5.00, specify 1000 in the rate and 500 in the amount.

amount_splits
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.

Headers
string
enum
Defaults to 2024-10-16
Allowed:
Responses

Language
Credentials
Bearer
APIKey
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json