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

# Submit spendback

`POST /payout/v3/spendback`

## Request

- Base URL: `https://api.nexiopaysandbox.com`
- URL: `https://api.nexiopaysandbox.com/payout/v3/spendback`
- Auth: HTTP basic

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](doc: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](ref: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](doc:common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payouts-api-reference.md) - [All operations](https://skmtc.dev/nexiopay/apis/payouts-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/nexiopay/apis/payouts-api-reference/revisions/36c088967d63?raw)