---
title: "Authenticate a transaction"
method: POST
path: "/authenticate"
---

# Authenticate a transaction

`POST /authenticate`

## Request

- Base URL: `https://gateway.pmnts-sandbox.io/v1.0`
- URL: `https://gateway.pmnts-sandbox.io/v1.0/authenticate`
- Auth: HTTP basic

This API is used to authenticate a transaction. The first step is to call this API with sca.type = "enrollment" to check whether the transaction is frictionless or needs further challenge. After a successful challenge, this API should be called with sca.type = "validation" which will return 3DS2/SCA fields.

## Headers

- `Content-Type` string

## Request body

- object
  - `card_token` string, required
  - `amount` integer, required: A positive integer representing how much to charge, in the smallest currency unit (eg., 100 to charge $1.00, or 100 to Charge ¥100, a zero decimal currency)
  - `currency` string, required: Three letter [ISO currency code](https://pmnts.readme.io/docs/iso-currency-codes), in UPPERCASE
  - `customer_ip` string: RFC791-compliant IP address
  - `sca` object
    - `type` string, required: The authentication type: enrollment, validation
    - `merchant_reference_code` string, required: Merchant order reference
    - `customer` object, required: Details about the customer
      - `address_1` string, required: The customer's primary address line
      - `address_2` string: The customer's secondary address line (such as building name)
      - `city` string, required: The customer's city
      - `state` string, required: The customer's state
      - `country` string, required: The ISO 3166 alpha-2 country code for the customer
      - `email` string, required: The customer's email address
      - `first_name` string, required: The customer's first name
      - `last_name` string, required: The customer's last name
      - `post_code` string, required: The customer's post code
      - `passport_number` string: The customer's passport number
      - `passport_country` string: The ISO 3166 numeric passport country
      - `account_changed_at` string: Date the cardholder’s account was last changed (format: YYYYMMDD)
      - `account_created_at` string: Date the cardholder opened the account (format: YYYYMMDD)
      - `account_password_changed_at` string: Date the cardholder last changed or reset password on account (format: YYYYMMDD)
    - `shipping_address` object: Details about the shipping
      - `address_1` string: The shipping address primary address line
      - `address_2` string: The shipping address secondary address line
      - `city` string: The shipping address city or suburb
      - `state` string: The shipping address state
      - `country` string: The ISO 3166 alpha-2 country code for the shipping
      - `email` string: The shipping email address
      - `first_name` string: The shipping address first name
      - `last_name` string: The shipping address last name
      - `home_phone` string: The shipping phone number
      - `post_code` string: The shipping post code
      - `method` string: The shipping method for the product
      - `destination_code` string: The destination chosen for the transaction
    - `custom` object: Custom data for the SCA. Please discuss using these fields with Support should you require assistance. x may be numerical or a string.
      - `transaction_mode` string, required: Transaction mode identifier: moto, mobile, retail, computer, tablet
      - `reference_id` string, required: Reference ID that corresponds to the device fingerprinting data that was collected previously
      - `merchant_name` string: Your company’s name as you want it to appear to the customer in the issuing bank’s authentication form
      - `merchant_new_customer` boolean: Indicates whether the consumer is a new or existing customer with the merchant
      - `preorder` integer: Indicates whether cardholder is placing an order with a future availability or release date: 0 (Merchandise available), 1 (Future availability)
      - `http_accept` string: Value of the Accept header sent by the customer’s web browser
      - `http_user_agent` string: Value of the User-Agent header sent by the customer’s web browser
      - `http_user_accept` string: The exact content of the HTTP accept header
      - `recurring_end_date` string: The date after which no further recurring authorizations should be performed (format: YYYYMMDD)
      - `recurring_frequency` integer: Integer value indicating the minimum number of days between recurring authorizations. A frequency of monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months.
      - `recurring_original_purchase_date` string: Date of original purchase (format: YYYYMMDDHH:MM:SS)
    - `items` object[]: Details about purchased items
      - `unit_price` number, float: Price of the product
      - `product_description` string: Brief description of item
      - `product_name` string: Name of the product
      - `quantity` integer: Quantity of the product being purchased. The default value is 1.
      - `product_sku` string: Merchant’s product identifier code
      - `passenger_first_name` string: Passenger's first name
      - `passenger_last_name` string: Passenger's last name
    - `airline_data` object: Details about the airline data
      - `number_of_passengers` integer: Number of passengers for whom the ticket was issued. The default value is 1 if no value is provided.
      - `passengers` object[]: Details about passengers
        - `first_name` string: passenger's first name
        - `last_name` string: Passenger's last name
      - `legs` object[]
        - `carrier_code` string: International Air Transport Association (IATA) code for the carrier for this leg of the trip. Required for each leg.
        - `departure_date` string: Departure date for the first leg of the trip (format: YYYYMMDD)
        - `destination` string: International Air Transport Association (IATA) code for the destination airport for this leg of the trip. Required for each leg.
        - `originating_airport_code` string: International Air Transport Association (IATA) code for the originating airport for the first leg of the trip.

## Response `200`

200

- union
  - object
    - `successful` boolean
    - `response` object
      - `action` object
        - `proceed` boolean
        - `challenge` boolean
        - `frictionless` boolean
        - `bypass` boolean
      - `version` string
      - `enrolled` string
      - `acs_url` string
      - `pareq` unknown
      - `pares` string
      - `xid` string
      - `eci` string
      - `cavv` string
      - `aav` unknown
      - `ucaf_collection_indicator` unknown
      - `authentication_path` unknown
      - `authentication_result` string
      - `authentication_transaction_id` string
      - `authentication_status_message` string
      - `card_bin` string
      - `card_type_name` string
      - `commerce_indicator` string
      - `proxy_pan` unknown
      - `currency` unknown
      - `request_id` string
      - `request_token` string
      - `decision` string
    - `errors` unknown[]
      - unknown
    - `test` boolean
  - object
    - `successful` boolean
    - `response` object
      - `action` object
        - `proceed` boolean
        - `challenge` boolean
        - `frictionless` boolean
        - `bypass` boolean
      - `version` string
      - `enrolled` string
      - `acs_url` string
      - `pareq` string
      - `pares` unknown
      - `xid` unknown
      - `eci` unknown
      - `cavv` unknown
      - `aav` unknown
      - `ucaf_collection_indicator` unknown
      - `authentication_path` unknown
      - `authentication_result` unknown
      - `authentication_transaction_id` string
      - `authentication_status_message` unknown
      - `card_bin` string
      - `card_type_name` string
      - `commerce_indicator` unknown
      - `proxy_pan` unknown
      - `currency` unknown
      - `request_id` string
      - `request_token` string
      - `decision` string
    - `errors` unknown[]
      - unknown
    - `test` boolean
  - object
    - `successful` boolean
    - `response` object
      - `action` object
        - `proceed` boolean
      - `version` string
      - `enrolled` unknown
      - `acs_url` string
      - `pareq` unknown
      - `pares` string
      - `xid` string
      - `eci` string
      - `cavv` string
      - `aav` unknown
      - `ucaf_collection_indicator` unknown
      - `authentication_path` unknown
      - `authentication_result` string
      - `authentication_transaction_id` unknown
      - `authentication_status_message` string
      - `card_bin` string
      - `card_type_name` string
      - `commerce_indicator` string
      - `proxy_pan` unknown
      - `currency` unknown
      - `request_id` string
      - `request_token` string
      - `decision` string
    - `errors` unknown[]
      - unknown
    - `test` boolean
  - object
    - `successful` boolean
    - `response` object
    - `errors` string[]
    - `test` boolean
  - object
    - `successful` boolean
    - `response` object
    - `errors` string[]
    - `test` boolean

## Changes

- **2026-11-03** `a62ddbae3800`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/fatzebra/apis/gateway/changes/authenticate/post.md)

---

[API](https://skmtc.dev/fatzebra/apis/gateway.md) - [All operations](https://skmtc.dev/fatzebra/apis/gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/fatzebra/apis/gateway/revisions/a62ddbae3800?raw)