---
updatedAt: 2026-06-03T16:50:56.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# Return FPS payment [beta]
Manually trigger a return for a previously credited FPS inbound transaction.
This endpoint allows clients to initiate a return of funds for an inbound FPS payment that has already been credited to the beneficiary's account. The return is submitted to the payment provider (Form3) for processing.
Returns initiated through this endpoint are marked with `return_origin` = `CLIENT` to distinguish them from provider-initiated returns.
The `return_reason` must be one of the 14 standardized Form3 reason codes (`00000001` through `00000014`).
This endpoint generates an [FPS inbound payment return processed](https://developers.pismo.io/events/docs/fps-fps-in-return-status-change-1) event with `return_origin` = `CLIENT`.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Faster payments",
"description": "Faster Payments (FPS) real-time payments system API",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
},
"version": "1.0"
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/fps",
"description": "Sandbox API server for testing."
}
],
"tags": [
{
"name": "Faster payments",
"description": "Faster Payment Service (FPS) endpoints"
}
],
"components": {
"parameters": {
"authHeader": {
"name": "Authorization",
"in": "header",
"schema": {
"type": "string"
},
"description": "Account token—token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.\n",
"required": true
},
"endToEndIDPath": {
"name": "endToEndId",
"in": "path",
"description": "FPS transaction's end to end ID.",
"required": true,
"schema": {
"type": "string",
"maxLength": 31
}
},
"idempotencyKeyHeader": {
"name": "Idempotency-key",
"in": "header",
"schema": {
"type": "string"
},
"description": "A UUID to ensure the operation remains idempotent, allowing for operation repetition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.\n",
"required": true
},
"tenantHeader": {
"name": "x-tenant",
"in": "header",
"schema": {
"type": "string"
},
"description": "Organization ID",
"required": true
},
"reqTrackingIdHeader": {
"name": "x-cid",
"in": "header",
"schema": {
"type": "string"
},
"description": "Request tracking identifier. If not provided, a random UUID will be generated.\n",
"required": false
}
},
"schemas": {
"customer.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/customer.PayloadMessage"
}
}
}
},
"customer.Error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error's code.",
"example": "EPT0001"
},
"details": {
"$ref": "#/components/schemas/customer.DetailMessage"
},
"message": {
"type": "string",
"description": "Error's message.",
"example": "User not found"
}
}
},
"customer.ExternalMessage": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"description": "Code",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Message",
"example": "Generic error"
}
}
},
"customer.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Field",
"example": "Query parameter"
},
"message": {
"type": "string",
"description": "Message",
"example": "Generic error"
}
}
},
"customer.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Field",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Message",
"example": "Generic error"
}
}
},
"fps_return.FpsReturnRequest": {
"type": "object",
"required": [
"return_reason",
"amount"
],
"properties": {
"return_reason": {
"$ref": "#/components/schemas/fps_return.ReturnReason"
},
"amount": {
"type": "string",
"maxLength": 20,
"description": "Amount to return. Must match the original transaction amount, since the Pismo platform does not support partial returns.",
"example": "10.50"
}
}
},
"fps_return.FpsReturnResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Return request status",
"example": "ACCEPTED"
},
"return_transaction_id": {
"type": "string",
"description": "Return transaction ID",
"example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
},
"original_transaction_id": {
"type": "string",
"description": "ID of the original inbound transaction being returned",
"example": "f1e2d3c4-b5a6-7890-abcd-ef1234567890"
},
"return_origin": {
"type": "string",
"description": "Origin of the return request.\n * `CLIENT` — The client manually triggered the return via this endpoint.\n",
"example": "CLIENT"
}
}
},
"fps_return.ReturnReason": {
"type": "string",
"description": "Form3 return reason code. Must be one of the following 14 codes:\n * `00000001`—Beneficiary sort code/account number unknown\n * `00000002`—Beneficiary account closed\n * `00000003`—Beneficiary account stopped\n * `00000004`—Beneficiary deceased\n * `00000005`—Account cannot be identified without data in reference field\n * `00000006`—Beneficiary account name does not match beneficiary account number\n * `00000007`—Sender of original payment requested this return\n * `00000008`—Account is not in currency quoted\n * `00000009`—Beneficiary not expecting funds/instructed return\n * `00000010`—Terms and conditions of account do not permit crediting of these funds\n * `00000011`—Sending institution action required\n * `00000012`—Account transferred\n * `00000013`—Payment cannot be applied because of beneficiary sensitivities\n * `00000014`—Reason not given\n",
"enum": [
"00000001",
"00000002",
"00000003",
"00000004",
"00000005",
"00000006",
"00000007",
"00000008",
"00000009",
"00000010",
"00000011",
"00000012",
"00000013",
"00000014"
],
"example": "00000001"
}
}
},
"paths": {
"/v1/payments/fps/return/{endToEndId}": {
"post": {
"summary": "Return FPS payment [beta]",
"description": "Manually trigger a return for a previously credited FPS inbound transaction.\n\nThis endpoint allows clients to initiate a return of funds for an inbound FPS payment that has already been credited to the beneficiary's account. The return is submitted to the payment provider (Form3) for processing.\n\nReturns initiated through this endpoint are marked with `return_origin` = `CLIENT` to distinguish them from provider-initiated returns.\n\nThe `return_reason` must be one of the 14 standardized Form3 reason codes (`00000001` through `00000014`).\n\nThis endpoint generates an [FPS inbound payment return processed](https://developers.pismo.io/events/docs/fps-fps-in-return-status-change-1) event with `return_origin` = `CLIENT`.\n",
"operationId": "post-return-fps",
"tags": [
"Faster payments"
],
"parameters": [
{
"$ref": "#/components/parameters/authHeader"
},
{
"$ref": "#/components/parameters/tenantHeader"
},
{
"$ref": "#/components/parameters/idempotencyKeyHeader"
},
{
"$ref": "#/components/parameters/reqTrackingIdHeader"
},
{
"$ref": "#/components/parameters/endToEndIDPath"
}
],
"requestBody": {
"description": "Return payment request body",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/fps_return.FpsReturnRequest"
}
}
},
"required": true
},
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/fps_return.FpsReturnResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0004": {
"summary": "Validation Error",
"value": {
"code": "EFPS0004",
"message": "Validation error"
}
},
"EFPS0016": {
"summary": "Unmarshal Error",
"value": {
"code": "EFPS0016",
"message": "Unmarshal error"
}
},
"EFPS0096": {
"summary": "Partial Return Not Allowed",
"value": {
"code": "EFPS0096",
"message": "Partial returns are not allowed. Return amount must match the original transaction amount"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0002": {
"summary": "Missing Tenant Header",
"value": {
"code": "EFPS0002",
"message": "Missing required header: 'x-tenant'"
}
},
"EFPS0085": {
"summary": "Missing Account ID Header",
"value": {
"code": "EFPS0085",
"message": "Missing required account-id"
}
},
"EFPS0086": {
"summary": "Missing Idempotency Key",
"value": {
"code": "EFPS0086",
"message": "Missing required header: 'Idempotency-Key'"
}
}
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0067": {
"summary": "Transaction Not Found",
"value": {
"code": "EFPS0067",
"message": "Transaction API not found error"
}
}
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0058": {
"summary": "Record Already Exists",
"value": {
"code": "EFPS0058",
"message": "Record already exists"
}
}
}
}
}
},
"422": {
"description": "Unprocessable Entity",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0093": {
"summary": "Payment Not Eligible For Return",
"value": {
"code": "EFPS0093",
"message": "Payment is not eligible for return"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0015": {
"summary": "PSP Gateway API Rate Limit",
"value": {
"code": "EFPS0015",
"message": "PSPGateway API Rate Limit exceeded"
}
}
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0006": {
"summary": "HTTP Error",
"value": {
"code": "EFPS0006",
"message": "HTTP request error"
}
},
"EFPS0012": {
"summary": "PSP Gateway API Timeout",
"value": {
"code": "EFPS0012",
"message": "PSPGateway API timeout error"
}
},
"EFPS0023": {
"summary": "Transaction Database Error",
"value": {
"code": "EFPS0023",
"message": "Transaction database error"
}
}
}
}
}
},
"502": {
"description": "Bad Gateway",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/customer.Error"
},
"examples": {
"EFPS0014": {
"summary": "PSP Gateway API Bad Gateway",
"value": {
"code": "EFPS0014",
"message": "PSPGateway API Bad Gateway"
}
}
}
}
}
}
}
}
}
}
}
```