Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Faster payments

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

post/v1/payments/fps/return/{endToEndId}

Path parameters

endToEndIdstring required

FPS transaction's end to end 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.

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.

x-cidstring

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

Request body

return_reason'00000001' | '00000002' | '00000003' | '00000004' | '00000005' | '00000006' | '00000007' | '00000008' | '00000009' | '00000010' | '00000011' | '00000012' | '00000013' | '00000014' required

Form3 return reason code. Must be one of the following 14 codes:

  • 00000001—Beneficiary sort code/account number unknown
  • 00000002—Beneficiary account closed
  • 00000003—Beneficiary account stopped
  • 00000004—Beneficiary deceased
  • 00000005—Account cannot be identified without data in reference field
  • 00000006—Beneficiary account name does not match beneficiary account number
  • 00000007—Return requested by sender of original payment
  • 00000008—Account is not in currency quoted
  • 00000009—Beneficiary not expecting funds/instructed return
  • 00000010—Terms and conditions of account do not permit crediting of these funds
  • 00000011—Sending institution action required
  • 00000012—Account transferred
  • 00000013—Payment cannot be applied because of beneficiary sensitivities
  • 00000014—Reason not given
amountstring required

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

Example request

{
  "return_reason": "00000001",
  "amount": "10.50"
}

Response

Accepted

statusstring

Return request status

return_transaction_idstring

Return transaction ID

original_transaction_idstring

ID of the original inbound transaction being returned

return_originstring

Origin of the return request.

  • CLIENT—Return was manually triggered by the client via this endpoint.

Example response

{
  "status": "ACCEPTED",
  "return_transaction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "original_transaction_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "return_origin": "CLIENT"
}