Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
BACS

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 event with return_origin = CLIENT.

post/v1/payments/bacs/directcredit/return/{id}

Path parameters

idstring required

BACS transaction ID.

Headers

Authorizationstring required

Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message

x-tenantstring required

Organization identifier.

x-cidstring

Request tracking identifier. If not provided, a random UUID is generated.

Idempotency-keystring required

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.

Request body

return_reason'account_closed' | 'account_currency_mismatch' | 'other' | 'cancelled_by_payer' required

The reason for the return.

  • account_closed—The beneficiary account is no longer active.
  • account_currency_mismatch—The payment currency does not match the account currency.
  • other—A reason that the other specific codes do not cover.
  • cancelled_by_payer—The payer requests cancellation of the payment.
amountnumber float required

Amount to return. Must match the original transaction amount, since the Pismo platform does not support partial returns.

Example request

{
  "return_reason": "account_closed",
  "amount": 100
}

Response

Response Body

status'PROCESSING' | 'SETTLED' | 'CANCELLED'
  • PROCESSING—The system processes the return and awaits settlement.
  • SETTLED—The return settles successfully.
  • CANCELLED—The system cancels the return due to an error.
return_transaction_idstring

The ID of the new return transaction.

original_transaction_idstring

The ID of the original inbound transaction that this return targets.

return_origin'CLIENT' | 'SYSTEM'

Indicates whether the client or the system initiates the return.

  • CLIENT—The client initiates the return via this endpoint.
  • SYSTEM—The system initiates the return automatically.

Example response

{
  "status": "PROCESSING",
  "return_transaction_id": "019e92ec-3362-7c54-9d17-89f5542a06e4",
  "original_transaction_id": "08ec4cf7-2d74-5453-80e0-e940ac8fc219",
  "return_origin": "CLIENT"
}