---
title: "Initiate the authentication"
method: POST
path: "/initiateAuthentication"
tags: ["authentication"]
---

# Initiate the authentication

`POST /initiateAuthentication`

## Request

- Base URL: `https://financial-services.developer.worldline.com` (the document declares no server; this is the origin it was published from)
- URL: `https://financial-services.developer.worldline.com/initiateAuthentication`
- Auth: none declared
- TypeScript: <https://skmtc.dev/worldline/apis/authentication-ws-client/docs/initiateAuthentication/post.ts> (a function with typed inputs; its response is checked against the schema)

This function is used to initiate the authentication. The APM platform requests the external server by providing at least a principal (PAN for example), a session ID, a chosen authentication means and information of the transaction requested for dynamic linking process. Additional information could be provided, like credential and authentication means data (challenge, OTP…) depending on which platform is in charge to generate and control the authentication. If the bank generates and controls autonomously, authenticationMeansData is not sent. Credentials field is provided only if APM has the cardholder's credentials in its local referential.

## Headers

- `Authorization` string
- `Date` string, rfc5322
- `Digest` string
- `Signature` string
- `x-jws-signature` string

## Request body

- InitiateRequestMessage: Initiate authentication request.
  - `header` Header, required: Metadata of the message.
    - `service` string, required: Service code of the caller, defined during project.
    - `issuerCode` string, required: Unique identifier code of issuer.
    - `subIssuerCode` string, required: Unique identifier code of sub-issuer.
    - `requestId` string, uuid, required: Unique identifier of the request.
    - `keyTag` string: Key indicator shared between client and server.
    - `iv` string: IV value used to crypt data. Can either be the requestId without dashes, a random value, or equals to the null IV. 32 characters long in case of CBC mode, 24 characters long in case of GCM mode (expect if configured otherwise).
  - `body` InitiateRequest, required: Initiate authentication request payload.
    - `principal` Principal, required: A pair of a type and a value (potentially encrypted).
      - `type` string, required: The type.
      - `value` string, required: The value.
    - `expiry` Expiry: A pair of a type and a value (potentially encrypted).
      - `type` string, required: The type.
      - `value` string, required: The value.
    - `sessionId` string, uuid, required: The unique identifier of the authentication session.
    - `cardholderId` string, required: The cardholder identifier.
    - `dynamicLinking` DynamicLinking, required: All information of the transaction which could be displayed to the cardholder during the authentication process.
      - `merchant` Merchant: The merchant information.
        - `id` string: The merchant identifier.
        - `name` string: The merchant name.
        - `country` string: The merchant country code (ISO 3166).
        - `url` string: The merchant URL.
      - `transactionAmount` object: The transaction amount.
        - `amount` string, required: The amount without exponent.
        - `exponent` string, required: The exponent of the amount.
        - `currency` Currency, required: The currency information.
          - `label` string, required: The currency label (ISO 4217 alphabetic code).
          - `code` string, required: The currency code (ISO 4217 numeric code).
      - `convertedAmount` object: The transaction amount, converted in Euro.
        - `amount` string, required: The amount without exponent.
        - `exponent` string, required: The exponent of the amount.
        - `currency` Currency, required: The currency information.
          - `label` string, required: The currency label (ISO 4217 alphabetic code).
          - `code` string, required: The currency code (ISO 4217 numeric code).
      - `transactionDate` string, yyyy-MM-ddTHH:mm:ss: The date and time of the transaction (ISO 8601).
      - `xid` string, uuid, required: The transaction XID (acsTransID).
      - `binAcquirer` string: The bin acquirer.
      - `ua` string: The user agent of the browser used during the purchase.
      - `browserIP` union: The IP address of the browser used during the purchase.
        - string, ipv4
        - string, ipv6
      - `deviceChannel` string: The 3DS channel type interface used to initiate the transaction, corresponding to EMV 3-D Secure protocol specification.
      - `network` string: The DS card network of the purchase transaction.
      - `messageCategory` string: The category of the message for a specific use case. Possible values are: - `01`: Payment; - `02`: Non-payment; - `03`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use.
      - `threeRIInd` string: The type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. Possible values are: - `01`: Recurring transaction; - `02`: Installment transaction; - `03`: Add card; - `04`: Maintain card; - `05`: Account verification; - `06`: Split/delayed shipment; - `07`: Top-up; - `08`: Mail order; - `09`: Telephone order; - `10`: Whitelist status check; - `11`: Other payment; - `12`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use.
      - `threeDSRequestorAuthenticationInd` string: The type of authentication request, providing additional information to the ACS to determine the best approach for handing an authentication request. Possible values are: - `01`: Payment transaction; - `02`: Recurring transaction; - `03`: Installment transaction; - `04`: Add card; - `05`: Maintain card; - `06`: Cardholder verification as part of EMV token ID&V; - `07`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use.
      - `threeDSRequestorDecReqInd` 'Y' | 'N': Indication whether the 3DS requestor requests the ACS to use decoupled authentication and agrees to use decoupled authentication if the ACS confirms its use. If not provided, it is expected for the ACS to interpret as `N`. - `Y`: Decoupled authentication is supported and preferred if challenge is necessary; - `N`: Do not use decoupled authentication.
      - `threeDSRequestorDecMaxTime` string: The maximum amount of time that the 3DS requestor will wait for an ACS to provide the results of a decoupled authentication transaction (in minutes), between 1 and 10080.
      - `threeDSRequestorAppURL` string: The client application callback URL provided by the requester.
      - `cardType` 'CREDIT' | 'DEBIT': The card type.
      - `deviceOs` string: The device OS label.
      - `maskedPan` string: The masked PAN value of the physical credit card. The mask format depends on the issuer configuration.
      - `maskedVPan` string: The masked PAN value of the virtual credit card. The mask format depends on the issuer configuration.
      - `amountInd` string: The amount indicator for recurring transactions. Possible values are: - `01`: Fixed purchase amount; - `02`: Variable purchase amount; - `03`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use.
      - `frequencyInd` string: The frequency indicator for recurring transactions. Possible values are: - `01`: Fixed frequency; - `02`: Variable or unknown frequency; - `03`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use.
      - `recurringDate` string, yyyyMMdd: The effective date of the new authorised amount following the first/promotional payment in a recurring or instalment transaction.
      - `recurringExpiry` string, yyyyMMdd: The date after which no further authorisations are performed.
      - `recurringFrequency` string: The minimum number of days between authorizations for a recurring or instalment transaction, between 1 and 9999.
      - `purchaseInstalData` string: The maximum number of authorizations permitted for instalment payments. Must be greater than 1.
      - `purchaseDate` string, yyyyMMddHHmmss: The date and time of the authentication, converted into UTC. The date is provided by merchant in AReq message.
      - `recurringAmount` object: The recurring payment amount (if fixed).
        - `amount` string, required: The amount without exponent.
        - `exponent` string, required: The exponent of the amount.
        - `currency` Currency, required: The currency information.
          - `label` string, required: The currency label (ISO 4217 alphabetic code).
          - `code` string, required: The currency code (ISO 4217 numeric code).
    - `authenticationMeans` string, required: The authentication means which must be used. The list of current authentication means available are: - `EXTOTP`: OTP pushed and verified by the bank; - `EXTPWD`: Authentication based on static password; - `EXTMOBAPP`: Authentication Out Of Band, on an external mobile application; - `EXTOTP_PWD`: Authentication with OTP and password managed by the bank; - `EXTOTRC`: Authentication with OTRC; - `SMS_EXT`: Authentication with OTP SMS managed by eWL and password managed by Bank; - `IVR_EXT`: Authentication with OTP IVR managed by eWL and password managed by Bank; - `PHOTO_TAN`: Authentication with PhotoTan solution.
    - `authenticationMeansData` AuthenticationMeansData: The additional information necessary to initialize the authentication.
      - `generatedChallenges` string: The map of challenges generated by APM, serialized as a string. Each challenge is a string of 1 to 55 characters.
      - `generatedOTP` string: The OTP generated by APM if bank don't want to take into account the OTP generation.
      - `chosenDevice` string: The value of the device to use for the authentication
      - `authenticationMethod` string: The method used to authenticate the cardholder, corresponding to 3DS2 protocol's `authenticationMethod`.
      - `oobAppLabel` string: The name of the authentication OOB application allowing the switch between merchant app to the bank app.
      - `oobAppURL` string, url: The URL of the authentication OOB application allowing the switch between merchant app to the bank app.
      - `friendlyName` string: Friendly name. (since 25R2)
      - `idDevice` string: Id device. (since 25R2)
      - `deviceModel` string: Device model. (since 25R2)
    - `credentials` object: A pair of a type and a value (potentially encrypted).
      - `type` string, required: The type.
      - `value` string, required: The value.
    - `callbackURL` string, url: The web service callback URL used to asynchronously return the result of the authentication.
    - `callbackSite` 'VDM' | 'SCL': The APM server site name which will receive the callback request (linked to `callbackURL`).
    - `trustedEnrollmentRequest` boolean: Is the enrolment request applied to trusted beneficiary.
    - `freeContext` FreeContext: A free map to add any specific information.
    - `oobAppURLInd` string: "The URL indicator of the authentication OOB application allowing the switch between merchant app to the bank app." Values accepted: - 01 = Supported - 02 = Not supported by the device - 03 = Not supported by the 3DS Requestor - 04-79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) - 80-99 = Reserved for DS use. If SDK Type = 02 and Split-SDK Type = 02, the OOB App URL Indicator is set to 02. Note: OOB App URL does not work for the Split-SDK/Browser.
  - `signature` string: The signature of the message. The signature is optional and is only filled and/or checked if explicitly required. Otherwise, signature value is ignored in responses and left empty in requests. Signatures can be activated for each issuer, sub-issuer individually and at a method level. To pass validation, the signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant. As such, a typical signature should look like this: `[header]..[signature]`, where: - `[header]` is the Base64 URL encoded value of the JOSE header which contains the key ID, algorithm and object type. For example: `eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ`, which gives, in clear JSON: `{"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}`. The `kid` (Key ID) and `alg` header fields are both required to perform the check. An additional `jku` parameter (JWKS URL where to retrieve the public key) can also be specified. Otherwise, it should be expected for public keys to have been exchanged beforehand. The `typ` is only there by convention and should only be set to `JOSE` or `JOSE+JSON` since were are not dealing JWT (tokens) here. - `[signature]` is the Base64 URL encoded value representation of the signature output. The payload used to generate the signature consists of the JSON serialization of the whole object, excluding old signatures and null values, which is then Base 64 URL encoded as well. If the signature from the response contains a payload value, then it will be ignored in favor of the actual object. Currently supported algorithms are: - RS256 - RS384 - RS512 - ES256 - ES256K - ES384 - ES512

## Response `200`

Initiate response.

- InitiateResponseMessage: Initiate authentication response.
  - `header` Header, required: Metadata of the message.
    - `service` string, required: Service code of the caller, defined during project.
    - `issuerCode` string, required: Unique identifier code of issuer.
    - `subIssuerCode` string, required: Unique identifier code of sub-issuer.
    - `requestId` string, uuid, required: Unique identifier of the request.
    - `keyTag` string: Key indicator shared between client and server.
    - `iv` string: IV value used to crypt data. Can either be the requestId without dashes, a random value, or equals to the null IV. 32 characters long in case of CBC mode, 24 characters long in case of GCM mode (expect if configured otherwise).
  - `body` InitiateResponse, required: Initiate authentication response payload.
    - `authenticationMeansData` AuthenticationMeansData: The additional information necessary to initialize the authentication.
      - `generatedChallenges` string: The map of challenges generated by APM, serialized as a string. Each challenge is a string of 1 to 55 characters.
      - `generatedOTP` string: The OTP generated by APM if bank don't want to take into account the OTP generation.
      - `chosenDevice` string: The value of the device to use for the authentication
      - `authenticationMethod` string: The method used to authenticate the cardholder, corresponding to 3DS2 protocol's `authenticationMethod`.
      - `oobAppLabel` string: The name of the authentication OOB application allowing the switch between merchant app to the bank app.
      - `oobAppURL` string, url: The URL of the authentication OOB application allowing the switch between merchant app to the bank app.
      - `friendlyName` string: Friendly name. (since 25R2)
      - `idDevice` string: Id device. (since 25R2)
      - `deviceModel` string: Device model. (since 25R2)
    - `trialLeft` integer: The number of remaining attempts before the authentication will be refused.
    - `transactionId` string: The bank's unique identifier of the authentication transaction.
    - `freeContext` FreeContext: A free map to add any specific information.
    - `devices` Device[]: The devices list returned by the bank.
      - `id` string: The device identifier.
      - `value` string: The device value.
  - `signature` string: The signature of the message. The signature is optional and is only filled and/or checked if explicitly required. Otherwise, signature value is ignored in responses and left empty in requests. Signatures can be activated for each issuer, sub-issuer individually and at a method level. To pass validation, the signature format must be RFC 7515 (JSON Web Signature) and RFC 7797 (Unencoded or detached payload) compliant. As such, a typical signature should look like this: `[header]..[signature]`, where: - `[header]` is the Base64 URL encoded value of the JOSE header which contains the key ID, algorithm and object type. For example: `eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ`, which gives, in clear JSON: `{"kid":"sign","typ":"JOSE+JSON","alg":"RS256"}`. The `kid` (Key ID) and `alg` header fields are both required to perform the check. An additional `jku` parameter (JWKS URL where to retrieve the public key) can also be specified. Otherwise, it should be expected for public keys to have been exchanged beforehand. The `typ` is only there by convention and should only be set to `JOSE` or `JOSE+JSON` since were are not dealing JWT (tokens) here. - `[signature]` is the Base64 URL encoded value representation of the signature output. The payload used to generate the signature consists of the JSON serialization of the whole object, excluding old signatures and null values, which is then Base 64 URL encoded as well. If the signature from the response contains a payload value, then it will be ignored in favor of the actual object. Currently supported algorithms are: - RS256 - RS384 - RS512 - ES256 - ES256K - ES384 - ES512

## Other responses

- `default`: Error response.

---

[API](https://skmtc.dev/worldline/apis/authentication-ws-client.md) - [All operations](https://skmtc.dev/worldline/apis/authentication-ws-client/llms.txt) - [OpenAPI document](https://skmtc.dev/worldline/apis/authentication-ws-client/revisions/5c21f3ad0e19?raw)