Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
Return Requests

Create return request

Create a return request for a payment order previously executed.

post/return_requests

Request body

related_payment_idstring uuid required

The ID of the payment order to be returned.

return_reasonstring required

Authorised reasons depend on the payment scheme. For SEPA, refer to SEPA reason codes.

metadataobject

Additional client data in JSON format. See Metadata.

Example request

{
  "return_reason": "AM05",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  }
}

Response

Successfully created return request.

idstring uuid required

The UUID of the return request.

object'return_request' required

Label used to identify this kind of object

type'sepa' | 'sepa_instant' required

The payment scheme or network. Only sepa and sepa_instant are supported for now.

connected_account_idstring uuid required

The ID of the connected account.

related_payment_idstring uuid required

The ID of the payment being returned, either an incoming payment or a payment order.

related_payment_type'payment_order' | 'incoming_payment' required

The type of the payment corresponding to the return request. It can be an incoming payment or a payment order.

return_reasonstring required

The reason for asking the payment's return. Authorised reasons depend on the payment scheme. For SEPA, refer to SEPA reason codes.

status'received' | 'accepted' | 'denied' | 'rejected' | 'pending' | 'failed' | 'sent' required

The lifecycle stage of this return request. It will be updated as the return request is processed. See return request's lifecycle.

status_detailsstring required

The details of the status of this return request.

metadataobject required

Additional client data in JSON format. See Metadata.

created_atstring date-time required

The UTC timestamp of the creation of this return request.

additional_informationstring[] required

Additional free-text information provided by the bank when denying a return request (populated from the <AddtlInf> field of the inbound camt.029 message). Empty array when no additional information was provided.

Example response

{
  "object": "return_request",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  },
  "additional_information": [
    "Insufficient funds",
    "Account closed"
  ]
}