---
title: "Initiate a spend back transaction"
method: POST
path: "/payout/spendback/{user_token}"
tags: ["Spend Back"]
---

# Initiate a spend back transaction

`POST /payout/spendback/{user_token}`

This **POST** endpoint is used to initiate a spendback transaction to a provided user token. <br> You can use this endpoint to enable spendback transactions for your users and help them manage their funds more effectively. <br> To use this endpoint, you need to provide the `user_token` as a parameter in the URL Path, along with the required parameters in the request Body, including `client_spendback_id`, `source_token`, `source_currency_code` and `amount`. <br> The endpoint will then initiate the spendback transaction, transferring funds from the user token to the source token. The response will contain a JSON object indicating the status of the request and any relevant transaction details.

## Headers

- `Idempotency-Key` string

## Request body

- SpendBackTxn
  - `client_spendback_id` string, required — A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
  - `source_token` string, uuid, required — Token that represents the funding source i.e. bank account, wallet. 36 characters long
  - `source_currency_code` string, required — The currency originating balance is stored in. Using [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. In most cases this value will be USD, and therefore the defaut value if none is provided
  - `amount` number, required — The amount to debit the user's wallet in source currency
  - `notes` string — A description for the spend back
  - `metadata` object — Optional JSON object with attributes that can later be searched to locate this spendback. Do not include PII as this object is not encrypted. There are two special attributes that can be provided in the metadata field: `batch_identifier` and `batch_name`. Either of those values, would group transactions in the ledger under the same description.

## Response `201`

Succesfully created.

- SpendBackTxnResp
  - `spendback_token` string, uuid, required — Token that represents the spend back that was just created.
  - `client_spendback_id` string, required — A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters.
  - `status` 'success' | 'failure', required — Status that indicates whether the transaction was successfully processed. If `success`, everything was processed correctly. `failure` indicates a generic error.
  - `metadata` object — Optional JSON object with attributes that can later be searched to locate this load. Do not include PII as this object is not encrypted.

## Other responses

- `400` — Bad request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `404` — Not found.
- `405` — Method Not Allowed.
- `500` — Internal server error.
- `504` — Gateway Time-out.

---

[API](https://skmtc.net/masspay/apis/masspay-api.md) · [All operations](https://skmtc.net/masspay/apis/masspay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/masspay/masspay-api/revisions/c03b61a6a551/schema)