# Card authorisation

Notification that a card authorisation attempt has been performed
on a managed card. This is sent irrespective of the authorisation outcome
- the approved field indicates whether the authorisation has been approved or denied.

Endpoint: POST /managed_cards/authorisations/watch
Version: v2

## Header parameters:

  - `call-ref` (string)
    A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

  - `published-timestamp` (integer, required)
    The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

  - `signature-v2` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the call-ref + payload + published-timestamp using your API key.

  - `signature` (string, required)
    The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

## Request fields (application/json):

  - `id` (object, required)
    The id of the managed card on which an authorisation has been performed.

  - `id.id` (string, required)

  - `id.type` (string, required)
    Enum: "managed_cards", "managed_accounts"

  - `transactionId` (string, required)
    The id of the transaction, for reference.

  - `transactionAmount` (object, required)
    The amount in the currency of the card.

  - `transactionAmount.currency` (string, required)
    The currency expressed in ISO-4217 code. Example: GBP, EUR, USD.

  - `transactionAmount.amount` (string, required)
    The monetary amount, scaled to the lowest denomination of the currency.

  - `transactionTimestamp` (string, required)
    The timestamp of the transaction, using epoch timestamp with millisecond precision.

  - `sourceAmount` (object, required)
    The amount in the currency of the merchant.

  - `merchantData` (object, required)
    Merchant related information

  - `merchantData.merchantName` (string, required)
    The name of the merchant where the authorisation has been made.

  - `merchantData.merchantCategoryCode` (string, required)
    The merchant category code.

  - `merchantData.merchantId` (string, required)
    The merchant ID.

  - `merchantData.merchantDescription` (string)
    The merchant description

  - `merchantData.merchantStreet` (string)
    The merchant street address (if available)

  - `merchantData.merchantCity` (string)
    The merchant city (if available)

  - `merchantData.merchantState` (string)
    The merchant state address (if available)

  - `merchantData.merchantPostalCode` (string)
    The merchant postal code (if available)

  - `merchantData.merchantCountry` (string)
    The merchant country address

  - `merchantData.merchantTelephone` (string)
    The merchant telephone number

  - `merchantData.merchantURL` (string)
    The merchant URL

  - `merchantData.merchantNameOther` (string)
    The alternative merchant name

  - `merchantData.merchantNetworkId` (string)
    The merchant's network id

  - `merchantData.merchantContact` (string)
    The merchant's contact (if available)

  - `approved` (boolean)
    Indicates whether the authorisation has been approved or denied.

  - `availableBalance` (object)
    The updated card available balance after this authorisation was processed.

  - `declineReason` (string)
    An indication of why the authorisation was declined
    Enum: "NO_REASON", "PHYSICAL_NOT_ACTIVATED", "INSUFFICIENT_BALANCE", "CVV_CHECKS_FAILED", "CVV_RETRIES_EXCEEDED", "CARD_STATUS_NOT_ALLOWED", "PIN_CHECKS_FAILED", "PIN_RETRIES_EXCEEDED", "CARD_EXPIRY_CHECKS_FAILED", "AVS_CHECKS_FAILED", "ATM_WITHDRAWAL_LIMIT_EXCEEDED", "SCA_REQUIRED", "AUTH_RULE_CHECKS_FAILED", "TRANSACTION_NOT_PERMITTED", "TIMEOUT"

  - `authRuleFailedReason` (string)
    If the authorisation was declined due to auth rule checks, this indicates the auth rule that was violated.
    Enum: "NONE", "MERCHANT_CATEGORY_NOT_IN_ALLOWED_LIST", "MERCHANT_CATEGORY_BLOCKED", "MERCHANT_ID_NOT_IN_ALLOWED_LIST", "MERCHANT_ID_BLOCKED", "ATM_NOT_ALLOWED", "CONTACTLESS_NOT_ALLOWED", "ECOMMERCE_NOT_ALLOWED", "CASHBACK_NOT_ALLOWED", "CREDIT_AUTHORISATIONS_NOT_ALLOWED", "SPEND_LIMIT_EXCEEDED", "MERCHANT_COUNTRY_NOT_IN_ALLOWED_LIST", "MERCHANT_COUNTRY_BLOCKED", "MIN_TRANSACTION_AMOUNT_EXCEEDED", "MAX_TRANSACTION_AMOUNT_EXCEEDED", "AUTH_FORWARDING"

  - `authorisationType` (string, required)
    The type of authorisation that was processed.
    Enum: "AUTHORISED", "AUTHORISED_CREDIT", "DECLINED", "ONLINE_REVERSE", "EXPIRED", "MANUAL_CLOSE", "CANCELLED"

  - `authorisationCategory` (string)
    The category of the authorisation.
    Enum: "PRE_AUTH", "FINAL_AUTH"

  - `relatedAuthorisationIds` (array)
    The list of related authorisation ids which this authorisation is related to.

  - `owner` (object, required)

  - `cardholderPresent` (string)
    Optional detail indicating if the card holder was present when the authorisation occurred.
    Enum: "PRESENT", "NOT_PRESENT", "PRESENCE_UNKNOWN"

  - `cardPresent` (boolean)
    Optional detail indicating if the card was present when the authorisation occurred.

  - `details` (object)

  - `details.prepaidModeDetails` (object)

  - `details.debitModeDetails` (object)

  - `details.debitModeDetails.parentManagedAccountId` (string)
    Id of the managed account holding funds which the managed card can access, up to a configurable spend limit.

  - `details.debitModeDetails.availableToSpend` (array)
    The amount of funds from the parent managed account that are available to be spent through the card, in a given time interval, after this transaction was performed.

  - `details.debitModeDetails.availableToSpend.value` (object)
    The amount in the currency of the card.

  - `details.debitModeDetails.availableToSpend.value.amount` (integer, required)
    The monetary amount, scaled to the lowest denomination of the currency.

Example, an amount of 1000 for a EUR currency is actually 1000 Euro cents or EUR 10.00.

  - `details.debitModeDetails.availableToSpend.interval` (string)
    The time period for which the spendLimit is valid.
 - DAILY: starting from 00:00:00 UTC of current day to 23:59:59 UTC of current day
 - WEEKLY: 00:00:00 UTC Monday of current week to following Sunday 23:59:59 UTC
 - MONTHLY: 1st of current calendar month to end of current calendar month
 - QUARTERLY: starting from beginning of current quarter where quarters are defined as follows:
  - 1 January 00:00:00 UTC to 31 March 23:59:59 UTC
  - 1 April 00:00:00 UTC to 30 Jun 23:59:59 UTC
  - 1 July 00:00:00 UTC to 30 September 23:59:59 UTC
  - 1 October 00:00:00 UTC to 31 December 23:59:59 UTC

- YEARLY: 1 January 00:00:00 UTC of current calendar year to 31 December 23:59:59 UTC of current calendar year.
- ALWAYS: This indicates that the spendLimit is the total amount that can be spent through the card throughout the whole lifetime of the card.
    Enum: "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "YEARLY", "ALWAYS"

  - `details.debitModeDetails.availableToSpend.availableAmount` (string)
    The amount and currency that is available to spend, (for the given interval).

  - `authCode` (string)
    The authorisation code associated with this authorisation.

  - `forexPadding` (object)
    The forex padding amount, if any, that has been included in the transactionAmount.

  - `forexFee` (object)
    The forex fee, if any, that has been included in the transactionAmount.

  - `authForwardingDetails` (object)
    Contains information about the authorisations that have been forwarded.

  - `authForwardingDetails.authForwardingTriggered` (boolean)
    Indicates whether the authorisation forwarding was triggered or not.

  - `authForwardingDetails.authForwardingDecisionOutcome` (string)
    The default timeout decision outcome that was processed.
    Enum: "APPROVE", "DECLINE"

  - `authForwardingDetails.authForwardingInnovatorTimedOut` (boolean)
    Indicates whether the authorisation forwarding was timed out while expecting a response from the Innovator’s system.

  - `digitalWalletDetails` (object)
    Contains information about the digital wallet, if it has been used.

  - `digitalWalletDetails.digitalWalletType` (string)
    The digital wallet type.
    Enum: "GOOGLE_PAY", "APPLE_PAY", "MERCHANT_TOKEN"

  - `userCurrencyTransactionDetails` (object)
    The object representing the localised transaction's details

  - `userCurrencyTransactionDetails.userTransactionAmount` (object, required)
    The object representing a monetary amount in a particular currency.

  - `userCurrencyTransactionDetails.userExchangeRate` (string, required)

  - `relatedAuthorisationId` (string)
    The related authorisation id which this authorisation is performing further updates on.

  - `merchantCountryCode` (string)
    The merchant country code.


## Response 204 fields