# Simulate card purchase using card number

Simulate card purchases. Provide card details and transaction amount and the transaction will be processed through the system.

Endpoint: POST /cards/purchase
Version: v2
Security: API_Secret_Key

## 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

## Request fields (application/json):

  - `cardNumber` (string, required)
    The 16-digit card number.

  - `cvv` (string, required)
    The 3-digit cvv

  - `expiryDate` (string, required)
    The expiry date in format MMYY

  - `merchantName` (string, required)
    The merchant name

  - `merchantId` (string)
    The merchant id (MID). If not specified, a random value will be used

  - `merchantCategoryCode` (string)
    The merchant category code (MCC). If unspecified or an invalid MCC is specified, the Merchant Code 5399 (Misc. General Merchandise) will be used instead

  - `transactionAmount` (object, required)
    A message representing a monetary amount in a particular currency.

  - `transactionAmount.currency` (string, required)
    The currency ISO-4217 code, i.e. a three letter uppercase code, such as GBP, EUR, USD.

  - `transactionAmount.amount` (integer)
    The monetary amount, scaled to the lowest denomination of the currency. For example, an amount of 1000 for a EUR currency is actually 1000 Euro cents, i.e. EUR 10.00.

  - `atmWithdrawal` (boolean)
    If set to true, this purchase simulates and ATM Withdrawal transaction. MCC will automatically be set to 6011

  - `additionalMerchantData` (object)
    Additional merchant data

  - `additionalMerchantData.merchantStreet` (string)

  - `additionalMerchantData.merchantCity` (string)

  - `additionalMerchantData.merchantState` (string)

  - `additionalMerchantData.merchantPostalCode` (string)

  - `additionalMerchantData.merchantCountry` (string)

  - `additionalMerchantData.merchantTelephone` (string)

  - `additionalMerchantData.merchantURL` (string)

  - `additionalMerchantData.merchantNameOther` (string)

  - `additionalMerchantData.merchantNetworkId` (string)

  - `additionalMerchantData.merchantContact` (string)

  - `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.

  - `initiateBiometricThreeDSecure` (boolean)
    If the card is enrolled for Biometric Authentication, a 3DS Flow is initiated before the Purchase can resume.

  - `transactionTimestamp` (integer)
    Epoch timestamp using millisecond precision.

  - `forexFee` (integer)
    If this is a cross-currency transaction, the forex fee amount in the card currency. Deprecated; the forex fee percentage configured at the card profile will be applied if this field is not provided

  - `forexPadding` (integer)
    If this is a cross-currency transaction, the forex padding amount in the card currency. Deprecated; a 2% forex padding will be applied if this field is not provided. Deprecated; a 2% forex padding will be applied if this field is not provided

## Response 200 fields (application/json):

  - `code` (string)
    Enum: "APPROVED", "DENIED_NOT_ENOUGH_FUNDS", "DENIED_CARD_NOT_FOUND", "DENIED_INCORRECT_CVV", "DENIED_CARD_EXPIRY", "DENIED_AMOUNT_NOT_POSITIVE", "DENIED_CARD_INACTIVE", "DENIED_OTHER", "DENIED_SPEND_CONTROL", "PENDING_BIOMETRIC_THREEDS_VERIFICATION", "CARD_NOT_ENROLLED_FOR_BIOMETRIC_THREEDS"

  - `threeDSecureChallengeId` (object)

  - `threeDSecureChallengeId.value` (integer)
    If value is 0, set has_value to true

  - `threeDSecureChallengeId.hasValue` (boolean)
    If value is default (0) then true indicates 0 while false indicates null

## Response 400 fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.

  - `validation` (object)
    Description of fields which were invalid.

  - `validation.invalid` (boolean)

  - `validation.fields` (array)

  - `validation.fields.name` (string)

  - `validation.fields.errors` (array)

  - `validation.fields.errors.type` (string)
    Enum: "REQUIRED", "HAS_TEXT", "REQUIRES", "SIZE", "RANGE", "IN", "NOT_IN", "REGEX", "EXACTLY", "AT_LEAST", "AT_MOST", "ALL_OR_NONE"

  - `validation.fields.errors.params` (array)

## Response default fields (application/json):

  - `message` (string)
    When present helps to identify and fix the problem.