Skip to main content
POST
/
v1
/
transactions
/
{id}
:return
Return transaction
curl --request POST \
  --url https://api.pgw-sandbox.finventi.com/v1/transactions/{id}:return \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "AC01",
  "compensation_amount": 123,
  "tax_amount": 123
}
'
{
  "cr_amount": 123,
  "cr_ccy_isocode": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "dr_amount": 123,
  "dr_ccy_isocode": "<string>",
  "id": 123,
  "status": "<string>",
  "status_hardvalue": "<string>",
  "status_id": 123,
  "type": "<string>",
  "type_id": 123,
  "compensation_amt": 123,
  "inbound": {
    "cr_amount": 123,
    "cr_bank_bic": "<string>",
    "cr_ccy_isocode": "<string>",
    "cr_name": "<string>",
    "dr_bank_bic": "<string>",
    "dr_name": "<string>",
    "id": 123,
    "sepa_msg_id": "<string>",
    "status": "<string>",
    "cr_acc": "<string>",
    "cr_address": "<string>",
    "cr_address_city": "<string>",
    "cr_address_country": "<string>",
    "cr_alt_code_company": "<string>",
    "cr_alt_code_company_issuer": "<string>",
    "cr_bank_name": "<string>",
    "cr_code_company": "<string>",
    "cr_code_issuer": "<string>",
    "cr_code_person": "<string>",
    "dr_acc": "<string>",
    "dr_address": "<string>",
    "dr_address_city": "<string>",
    "dr_address_country": "<string>",
    "dr_alt_code_company": "<string>",
    "dr_alt_code_company_issuer": "<string>",
    "dr_bank_name": "<string>",
    "dr_code_company": "<string>",
    "dr_code_issuer": "<string>",
    "dr_code_person": "<string>",
    "end_to_end_id": "<string>",
    "method": "SEPA",
    "settlement_date": "2023-12-25",
    "trx_purpose": "<string>",
    "trx_purpose_information": "<string>",
    "trx_purpose_structured_issuer": "<string>",
    "trx_purpose_structured_ref": "<string>",
    "ucr_address": "<string>",
    "ucr_address_city": "<string>",
    "ucr_address_country": "<string>",
    "ucr_id_type": 123,
    "ucr_identification": "<string>",
    "ucr_issuer": "<string>",
    "ucr_name": "<string>",
    "ucr_organisation_bic": "<string>",
    "ucr_private_birth": "<string>",
    "ucr_private_birth_city": "<string>",
    "ucr_private_birth_country": "<string>",
    "ucr_private_birth_province": "<string>",
    "ucr_scheme_code": "<string>",
    "ucr_scheme_proprietary": "<string>",
    "udr_address": "<string>",
    "udr_address_city": "<string>",
    "udr_address_country": "<string>",
    "udr_id_type": 123,
    "udr_identification": "<string>",
    "udr_issuer": "<string>",
    "udr_name": "<string>",
    "udr_organisation_bic": "<string>",
    "udr_private_birth": "<string>",
    "udr_private_birth_city": "<string>",
    "udr_private_birth_country": "<string>",
    "udr_private_birth_province": "<string>",
    "udr_scheme_code": "<string>",
    "udr_scheme_proprietary": "<string>"
  },
  "mandate_information": {
    "date_of_signature": "2023-12-25",
    "id": "<string>"
  },
  "origin_bic": "<string>",
  "origin_name": "<string>",
  "origin_reason_code": "<string>",
  "origin_reason_info": "<string>",
  "outbound": {
    "cr_acc": "<string>",
    "cr_bank_bic": "<string>",
    "cr_name": "<string>",
    "dr_acc": "<string>",
    "dr_amount": 123,
    "dr_bank_bic": "<string>",
    "dr_ccy_isocode": "<string>",
    "dr_name": "<string>",
    "id": 123,
    "sepa_msg_id": "<string>",
    "status": "<string>",
    "cr_address": "<string>",
    "cr_address_city": "<string>",
    "cr_address_country": "<string>",
    "cr_alt_code_company": "<string>",
    "cr_alt_code_company_issuer": "<string>",
    "cr_bank_name": "<string>",
    "cr_code_company": "<string>",
    "cr_code_issuer": "<string>",
    "cr_code_person": "<string>",
    "dr_address": "<string>",
    "dr_address_city": "<string>",
    "dr_address_country": "<string>",
    "dr_alt_code_company": "<string>",
    "dr_alt_code_company_issuer": "<string>",
    "dr_bank_name": "<string>",
    "dr_code_company": "<string>",
    "dr_code_issuer": "<string>",
    "dr_code_person": "<string>",
    "end_to_end_id": "<string>",
    "method": "SEPA",
    "settlement_date": "2023-12-25",
    "trx_purpose": "<string>",
    "trx_purpose_information": "<string>",
    "trx_purpose_structured_issuer": "<string>",
    "trx_purpose_structured_ref": "<string>",
    "ucr_address": "<string>",
    "ucr_address_city": "<string>",
    "ucr_address_country": "<string>",
    "ucr_id_type": 123,
    "ucr_identification": "<string>",
    "ucr_issuer": "<string>",
    "ucr_name": "<string>",
    "ucr_organisation_bic": "<string>",
    "ucr_private_birth": "<string>",
    "ucr_private_birth_city": "<string>",
    "ucr_private_birth_country": "<string>",
    "ucr_private_birth_province": "<string>",
    "ucr_scheme_code": "<string>",
    "ucr_scheme_proprietary": "<string>",
    "udr_address": "<string>",
    "udr_address_city": "<string>",
    "udr_address_country": "<string>",
    "udr_id_type": 123,
    "udr_identification": "<string>",
    "udr_issuer": "<string>",
    "udr_name": "<string>",
    "udr_organisation_bic": "<string>",
    "udr_private_birth": "<string>",
    "udr_private_birth_city": "<string>",
    "udr_private_birth_country": "<string>",
    "udr_private_birth_province": "<string>",
    "udr_scheme_code": "<string>",
    "udr_scheme_proprietary": "<string>"
  },
  "parent_trx_amt": 123,
  "parent_trx_id": 123,
  "rtrn_chrgs_amt": 123,
  "sepa_trx_id": "<string>",
  "sequence_type": "FRST",
  "status_reason": "<string>",
  "unaccounted_tax_amt": 123,
  "updated_at": "2023-11-07T05:31:56Z"
}

​
Overview

This endpoint returns a SEPA Direct Debit transaction to the originator. Use this when you cannot process the debit due to account issues or customer disputes.

​
Common Return Scenarios

  • Insufficient funds
  • Account closed or blocked
  • No valid mandate
  • Customer dispute

​
Requirements

  • Transaction must be in a returnable state
  • Valid return reason code required
  • Return must occur within allowed timeframe

​
SEPA SDD Return Reasons

This document lists the supported SEPA Direct Debit (SDD) return reason codes that can be used when returning an SDD transaction, because ervice /v1/transactions/:return is used not only for SDD payment returns

​
Validation Rules

  • The reason field must be one of the supported values listed below.
  • Using an unsupported reason code (for example FOCR) will result in a VALIDATION_ERROR.

​
Supported Return Reason Codes

  • AC01 – Incorrect IBAN
  • AC04 – Closed account
  • AC06 – Blocked account
  • AG01 – Transaction forbidden on this account
  • AG02 – Invalid bank operation code
  • AM04 – Insufficient funds
  • AM05 – Duplication
  • MD01 – No valid mandate
  • MD06 – Revoked mandate
  • MD07 – End of mandate
  • MS02 – Missing or incorrect information
  • MS03 – Not specified reason

​
Regulatory / Compliance

  • RC01 – Invalid creditor identifier
  • RR01 – Regulatory reasons
  • RR02 – Regulatory reasons
  • RR03 – Regulatory reasons
  • RR04 – Regulatory reasons

​
Miscellaneous

  • SL01 – Specific service offered by debtor bank
  • BE05 – Unrecognised initiating party
  • FF05 – File format error

​
Example Error Response

{
  "status": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Unable to return SDD transaction with id ... because it is of reason: FOCR.",
    "data": {
      "errors": [
        {
          "field_name": "reason",
          "value": "Supported values are [AC01, AC04, AC06, AG01, AG02, AM04, AM05, MD01, MD06, MD07, MS02, MS03, RC01, RR01, RR02, RR03, RR04, SL01, BE05, FF05]"
        }
      ]
    }
  }
}

Path Parameters

​
id
integer<int64>
required

Transaction ID.

Body

application/json
​
reason
enum<string>
required

Return reason.

Available options:
AC01,
AC04,
AC06,
AG01,
AG02,
AM04,
AM05,
BE04,
BE05,
CNOR,
ERIN,
FF05,
FOCR,
MD01,
MD06,
MD07,
MS02,
MS03,
RC01,
RR01,
RR02,
RR03,
RR04,
SL01,
AM09,
BE01,
FRAD,
UPAY,
DUPL,
NARR,
RC03,
RC04,
INDM,
LEGL,
NOAS,
AGNT
​
compensation_amount
number

Compensation amount.

​
tax_amount
number

Tax amount.

Response

Returned transaction

​
cr_amount
integer
required

Payment amount in minor currency units (cents)

​
cr_ccy_isocode
string
required

SEPA payment currency code

​
created_at
string<date-time>
required

Time and date when transaction was created

​
dr_amount
integer
required

Payment amount in minor currency units (cents)

​
dr_ccy_isocode
string
required

SEPA payment currency code

​
id
integer<int64>
required

Transaction ID

​
status
string
required

Name of the status

​
status_hardvalue
string
required

Hard value of status

​
status_id
integer<int32>
required

Status id, all statuses can be retrived using API getTransactionStatuses

​
type
string
required

Type name

​
type_id
integer<int32>
required

Type id, all transaction types can be retrieved using API getTransactionTypes

​
compensation_amt
integer

Payment compensation amount

​
inbound
object

Information about inbound transaction

​
mandate_information
object

Provides further details of the direct debit mandate signed between the creditor and the debtor.

​
origin_bic
string

Payment return originator bic

​
origin_name
string

Payment return originator name

​
origin_reason_code
string

Payment return originator reason code

​
origin_reason_info
string

Payment return originator reason information

​
outbound
object

Information about outbound transaction

​
parent_trx_amt
integer

Original transaction amount

​
parent_trx_id
integer<int64>

Transaction id for parent transaction

​
rtrn_chrgs_amt
integer

Payment return tax amount

​
sepa_trx_id
string

Sepa transaction ID

​
sequence_type
enum<string>

Identifies the direct debit sequence, such as first, recurrent, final or one-off.

Available options:
FRST,
RCUR,
FNAL,
OOFF
​
status_reason
string

If there is some error, it is displayed in status reason or processing info tags

​
unaccounted_tax_amt
integer

Payment unaccounted tax amount

​
updated_at
string<date-time>

Time and date when transaction was last updated