> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get external transaction reference

> Retrieve details of an external transaction reference by its ID.

External transaction references contain original transaction data from inbound SEPA messages (such as camt.056 cancellation requests or camt.027 claim non-receipt inquiries) for which the impacted transaction could not be found in the system.


## OpenAPI

````yaml get /v1/external-transaction-reference
openapi: 3.1.0
info:
  description: >
    # General info

    ## Base API URL for environments:

    * TEST: https://api.pgw-sandbox.finventi.com

    * PROD: https://api.pgw.finventi.com


    # Authentication

    <b>NOTE:</b> IP whitelisting is mandatory to gain access to our APIs in both
    TEST and PROD environments. To register your IPs, please contact
    `connectors-support@inventi.lt`.


    Our API uses OAuth 2.0 for authentication. To access the API, you need to
    obtain a bearer token from the authorization server.


    ### Obtain a Bearer Token

    To get a bearer token, use the following cURL command:


    ```

    curl -X POST \

    --location
    '<auth-server-url>/realms/<client-name>/protocol/openid-connect/token' \

    --header 'Content-Type: application/x-www-form-urlencoded' \

    --data-urlencode 'grant_type=client_credentials' \

    --data-urlencode 'client_id=api-sepa-gateway-client' \

    --data-urlencode 'client_secret=<client-secret>'

    ```


    where:


    `<auth-server-url>` is either `https://auth.sandbox.finventi.com/` (TEST) or
    `https://auth.finventi.com/` (PROD).


    `<client-name>` is a value of TenantID that was assigned by INVENTI team
    during initial configuration and could be found in Configuration Matrix that
    was shared to your representative.


    `<client-secret>` is a value that can be obtained by logging into SEPA
    Dashboard UI and going to <i>User Management</i> -> <i>Clients</i> ->
    `api-sepa-gateway-client` -> <i>Credentials</i> -> <i>Client Secret</i>.


    <b>NOTE:</b> The token is valid for 45 minutes.


    ### Include the Bearer Token in Requests

    Include the obtained token in the `Authorization` header of your API
    requests with the `Bearer` prefix:


    ```

    Authorization: Bearer <bearer-token>

    ```


    ### Example Request:

    ```

    curl --location --request POST
    'https://api.pgw-sandbox.finventi.com/gateway/createSepaPmt' \

    --header 'Authorization: Bearer <bearer-token>' \

    ```


    # Idempotency

    In our API, we support idempotency for certain endpoints to ensure that
    repeated requests have the same effect as a single request.

    Idempotent endpoints allow you to safely retry requests without worrying
    about unintended side effects, such as duplicate resource creation or
    modification. \


    To achieve idempotency, you need to include the **Idempotency-Key** header
    in your requests to the supported endpoints.

    If the provided idempotency key corresponds to an existing database object,
    the response will retrieve the data of the existing object instead of
    creating a new one.

    ## Idempotency-Key Header

    The **Idempotency-Key** header is used to uniquely identify a request and
    associate it with a specific operation. While the header value can be any
    string, we recommend using a UUID (Universally Unique Identifier) for
    uniqueness within the scope of the endpoint. This allows you to easily
    generate a unique key for each request.

    ### Example Request

    ```

    curl --location --request POST
    'https://api.pgw-sandbox.finventi.com/gateway/createSepaPmt' \

    --header 'Idempotency-Key: 123e4567-e89b-12d3-a456-426655440000' \

    ```

    ## Supported endpoints:

    * /gateway/createSepaPmt


    # Webhooks

    ## Signature Verification


    ### Introduction

    To ensure the authenticity and integrity of webhooks sent from our system,
    each webhook includes a digital signature. This signature allows the
    receiver to verify that the payload has not been altered during
    transmission. Verifying the signature confirms the webhook's origin and
    ensures its data integrity.


    Each webhook includes the signature in the `finventi-signature-N` HTTP
    header, where `N` represents the version of the signature. The current
    version is `1` (`finventi-signature-1`). When public keys are rotated, new
    header versions are issued, ensuring backward compatibility for clients
    until their code is updated.


    The signature should be verified using the RSASSA-PKCS1-v1.5 algorithm and
    the appropriate public key, based on the environment.


    ### Environment Public Keys

    Use the corresponding public key based on the environment in which you are
    verifying the webhook (current version - `1`)

    #### Test Environment Public Key

    ```text

    -----BEGIN PUBLIC KEY-----

    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvoc7GrFbduCeSVxFPJ3l

    a0NRa0caUqBddQAOUxuHTOuShOvdKbxRYc5u1vb9YNLJWjx4XSHESp8Q7oocqXt8

    +weBFsk/kAtJ4zjbYPY1PvAOLe+WObdxxZtfwzpwVxbtP6GQk5aUi2HbITe3EDf/

    7WEmvnAcWm++Mo6+GSh2Ky1t6o4htrx1lH2gYVg0iRHx1W9lLXjMl/5oLi1C6dtx

    TnBmXMlN/NT5YYU4lVlXQBZzS7a8ZgwosfW+v1uCimzbGcWytmmcFISjSNqkYaeg

    IXDYwKLwlsWtm975ln6UL20KcSt7ia+Lpuv7cdxJlOY95y0ds/PCw1x0HEPxU+44

    swIDAQAB

    -----END PUBLIC KEY-----

    ```


    #### Production Environment Public Key

    ```text

    -----BEGIN PUBLIC KEY-----

    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1pTRk8oUoGAAgXE8Gni8

    xvG2MJz6uYkZcNlXhPTrsxfqD4W5uDZOhy7APLz47Plcv+XL45kO0BFgjYHDRASx

    IIb6K5+YVyf9p1biLdZgf047wxwuC65bT6ddhuSX9FrMEtgPvghltSSfTZjdwVck

    QNE2JEV7vcIfq3ke5US+SP+6AHIcPyXypslp50CtO8wpZG+pz7rSdOoiRFTMhzVZ

    efDetRcnFv6DoAdapOiNVG9MBPqnE+BT5mnAlgF6V551ZJFOMhFvm/cLtP3Gj2a9

    /zNeCT1ZXHIuqxwrBUy/R8RSKJJIBWUbJEHF+pcPite+MgJm529Bt6K4mGCv1Nzv

    GwIDAQAB

    -----END PUBLIC KEY-----

    ```


    ### Additional Headers


    Each webhook includes the following HTTP headers to assist in verifying the
    signature:

    * `finventi-signature-N`: Each webhook contains the signature.

    * `finventi-signature-timestamp`: A UNIX timestamp (UTC) indicating when the
    webhook was sent.

    * `finventi-receiver-tenant-id`: The tenant ID for the webhook recipient.


    These headers must be used during the signature verification process to
    ensure consistency.


    ### Signature Verification Process

    To verify the authenticity of the webhook, the following steps must be
    performed:

    1. Concatenate the following components in the specified order, separated by
    periods (.):
      * The request body
      * The tenant ID from `finventi-receiver-tenant-id`
      * The timestamp from `finventi-signature-timestamp`

    Example:

    ```text

    {"trx_id":10300003,"end_to_end_id":"NOTPROVIDED","type":"Payment","direction":"OUTBOUND","amount":1,"currency":"EUR","status":"Created","updated_at":"2024-09-20T13:46:32.092083Z"}.demo1.1726839992

    ```

    2. Hash the concatenated string using the SHA-256 algorithm.

    3. Base64 decode the received finventi-signature-v header to obtain the
    signature.

    4. Verify the signature using
    [RSASSA-PKCS1-v1_5](https://datatracker.ietf.org/doc/html/rfc8017#section-8.2.2)
    with the hashed data, decoded signature, and the latest public key.


    ### Code Example (Node.js)

    ```js

    const crypto = require('crypto');


    const signatureBase64 =
    "GtZFu1uNFqOir8eDkar7+d/S+FtwQpk4mPGCuByKhJG29K1u7ynbVhkrDF8c3TqyX9wYHxpOa94FsgW2I4CnLh+B24LqL7WVSuACOL6GoSjfKeXP00NSp0ps8QYbVaJ8Ys6E4FePhp+7piAACkIP5vZ91JCLQ8lz36KRJlOnByQMTBH6j924n1GwZiZfbMojOGmMhLA0h8jWgTIeuvYPswiZXZXp0vpqJfWmdoqiU1ldoausTNFyoVwFuuzkxPv1VHvWeEeWirObUv3wNpyAnLnqomDgR7pe/9dDV0bkq5r0JkRhnbPCEFE/zzHeDgZ957hv8Oq3wJkGJarZ0NvPLw=="

    const signature = Buffer.from(signatureBase64, 'base64');


    const publicKey = `-----BEGIN PUBLIC KEY-----

    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvoc7GrFbduCeSVxFPJ3l

    a0NRa0caUqBddQAOUxuHTOuShOvdKbxRYc5u1vb9YNLJWjx4XSHESp8Q7oocqXt8

    +weBFsk/kAtJ4zjbYPY1PvAOLe+WObdxxZtfwzpwVxbtP6GQk5aUi2HbITe3EDf/

    7WEmvnAcWm++Mo6+GSh2Ky1t6o4htrx1lH2gYVg0iRHx1W9lLXjMl/5oLi1C6dtx

    TnBmXMlN/NT5YYU4lVlXQBZzS7a8ZgwosfW+v1uCimzbGcWytmmcFISjSNqkYaeg

    IXDYwKLwlsWtm975ln6UL20KcSt7ia+Lpuv7cdxJlOY95y0ds/PCw1x0HEPxU+44

    swIDAQAB

    -----END PUBLIC KEY-----`;


    const body =
    `{"trx_id":10300003,"end_to_end_id":"NOTPROVIDED","type":"Payment","direction":"OUTBOUND","amount":1,"currency":"EUR","status":"Created","updated_at":"2024-09-20T13:46:32.092083Z"}`;

    const tenantId = "demo1"

    const timestamp = "1726839992";

    const dataToVerify = Buffer.from(body + '.' + tenantId + '.' + timestamp);


    const isVerified = crypto.verify(

    "sha256",

    dataToVerify,

    {
      key: publicKey,
      padding: crypto.constants.RSA_PKCS1_PADDING,
    },

    signature

    );

    console.log("Verification successful:", isVerified);

    ```

    ## Payment status change webhook

    Payment status changes can send notifications using webhook to clients
    provided HTTP POST endpoint.


    Notifications are sent when payment/payment return status changes to one of
    the following statuses: Created, To sign, Signed, Accepted, Completed, Some
    problems, Cancelled, Rejected.


    There is retry mechanism - if an endpoint fails, the notification will be
    repeatedly sent until it is successfully delivered. During this retry
    process, all other notifications will be held back and will only be
    delivered once the initially blocked notification is successfully sent.


    Request is sent in json format.

    ### Request Body Example:

    ```json

    {
      "trx_id": 2018845,
      "end_to_end_id": "2302231660139326",
      "type": "Payment",
      "direction": "OUTBOUND",
      "amount": 10657, (CENTS)
      "currency": "EUR",
      "status": "Created",
      "updated_at": "2023-02-23 07:49:37.524808" (date&time when status was updated),
      "debtor_iban": "LT543210010000000003",
      "creditor_iban": "LT123450010000000004"
    }

    ```


    | Body parameter | Type |

    |-------------------|-------|

    | **trx_id**            | **Integer** |

    | **end_to_end_id**     | **String** |

    | **type**              | **String** classifier.<br>  Available values:
    "Payment", "Payment return", "Payment cancellation", "CSM fees", "Reverse
    payment", "Adjustment" |

    | **direction**         | **Enum**.<br>  Available values: "INBOUND",
    "OUTBOUND" |

    | **amount**            | **Integer** |

    | **currency**          | **String** classifier.<br>  Available values:
    "EUR" |

    | **status**            | **String** classifier.<br>  Available values:
    "Created", "To sign", "Signed", "Accepted", "Completed", "Some problems",
    "Cancelled", "Rejected", "Pending confirmation" |

    | **updated_at**        | **DateTime** |

    | **debtor_iban**       | **String** |

    | **creditor_iban**     | **String** |

     ## Payment cancellation status change webhook
    Payment cancellation status changes can send notifications using webhook to
    clients provided HTTP POST endpoint.


    Notifications are sent when payment cancellation status changes to one of
    the following statuses: CANCELLATION_IN_PROGRESS, CANCELLATION_ACCEPTED,
    CANCELLATION_REJECTED, CANCELLATION_COMPLETED.


    There is retry mechanism - if an endpoint fails, the notification will be
    repeatedly sent until it is successfully delivered. During this retry
    process, all other notifications will be held back and will only be
    delivered once the initially blocked notification is successfully sent.


    Request is sent in json format.

    ### Request Body Example:

    ```json

    {
      "cancellationId": 102,
      "trxId": "2018845",
      "direction": "OUTBOUND",
      "reason": "CUST",
      "status": "CANCELLATION_IN_PROGRESS",
    }

    ```


    | Body parameter | Type |

    |-------------------|-------|

    | **cancellationId**    | **Integer** |

    | **trxId**            | **Integer** |

    | **direction**         | **Enum**.<br>  Available values: "INBOUND",
    "OUTBOUND" |

    | **reason**            | **Enum**.<br>  Available values: "DUPL", "CUST",
    "FRAD", "TECH", "AC03", "AM09", "AGNT", "COVR", "CURR", "CUTA", "DS24",
    "FRNA", "FRTR", "INDM", "SYAD", "UPAY","AC01", "AC04", "AC06", "AC13",
    "AG01", "AG02", "AM01", "AM04", "AM05", "CNOR", "DNOR", "MD01", "MD02",
    "MD07", "MS02", "MS03", "RC01", "RR01", "RR02", "RR04", "SL01", "BE05",
    "FF01", "DT01", "ED05", "PY01" |

    | **status**            | **Enum**.<br>  Available values:
    "CANCELLATION_CREATED", "CANCELLATION_IN_PROGRESS", "RETURNING", "REFUSING",
    "PAYMENT_RETURNED", "CANCELLATION_REFUSED", "PROCESSING_FAILED",
    "CANCELLATION_COMPLETED", "CANCELLATION_REJECTED", "CANCELLATION_ACCEPTED" |


    ### Cancellation request processing statuses

    The table below standardises how you track SEPA cancellation requests from
    start to finish. Each status maps to specific inbound/outbound ISO-20022
    messages, giving you clear, machine-readable checkpoints for monitoring and
    automating your cancellation workflow.


    | Status name | Description |

    | ----------- | ---------------- |

    | CANCELLATION_CREATED | Cancellation request successfully created and
    validated by the Payment Gateway system. |

    | CANCELLATION_IN_PROGRESS | The camt.056 payment cancellation request is
    received from the clearing system and waiting for the User activities. Can
    be accepted and payment will be returned or rejected. |

    | RETURNING | User decides to return the funds. The pacs.004 payment return
    message is sent to the initiator of the payment cancellation request. The
    intermediary cancellation request status, which doesn't allow to execute any
    actions until the final status of the payment return will be set. |

    | REFUSING | User rejects to return the funds. The camt.029 resolution of
    investigation message is sent to the initiator of the payment cancellation
    request. The intermediary cancellation request status, which doesn't allow
    to execute any actions until the final status of the resolution of
    investigation will be set. |

    | PAYMENT_RETURNED | Incoming cancellation: The pacs.004 payment return
    message successfully delivered to the beneficiary bank. This is the final
    processing status, which doest allow to perform any actions with the
    cancellation request. <br> Outgoing cancellation: The payment return
    pacs.004 message, following the sent cancellation request is received from
    the clearing system. The transaction based  on the payment return message is
    successfully created in system, its data linked with the respective
    cancellation request and the original outbound payment. |

    | CANCELLATION_REFUSED | Incoming cancellation: The camt.029 resolution of
    investigation message successfully delivered to the beneficiary bank. This
    is the final processing status, which doest allow to perform any actions
    with the cancellation request. <br> Outgoing cancellation: The resolution of
    investigation camt.029 message, following the sent cancellation request is
    received from the clearing system. The payment return refusal data are
    indicated for the related cancellation request. |

    | PROCESSING_FAILED | The state which indicates that there was an error
    during processing of the response for the cancellation request message. This
    state allows to reprocess the cancellation request after the errors will be
    eliminated. |

    | CANCELLATION_COMPLETED | Incoming cancellation: The payment return
    transaction completed successfully. If failed, the status will be changed to
    the CANCELLATION_IN_PROGRESS and it is possible to reprocess the
    cancellation request. <br> Outgoing cancellation: The pacs.004 payment
    return message following cancellation request is received from the clearing
    system. |

    | CANCELLATION_REJECTED | The payment cancellation request camt.056 message
    was rejected by the clearing system due to errors. The state allows to
    initiated additional cancellation request after the errors will be
    eliminated. |

    | CANCELLATION_ACCEPTED | The payment cancellation request camt.056 message
    successfully delivered to the beneficiary bank. |


    # External code sets
      ## Private identification codes

      | Identification code | Definition |
      |-------------------|-------|
      | **ARNU**    | **Number assigned by a social security agency to identify a non-resident person.** |
      | **CCPT**    | **Number assigned by an authority to identify the passport number of a person.** |
      | **CUST**    | **Number assigned by an issuer to identify a customer.** |
      | **DRLC**    | **Number assigned by an authority to identify a driver's license.** |
      | **EMPL**    | **Number assigned by a registration authority to an employee.** |
      | **NIDN**    | **Number assigned by an authority to identify the national identity number of a person.** |
      | **SOSE**    | **Number assigned by an authority to identify the social security number of a person.** |
      | **TXID**    | **Number assigned by a tax authority to identify a person.** |

      ## Organisation identification codes

      | Identification code | Definition |
      |-------------------|-------|
      | **BANK**    | **Unique and unambiguous assignment made by a specific bank or similar financial institution to identify a relationship as defined between the bank and its client.** |
      | **CBID**    | **A unique identification number assigned by a central bank to identify an organisation.** |
      | **CHID**    | **A unique identification number assigned by a clearing house to identify an organisation.** |
      | **CINC**    | **A unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation.** |
      | **COID**    | **Country authority given organisation identification (e.g., corporate registration number).** |
      | **CUST**    | **Number assigned by an issuer to identify a customer. Number assigned by a party to identify a creditor or debtor relationship.** |
      | **DUNS**    | **A unique identification number provided by Dun & Bradstreet to identify an organisation.** |
      | **EMPL**    | **Number assigned by a registration authority to an employer.** |
      | **GS1G**    | **Global Location Number. A non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules.The number is used to retrieve detailed information that is linked to it.** |
      | **SREN**    | **The SIREN number is a 9 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation in France.** |
      | **SRET**    | **The SIRET number is a 14 digit code assigned by INSEE, the French National Institute for Statistics and Economic Studies, to identify an organisation unit in France. It consists of the SIREN number, followed by a five digit classification number, to identify the local geographical unit of that entity.** |
      | **TXID**    | **Number assigned by a tax authority to identify an organisation.** |
  title: SEPA Payment Gateway
  version: '1.0'
servers:
  - description: Payment Platform sandbox environment
    url: https://api.pgw-sandbox.finventi.com
security: []
tags:
  - description: >-
      Manage payment investigations. Supports two types: Claim Non-Receipt
      (camt.027) for outbound SEPA CT payments, and Payment Status Request
      (pacs.028) for outbound SEPA INST payments. Inbound investigations
      received from counterparties can be searched, viewed, and resolved via
      :resolve API (camt.029).
    name: Investigations
paths:
  /v1/external-transaction-reference:
    get:
      tags:
        - Payments Information
      summary: Get external transaction reference.
      description: >-
        Retrieve details of an external transaction reference by its ID.
        External transaction references contain original transaction data from
        inbound SEPA messages (such as camt.056 cancellation requests or
        camt.027 claim non-receipt inquiries) for which the impacted transaction
        could not be found in the system.
      operationId: getExternalTransactionReference
      parameters:
        - description: External transaction reference ID
          example: 123
          in: query
          name: id
          required: true
          schema:
            format: int64
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalTransactionReferenceResponse'
          description: >-
            Original transaction data from inbound SEPA messages for which the
            impacted transaction could not be found in the system
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Tenant does not have an access to the resource
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: External transaction reference is not found
components:
  schemas:
    ExternalTransactionReferenceResponse:
      properties:
        amount:
          description: Payment amount
          type: number
        creditorBic:
          description: Creditor (Recipient) BIC
          type: string
        creditorIban:
          description: Creditor (Recipient) IBAN
          type: string
        creditorName:
          description: Creditor (Recipient) name
          type: string
        currencyCode:
          description: Payment currency code
          type: string
        debtorBic:
          description: Debtor (Sender) BIC
          type: string
        debtorIban:
          description: Debtor (Sender) IBAN
          type: string
        debtorName:
          description: Debtor (Sender) name
          type: string
        endToEndId:
          description: End to end identification of the original transaction
          type: string
        method:
          description: Transaction method
          type: string
        orgnlMsgId:
          description: Original SEPA message identification
          type: string
        purposeCode:
          description: Category purpose code
          type: string
        remittanceInfo:
          description: Unstructured remittance information
          type: string
        settlementDate:
          description: Settlement date of the original transaction
          format: date
          type: string
        ultimateCreditorName:
          description: Ultimate Creditor name
          type: string
        ultimateDebtorName:
          description: Ultimate Debtor name
          type: string
      required:
        - amount
        - currencyCode
        - endToEndId
        - orgnlMsgId
        - settlementDate
      type: object
    ErrorResponse:
      description: Error response
      properties:
        code:
          description: Code of error
          type: string
        data:
          $ref: '#/components/schemas/ErrorResponseData'
          description: 'Error data '
        message:
          description: Error message
          type: string
      required:
        - code
      type: object
    ErrorResponseData:
      description: Error wrapper containing all occurred errors
      properties:
        errors:
          description: All occurred errors
          items:
            $ref: '#/components/schemas/ErrorResponseViolation'
          type: array
        message:
          description: Generic message for occurred errors
          type: string
      required:
        - errors
      type: object
    ErrorResponseViolation:
      description: Single error wrapper
      properties:
        code:
          description: Error code
          type: string
        field_name:
          description: Field name which failed
          type: string
        message:
          description: Error message
          type: string
        value:
          description: Value which was invalid
          type: string
      type: object

````