Sign in

v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB
Returns

Update return

Update a return.

post/returns/{id}

Path parameters

idstring required

The ID of the return.

Request body

status'executed' | 'rejected'

The new status of this return.

status_detailsstring

The details of the status of this return. Required if status is provided.

{"stackTrail":"components:schemas:return.update_details:properties:metadata","oasType":"schema","type":"unknown","description":"Additional client data in JSON format. See [Metadata](https://docs.numeral.io/reference/metadata). Required if `status` is not provided."}

Example request

{
  "status": "rejected",
  "status_details": "DUPL"
}

Response

200

idstring uuid required

The UUID of the return.

object'return' 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.

direction'credit' | 'debit' required

The direction of the return. credit for credit transfer returns (SCT/SCT Inst), and debit for direct debit returns (SDD).

return_type'return' | 'refund' | 'reversal' required

The type of the return. Authorized values include return, refund and reversal. Only available when related payment is a direct debit.

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. It can be an incoming payment or a payment orders.

return_reasonstring required

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

status'received' | 'pending-approval' | 'approved' | 'canceled' | 'failed' | 'processing' | 'sent' | 'executed' | 'rejected' required

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

status_detailsstring required

The details of the status of this return.

metadataobject required

Additional client data in JSON format. See Metadata.

value_datestring date required

The value date of the return.

returned_amountinteger required

The absolute value of the return in the specified currency's smallest unit. For euro payments, the smallest unit is cents. €20 is represented as 2000.

currency'EUR' required

The currency of the return. Only EUR is supported for now.

receiving_account_numberstring required

The account receiving the return.

originating_account_numberstring

The account number of the originator of the return.

originating_account_holder_namestring

The holder name of the originating account.

originating_account_bank_namestring nullable

The bank name of the originating account.

receiving_account_bank_namestring nullable

The bank name of the receiving account.

reconciliation_status'unreconciled' | 'partially_reconciled' | 'reconciled' | 'excluded' required

The reconciliation status of the return, which is either unreconciled, reconciled, partially_reconciled, or excluded.

reconciled_amountinteger required

The amount that is already reconciled. It is the sum of the amount of the reconciliations related to this return.

created_atstring date-time required

The UTC timestamp of the creation of this return.

Example response

{
  "object": "return",
  "metadata": {
    "property_a": true,
    "property_b": "false"
  },
  "originating_account_bank_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  },
  "receiving_account_bank_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  }
}