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

# authenticate

`POST /v1/Payment/authenticate/json`

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
    - `id` string — The Id of the transaction.
    - `serviceId` Id, required — unresolved $ref
    - `description` string — Is shown on the statement of the payer.
    - `reference` string — The merchant identification of this transaction. This field only allows alphanumeric characters
    - `manualTransferCode` string — Payment reference used to identify manual bank transfers
    - `orderId` string — The orderId of the transaction.
    - `ipAddress` string — An ip address
    - `exchangeUrl` string, uri — The URL where we exchange the status of a transaction.
    - `returnUrl` string, uri, required — The URL where the payer has to be send to after the payment.
    - `paymentUrl` string, uri — The payment URL for this transaction
    - `amount` Amount, required
      - `value` integer, required — The amount in cents.
      - `currency` string — The currency in ISO-4217 format.
    - `expire` string, date-time — Expire date in the correct ISO-8601 (a.k.a. ATOM) notation.
    - `created` string, date-time — The date at which this entity was created presented in the correct ISO-8601 (a.k.a. ATOM) notation.
    - `modified` string, date-time — The date at which this entity was modified presented in the correct ISO-8601 (a.k.a. ATOM) notation.
    - `amountConverted` Amount
      - `value` integer, required — The amount in cents.
      - `currency` string — The currency in ISO-4217 format.
    - `amountPaid` Amount
      - `value` integer, required — The amount in cents.
      - `currency` string — The currency in ISO-4217 format.
    - `amountRefunded` Amount
      - `value` integer, required — The amount in cents.
      - `currency` string — The currency in ISO-4217 format.
    - `paymentMethod` PaymentMethod
      - `id` integer, required — The ID of the payment option e.g. iDEAL is 10. See: services/get/sl-xxxx-xxx.
      - `subId` string — The chosen sub ID of the payment option e.g. The bank id for iDEAL. See: services/get/sl-xxxx-xxx.
      - `name` string — The name of the payment method.
      - `terminalCode` string — The terminalCode of the payment terminal used for in-store transactions.
    - `status` Status
      - `code` integer — The status code.
      - `action` string — The state in which the transaction resides
      - `phase` string — The current phase in the transaction state
    - `integration` Integration
      - `testMode` boolean — Indicates if the service is in testmode or not, possible values: false or true
    - `customer` Customer
      - `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).
      - `type` 'B' | 'C' — Either B for business or C for consumer.
      - `ip` string — An ip address
      - `birthDate` string, date — Date of birth as defined in ISO-8601.
      - `gender` string — The subject's gender. Choose either M for male or F for female.
      - `phone` string — The subject's phone number. Optionally prepended with a + and country code
      - `email` string, email — An email address.
      - `language` 'NL' | 'EN' | 'DE' | 'FR' | 'IT' | 'ES' — The language code consisting of 2 uppercase letters. Can be one of the following: EN, NL, DE, FR, ES, IT. You can find all available languages here: https://paynl.readme.io/reference/languages
      - `trust` integer — Indicates whether you trust the payer, scale -10 -> 10 (10 Reliable, -10 Unreliable).
      - `reference` string — Unique reference of the payer. This field only allows alphanumeric characters.
      - `bankAccount` BankAccount
        - `iban` string, required — The International Bank Account Number (IBAN).
        - `bic` string, required — Business Identifier Codes (BIC/SWIFT).
        - `owner` string, required — The owner of the bank account.
      - `company` Company
        - `name` string — The name of your merchant.
        - `coc` string — Your Chamber of commerce registration number. This format differs per country.
        - `vat` string — Value added tax identification number (VAT identification number).
        - `countryCode` string — The country code consisting of 2 uppercase letters
    - `order` Order
      - `countryCode` string — When used this countryCode takes preference over the one set in the deliveryAddress and is then used as the countryCode for this transaction
      - `deliveryDate` string, date — The date of delivery.
      - `invoiceDate` string, date — The date of the invoice
      - `deliveryAddress` Address
        - `code` string
        - `firstName` FirstName — unresolved $ref
        - `lastName` LastName — unresolved $ref
        - `streetName` string — The name of the street
        - `streetNumber` string — The street number
        - `streetNumberExtension` string — A house number extension is required to deal with appartments 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
      - `invoiceAddress` Address
        - `code` string
        - `firstName` FirstName — unresolved $ref
        - `lastName` LastName — unresolved $ref
        - `streetName` string — The name of the street
        - `streetNumber` string — The street number
        - `streetNumberExtension` string — A house number extension is required to deal with appartments 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
      - `products` Product[]
        - `id` string — The product identifier.
        - `description` string — The description of the product.
        - `type` 'shipping' | 'article' | 'discount' | 'rounding' | 'handling' | 'payment' | 'credit' | 'giftcard' | 'emoney' | 'crypto' — The type of product. More information can be found here: https://paynl.readme.io/reference/producttypes
        - `price` object
          - `value` integer — The amount in cents.
        - `quantity` number, float — The quantity.
        - `vatCode` 'N' | 'H' | 'L' — The VAT code to use.
    - `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.
      - `domainId` string — The ID of the duplicate content URL
    - `type` 'POS' | 'ECOM' | 'CIT' | 'MIT' | 'MOTO' — 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
    - `transferData` TransferData[]
      - `name` string — The name of the variable to be tracked in the transaction.
      - `value` string — The value of the variable to be tracked in the transaction.
  - `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.
    - `domainId` string — The ID of the duplicate content URL
  - `customer` Customer
    - `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).
    - `type` 'B' | 'C' — Either B for business or C for consumer.
    - `ip` string — An ip address
    - `birthDate` string, date — Date of birth as defined in ISO-8601.
    - `gender` string — The subject's gender. Choose either M for male or F for female.
    - `phone` string — The subject's phone number. Optionally prepended with a + and country code
    - `email` string, email — An email address.
    - `language` 'NL' | 'EN' | 'DE' | 'FR' | 'IT' | 'ES' — The language code consisting of 2 uppercase letters. Can be one of the following: EN, NL, DE, FR, ES, IT. You can find all available languages here: https://paynl.readme.io/reference/languages
    - `trust` integer — Indicates whether you trust the payer, scale -10 -> 10 (10 Reliable, -10 Unreliable).
    - `reference` string — Unique reference of the payer. This field only allows alphanumeric characters.
    - `bankAccount` BankAccount
      - `iban` string, required — The International Bank Account Number (IBAN).
      - `bic` string, required — Business Identifier Codes (BIC/SWIFT).
      - `owner` string, required — The owner of the bank account.
    - `company` Company
      - `name` string — The name of your merchant.
      - `coc` string — Your Chamber of commerce registration number. This format differs per country.
      - `vat` string — Value added tax identification number (VAT identification number).
      - `countryCode` string — The country code consisting of 2 uppercase letters
  - `order` Order
    - `countryCode` string — When used this countryCode takes preference over the one set in the deliveryAddress and is then used as the countryCode for this transaction
    - `deliveryDate` string, date — The date of delivery.
    - `invoiceDate` string, date — The date of the invoice
    - `deliveryAddress` Address
      - `code` string
      - `firstName` FirstName — unresolved $ref
      - `lastName` LastName — unresolved $ref
      - `streetName` string — The name of the street
      - `streetNumber` string — The street number
      - `streetNumberExtension` string — A house number extension is required to deal with appartments 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
    - `invoiceAddress` Address
      - `code` string
      - `firstName` FirstName — unresolved $ref
      - `lastName` LastName — unresolved $ref
      - `streetName` string — The name of the street
      - `streetNumber` string — The street number
      - `streetNumberExtension` string — A house number extension is required to deal with appartments 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
    - `products` Product[]
      - `id` string — The product identifier.
      - `description` string — The description of the product.
      - `type` 'shipping' | 'article' | 'discount' | 'rounding' | 'handling' | 'payment' | 'credit' | 'giftcard' | 'emoney' | 'crypto' — The type of product. More information can be found here: https://paynl.readme.io/reference/producttypes
      - `price` object
        - `value` integer — The amount in cents.
      - `quantity` number, float — The quantity.
      - `vatCode` 'N' | 'H' | 'L' — The VAT code to use.

## 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-transaction-gateway-unit-api.md) · [All operations](https://skmtc.dev/pay/apis/pay-transaction-gateway-unit-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pay/pay-transaction-gateway-unit-api/revisions/2bc260c7bdfc/schema)