> ## Documentation Index > Fetch the complete documentation index at: https://nextgen-docs.enfuce.com/llms.txt > Use this file to discover all available pages before exploring further. # Transaction event webhook > Enfuce sends a transaction event webhook to inform you about the current processing state. You might need to adjust the ledger balance, if impacted. ## OpenAPI ````yaml json-files/transaction-event-v1.openapi.json post /v1/transaction-events openapi: 3.0.3 info: title: Transaction events API version: 1.0.0 servers: [] security: [] tags: - name: Transaction events paths: /v1/transaction-events: post: tags: - Transaction events summary: Transaction event webhook description: >- Enfuce sends a transaction event webhook to inform you about the current processing state. You might need to adjust the ledger balance, if impacted. requestBody: content: application/json: schema: $ref: '#/components/schemas/transactionEvent' responses: '204': $ref: '#/components/responses/eventBridgeResponseOk' '429': $ref: '#/components/responses/eventBridgeResponse429' 5XX: $ref: '#/components/responses/eventBridgeResponse5xx' 4XX: $ref: '#/components/responses/eventBridgeResponse4xx' components: schemas: transactionEvent: allOf: - $ref: '#/components/schemas/transactionEventMetadata' - type: object properties: card: $ref: '#/components/schemas/card' merchant: $ref: '#/components/schemas/merchant' transaction: allOf: - $ref: '#/components/schemas/approvedTransaction' - $ref: '#/components/schemas/processedTransaction' - type: object properties: clearingStatus: $ref: '#/components/schemas/clearingStatus' partialClearingApplied: type: boolean description: >- Indicates if transaction was cleared in a single operation. responseCode: $ref: '#/components/schemas/responseCode' title: transactionEventTransaction token: $ref: '#/components/schemas/token' transactionEventMetadata: type: object properties: id: $ref: '#/components/schemas/id' referenceTransactionEventId: allOf: - $ref: '#/components/schemas/id' description: >- Unique ID assigned to VOID_AUTHORIZATION message category — applicable only for VOID_AUTHORIZATION. transactionId: $ref: '#/components/schemas/transactionId' messageCategory: allOf: - $ref: '#/components/schemas/messageCategoryTransactionEvent' title: messageCategory messageFunction: allOf: - $ref: '#/components/schemas/messageFunctionTransactionEvent' title: messageFunction clearingStatus: allOf: - $ref: '#/components/schemas/clearingStatus' card: type: object description: Information about the card used for the payment. properties: id: type: string format: uuid description: > Enfuce generated unique ID assigned to each card used — enables you to identify the card that you must authorise. expirationDate: allOf: - $ref: '#/components/schemas/expiration' description: Card expiration date as received in the scheme message. title: expiration sequenceNumber: type: integer minimum: 0 description: Card sequence number as received in the scheme message. accountId: type: string pattern: '[a-zA-Z0-9-]{1,36}' description: Ledger provided account ID associated with the card. cardholderId: type: string format: uuid description: Unique ID of the cardholder associated with the card. groups: type: array items: type: object required: - groupId properties: groupId: type: string description: Unique ID assigned to the parent card group. description: Information about any parent card group associated with the card. applicationSelection: type: string enum: - DEBIT - CREDIT description: The type of card application used for the transaction. merchant: type: object properties: id: type: string description: ID assigned code each card acceptor, i.e. a merchant or a bank. name: type: string description: >- Merchant name as received from the card scheme. For ATMs, this can be a street address or a bank branch number. city: type: string description: >- The city where the transaction/withdrawal has occurred or where the merchant is registered. country: allOf: - $ref: '#/components/schemas/country' description: >- The country where the transaction/withdrawal has occurred or where the merchant is registered. zipCode: type: string description: The merchant's postal code. address: type: string description: Contains the merchant's street address. category: type: object properties: code: type: string description: > Merchant category code as per the card scheme classification. Categorisation is done based on the type of business or service the merchant provides. description: type: string description: Description of the Merchant Category Code (MCC). group: type: string description: Merchant Category Code (MCC) group as received from the scheme. terminalId: type: string description: Uniquely ID assigned to each terminal used by the merchant. subMerchantId: type: string description: > The sub-merchant ID is used when merchant ID is not adequate to identify the merchant. Used when a merchant uses a payment facilitator. partialApprovalCapable: type: boolean description: > Indicates whether the merchant is capable of accepting partial approval of an amount: - TRUE: Specifies `TRUE` if the merchant accepts partial approval. - FALSE: Specifies `FALSE` if the merchant does not accept partial approval. acquirerId: type: string description: >- Unique ID assigned to the financial institution acting as the merchant's acquirer. acquirerCountry: allOf: - $ref: '#/components/schemas/country' description: >- The country of the merchant's acquirer — mention the ISO-3166-1 alpha-3 country code. acquirerReferenceData: type: string description: > Data an acquirer supplies in an acquirer-originated message, might be required for the issuer to return to the acquirer in a subsequent message. approvedTransaction: allOf: - $ref: '#/components/schemas/transaction' - type: object properties: transactionType: $ref: '#/components/schemas/transactionType' approvedAmount: allOf: - $ref: '#/components/schemas/money' description: > Amount approved at the current payment processing stage; the amount might be further reduced in the subsequent stages, when the Ledger performs additional validations. If any issuer transaction fee is applied (see the issuerTransactionFees field), the approvedAmount also includes those fees. title: money processedDateTime: type: string format: date-time example: '2099-12-31T03:00:00.000Z' description: Time when processed by Enfuce. processedTransaction: allOf: - $ref: '#/components/schemas/transaction' - type: object properties: transactionType: allOf: - $ref: '#/components/schemas/transactionTypeClearing' title: transactionType originalAmount: allOf: - $ref: '#/components/schemas/money' description: >- Contains previous amounts in a Financial message that has been corrected, in transaction currency. title: money reconciliationDate: type: string format: date example: '2099-12-31' description: >- Identifies the clearing systems processing date expressed in the local time zone of the clearing system. reconciliationCycle: type: string description: Identifies a reconciliation period in a reconciliation date. processedDateTime: type: string format: date-time example: '2099-12-31T03:00:00.000Z' description: Time when processed by Enfuce. interchangeFee: $ref: '#/components/schemas/interchangeFee' exchangeRates: $ref: '#/components/schemas/exchangeRates' clearingStatus: type: string enum: - CLEARED - PARTIALLY_CLEARED description: >- The status of the transaction. CLEARED means that the transaction has been fully cleared, PARTIALLY_CLEARED means that the transaction is partially cleared. responseCode: type: string pattern: '[0-9A-Z]{2}' description: >- Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined. Supports alphanumeric codes (e.g., Visa N7). token: type: object description: Information about the token associated with the card. properties: id: type: string walletIdentifier: type: string description: Identifies the specific digital wallet. enum: - MASTERPASS - APPLE_PAY - GOOGLE_PAY - SAMSUNG_PAY - REMOTE_COMMERCE_PROGRAMS id: type: string format: uuid description: > Unique system generated ID assigned to each event in the payment processing workflow. For example, an ID assigned to the initial authorisation event. transactionId: type: string format: uuid description: > Enfuce generated unique ID assigned to each card transaction. Transaction events for the same card payment includes the same `transactionId`. For example, authorisation, incremental authorisation, and adjustment for the same transaction includes the same `transactionID`. messageCategoryTransactionEvent: type: string format: enum description: > Message category sent in the transaction event webhook. Possible enums: - INITIAL_AUTHORIZATION: Initial authorisation of the card payment. - INCREMENTAL_AUTHORIZATION: Additional authorisation for a previously authorised transaction. - DECLINED_AUTHORIZATION: Scheme declined the transaction on behalf of Enfuce in the STIP mode. - ADJUSTMENT: Corrections to a previously authorised transaction. - REVERSAL: Reversal of a previously authorised transaction. - BALANCE_INQUIRY: Enquiring about the current balance of the funding account from the external application. - PIN_MANAGEMENT: Request to change the card PIN. - PIN_MANAGEMENT_REVERSAL: Reversal of a pin change request. - FINANCIAL: Clearing message of batch payments. - PURGE_AUTHORIZATION: Excluded authorisations are purged after a specific period. - VOID_AUTHORIZATION: When an initial authorisation or an incremental authorisation request times out, a `VOID_AUTHORIZATION` message is generated. - ACCOUNT_STATUS_INQUIRY: When an account status is requested. enum: - INITIAL_AUTHORIZATION - INCREMENTAL_AUTHORIZATION - DECLINED_AUTHORIZATION - ADJUSTMENT - REVERSAL - BALANCE_INQUIRY - PIN_MANAGEMENT - PIN_MANAGEMENT_REVERSAL - FINANCIAL - FINANCIAL_ADDENDUM - FEE_COLLECTION - RECONCILIATION - PURGE_AUTHORIZATION - VOID_AUTHORIZATION - CHARGEBACK - CHARGEBACK_REVERSAL - REPRESENTMENT - REPRESENTMENT_REVERSAL - DOCUMENT_REQUEST - ACCOUNT_STATUS_INQUIRY messageFunctionTransactionEvent: type: string format: enum description: Identifies the message function of the transaction event. enum: - REQUEST - ADVICE - NOTIFICATION - ACCOUNT_STATUS_INQUIRY expiration: type: object required: - year - month properties: year: type: integer format: int32 description: Expiration year in YYYY format. example: 2024 month: type: integer format: int32 description: Expiration month in MM format. example: 1 title: expiration country: type: string description: A valid ISO-3166-1 alpha-3 country code. pattern: '[A-Z]{3}' example: FIN transaction: type: object properties: authCode: type: string pattern: '[0-9]{6}' description: > Enfuce generated code/number (6-digits)— returned to the merchant when authorisation is approved. In case of scheme advices, this is generated and transmitted by the scheme. authValidity: type: integer description: > Number of days the authorisation is valid (applicable when merchants requests for extended authorisation period, longer than the default 7 days). billingAmount: allOf: - $ref: '#/components/schemas/money' description: > Transaction amount in the currency of the ledger account (associated with the card). If any issuer transaction fee is applied (see the issuerTransactionFees field), the billingAmount also includes those fees. title: money transactionAmount: allOf: - $ref: '#/components/schemas/money' description: >- The transaction amount in the local currency of the acquirer or the merchant, where the transaction occurred. title: money settlementAmount: allOf: - $ref: '#/components/schemas/money' description: > The amount of funds transferred between the acquirer and the issuer, equal to the `transactionAmount`, in the settlement currency. title: money acquirerTransactionFeeAmount: allOf: - $ref: '#/components/schemas/money' description: Fee charged (for example, by the acquirer) for transaction activity. title: money issuerTransactionFees: type: array items: $ref: '#/components/schemas/transactionFee' cardholderVerificationMethods: type: array items: $ref: '#/components/schemas/cardholderVerificationMethod' retrievalReferenceNumber: type: string description: Merchant/acquirer generated transaction reference number. cardEntryMode: $ref: '#/components/schemas/cardEntryMode' cardholderPresent: type: boolean description: >- Indicates whether the cardholder is physically present during transaction. cardPresent: type: boolean description: Indicates whether the card is present at the point of service. merchantInitiated: type: boolean description: > Indicates whether the transaction is a recurring payment or merchant initiated. This implies whether the cardholder has approved the merchant initiated transaction. transactionDateTime: type: string format: local-date-time example: '2099-12-31T03:00:00.000' description: Date and time in the time zone where the transaction occurred. originalTransactionId: type: string description: >- This value is present only for recurring transaction, and it's value is first original authorisation request in the chain. transactionType: type: string format: enum description: The transaction Type enum: - RETAIL - ATM - UNIQUE - CASH_DISBURSEMENT - CREDIT - ORIGINAL_CREDIT - BALANCE_INQUIRY - P2P_DEBIT - P2P_CREDIT - PIN_CHANGE - PIN_UNBLOCK - CASHBACK - CONVENIENCE_CHECK - BALANCE_TRANSFER - REVERSAL - AFT money: description: Amount including currency. type: object required: - amount - currency properties: amount: type: number example: 3.14 currency: $ref: '#/components/schemas/currency' transactionTypeClearing: type: string format: enum description: The transaction Type enum: - RETAIL - ATM - UNIQUE - CASH_DISBURSEMENT - CREDIT - ORIGINAL_CREDIT - BALANCE_INQUIRY - P2P_DEBIT - P2P_CREDIT - PIN_CHANGE - PIN_UNBLOCK - FEE_COLLECTION_DEBIT - FEE_COLLECTION_CREDIT - CASHBACK - CONVENIENCE_CHECK - BALANCE_TRANSFER - REVERSAL - AFT interchangeFee: type: object description: Interchange calculated by the scheme for the transaction. properties: amount: type: number example: 3.14 currency: $ref: '#/components/schemas/currency' direction: allOf: - $ref: '#/components/schemas/interchangeFeeDirection' example: CREDIT required: - amount - currency - direction exchangeRates: type: object description: >- Field that contains exchange rates for the transaction, it is null if both currencies are the same. properties: ecbRate: type: number example: 2.72 description: European Central Bank exchange rate. transactionFee: type: object properties: type: type: string format: enum description: > Type of Issuer generated transaction fee in cardholder billing currency. Transaction based fees that are additional fees charged on top of the transaction. enum: - CASH_FEE - ATM_FEE - MARKUP_FEE amount: allOf: - $ref: '#/components/schemas/money' description: Transaction fee amount in cardholder billing currency. title: money cardholderVerificationMethod: type: string format: enum description: | The method used for verifying the cardholder: - PIN_VERIFIED_BY_CARD: The card's PIN is verified. - PIN_VERIFIED_BY_ISSUER: The card's PIN is verified by issuer. - WALLET: The cardholder is verified by the digital wallet. - THREE_DS: The cardholder is 3DS authenticated. - BIOMETRIC: The cardholder is verified by biometrics data. - SIGNATURE: The cardholder's signature verified. - NO_VERIFICATION: No verification is performed. enum: - PIN_VERIFIED_BY_CARD - PIN_VERIFIED_BY_ISSUER - WALLET - THREE_DS - BIOMETRIC - SIGNATURE - NO_VERIFICATION cardEntryMode: type: string format: enum description: Describes how the card credentials were captured. enum: - CHIP - CHIP_CONTACTLESS - MAGNETIC_STRIPE - MANUAL_ENTRY - WALLET_CONTACTLESS - ECOMMERCE - WALLET_ECOMMERCE - CREDENTIALS_ON_FILE - UNKNOWN currency: type: string description: A valid ISO 4217 currency code pattern: '[A-Z]{3}' example: EUR interchangeFeeDirection: type: string enum: - CREDIT - DEBIT - UNKNOWN description: >- Specifies if the interchange fee amount is a credit or a debit for the cardholder. responses: eventBridgeResponseOk: description: Webhook successfully delivered. eventBridgeResponse429: description: Too many requests. Delivery would be retried. eventBridgeResponse5xx: description: Internal server error. Delivery would be retried. eventBridgeResponse4xx: description: >- Either server error or error with the client. Delivery would not be retried. ````