> ## 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. # Authorisation Request API > Enfuce sends an authorisation request to the issuer/ledger, when it expects an authorisation decision from the recipient. ## OpenAPI ````yaml json-files/authorisation-control-v1.openapi.json post /auth openapi: 3.0.3 info: title: Enfuce Authorisation Request API description: >- Authorisation Request API gives the issuer/ledger the flexibility to create sophisticated rules for approving and declining transactions in real time. version: 1.0.0 servers: - url: https://api.{{tenant}}.ext-uat1-sandbox.mycore.enfuce.com/processor description: UAT Sandbox - url: https://api.{{tenant}}.eu.live.prod.mycore.enfuce.com/processor description: Production security: [] tags: - name: Authorisation Request API paths: /auth: post: tags: - Authorisation Request API summary: Authorisation Request API description: >- Enfuce sends an authorisation request to the issuer/ledger, when it expects an authorisation decision from the recipient. operationId: authPost requestBody: $ref: '#/components/requestBodies/authRequestBody' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authResponseBody' components: requestBodies: authRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/authRequestBody' schemas: authResponseBody: type: object required: - authResponseCode properties: authResponseCode: $ref: '#/components/schemas/authResponseCode' account: $ref: '#/components/schemas/account' partialApprovalAmount: allOf: - $ref: '#/components/schemas/money' description: > Return when there is a partial approval. When the balance is less than the transaction amount, return the available amount that you authorise. Return this attribute only when in the request `merchant.partialApprovalCapable` is true (i.e. the merchant approves that a smaller amount than the full transaction amount is authorised), and `authResponseCode` should be `PARTIALLY_APPROVED`. title: money authRequestBody: allOf: - $ref: '#/components/schemas/authorizationMetadata' - type: object required: - card - merchant - transaction properties: token: $ref: '#/components/schemas/token' card: $ref: '#/components/schemas/card' merchant: $ref: '#/components/schemas/merchant' transaction: allOf: - $ref: '#/components/schemas/approvedTransaction' title: transaction authResponseCode: type: string format: enum enum: - APPROVED - PARTIALLY_APPROVED - DO_NOT_HONOR - NOT_SUFFICIENT_FUNDS - NOT_PERMITTED - EXCEEDS_AMOUNT_LIMIT - RESTRICTED_CARD - EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT - SYSTEM_ERROR description: | Indicates whether the authorisation request is approved or declined. Possible enums: * `APPROVED` - Approved * `PARTIALLY_APPROVED` - Approved for partial amount * `DO_NOT_HONOR` - Do not honor (**Note**: Card schemes recommend to use this only when other options do not apply) * `NOT_SUFFICIENT_FUNDS` - Inadequate funds * `NOT_PERMITTED` - Transaction not permitted to cardholder * `EXCEEDS_AMOUNT_LIMIT` - Exceeds approval amount limit * `RESTRICTED_CARD` - Restricted card (card invalid in region or country) * `EXCEEDS_WITHDRAWAL_FREQUENCY_LIMIT` - Exceeds withdrawal frequency limit * `SYSTEM_ERROR` - System malfunction account: type: object required: - availableAmount properties: availableAmount: allOf: - $ref: '#/components/schemas/money' description: Available amount before this transaction has been processed. title: money money: description: Amount including currency. type: object required: - amount - currency properties: amount: type: number example: 3.14 currency: $ref: '#/components/schemas/currency' authorizationMetadata: type: object properties: id: $ref: '#/components/schemas/id' transactionId: $ref: '#/components/schemas/transactionId' messageCategory: allOf: - $ref: '#/components/schemas/messageCategoryAuthorization' title: messageCategory messageFunction: allOf: - $ref: '#/components/schemas/messageFunctionAuthorization' title: messageFunction 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 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. currency: type: string description: A valid ISO 4217 currency code pattern: '[A-Z]{3}' example: EUR 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`. messageCategoryAuthorization: type: string format: enum description: > Message category sent in the authorisation control webhook. Possible enums: - INITIAL_AUTHORIZATION: Initial authorisation of the card payment. - INCREMENTAL_AUTHORIZATION: Additional authorisation for 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. enum: - INITIAL_AUTHORIZATION - INCREMENTAL_AUTHORIZATION - BALANCE_INQUIRY - PIN_MANAGEMENT messageFunctionAuthorization: type: string format: enum description: Identifies the message function of the authorisation request. enum: - REQUEST 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 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 ````