---
title: "authenticate"
method: POST
path: "/v1/Payment/authenticate/json"
tags: ["Card Payments"]
---

# authenticate

`POST /v1/Payment/authenticate/json`

## Request

- Base URL: `https://payment.pay.nl`
- URL: `https://payment.pay.nl/v1/Payment/authenticate/json`
- Auth: HTTP basic

API handles the calls for starting and authenticating the transaction in one go. The merchant calls this API with the same
parameters as the Transaction Start V16 with the necessary card data appended to it. For existing transactions the orderId
and entranceCode can be passed on instead of the transaction details.

Note: this API will try to process the transaction based upon the settings for the service. This can result in an 3DS challenge,
for which the necessary data will be returned. The payload of the challenge must be sent to the Authorization API.

In case of an SCA Exempted (Low-value-payment) or frictionless transaction the authorization will be handled in this request.

## Request body

- Authenticate
  - `transaction` Transaction, required
    - `type` 'POS' | 'CIT' | 'MIT' | 'MOTO' | 'ECOM', required: Defines the type of the transaction. Possible values are: `CIT` = Customer initiated simple e-com transaction, `MIT` = Merchant initiated transaction, `MOTO` = Customer initiated payment where card number entered manually, `POS` = Point of sale, `ECOM`
    - `serviceId` Id, required (unresolved $ref)
    - `description` string: The description of the transaction.
    - `reference` string: The merchants reference for the transaction, eg. an order number or invoice id.
    - `amount` integer, required: The amount in cents.
    - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `ipAddress` string, required: An ip address
    - `language` string: The language code consisting of 2 uppercase letters.
    - `exchangeUrl` string, uri: The URL of the exchange that needs to be called.
    - `expireDate` number: Timestamp of the date the transaction should expire.
  - `options` Options
    - `tokenization` -1 | 0 | 1: Include the `tokenize` option in the options array and set the value to override the default settings for this payment. Possible values are: `-1` = disable, `1` = enable or `0` = use default.
  - `payment` PaymentAuthenticate, required: Afhankelijk van de keuze voor CSE of CARD, kies hier de bijbehorende data
    - `method` 'cse' | 'card' | 'token', required: Defines the method in which the card details are submitted. Choose CSE when submitting the details in `cse` format, `card` when submitting plain card data. Note: the corresponding array must be included in the request.
    - `cse` Cse
      - `data` string, required: The encrypted card details, base64 encoded. See the `card` option for the fields that should be part of the encrypted card data.
      - `identifier` string, required: ID of the public key that is used to encrypt the card details.
    - `card` Card
      - `number` string, required: The customer's card number
      - `expire_month` string, required: Expire month of the card in MM format (2 digits).
      - `expire_year` string, required: Year the card expires in YY format (2 digits).
      - `cvc` string: Card verification code / safekey code of the card used
      - `name` string, required: The name of the customer as printed on his/her card
    - `token` Token
      - `id` string, required
    - `browser` Browser
      - `javaEnabled` 'true' | 'false', required: Indicator that represents the ability of the cardholder browser to execute Java.
      - `javascriptEnabled` 'true' | 'false', required: Indicator that represents the ability of the cardholder browser to execute Javascript.
      - `language` string, required: Value representing the browser language as defined in IETF BCP47.
      - `colorDepth` 1 | 4 | 8 | 15 | 16 | 24 | 32 | 48, required: Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Possible values: `1` = 1 bit, `4` = 4 bits, `8` = 8 bits, `15` = 15 bits, `16` = 16 bits, `24` = 24 bits, `32` = 32 bits, `48` = 48 bits
      - `screenHeight` number, required: Total height of the Cardholder’s screen in pixels.
      - `screenWidth` number, required: Total width of the cardholder’s screen in pixels.
      - `tz` number, required: Time difference between UTC time and the Cardholder browser local time, in minutes.
    - `auth` object
      - `payTdsTransactionId` string: The identifier of the 3DS2 authentication session
      - `acquirerID` string: The identifier of the 3DS2 authentication session
  - `stats` Stats
    - `info` string: The used info code which can be tracked in the stats.
    - `tool` string: The used tool code which can be tracked in the stats.
    - `object` string: The object which can be tracked in stats.
    - `extra1` string: The first free value which can be tracked in the stats.
    - `extra2` string: The second free value which can be tracked in the stats.
    - `extra3` string: The third free value which can be tracked in the stats.
  - `customer` Customer
    - `reference` string: The reference for the customer, eg. a customer ID or account identification number.
    - `trust` integer: Indicates whether you trust the customer, scale -10 -> 10 (10 Reliable, -10 Unreliable).
    - `firstName` string: The forename (also known as a given name, Christian name or a first name).
    - `lastName` string: The surname (also known as a family name or a last name).
    - `gender` 'M' | 'F' | 'X': The subject's gender. Choose either M for male or F for female.
    - `dob` string, date: Date of birth.
    - `phoneNumber` string: The subject's phone number.
    - `emailAddress` string, email: An email address.
    - `company` Company
      - `name` string: Name of the company when processing a business order.
      - `cocNumber` string: The Chamber of commerce registration number of the business for which this payment is processed. This format differs per country.
      - `vatNumber` string: VAT number of the business for which this payment is processed.
    - `address` Address
      - `streetName` string: The name of the street.
      - `streetNumber` string: The street number.
      - `streetNumberExtension` string: A house number extension is required to deal with apartments or other addresses sharing the same front door.
      - `zipCode` string: A zip/postal code. see https://en.wikipedia.org/wiki/List_of_postal_codes for a list of formats per country.
      - `city` string: The name of a city.
      - `regionCode` string: Region code (iso-3166-2).
      - `countryCode` string: The country code consisting of 2 uppercase letters.
    - `invoice` Invoice
      - `firstName` FirstName (unresolved $ref)
      - `lastName` LastName (unresolved $ref)
      - `gender` Gender (unresolved $ref)
      - `company` Company
        - `name` string: Name of the company when processing a business order.
        - `cocNumber` string: The Chamber of commerce registration number of the business for which this payment is processed. This format differs per country.
        - `vatNumber` string: VAT number of the business for which this payment is processed.
      - `address` Address
        - `streetName` string: The name of the street.
        - `streetNumber` string: The street number.
        - `streetNumberExtension` string: A house number extension is required to deal with apartments or other addresses sharing the same front door.
        - `zipCode` string: A zip/postal code. see https://en.wikipedia.org/wiki/List_of_postal_codes for a list of formats per country.
        - `city` string: The name of a city.
        - `regionCode` string: Region code (iso-3166-2).
        - `countryCode` string: The country code consisting of 2 uppercase letters.
  - `order` Order
    - `deliveryDate` string, date: The date of delivery.
    - `invoiceDate` string, date: The date of the invoice
    - `products` Product[]
      - `id` string: The product identifier.
      - `type` 'shipping' | 'article' | 'discount' | 'rounding' | 'handling' | 'payment' | 'credit' | 'giftcard' | 'emoney' | 'crypto': The type of product.
      - `description` string: The description of the product.
      - `amount` number, float: The amount in cents.
      - `quantity` number, float: The quantity.
      - `vatPercentage` number, float

## Response `200`

Successful operation

- AuthenticateResponse
  - `request` RequestResponse
    - `result` integer: Indicates whether the request was successfully processed (`1`) or some error has occurred (`0`).
    - `errorId` string: If the request was not successfully processed this parameter holds the ID of the error that has occurred.
    - `errorTag` string: The error tag can be used to generate an error response for the customer.
    - `errorMessage` string: Description of the error that occurred. This message is returned in the language (if available) in which the transaction is/was submitted.
  - `payment` PaymentResponse
    - `bankCode` string: Response code returned from the issuer indicating the outcome of the authorization.
    - `bankMessage` string: Description of the response code.
    - `approvalCode` string
    - `schemeTransactionId` string
    - `cvcCheck` string
    - `threeDs` string
    - `avsResult` string
  - `transaction` TransactionResponse
    - `transactionId` string: The Id of the transaction.
    - `orderId` string: The orderId of the transaction.
    - `entranceCode` string: The orderId of the transaction.
    - `paymentProfileId` integer: The payment profile identifier.
    - `state` integer
    - `stateName` string
    - `amount` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `created` number
    - `identifierName` string
    - `identifierPublic` string
    - `identifierHash` string
    - `startIpAddress` string
    - `completedIpAddress` string
    - `orderNumber` string: The merchants reference for the transaction, eg. an order number or invoice id.
    - `amountOriginal` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `amountPaidOriginal` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `amountPaid` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `amountRefundOriginal` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF
    - `amountRefund` MonetaryAmount
      - `amount` integer: The amount in cents.
      - `currency` string: The currency in ISO-4217 format, e.g.: EUR, USD, CHF

## Other responses

- `400`: Bad request. See response for details.
- `401`: Unauthorized.
- `403`: Forbidden.
- `404`: Not found.

---

[API](https://skmtc.dev/pay/apis/pay-card-payment-api-v1-2-3.md) - [All operations](https://skmtc.dev/pay/apis/pay-card-payment-api-v1-2-3/llms.txt) - [OpenAPI document](https://skmtc.dev/pay/apis/pay-card-payment-api-v1-2-3/revisions/07c50a8d28b1?raw)