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

# authorize

`POST /v1/Payment/authorize/json`

API handles the calls for starting and completing 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 can only handle:
1. NON 3DS transactions - no fallback to 3DS auth
2. 3DS transactions where the merchant provides the 3DS data (using 3rd party 3DSecure provider)
3. 3DS transactions where the merchant adds the transaction ID of the integrated 3DSecure provider
4. Wallet transactions (e.g. Apple Pay / Google Pay)

## Request body

- Authorize
  - `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` PaymentAuthorize, 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
    - `auth` Auth — Provide the data that you have received from your 3DS provider to process the transaction 3DSecure. The payment will be processed without 3DSecure if no data is provided.
      - `dsTransactionId` string — The identifier of the 3DS2 authentication session
      - `cryptogram` string — Authentication value/cryptogram received from your 3DSecure or Wallet provider
      - `eci` number — ECI (Electronic Commerce Indicator) returned by 3DSecure provider indicating the outcome of authentication attempted.
      - `status` string — 3DSecure status returned by the provider indicating the outcome of authentication attempted.
      - `version` string — Provide the protocol version returned by your 3DSecure provider
      - `type` 'challenged' | 'frictionless' | 'wallet' — The type of 3DSecure authentication; eg. `challenged`, `frictionless`, `wallet`
      - `walletProvider` 'applepay' | 'googlepay' — When processing Wallet payments like Apple Pay or Google Pay the corresponding value must be selected. Submitting Wallet cryptograms without the wallet provider correctly set, can result in declines or non-3ds processed transactions.
      - `payTdsTransactionId` string
      - `payTdsAcquirerId` number
  - `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

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