---
updatedAt: 2026-08-06T16:59:56.000Z
agentTools:
  siteIndex: https://developers.pismo.io/llms.txt
  projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---

# Return BACS direct credit inbound payment [beta]

Initiates a client return for a settled BACS direct credit inbound payment. The return amount must match the original transaction amount exactly, since the platform does not allow partial returns. The platform permits only one return per original transaction.

Returns initiated through this endpoint are marked with `return_origin` = `CLIENT` to distinguish them from system-initiated returns (`return_origin` = `SYSTEM`).

This endpoint generates a [BACS direct credit inbound return payment processed](https://developers.pismo.io/events/docs/bacs-direct-credit-in-return-status-change-1) event with `return_origin` = `CLIENT`.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Payment rails - BACS payments",
    "description": "BACS 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/bacs",
      "description": "Sandbox API server for testing."
    }
  ],
  "tags": [
    {
      "name": "BACS direct credit"
    }
  ],
  "components": {
    "parameters": {
      "authHeader": {
        "name": "Authorization",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "Account token - access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message\n",
        "required": true
      },
      "idempotencyKeyHeader": {
        "name": "Idempotency-key",
        "in": "header",
        "schema": {
          "type": "string",
          "maxLength": 32
        },
        "description": "A UUID (without hyphens) to ensure the operation remains idempotent, allowing for operation repetition without causing unintended effects or duplication. Identifies the transaction on future events.\n",
        "required": true
      },
      "idPath": {
        "name": "id",
        "in": "path",
        "description": "BACS transaction ID.",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 31
        }
      },
      "reqTrackingIdHeader": {
        "name": "x-cid",
        "in": "header",
        "schema": {
          "type": "string"
        },
        "description": "Request tracking ID. If not provided, a random UUID is generated.\n",
        "required": false
      }
    },
    "schemas": {
      "bacs_return.ClientReturnRequest": {
        "type": "object",
        "required": [
          "return_reason",
          "amount"
        ],
        "properties": {
          "return_reason": {
            "$ref": "#/components/schemas/returnReason"
          },
          "amount": {
            "type": "number",
            "format": "float",
            "description": "Amount to return. Must match the original transaction amount, since the Pismo platform does not support partial returns.\n",
            "example": 100
          }
        }
      },
      "bacs_return.ClientReturnResponse": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/returnStatus"
          },
          "return_transaction_id": {
            "$ref": "#/components/schemas/returnTransactionId"
          },
          "original_transaction_id": {
            "$ref": "#/components/schemas/originalTransactionId"
          },
          "return_origin": {
            "$ref": "#/components/schemas/returnOrigin"
          }
        }
      },
      "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"
          }
        }
      },
      "originalTransactionId": {
        "type": "string",
        "description": "Original transaction ID",
        "example": "08ec4cf7-2d74-5453-80e0-e940ac8fc219"
      },
      "returnOrigin": {
        "type": "string",
        "description": "Indicates whether the client or the system initiates the return\n  * `CLIENT`—The client initiates the return via this endpoint\n  * `SYSTEM`—The system initiates the return automatically\n",
        "enum": [
          "CLIENT",
          "SYSTEM"
        ],
        "example": "SYSTEM"
      },
      "returnReason": {
        "type": "string",
        "description": "The reason for the return.\n  * `account_closed` — The beneficiary account is no longer active.\n  * `account_currency_mismatch` — The payment currency does not match the account currency.\n  * `other` — A reason that the other specific codes do not cover.\n  * `cancelled_by_payer`— The payer requests cancellation of the payment.\n",
        "enum": [
          "account_closed",
          "account_currency_mismatch",
          "cancelled_by_payer",
          "other"
        ],
        "example": "account_closed"
      },
      "returnStatus": {
        "type": "string",
        "description": "* `PROCESSING`—The system processes the return and awaits settlement.\n*`SETTLED`—The return settles successfully.\n*`CANCELLED`—The system cancels the return due to an error.\n",
        "enum": [
          "PROCESSING",
          "SETTLED",
          "CANCELLED"
        ],
        "example": "PROCESSING"
      },
      "returnTransactionId": {
        "type": "string",
        "description": "The ID of the new return transaction.",
        "example": "019e92ec-3362-7c54-9d17-89f5542a06e4"
      }
    }
  },
  "paths": {
    "/v1/payments/bacs/directcredit/return/{id}": {
      "post": {
        "summary": "Return BACS direct credit inbound payment [beta]",
        "description": "Initiates a client return for a settled BACS direct credit inbound payment. The return amount must match the original transaction amount exactly, since the platform does not allow partial returns. The platform permits only one return per original transaction.\n\nReturns initiated through this endpoint are marked with `return_origin` = `CLIENT` to distinguish them from system-initiated returns (`return_origin` = `SYSTEM`).\n\nThis endpoint generates a [BACS direct credit inbound return payment processed](https://developers.pismo.io/events/docs/bacs-direct-credit-in-return-status-change-1) event with `return_origin` = `CLIENT`.\n",
        "operationId": "post-bacs-client-return",
        "tags": [
          "BACS direct credit"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/authHeader"
          },
          {
            "$ref": "#/components/parameters/reqTrackingIdHeader"
          },
          {
            "$ref": "#/components/parameters/idempotencyKeyHeader"
          },
          {
            "$ref": "#/components/parameters/idPath"
          }
        ],
        "requestBody": {
          "description": "Client return request body",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/bacs_return.ClientReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Response Body",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/bacs_return.ClientReturnResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0004": {
                    "summary": "Validation Error",
                    "value": {
                      "code": "EBACS0004",
                      "message": "Validation error"
                    }
                  },
                  "EBACS0095": {
                    "summary": "Partial Returns Not Allowed",
                    "value": {
                      "code": "EBACS0095",
                      "message": "Partial returns are not allowed"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0002": {
                    "summary": "Missing Tenant Header",
                    "value": {
                      "code": "EBACS0002",
                      "message": "Missing required header: 'x-tenant'"
                    }
                  },
                  "EBACS0033": {
                    "summary": "Invalid Account Id",
                    "value": {
                      "code": "EBACS0033",
                      "message": "Invalid account id header: 'x-account-id'"
                    }
                  },
                  "EBACS0086": {
                    "summary": "Missing Idempotency Key",
                    "value": {
                      "code": "EBACS0086",
                      "message": "Missing required header: 'Idempotency-key'"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0067": {
                    "summary": "Transaction Not Found",
                    "value": {
                      "code": "EBACS0067",
                      "message": "Transaction not found"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0015": {
                    "summary": "PSP Gateway API Rate Limit",
                    "value": {
                      "code": "EBACS0015",
                      "message": "PSPGateway API Rate Limit exceeded"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0006": {
                    "summary": "HTTP Error",
                    "value": {
                      "code": "EBACS0006",
                      "message": "HTTP request error"
                    }
                  },
                  "EBACS0012": {
                    "summary": "PSP Gateway API Timeout",
                    "value": {
                      "code": "EBACS0012",
                      "message": "PSPGateway API timeout error"
                    }
                  },
                  "EBACS0023": {
                    "summary": "Transaction Database Error",
                    "value": {
                      "code": "EBACS0023",
                      "message": "Transaction database error"
                    }
                  },
                  "EBACS0048": {
                    "summary": "PSP Gateway Client Error",
                    "value": {
                      "code": "EBACS0048",
                      "message": "PSPGateway API returned 4xx error"
                    }
                  },
                  "EBACS0049": {
                    "summary": "PSP Gateway Server Error",
                    "value": {
                      "code": "EBACS0049",
                      "message": "PSPGateway API returned 5xx error"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/customer.Error"
                },
                "examples": {
                  "EBACS0014": {
                    "summary": "PSP Gateway API Bad Gateway",
                    "value": {
                      "code": "EBACS0014",
                      "message": "PSPGateway API Bad Gateway"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```