---
title: "Submit spendback"
method: POST
path: "/payout/v3/spendback"
tags: ["Spendbacks"]
---

# Submit spendback

`POST /payout/v3/spendback`

Allows you to submit a spendback in the body of an API request.

A spendback request can only be made for an existing recipient and you can only process one spendback at a time.


### Required parameters
Each spendback request must include the `amount` and `currency` parameters as well as one of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `recipientId`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `recipientRef`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `email`

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you must use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).<br/><br/>Include at least the `amount` and `currency` parameters, along with one of the recipient parameters (see above).

<div style="display:none;">

## Request parameters
- recipientId
- recipientRef
- email
- amount
- currency
- description
- spendbackRef
- providerId

## Response parameters
- id
- spendbackRef
- recipientId
- recipientRef
- payoutAccountId
- providerId
- providerType
- providerSpendbackRef
- amount
- currency
- description
- spendbackDate
- spendbackStatus
- providerResponse
- createdAt
- updatedAt

</div>

## Request body

- union
  - object
    - `recipientId` integer, required — The Nexio-generated ID for a recipient. This is the payer account to use for the spendback. This value takes precedence over values for `recipientRef` and `email` if they are also included in the request. Only required if neither `recipientRef` nor `email` are specified in the request.
    - `amount` Amount, required — unresolved $ref
    - `currency` Currency, required — unresolved $ref
    - `description` Description — unresolved $ref
    - `spendbackRef` string — Reference value for the spendback request. You can use your own reference value for the spendback request. If you want multiple requests to display as a single group in a report, specify the same value. If you do not specify a value, the system generates one. <!-- theme: info --> > #### Note > Nexio recommends that you include this parameter, with your own value, in the request.
    - `providerId` integer — The Nexio ID for the provider. Indicates a specific set of payout provider credentials to use for processing a spendback request. This is useful to include for cases where you are not sending the `recipientId` in the request and a recipient may have accounts with multiple payout providers. In these situation, it can help the system to identify the correct recipient account when you send an `email` or `recipientRef` for the recipient along with a `providerId`.
  - object
    - `recipientRef` string, required — Your unique identifier for a recipient. This is the payer account to use for the spendback. If `recipientId` and this parameter are specified in the request, this value is ignored. This value takes precedence over a value for `email` if it is also included in the request. <!-- theme: warning --> > #### Important > We strongly recommend that you include this value in your request in order to facilitate spendback reconciliation. Only required if neither `recipientId` nor `email` are specified in the request.
    - `amount` Amount, required — unresolved $ref
    - `currency` Currency, required — unresolved $ref
    - `description` Description — unresolved $ref
    - `spendbackRef` SpendbackRef — unresolved $ref
    - `providerId` ProviderId — unresolved $ref
  - object
    - `email` string, required — The email account associated with a recipient to use as the payer account for the spendback. If either `recipientId` or `recipientRef` and this parameter are specified in the request, this value is ignored. Only required if neither `recipientId` nor `recipientRef` are specified in the request.
    - `amount` Amount, required — unresolved $ref
    - `currency` Currency, required — unresolved $ref
    - `description` Description — unresolved $ref
    - `spendbackRef` SpendbackRef — unresolved $ref
    - `providerId` ProviderId — unresolved $ref

## Response `200`

OK

- object — Spendback, payout, and recipient parameters.
  - `id` integer — The ID value auto-generated by Nexio when the spendback request was submitted.
  - `spendbackRef` SpendbackRef — unresolved $ref
  - `recipientId` integer — The Nexio-generated ID for a recipient. This is the payer account used for the spendback.
  - `recipientRef` RecipientRef — unresolved $ref
  - `payoutAccountId` PayoutAccountId — unresolved $ref
  - `providerId` integer — The Nexio ID for the provider. Indicates a specific set of payout provider credentials that were used to process a spendback request.
  - `providerType` ProviderType — unresolved $ref
  - `providerSpendbackRef` ProviderSpendbackRef — unresolved $ref
  - `amount` number — The spendback amount refunded. For testing purposes with the Mock Payout account, you can trigger an error by sending `amount` with a value of `12.34`.
  - `currency` Currency — unresolved $ref
  - `description` string — Description information for the spendback. The system returns this parameter only when a value is provided for it in the [Submit spendback](https://docs.nexiopay.com/reference/submitspendback) request.
  - `spendbackDate` SpendbackDate — unresolved $ref
  - `spendbackStatus` SpendbackStatus — unresolved $ref
  - `providerResponse` string — Error message from the provider in case of a failed spendback.
  - `createdAt` CreatedAt — unresolved $ref
  - `updatedAt` UpdatedAt — unresolved $ref

## Other responses

- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)