> ## Documentation Index > Fetch the complete documentation index at: https://docs.enfuce.com/llms.txt > Use this file to discover all available pages before exploring further. # Outgoing authorisation control webhook endpoint > This is not an endpoint. This is the description of a request that is sent to issuers' decision-making systems ## OpenAPI ````yaml authorisation-control post /auth openapi: 3.0.3 info: title: Enfuce Authorisation Control description: >- Authorisation control gives the issuer the flexibility to create sophisticated rules for approving and declining transactions in real time. version: 1.0.0 servers: - url: http://localhost security: [] tags: - name: Authorisation Control Webhook paths: /auth: post: tags: - Authorisation Control Webhook summary: Outgoing authorisation control webhook endpoint description: >- This is not an endpoint. This is the description of a request that is sent to issuers' decision-making systems operationId: authPost requestBody: $ref: '#/components/requestBodies/authorisationRequestBodyV2' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorisationResponseV2' components: requestBodies: authorisationRequestBodyV2: required: true content: application/json: schema: $ref: '#/components/schemas/authorisationRequestV2' schemas: authorisationResponseV2: type: object required: - transactionData properties: transactionData: $ref: '#/components/schemas/responseTransactionData' authorisationRequestV2: type: object required: - metadata - customer - account - card - transactionData - merchantData properties: metadata: $ref: '#/components/schemas/metadata' customer: $ref: '#/components/schemas/customer' account: $ref: '#/components/schemas/account' card: $ref: '#/components/schemas/card' transactionData: $ref: '#/components/schemas/transactionData' merchantData: $ref: '#/components/schemas/merchantData' token: $ref: '#/components/schemas/token' responseTransactionData: required: - authResponseCode properties: authResponseCode: $ref: '#/components/schemas/responseAuthResponseCode' additionalAmountAccountType: type: string maxLength: 2 additionalAmountType: type: string maxLength: 2 additionalAmount: $ref: '#/components/schemas/money' partialApprovalAmount: $ref: '#/components/schemas/money' description: > Used when issuer does a partial approval. When the available balance is not sufficient considering the transaction amount, the issuer is expected to block whatever available balance there is and return the amount that can be authorised in the `partialApprovalAmount` field. Can only be used when `partialApprovalCapable` is `true` , i.e. the merchant approves that a smaller amount than the full transaction amount is authorised. availableBalance: $ref: '#/components/schemas/money' description: > Used for responses on BALANCE_INQUIRY requests when issuer keeps balance on their end. metadata: description: >- The metadata includes relevant message and authorisation ids and the message category that identifies the type of authorisation message. type: object required: - id - traceId - linkId - messageCategory properties: id: description: >- Unique id for authorisation message, but DECLINED_AUTH_ADVICE and APPROVED_AUTH_ADVICE has id of authorisation which they associated with but not unique. type: string maxLength: 18 traceId: description: > Unique random-generated id per http message. Can be used by receiver to confirm that no messages has been processed twice. type: string maxLength: 36 linkId: description: >- The link ID is a number linking all messages connected to the same purchase (authorisation, financial transaction, reversal) type: string maxLength: 18 messageCategory: $ref: '#/components/schemas/messageCategory' customer: description: > Data of the customer linked to the card with which the transaction is done with. Enables the issuer to identify to which customer the authorisation is related to. type: object required: - customerId properties: customerId: description: Unique ID of the customer that is linked to the card that is used. type: string maxLength: 18 account: description: > Data of the account linked to the card with which the transaction is done with. Enables the issuer to identify to which account the authorisation is related to. type: object required: - accountId - availableAmount properties: accountId: description: Unique ID of the account that is linked to the card that is used. type: string maxLength: 18 availableAmount: $ref: '#/components/schemas/money' description: > Available amount of the account that is linked to the card that is used. This amount does not consider possible spend controls. Note that this amount is only valid for setups where ledger is managed by Enfuce. If ledger is held by issuer, the amount in this field will be zero (0). The available amount is fetched mid-authorisation process. As the end to end authorisation process takes 0,5-3 sec, there can occur situations where another authorisation, API transaction or financial transaction is processed in parallel which is not reflected in the available. This is however extremely rare. The amount provided in this field can have a minus sign if the account is overlimit. card: description: > Data of the card with which the transaction is done with. Enables the issuer to identify to which card the authorisation is related to. type: object required: - cardId properties: cardId: description: Unique ID of the card. type: string maxLength: 18 expiration: $ref: '#/components/schemas/expiration' description: '' transactionData: description: >- Transaction specific data including amounts and fees, transaction type as well as information about the purchase conditions. type: object required: - transactionType - transactionAmount - cardEntryMode - cardholderPresent - merchantInitiated - cardholderVerifications - transactionFees properties: transactionType: $ref: '#/components/schemas/transactionType' transactionAmount: $ref: '#/components/schemas/money' description: > Transaction amount in the original transaction currency. The value provided in the amount field is always non-negative. settlementAmount: $ref: '#/components/schemas/money' description: > Transaction amount converted to card account currency (excluding mark-up). The value provided in the amount field is always non-negative. additionalAmountAccountType: type: string maxLength: 2 additionalAmountType: type: string maxLength: 2 additionalAmount: $ref: '#/components/schemas/money' replacementAmount: $ref: '#/components/schemas/money' description: > The amount **(in the settlement currency)** that the authorisation should be adjusted to in case a merchant makes a reversal. If a merchant makes a full reversal this field can be either missing or have a value of zero. If a merchant makes a partial reversal, this should be considered the actual amount that should be blocked. When a value is provided in this field, it is always positive. replacementTransAmount: $ref: '#/components/schemas/money' description: > The amount **(in the transaction currency)** that the authorisation should be adjusted to in case a merchant makes a reversal. If a merchant makes a full reversal this field can be either missing or have a value of zero. If a merchant makes a partial reversal, this should be considered the actual amount that should be blocked in transaction currency. When a value is provided in this field, it is always positive. transactionDateTime: description: > The local date (and time) when the transaction was made. I.e. the date/time in the time zone in which the payment terminal/merchant is. In date-time format YYYY-MM-DDThh:mm:ss. Please note that the authorisation formats used by card schemes do not support conveying the time zone in which the transaction has been done. The card scheme may also just include the date and no specific time. Enfuce relays the date and time as received from the card scheme. type: string format: date-time authResponseCode: $ref: '#/components/schemas/authResponseCode' description: > Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined cardEntryMode: $ref: '#/components/schemas/cardEntryMode' description: '' authValidityInDays: description: > Some merchants are allowed to request for a longer authorisation validity period than the default 7 days. When merchant has requested a longer validity period, this field indicates the amount of days the authorisation should be considered valid. This field is not present if no deviation from default has been requested. type: integer cardholderPresent: description: >- Indicates if cardholder has been physically present during transaction. type: boolean retrievalReferenceNumber: description: > Merchant/acquiring generated reference number for a purchase. Commonly used as the one of the main variables, in addition to cardId, to uniquely identify a transaction. Reference number is expected to remain the same for all messages during the transaction lifecycle (authorisation, clearing, reversals). This information can be used as one variable to match the authorisation message to purchase receipt data. type: string maxLength: 12 authCode: description: > Issuer generated code (6-digits) that is returned to the merchant if authorisation is approved. Commonly used as the one of the main variables, in addition to cardId, to uniquely identify a transaction. This information can be used as one variable to match the authorisation message to purchase receipt data. type: string maxLength: 6 merchantInitiated: description: > Indicates that transaction is recurring or merchant initiated. This implies that the cardholder has approved that the merchant initiates the transaction on a regular or frequent basis. type: boolean cardholderVerifications: description: > Describes what method was used to verify the cardholder. The verification methods are limited to verification methods that are considered as valid verification methods according to strong customer authentication principles. Possible values: * `WALLET` - cardholder has been verified with the digital wallet device. * `PIN` - cardholder has entered the correct PIN of the card to the payment terminal. * `BIO` - cardholder has successfully been verified through a biometric method (e.g. fingerprint reader on card). * `THREE_DS` - cardholder has successfully been verified through 3DS. type: array items: $ref: '#/components/schemas/cardholderVerificationType' transactionFees: description: > Transaction based fees that are additional fees charged on top of the transaction. Standard options are `MARKUP_FEE` for transactions done in non-domestic currency, `ATM_FEE` for ATM withdrawals and `CASH_FEE` for cash transactions. Fees are always presented with positive values in the amount field. `UNKNOWN` is a fallback value that is not expected but in case present represents another transaction based fee not covered by the above options. type: array items: $ref: '#/components/schemas/transactionFee' schemeTransactionLinkId: description: > A unique reference linking the original authorization to subsequent messages. For Visa customers this is the `Transaction Identifier` and for Mastercard customers this is the `Transaction Link ID`. type: string incremental: description: If it's set to true, this is an incremental transaction. type: boolean merchantData: description: >- Merchant specific data including acquirer data, merchant data and merchant category. type: object required: - merchantCategory - acquirerId - partialApprovalCapable properties: merchantId: description: > A code that uniquely identifies a particular card acceptor, i.e. a merchant or a bank. This information can be used as one variable to match the authorisation message to purchase receipt data. While merchantIds are not globally unique, they are expected to be unique per acquirer, so combining merchantId with acquirerId creates a unique identifier of a specific merchant. type: string maxLength: 15 subMerchantId: description: > The sub-merchant ID is used when merchant ID is not sufficient to identify the merchant. When a merchant uses a payment facilitator, the payment facilitator´s merchant id is transmitted and the merchant can be identified by the sub-merchant ID. This field is only required when merchant uses a payment facilitator. type: string maxLength: 15 merchantName: description: > Merchant name as conveyed from the card scheme (max 25 characters long). For ATMs this can be a street address or bank branch number. For money transfer transactions there can be the sender name or other transaction related data. type: string maxLength: 25 merchantCity: description: The city where the transaction or withdrawal occurs. type: string maxLength: 13 merchantCountry: $ref: '#/components/schemas/country' description: >- The country where the transaction or withdrawal occurs as a ISO-3166-1 alpha-3 country code. acquirerCountry: $ref: '#/components/schemas/country' description: > The country of the merchants acquirer as a ISO-3166-1 alpha-3 country code. This can be used to identify if transaction is in scope of PSD2 regulation. merchantCategory: $ref: '#/components/schemas/merchantCategory' description: '' acquirerId: description: > This code identifies the financial institution acting as the acquirer for the merchant. This information can be used as one variable to match the authorisation message to purchase receipt data. While merchantIds are not globally unique, they are expected to be unique per acquirer, so combining merchantId with acquirerId creates a unique identifier of a specific merchant. type: string maxLength: 11 terminalId: description: > A code that uniquely identifies a particular terminal at the merchant. This information can be used as one variable to match the authorisation message to purchase receipt data. type: string maxLength: 8 partialApprovalCapable: description: > Indicates if merchant will accept partial approval of amount. E.g. at a fuel pump the initial authorisation might be a predefined flat amount to which the issuer can respond an available amount smaller than the actual authorisation request. Note that this functionality is only available when card account balance resides at issuer. type: boolean token: description: > Data of the token with which the transaction is done with. Enables the issuer to identify if a token was used and what kind. type: object required: - tokenId - tokenNumber - tokenCategory - deviceType properties: tokenId: description: >- Enfuce generated token ID from the scheme provided message; mandatory for Mastercard and optional for Visa. Null sent if no ID could be generated. type: string maxLength: 18 tokenNumber: description: Scheme assigned token number. type: string maxLength: 20 tokenCategory: $ref: '#/components/schemas/tokenCategory' description: > Indicates which of the mobile digital wallet has been used. `UNKNOWN` can indicate that the card is tokenised at a merchant or another wallet. deviceType: $ref: '#/components/schemas/tokenDeviceType' description: > Used to convey information about the kind of device that has been used for the transaction. For instance: Phone, watch, tablet, wearable. responseAuthResponseCode: description: | Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined. Issuer can use the following response codes: * `00`: Approved * `1A`: Soft decline (Visa) * `03`: Invalid merchant * `04`: Card closed due to fraud * `05`: Do not honor (**Note**: Card schemes recommend to use this only when other options do not apply) * `5C`: Transaction not supported * `9G`: Blocked by cardholder / contact cardholder * `10`: Approved for partial amount (can only be used if `partialApprovalCapable` is `true` and ledger resides at issuer). Requires that issuer includes the `partialApprovalAmount` * `41`: Lost card * `43`: Stolen card * `46`: Card account closed * `51`: Not sufficient funds * `57`: Transaction not permitted to cardholder * `58`: Transaction not allowed to terminal * `59`: Fraud suspected * `61`: Exceeds approval amount limit * `62`: Restricted card (card invalid in region or country) * `65`: Exceeds withdrawal frequency limit * `78`: Record not found * `91`: Issuer unresponsive * `93`: Transaction cannot be completed * `96`: System malfunction type: object required: - code properties: code: description: > Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined. type: string maxLength: 2 example: '00' money: description: Amount including currency type: object required: - amount - currency properties: amount: type: number example: 3.14 currency: $ref: '#/components/schemas/currency' messageCategory: description: | Identifies the type of authorisation message: * `REQUEST` - requires a decision in the form of an approval or decline. The transaction type indicates if it is a crediting or debiting transaction. * `REVERSAL_ADVICE` - requires a previously done authorisation to be reversed either fully or partially. Does not require a response from the issuer. The linkId can be used to identify the original authorisation request to be reversed. `replacementAmount` and `replacementTransAmount` indicate relevant amounts for partial reversals. * `SCHEME_ADVICE` - This message category is sent when the authorisation has been processed by the card scheme. Typically, this occurs when the issuer is unresponsive or experiencing a technical outage. In such cases, since the issuer is unable to process the payment, the card scheme steps in to process it on the issuer's behalf. This process is known as Stand-In Processing (STIP). This can result in either an approved or declined advice. The response code indicates whether the advice was approved or declined. If the response code is 0, 10 or 85 the advice was approved, and the balance should be adjusted accordingly. If the response code is not 0, 10 or 85, the advice was declined, and the balance should remain unchanged. No further response from the issuer is required. * `ADJUSTMENT` - adjustment of the settlementAmount of a previously made authorisation. Mainly used by automated fuel dispensers and EV chargiong stations to adjust the amount after fueling/charging has ended. Issuer is expected to adjust the settlementAmount of the initial authorisation request, to the settlementAmount of the adjustment. Does not require a response from the issuer. * `DECLINED_AUTH_ADVICE` - this message category is only available for issuers that do fraud monitoring. It indicates that authorisation has been declined during a validation step at Enfuce. For issuers that do fraud monitoring themselves, these messages could e.g. be authorisation attempts with incorrect PAN (card number) which could indicate an ongoing BIN attack. * `APPROVED_AUTH_ADVICE` - this message category is only available for issuers that do fraud monitoring. It indicates that authorisation has been approved. For issuers that do fraud monitoring themselves, these messages might be interesting. type: string enum: - REQUEST - ADJUSTMENT - SCHEME_ADVICE - REVERSAL_ADVICE - DECLINED_AUTH_ADVICE - APPROVED_AUTH_ADVICE - ENFUCE_STIP_DECLINED_AUTH_ADVICE - ENFUCE_STIP_APPROVED_AUTH_ADVICE expiration: type: object properties: year: type: integer format: int32 description: Expiration year in format YYYY example: 2019 month: type: integer format: int32 description: Expiration month in format MM example: 1 title: expiration transactionType: description: The transaction type. type: string enum: - RETAIL - ATM - UNIQUE - CASH - CREDIT - BALANCE_INQUIRY - J3_ELIGIBILITY_INQUIRY - P2P_DEBIT - P2P_CREDIT - RETAIL_REVERSAL - ATM_REVERSAL - UNIQUE_REVERSAL - CASH_REVERSAL - CREDIT_REVERSAL - P2P_CREDIT_REVERSAL - P2P_DEBIT_REVERSAL - RETAIL_WITH_CASHBACK - RETAIL_WITH_CASHBACK_REVERSAL - CARDHOLDER_CREDIT - CARDHOLDER_CREDIT_REVERSAL - CASH_DISPENSE - CASH_DISPENSE_REVERSAL authResponseCode: description: > Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined. type: object required: - code properties: code: description: > Response to the authorisation. Indicates to the merchant if the authorisation was approved or declined. type: string maxLength: 2 example: '00' cardEntryMode: description: | Describes how the card credentials were captured. Possible values: * `UNKNOWN` - the message from the merchant did not include a distinct method. * `MANUAL_ENTRY` - the card credentials were manually entered by the merchant. * `MAGNETIC_STRIPE_READ` - the magnetic stripe of the card was read by a terminal. * `CHIP_READ` - the EMV chip of the card was read by a terminal * `CONTACTLESS` - contactless transactions, i.e. the card credentials were read with near field communication (NFC) either from chip or digital wallet. * `ELECTRONIC_COMMERCE` - the cardholder entered the card credentials as an e-com merchant. type: string enum: - UNKNOWN - MANUAL_ENTRY - MAGNETIC_STRIPE_READ - CHIP_READ - CONTACTLESS - ELECTRONIC_COMMERCE cardholderVerificationType: description: Cardholder verification type type: string enum: - WALLET - PIN - BIO - THREE_DS transactionFee: type: object required: - feeType - feeAmount properties: feeType: $ref: '#/components/schemas/feeType' description: Fee Type feeAmount: $ref: '#/components/schemas/money' country: type: string description: >- A valid ISO 3166-1 alpha-3 country code, except for QZZ (UNMIK in Kosovo) and ROM for Romania. pattern: '[A-Z]{3}' example: FIN merchantCategory: description: '' type: object required: - code - codeDescription - group properties: code: description: > Merchant category code as per card scheme classification. Merchants classification is done based on the type of business or service they sell. type: string maxLength: 4 example: '5734' codeDescription: description: '' type: string maxLength: 255 group: $ref: '#/components/schemas/merchantCategoryGroup' description: '' tokenCategory: description: Indicates which digital wallet has been used or if it is an ecom token. type: string enum: - APPLE_PAY - GOOGLE_PAY - SAMSUNG_PAY - UNKNOWN tokenDeviceType: description: type of device which is used for payment type: string enum: - UNKNOWN_DEVICE - MOBILE_PHONE - TABLET - WATCH - ANDROID_DEVICE - ENTERTAINMENT_DEVICE - HOUSEHOLD_DEVICE - WEARABLE - VEHICLE - E_COMMERCE currency: type: string description: A valid ISO 4217 currency code pattern: '[A-Z]{3}' example: EUR feeType: description: > * `MARKUP_FEE` - fee for transactions done in non-domestic currency. * `ATM_FEE` - fee for ATM withdrawals. * `CASH_FEE` - fee for cash transactions. * `UNKNOWN` - is a fallback value that is not expected but in case present represents another transaction based fee not covered by the above options. type: string enum: - MARKUP_FEE - ATM_FEE - CASH_FEE - UNKNOWN merchantCategoryGroup: description: '' type: string enum: - CASH - ATM - LODGING - RESTAURANT - SCHOOL - RETAIL - VEHICLE_RENTAL - PAYMENT_SERVICES - TRANSPORTATION - UNIQUE ````