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 the inbound SEPA CT transaction to the originator. Use this when you cannot credit the beneficiary account due to account issues or customer disputes.

​
Common Return Scenarios

  • Various AML reasons
  • Account closed or blocked

​
Requirements

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

​
reason

  • Business description: Payment return reason code
  • Validations / Allowed values:
    • AC01 — IncorrectAccountNumber
    • AC04 — ClosedAccountNumber
    • AC06 — BlockedAccount
    • AG01 — TransactionForbidden
    • AG02 — InvalidBankOperationCode
    • AM05 — Duplication
    • BE04 — MissingCreditorAddress
    • MD07 — EndCustomerDeceased
    • MS02 — NotSpecifiedReasonCustomerGenerated
    • MS03 — NotSpecifiedReasonAgentGenerated
    • RC01 — BankIdentifierIncorrect
    • RR01 — MissingDebtorAccountOrIdentification
    • RR02 — MissingDebtorNameOrAddress
    • RR03 — MissingCreditorNameOrAddress
    • RR04 — RegulatoryReason
    • CNOR — Creditor PSP is not registered
    • ERIN — ERI Option Not Supported
Note: The same API is also used for SDD transaction returns, but the return reasons listed here are for SEPA CT payments. The API specification contains a broader list, however only the values listed above are currently used.

​
tax_amount

  • Business description: Amount of taxes charged by the PSP for the payment return initiation.
  • Rules / Notes:
    • The returned amount will be decreased by the amount of taxes applied by the PSP.
    • Information about the applied taxes will be provided in the outbound payment return message.

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