Create Return Intent

Return Transfer Flow

The return transfer follows a two-step intent/confirm pattern:

1. Create return intent (POST /v1/transfer/return) — validates the transaction, checks balance, and creates a return intent
2. Review intent (GET /v1/transactions/:transactionID) — retrieve the transaction to review the return details before confirming
3. Confirm return (PUT /v1/transfer/return) — confirms the intent and triggers the SWIFT Pacs008 return message
4. Cancel intent (DELETE /v1/transfer/return/:transactionID) — optionally cancel the intent before confirmation

Example POST to create a return intent

curl -X POST 'https://developer-api-staging.pavebank.dev/v1/transfer/return' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>' \
  --header 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  --data '{
  "transfer_return_type": "SWIFT_FI_TO_FI_RETURN",
  "transaction_id": "transaction_<SETTLED_INCOMING_TRANSACTION_ID>",
  "return_amount": "1000000",
  "description": "Return - following cancellation request",
  "status_reason_code": "FOCR"
}'

This API will respond with a transaction_id

{
  "transaction_id": "transaction_1jt9vwzof57z427158knbxsf2s"
}

The transaction status changes from completed to intent_created.

Use this transaction_id in the GET Transaction endpoint to review the return details before confirming. The response will include the return transfer amount, fee amount, description, SWIFT reason code, and who initiated the return.

Preconditions

• The transaction must be in completed (SETTLED) status
• The creditor account must have sufficient balance to cover the return amount

Request body fields

Common status reason codes

Reviewing the return intent

After creating the intent, use the GET Transaction endpoint to review the return details:

GET /v1/transactions/transaction_1jt9vwzof57z427158knbxsf2s

The response will include:

• status: "intent_created"
• fi_to_fi_swift_incoming.return_transfer_amount: the return amount
• fi_to_fi_swift_incoming.return_fee_amount: always "0" (no fee charged)
• fi_to_fi_swift_incoming.return_description: the description provided
• fi_to_fi_swift_incoming.return_status_reason_code: the SWIFT reason code
• fi_to_fi_swift_incoming.return_initiated_by: the user who initiated the return
• fi_to_fi_swift_incoming.return_created_at: timestamp of intent creation
• fi_to_fi_swift_incoming.return_updated_at: timestamp of last update

Status lifecycle

completed → (POST) → intent_created → (PUT) → in_progress → return_completed
                          ↓
                       (DELETE)
                          ↓
                      completed

curl -X POST "https://developer-api-staging.pavebank.dev/v1/transfer/return" \
  -H "Idempotency-Key: string" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_return_type": "SWIFT_FI_TO_FI_RETURN",
    "transaction_id": "string",
    "return_amount": "string",
    "description": "string",
    "status_reason_code": "string"
  }'

{
  "transaction_id": "string"
}