Return Incoming Transfer

This guide explains how to initiate a return for an existing incoming transfer using the returnContext object.

The return operation is state-driven and is triggered by updating the Incoming Transfer via PATCH when specific eligibility conditions are met.

Overview

Returns are controlled via the returnContext field on the Incoming Transfer resource.
A return cannot be initiated if returnContext.enabled = false.
A return is triggered when returnContext.status is updated to processing.
Returns are allowed only if the Incoming Transfer status is completed or failed.
Providing a valid reason is mandatory.

Incoming Transfer Model – returnContext

A new object returnContext is added to the Incoming Transfer response model.

...
"returnContext": {
  "enabled": true,
  "cutOffDateTime": "2026-01-12T17:00:00Z",
  "status": "processing",
  "reason": "user-requested"
}
...

Field Definitions

Field	Type	Mutability	Description
enabled	boolean	Read only	Indicates whether a return request is allowed for this incoming transfer
cutOffDateTime	datetime \| null	Read only	Last date-time when a return can be initiated. Present only if enabled = true
status	string	Required	Current return process status
reason	string	Required	Mandatory reason code for the return

`returnContext.status` Values

The status field reflects the lifecycle of the return process.

Status	Description
`processing`	Return request has been triggered and is being processed
`released`	Funds have been released for return
`completed`	Return successfully completed
`failed`	Return attempt failed

`returnContext.reason` Values

The reason field must be provided when triggering a return.

reason	Description
`account-inactivated`	Account inactive
`account-closed`	Account closed
`account-not-found`	Account not found / invalid
`user-requested-duplicate`	User requested / duplicate
`user-requested-wrong-amount`	User requested / wrong amount
`user-requested`	User requested
`sender-recalled`	Sender requested
`rejected-by-compliance`	Compliance rejection

Eligibility Rules

A return request can be initiated only if all conditions below are met:

returnContext.enabled = true
Incoming Transfer status is either (completed, failed)
cutOffDateTime (if present) has not passed
reason is provided and valid

If any of the above conditions fail, the return request will be rejected.

Triggering a Return (PATCH)

PATCH /incoming-transfers/{id}

A return is initiated by updating the Incoming Transfer and setting:

returnContext.status = processing
returnContext.reason = <valid_reason>

Sample Request/Respons

{
  "workflow": {
		"code": "client.direct"
  },
	"data": {
    "incomingTransfer": {
      "returnContext": {
        "status": "processing",
        "reason": "user-requested"
      }
    }
  },
	"connect": {},
	"metadata": {}
}

{
  "workflow": {},
  "data": {
    "incomingTransfer":{
      "id": "00000000-0000-0000-0000-000000000000",
      "owner": "client",
      "clientId": "00000000-0000-0000-0000-000000000000",
      "accountId": "00000000-0000-0000-0000-000000000000",
      "transactionNumber": "20210101-ABC123",
      "status": "completed",
      "currency": "GBP",
      "amount": 100.00,
      "feeAmount": 3.00,
      "feeCurrency": "GBP",
      "provisionedAccountCreditId": "00000000-0000-0000-0000-000000000000",
      "outgoingTransferId": null,
      "serviceProvider": "service-provider-code",
      "serviceProviderId": "",
      "serviceProviderReference": "",
      "senderInformation": null,
      "senderName": "",
      "transferDate": "2021-04-25",
      "scheme": "sepa",
      "scope": "external",
      "totalAmount": 97.00,
      "relatedTransaction": {
        "nature": "actual",
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "senderAccount": {
        "ledgerNumber": null,
        "alias": null,
        "accountHolderName": null,
        "accountNumber": "00000000",
        "iban": "GB99AAAA01234567890123",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {
          "bic": "AAAAGB22",
          "sort-code": "000000"
        }
      },
      "receiverAccount": {
        "ledgerNumber": "12345678",
        "alias": "GBP Account",
        "accountHolderName": "",
        "accountNumber": "00000000",
        "iban": "GB99AAAA01234567890123",
        "country": "GB",
        "currency": "GBP",
        "routingCodes": {
          "bic": "AAAAGB22",
          "sort-code": "000000"
        }
      },
      "returnContext": {
        "enabled": true,
        "cutOffDateTime": "2026-01-01T09:00:00",
        "status": "processing",
				"reason": "user-requested"
			}
    }
  },
  "connect": {},
  "metadata": {}
}