---
updatedAt: 2026-03-13T17:01:00.000Z
agentTools:
projectIndex: https://developers.masspay.io/llms.txt
---
# Initiate a spend back transaction
This **POST** endpoint is used to initiate a spendback transaction to a provided user token.
You can use this endpoint to enable spendback transactions for your users and help them manage their funds more effectively.
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`.
The endpoint will then initiate the spendback transaction, transferring funds from the source token to the user token. The response will contain a JSON object indicating the status of the request and any relevant transaction details.
# OpenAPI definition
```json
{
"openapi": "3.0.1",
"info": {
"description": "MassPay API",
"version": "1.0.0",
"title": "MassPay API",
"termsOfService": "https://www.masspay.io/terms/",
"contact": {
"name": "MassPay",
"email": "info@masspay.io",
"url": "https://www.masspay.io"
},
"license": {
"name": "Apache 2.0",
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
}
},
"x-amazon-apigateway-api-key-source": "AUTHORIZER",
"tags": [
{
"name": "Spend Back",
"description": "The spend back resource describes a spend bank from the user's wallet."
}
],
"paths": {
"/payout/spendback/{user_token}": {
"parameters": [
{
"schema": {
"type": "string",
"example": "usr_3f5d3fe8-a9c0-48c7-90ad-a72948730f56"
},
"name": "user_token",
"in": "path",
"required": true,
"description": "Token representing the user to fetch/initiate spend back"
}
],
"post": {
"summary": "Initiate a spend back transaction",
"description": "This **POST** endpoint is used to initiate a spendback transaction to a provided user token.
You can use this endpoint to enable spendback transactions for your users and help them manage their funds more effectively.
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`.
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.",
"operationId": "initiateSpendback",
"tags": [
"Spend Back"
],
"parameters": [
{
"schema": {
"type": "string"
},
"in": "header",
"name": "Idempotency-Key",
"description": "Unique key to prevent duplicate processing"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SpendBackTxn"
}
}
},
"description": "Spend back information"
},
"responses": {
"201": {
"description": "Succesfully created.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SpendBackTxnResp"
},
"examples": {
"Initiate Spendback Response": {
"value": {
"spendback_token": "spnd_bk_123e4567-e89b-12d3-a456-426614174000",
"client_spendback_id": "aEjn345",
"status": "success",
"metadata": {
"group_id": 541
}
}
}
}
}
}
},
"400": {
"description": "Bad request.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error400"
}
}
}
},
"401": {
"description": "Unauthorized.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error401"
}
}
}
},
"403": {
"description": "Forbidden.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error403"
}
}
}
},
"404": {
"description": "Not found.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error404"
}
}
}
},
"405": {
"description": "Method Not Allowed.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error405"
}
}
}
},
"500": {
"description": "Internal server error.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error500"
}
}
}
},
"504": {
"description": "Gateway Time-out.",
"headers": {
"Access-Control-Allow-Origin": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error504"
}
}
}
}
},
"security": [
{
"AUTHORIZER_NAME": []
},
{
"api_key": []
}
],
"x-amazon-apigateway-integration": {
"uri": "LAMBDA_URI",
"responses": {
"default": {
"statusCode": "200"
}
},
"passthroughBehavior": "when_no_match",
"httpMethod": "POST",
"contentHandling": "CONVERT_TO_TEXT",
"type": "aws_proxy"
}
}
}
},
"servers": [
{
"url": "https://{environment}.masspay.io/{VERSION}",
"description": "MassPay's API server",
"variables": {
"VERSION": {
"default": "v1.0.0",
"enum": [
"v1.0.0"
]
},
"environment": {
"default": "api",
"enum": [
"api",
"staging-api"
]
}
},
"x-amazon-apigateway-endpoint-configuration": {
"disableExecuteApiEndpoint": true
}
}
],
"components": {
"schemas": {
"SpendBackTxnResp": {
"title": "SpendBackTxnResp",
"type": "object",
"x-tags": [
"Spend Back"
],
"properties": {
"spendback_token": {
"type": "string",
"description": "Token that represents the spend back that was just created.",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"client_spendback_id": {
"type": "string",
"example": "aEjn345",
"maxLength": 50,
"description": "A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters."
},
"status": {
"type": "string",
"enum": [
"success",
"failure"
],
"description": "Status that indicates whether the transaction was successfully processed. If `success`, everything was processed correctly. `failure` indicates a generic error.",
"example": "success"
},
"metadata": {
"type": "object",
"description": "Optional JSON object with attributes that can later be searched to locate this load. Do not include PII as this object is not encrypted.",
"example": {
"group_id": 541
}
}
},
"required": [
"spendback_token",
"client_spendback_id",
"status"
]
},
"SpendBackTxn": {
"title": "SpendBackTxn",
"type": "object",
"x-tags": [
"Spend Back"
],
"required": [
"client_spendback_id",
"source_token",
"source_currency_code",
"amount"
],
"properties": {
"client_spendback_id": {
"type": "string",
"example": "aEjn345",
"maxLength": 50,
"description": "A client defined spend back identifier. This is the unique ID assigned to the load on your system. Max 50 characters."
},
"source_token": {
"type": "string",
"description": "Token that represents the funding source i.e. bank account, wallet. 36 characters long",
"format": "uuid",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"source_currency_code": {
"type": "string",
"default": "USD",
"description": "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",
"example": "USD"
},
"amount": {
"type": "number",
"example": 100.5,
"description": "The amount to debit the user's wallet in source currency"
},
"notes": {
"type": "string",
"description": "A description for the spend back",
"example": "Purchase of Candles. Order #14930",
"maxLength": 255
},
"metadata": {
"type": "object",
"description": "Optional JSON object with attributes that can later be searched to locate this spendback. Do not include PII as this object is not encrypted.\nThere 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.",
"example": {
"group_id": 541
}
}
}
},
"Error400": {
"description": "Bad request.",
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Bad request."
],
"example": "Bad request."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
],
"example": "The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
400
],
"example": 400
},
"error": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"example": "Error initiating payout",
"description": "Reason for error"
},
"details": {
"type": "array",
"description": "Specific details of the cause of the error",
"items": {
"type": "string",
"example": "Source amount cannot be $0"
}
}
}
}
},
"required": [
"message",
"code"
]
},
"Error401": {
"description": "Unauthorized.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Unauthorized."
],
"example": "Unauthorized."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
],
"example": "Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
401
],
"example": 401
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error403": {
"description": "Forbidden.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Forbidden."
],
"example": "Forbidden."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
],
"example": "The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
403
],
"example": 403
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error404": {
"description": "Not found.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Not found."
],
"example": "Not found."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The requested resource was not found. Please ensure that the URL for the request is correct and that the requested resource exists."
],
"example": "The requested resource was not found. Please ensure that the URL for the request is correct and that the requested resource exists."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
404
],
"example": 404
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error405": {
"description": "Method not allowed.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Method not allowed."
],
"example": "Method not allowed."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
],
"example": "The HTTP method used for the request is not supported by the MassPay API. Please ensure that you are using the correct HTTP method (e.g., POST) for the specific MassPay API endpoint."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
405
],
"example": 405
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error500": {
"description": "Internal server error",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Internal server error."
],
"example": "Internal server error."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
],
"example": "An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
500
],
"example": 500
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
},
"Error504": {
"description": "Gateway Time-out.",
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Error title.",
"enum": [
"Gateway Time-out."
],
"example": "Gateway Time-out."
},
"message": {
"type": "string",
"description": "Error description.",
"enum": [
"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
],
"example": "The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists."
},
"code": {
"type": "integer",
"description": "Error code.",
"enum": [
500
],
"example": 500
}
},
"additionalProperties": false,
"required": [
"error",
"message",
"code"
]
}
},
"securitySchemes": {
"api_key": {
"type": "apiKey",
"name": "x-api-key",
"in": "header",
"x-internal": true
},
"AUTHORIZER_NAME": {
"x-amazon-apigateway-authtype": "custom",
"x-amazon-apigateway-authorizer": {
"authorizerUri": "AUTHORIZER_VALIDATION_INVOKE_ARN",
"authorizerCredentials": "AUTHORIZER_VALIDATION_ROLE",
"authorizerResultTtlInSeconds": 300,
"identityValidationExpression": "AUTHORIZER_VALIDATION_EXP",
"type": "token"
},
"name": "Authorization",
"in": "header",
"type": "apiKey"
}
}
},
"x-amazon-apigateway-gateway-responses": {
"AUTHORIZER_FAILURE": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"MISSING_AUTHENTICATION_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"EXPIRED_TOKEN": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"REQUEST_TOO_LARGE": {
"statusCode": 413,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 413 }"
}
},
"ACCESS_DENIED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"INVALID_API_KEY": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"QUOTA_EXCEEDED": {
"statusCode": 429,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": $context.error.messageString,\n \"code\": 429\n}"
}
},
"INVALID_SIGNATURE": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
},
"DEFAULT_4XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": $context.error.messageString,\n \"code\": 400\n}"
}
},
"THROTTLED": {
"statusCode": 429,
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 429 }"
}
},
"BAD_REQUEST_PARAMETERS": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"API_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"AUTHORIZER_CONFIGURATION_ERROR": {
"statusCode": 500,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": \"An unexpected error occurred on the server-side while processing the request. Please try again later or contact support if the issue persists.\",\n \"code\": 500\n}"
}
},
"INTEGRATION_TIMEOUT": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"BAD_REQUEST_BODY": {
"statusCode": 400,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Bad request.\",\n \"message\": \"The request was invalid or malformed. Please ensure that the request body conforms to the required format and that all required parameters are included.\",\n \"code\": 400\n}"
}
},
"INTEGRATION_FAILURE": {
"statusCode": 504,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Gateway Time-out.\",\n \"message\": \"The request timed out while waiting for a response from the server. Please try again later or contact support if the issue persists.\",\n \"code\": 504\n}"
}
},
"DEFAULT_5XX": {
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Internal server error.\",\n \"message\": $context.error.messageString,\n \"code\": 500\n}"
}
},
"RESOURCE_NOT_FOUND": {
"statusCode": 404,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 404 }"
}
},
"UNAUTHORIZED": {
"statusCode": 401,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Unauthorized.\",\n \"message\": \"Authentication failed or credentials were not provided. Please ensure that you have provided valid API credentials and that they are authorized to access the MassPay API.\",\n \"code\": 401\n}"
}
},
"UNSUPPORTED_MEDIA_TYPE": {
"statusCode": 415,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{ \"title\": \"Unauthorized.\", \"message\": $context.error.messageString, \"code\": 415 }"
}
},
"WAF_FILTERED": {
"statusCode": 403,
"responseParameters": {
"gatewayresponse.header.Access-Control-Allow-Origin": "'*'"
},
"responseTemplates": {
"application/json": "{\n \"title\": \"Forbidden.\",\n \"message\": \"The requested action is not allowed or the API credentials do not have sufficient permissions. Please ensure that the API credentials used for the request have the necessary permissions to perform the requested action.\",\n \"code\": 403\n}"
}
}
},
"x-amazon-apigateway-minimum-compression-size": 1024
}
```