openapi: "3.1.0" info: title: "Authentication web service client" description: "Standard interface for authentication implemented by the bank. The APM platform is the client, and call the bank which is the server." version: "25R1.1" paths: /echo: post: tags: - "monitoring" operationId: "echo" description: "Test the availability of the web service. Timestamps are exchanged between the client and the server." requestBody: $ref: '#/components/requestBodies/EchoMessageRequest' responses: "200": description: "OK." $ref: '#/components/responses/EchoMessageResponse' /initiateAuthentication: post: tags: - "authentication" operationId: "initiateAuthentication" summary: "Initiate the authentication" description: "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." parameters: - $ref: '#/components/parameters/AuthorizationHeader' - $ref: '#/components/parameters/DateHeader' - $ref: '#/components/parameters/DigestHeader' - $ref: '#/components/parameters/HttpSignatureHeader' - $ref: '#/components/parameters/JwsSignatureHeader' requestBody: $ref: '#/components/requestBodies/InitiateRequest' responses: "200": description: "Success" $ref: '#/components/responses/InitiateResponse' "default": description: "Error" $ref: '#/components/responses/ErrorMessageResponse' /updateAuthentication: post: tags: - "authentication" operationId: "updateAuthentication" summary: "Update the authentication" description: "This method is used by the APM to forward the device chosen by the cardholder to the bank, in case the bank returned a list of devices during the initiateAuthentication call." parameters: - $ref: '#/components/parameters/AuthorizationHeader' - $ref: '#/components/parameters/DateHeader' - $ref: '#/components/parameters/DigestHeader' - $ref: '#/components/parameters/HttpSignatureHeader' - $ref: '#/components/parameters/JwsSignatureHeader' requestBody: $ref: '#/components/requestBodies/UpdateRequest' responses: "200": description: "Success" $ref: '#/components/responses/UpdateResponse' "default": description: "Error" $ref: '#/components/responses/ErrorMessageResponse' /validateAuthentication: post: tags: - "authentication" operationId: "validateAuthentication" summary: "Validate the authentication" description: "Validate the authentication data provided by the cardholder." parameters: - $ref: '#/components/parameters/AuthorizationHeader' - $ref: '#/components/parameters/DateHeader' - $ref: '#/components/parameters/DigestHeader' - $ref: '#/components/parameters/HttpSignatureHeader' - $ref: '#/components/parameters/JwsSignatureHeader' requestBody: $ref: '#/components/requestBodies/ValidateRequest' responses: "200": description: "Success" $ref: '#/components/responses/ValidateResponse' "default": description: "Error" $ref: '#/components/responses/ErrorMessageResponse' /cancelAuthentication: post: tags: - "authentication" operationId: "cancelAuthentication" summary: "Cancel the authentication" description: "Cancel/close the authentication." parameters: - $ref: '#/components/parameters/AuthorizationHeader' - $ref: '#/components/parameters/DateHeader' - $ref: '#/components/parameters/DigestHeader' - $ref: '#/components/parameters/HttpSignatureHeader' - $ref: '#/components/parameters/JwsSignatureHeader' requestBody: $ref: '#/components/requestBodies/CancelRequest' responses: "200": description: "Success" $ref: '#/components/responses/CancelResponse' "default": description: "Error" $ref: '#/components/responses/ErrorMessageResponse' components: parameters: AuthorizationHeader: name: "Authorization" in: "header" description: "The bearer token. The access token is returned in response of /oauth2/token endpoint. Mandatory if OAuth2 protocol is required to secure the API." schema: type: "string" maxLength: 2048 examples: - "Bearer eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiYWxnIjoiZGlyIn0..yQGpzEpF3OT1y_QZUzL2Ag.mLiSvEZElh2ryJOFGDwmb1hvP-2vAgUck20qzj5uExfWSodomogSGk1lHaJEHo3Oa3C4yzdpGVRz6C2crWHKzUxgrNgNzV2sTxFf_FpW-OueEZwW3Sf41qi7dWoIHMaFc6v7hJOsrWrELv7nBnY1xKQ7TCll37xW6JgSEM_IyAvGopaME1WnWvbN2k_lOUcJowxQutFtRzey8c0VNPKFOj3XG9PvdeApcyZoGj7Emi9whJ_OsCSzyYRmTEZ-KR9Ay6383nedhANUTbAsZgD18Jzty0be7hCbnnRRgr4tt7thIIoAK99G14ZWJTRS7iOG41Srch30PkXskp9PG3sa4KgQqgE_bCgVtZgGTN19A7taVPYo6V7oeeM_iufzkhMuyHuwomKRWhW0moXikHcFLO0ACg3FpdQl8Seflq9hLHqYSTli4gyo04syq9VkZ0HjKyaIXb4iF6OAVNGX8h80BzzRgRTMbhEcu_PQWiwdJ6fHgINRM3tWFvhIwIdKiIeOBVy5wSKLrDxCRUZTTMafknhaVqflncDuvJJ4A9ebNcVblhViFNgRzQkDYlbIXKpfblc-7iDUGowyF9GES2ReGrLPWPc0vXt6LTLbwqpeOMoLYRR5X9x-NwQYA_Dm_f8bdMsEDfI_PqOuRFI5jioZGrqBXCBdlT7Oq5mxJRNSOY5mP--vcJQsKlbpIuPoExRRGLcVR6TgCeVL5R_gshonSiPohn2dG1oyxU5UYC4mpDkg9B1p7OFggvoIiUKlT41m.1-iOmA8AuGxZo6sn9k3JXuBsAhRM1bJWQSfYfiUK5Qk" DateHeader: name: "Date" in: "header" description: "The date and time of the request. Mandatory if OAuth2 protocol is required to secure the API." schema: type: "string" format: "rfc5322" examples: - "Wed, 25 Oct 2023 13:00:05 GMT" DigestHeader: name: "Digest" in: "header" description: "The digest of the request, corresponding to the SHA-256 hash of the payload, encoded in Base64, prefixed by \"SHA-256=\". Mandatory if OAuth2 protocol is required to secure the API." schema: type: "string" examples: - "SHA-256=8HAW5Ig3X/RCOG840pFdji5JnPGNa4i32lsilUt3qK4=" HttpSignatureHeader: name: "Signature" in: "header" description: | The HTTP Signature of the request, including the 4 following parameters: - keyId: The client ID of APM platform defined during the Oauth 2.0 project; - algorithm: The algorithm used to sign the request, corresponding to the RSA-SHA256 algorithm; - headers: The list of headers included in the signature, separated by a space, which is currently \"(request-target) date digest\"; - signature: The signature of the headers value, using the chosen algorithm (rsa-sha256). Mandatory if OAuth2 protocol **using HTTP signature** is required to secure the API. schema: type: "string" examples: - "keyId=\"e77d776b-90af-4684-bebc-521e5b2614dd\",algorithm=\"rsa-sha256\",headers=\"(request-target) date digest\",signature=\"v7aAwExqWvvksa3OqwTF1aSumK2LDj3K8B8zxRTn+uc3dENlkAK9vptpTYYL/djHYcRB277EAopP0TCD6xZNwyA4vAdFJCsZc81a74c6zW8PgMAScFeIeLqIbJ1BbrYu1WUyhIHiS1Sa909NyjqmGrN4eGanGe4c8ve2sdbfuv4cC/4jrdKFfoLN8uvgF5XFqrfXih6C990OX4c2pKetroEuLOY3nkM2584XdAuo6jRHg78f4BfCgHZ8qOH8uVls3dXhMQxgyzTov2UA73zfczX5XM3ugU219gBBm5Z5XOWq2KJrxJQ1GrHY1rTaehzSmIIpQrjO/W6cyJ8lLAfQvw==\"" JwsSignatureHeader: name: "x-jws-signature" in: "header" description: | The JWS Signature of the request, composed of `[protected_header].[payload].[signature]`, where: - `[protected_header]` is a base64 encoded JSON composed of parameters: - `b64`: Parameter set to `false`; - `x5t#S256`: The digest (fingerprint) of the X.509 signing certificate using SHA 256, that shall be checked against the certificate used to validate the signature; - `crit`: Critical non-standard JWS header parameters (not defined in RFC 7515), set to `["sigT","sigD","b64"]`; - `sigT`: The date and time of the signature creation, to the second, indicated in UTC (ending with `Z`); - `sigD`: Parameter that shall contain: - `mId`: Parameter set to `http://uri.etsi.org/19182/HttpHeaders`; - `pars`: List including the following HTTP header field names: `(request-target)`, `content-type`, `digest`; - `alg`: The algorithm used to sign the request, set to `RS256`; - `[payload]` is empty; - `[signature]` is the Base64 encoded signature of `protected_header` concatenated with HTTP header strings. Example of `protected_header` before Base64 encoding: ```json { "b64": false, "x5t#S256": "dytPpSkJYzhTdPXSWP7jhXgG4kCOWIWGiesdzkvNLzY", "crit": [ "sigT", "sigD", "b64" ], "sigT": "2023-11-26T11:26:57Z", "sigD": { "pars": [ "(request-target)", "content-type", "digest" ], "mId": "http://uri.etsi.org/19182/HttpHeaders" }, "alg": "RS256" } ``` Example of resulting Base64 encoded `protected_header` (without line breaks or extra spaces): ``` eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ ``` Example of HTTP headers: ``` (request-target): post /initiateAuthentication content-type: application/json digest: SHA-256=+xeh7JAayYPh8K13UnQCBBcniZzsyat+KDiuy8aZYdI= ``` Example of resulting input data for signature: ``` eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ.(request-target): post /initiateAuthentication content-type: application/json digest: SHA-256=+xeh7JAayYPh8K13UnQCBBcniZzsyat+KDiuy8aZYdI= ``` Example of signed data: ``` Q9ZSYXJ0QWSoPBfBUR58Sqplw7BQcrcqVR6rvnqfBOvosbBLcsBjkjzi1kCF 2cJsHTJRtp6GcJmZplqRg-7_QBKQAgkUq0BGQpzZwhVYrvP0opdLEarVBrej YA05gt3qnleuS53DWmyZu9iNxhwJTYVPyXediwo3TIlSn-8XjSTZAVHa728E WK6XzRC9rEroXYPYd23iQLXetMygLaDhRT2lGhV5WvmO0wC0B6RbGiYl2zIv D0XliMP6MidX4SDY5zlzyWyFlHqX7eHpkH8xxqAsBdKb16y4IdOoRhil9yws vlzkG6-U9jmBU4y_m3mZArD22oRVXTywzFn9NUtY9w ``` Example of resulting JWS: ``` eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ..Q9ZSYXJ0QWSoPBfBUR58Sqplw7BQcrcqVR6rvnqfBOvosbBLcsBjkjzi1kCF 2cJsHTJRtp6GcJmZplqRg-7_QBKQAgkUq0BGQpzZwhVYrvP0opdLEarVBrej YA05gt3qnleuS53DWmyZu9iNxhwJTYVPyXediwo3TIlSn-8XjSTZAVHa728E WK6XzRC9rEroXYPYd23iQLXetMygLaDhRT2lGhV5WvmO0wC0B6RbGiYl2zIv D0XliMP6MidX4SDY5zlzyWyFlHqX7eHpkH8xxqAsBdKb16y4IdOoRhil9yws vlzkG6-U9jmBU4y_m3mZArD22oRVXTywzFn9NUtY9w ``` Mandatory if OAuth2 protocol **using JWS signature** is required to secure the API." schema: type: "string" examples: - "eyJiNjQiOmZhbHNlLCJ4NXQjUzI1NiI6ImR5dFBwU2tKWXpoVGRQWFNXUDdqaFhnRzRrQ09XSVdHaWVzZHprdk5MelkiLCJjcml0IjpbInNpZ1QiLCJzaWdEIiwiYjY0Il0sInNpZ1QiOiIyMDIzLTExLTI2VDExOjI2OjU3WiIsInNpZ0QiOnsicGFycyI6WyIocmVxdWVzdC10YXJnZXQpIiwiY29udGVudC10eXBlIiwiZGlnZXN0Il0sIm1JZCI6Imh0dHA6Ly91cmkuZXRzaS5vcmcvMTkxODIvSHR0cEhlYWRlcnMifSwiYWxnIjoiUlMyNTYifQ..Q9ZSYXJ0QWSoPBfBUR58Sqplw7BQcrcqVR6rvnqfBOvosbBLcsBjkjzi1kCF 2cJsHTJRtp6GcJmZplqRg-7_QBKQAgkUq0BGQpzZwhVYrvP0opdLEarVBrej YA05gt3qnleuS53DWmyZu9iNxhwJTYVPyXediwo3TIlSn-8XjSTZAVHa728E WK6XzRC9rEroXYPYd23iQLXetMygLaDhRT2lGhV5WvmO0wC0B6RbGiYl2zIv D0XliMP6MidX4SDY5zlzyWyFlHqX7eHpkH8xxqAsBdKb16y4IdOoRhil9yws vlzkG6-U9jmBU4y_m3mZArD22oRVXTywzFn9NUtY9w" requestBodies: EchoMessageRequest: description: "Echo request." required: true content: application/json: schema: $ref: '#/components/schemas/EchoMessage' InitiateRequest: description: "Initiate request." required: true content: application/json: schema: $ref: '#/components/schemas/InitiateRequestMessage' UpdateRequest: description: "Update request." required: true content: application/json: schema: $ref: '#/components/schemas/UpdateRequestMessage' ValidateRequest: description: "Validate request." required: true content: application/json: schema: $ref: '#/components/schemas/ValidateRequestMessage' CancelRequest: description: "Cancel request." required: true content: application/json: schema: $ref: '#/components/schemas/CancelRequestMessage' responses: EchoMessageResponse: description: "Echo response." content: application/json: schema: $ref: '#/components/schemas/EchoMessage' InitiateResponse: description: "Initiate response." content: application/json: schema: $ref: '#/components/schemas/InitiateResponseMessage' UpdateResponse: description: "Update response." content: application/json: schema: $ref: '#/components/schemas/UpdateResponseMessage' ValidateResponse: description: "Validate response." content: application/json: schema: $ref: '#/components/schemas/ValidateResponseMessage' CancelResponse: description: "Cancel response." content: application/json: schema: $ref: '#/components/schemas/CancelResponseMessage' ErrorMessageResponse: description: "Error response." content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' schemas: Amount: type: "object" required: - "amount" - "exponent" - "currency" properties: amount: description: "The amount without exponent." type: "string" pattern: "^[0-9]+$" examples: - "2200" exponent: description: "The exponent of the amount." type: "string" pattern: "^[0-9]$" examples: - "2" currency: $ref: '#/components/schemas/Currency' AuthenticationMeansData: description: "The additional information necessary to initialize the authentication." type: "object" properties: generatedChallenges: description: "The map of challenges generated by APM, serialized as a string. Each challenge is a string of 1 to 55 characters." type: "string" examples: - "{\"1\":\"NNNN\",\"2\":\"MMM\"}" generatedOTP: description: "The OTP generated by APM if bank don't want to take into account the OTP generation." type: "string" minLength: 1 maxLength: 10 examples: - "123456" chosenDevice: description: "The value of the device to use for the authentication" type: "string" minLength: 1 maxLength: 255 authenticationMethod: description: "The method used to authenticate the cardholder, corresponding to 3DS2 protocol's `authenticationMethod`." type: "string" minLength: 2 maxLength: 2 oobAppLabel: description: "The name of the authentication OOB application allowing the switch between merchant app to the bank app." type: "string" minLength: 1 maxLength: 45 oobAppURL: description: "The URL of the authentication OOB application allowing the switch between merchant app to the bank app." type: "string" format: "url" minLength: 1 maxLength: 2048 CancelRequest: description: "Cancel authentication request payload." type: "object" required: - "sessionId" properties: sessionId: $ref: '#/components/schemas/SessionId' transactionId: $ref: '#/components/schemas/TransactionId' freeContext: $ref: '#/components/schemas/FreeContext' CancelRequestMessage: description: "Cancel authentication request." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/CancelRequest' signature: $ref: '#/components/schemas/Signature' CancelResponse: description: "Cancel authentication response payload." type: "object" properties: transactionId: $ref: '#/components/schemas/TransactionId' freeContext: $ref: '#/components/schemas/FreeContext' CancelResponseMessage: description: "Cancel authentication response." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/CancelResponse' signature: $ref: '#/components/schemas/Signature' Currency: description: "The currency information." type: "object" required: - "label" - "code" properties: label: description: "The currency label (ISO 4217 alphabetic code)." type: "string" pattern: "^[A-Z]{3}$" examples: - "EUR" code: description: "The currency code (ISO 4217 numeric code)." type: "string" pattern: "^[0-9]{3}$" examples: - "978" Device: description: "The device information." type: "object" properties: id: description: "The device identifier." type: "string" minLength: 1 maxLength: 50 examples: - "1820b59376fed03ddab5efcc5353bdc5" value: description: "The device value." type: "string" minLength: 1 maxLength: 255 examples: - "061xxxxx78" DynamicLinking: description: "All information of the transaction which could be displayed to the cardholder during the authentication process." required: - "xid" type: "object" properties: merchant: $ref: '#/components/schemas/Merchant' transactionAmount: allOf: - description: "The transaction amount." - $ref: '#/components/schemas/Amount' convertedAmount: allOf: - description: "The transaction amount, converted in Euro." - $ref: '#/components/schemas/Amount' transactionDate: description: "The date and time of the transaction (ISO 8601)." format: "yyyy-MM-ddTHH:mm:ss" examples: - "2025-12-23T14:18:02" xid: description: "The transaction XID (acsTransID)." type: "string" format: "uuid" minLength: 36 maxLength: 36 examples: - "1d1ff27f-a896-d35a-1bbc-8f5c28059736" binAcquirer: description: "The bin acquirer." type: "string" minLength: 1 maxLength: 11 examples: - "700004" ua: description: "The user agent of the browser used during the purchase." type: "string" minLength: 1 maxLength: 2048 examples: - "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.98 Safari/537.36" browserIP: description: "The IP address of the browser used during the purchase." type: "string" minLength: 1 maxLength: 45 oneOf: - format: "ipv4" - format: "ipv6" examples: - "155.155.155.155" deviceChannel: description: "The 3DS channel type interface used to initiate the transaction, corresponding to EMV 3-D Secure protocol specification." type: "string" minLength: 2 maxLength: 2 examples: - "06" network: description: "The DS card network of the purchase transaction." type: "string" minLength: 1 maxLength: 50 examples: - "VISA" - "MASTERCARD" - "CB" - "BANCONTACT" - "MAESTRO" messageCategory: description: | 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. type: "string" minLength: 2 maxLength: 2 threeRIInd: description: | 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. type: "string" minLength: 2 maxLength: 2 threeDSRequestorAuthenticationInd: description: | 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. type: "string" minLength: 2 maxLength: 2 threeDSRequestorDecReqInd: description: | 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. type: "string" enum: - "Y" - "N" threeDSRequestorDecMaxTime: description: "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." type: "string" minLength: 1 maxLength: 5 threeDSRequestorAppURL: description: "The client application callback URL provided by the requester." type: "string" minLength: 1 maxLength: 2048 cardType: description: "The card type." type: "string" enum: - "CREDIT" - "DEBIT" examples: - "CREDIT" deviceOs: description: "The device OS label." type: "string" examples: - "Android" - "iOS" maskedPan: description: "The masked PAN value of the physical credit card. The mask format depends on the issuer configuration." type: "string" minLength: 13 maxLength: 19 examples: - "497670xxxxxxxx15" maskedVPan: description: "The masked PAN value of the virtual credit card. The mask format depends on the issuer configuration." type: "string" minLength: 13 maxLength: 19 examples: - "471663xxxxxxxx07" amountInd: description: | 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. type: "string" minLength: 2 maxLength: 2 frequencyInd: description: | 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. type: "string" minLength: 2 maxLength: 2 recurringDate: description: "The effective date of the new authorised amount following the first/promotional payment in a recurring or instalment transaction." type: "string" format: "yyyyMMdd" minLength: 8 maxLength: 8 recurringExpiry: description: "The date after which no further authorisations are performed." type: "string" format: "yyyyMMdd" minLength: 8 maxLength: 8 recurringFrequency: description: "The minimum number of days between authorizations for a recurring or instalment transaction, between 1 and 9999." type: "string" minLength: 1 maxLength: 4 examples: - "31" - "031" - "0031" purchaseInstalData: description: "The maximum number of authorizations permitted for instalment payments. Must be greater than 1." type: "string" minLength: 1 maxLength: 3 examples: - "2" - "02" - "002" purchaseDate: description: "The date and time of the authentication, converted into UTC. The date is provided by merchant in AReq message." type: "string" format: "yyyyMMddHHmmss" examples: - "20251223141802" recurringAmount: allOf: - description: "The recurring payment amount (if fixed)." - $ref: '#/components/schemas/Amount' EchoBody: description: "Body of echo message, which contains the timestamp of the message." type: "object" required: - "timestamp" properties: timestamp: description: "Timestamp of the message." type: "string" format: "yyyyMMddHHmmss" minLength: 14 maxLength: 14 examples: - "20250215174159" EchoMessage: description: "Echo message." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/EchoBody' signature: $ref: '#/components/schemas/Signature' ErrorMessage: description: "Error response." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ErrorResponse' signature: $ref: '#/components/schemas/Signature' ErrorResponse: description: "Error response payload." type: "object" required: - "errorCode" properties: errorCode: description: | The 5-digits error code used in case of functional error. Depending on the use case, possible values are: - `30200`: Fallback authentication; - `40001`: Invalid issuer or sub-issuer code; - `40002`: Invalid service; - `40003`: Invalid requestId; - `40004`: Invalid keyTag; - `40011`: Invalid principal value or type; - `40012`: Invalid expiry value or type; - `40020`: Invalid userInputs value or type; - `40030`: Invalid algorithm or keyInfo; - `40101`: OAuth empty date; - `40102`: OAuth invalid date; - `40103`: Signature client id not provided; - `40104`: Invalid signature; - `40105`: Invalid Access Token; - `40106`: Invalid Payload; - `40107`: Invalid Access Token Scope; - `40108`: Expired access token; - `40303`: Card not enrolled; - `40311`: Card blocked; - `40312`: Card temporary blocked or Authentication blocked; - `40322`: Authentication blocked; - `40331`: Invalid Signature; - `40401`: Card not found; - `40402`: transactionId not found. type: "integer" Expiry: allOf: - description: "The expiry date." - $ref: '#/components/schemas/TypeValue' - examples: - { "type": "plain", "value": "2023-01" } FreeContext: description: "A free map to add any specific information." type: "object" additionalProperties: type: "string" minLength: 1 maxLength: 255 Header: description: "Metadata of the message." type: "object" required: - "service" - "issuerCode" - "subIssuerCode" - "requestId" properties: service: description: "Service code of the caller, defined during project." type: "string" minLength: 1 maxLength: 255 examples: - "ACS_H0A" issuerCode: description: "Unique identifier code of issuer." type: "string" minLength: 5 maxLength: 5 examples: - "66666" subIssuerCode: description: "Unique identifier code of sub-issuer." type: "string" minLength: 5 maxLength: 5 examples: - "66666" requestId: description: "Unique identifier of the request." type: "string" format: "uuid" examples: - "d6156f8a-a504-48c4-8f5a-722606bd3d91" keyTag: description: "Key indicator shared between client and server." type: "string" minLength: 2 maxLength: 2 examples: - "01" iv: description: "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)." type: "string" minLength: 24 maxLength: 32 examples: - "d6156f8aa50448c48f5a722606bd3d91" - "75455355452260861386826312477255" InitiateRequest: description: "Initiate authentication request payload." type: "object" required: - "principal" - "cardholderId" - "sessionId" - "dynamicLinking" - "authenticationMeans" properties: principal: $ref: '#/components/schemas/Principal' expiry: $ref: '#/components/schemas/Expiry' sessionId: $ref: '#/components/schemas/SessionId' cardholderId: description: "The cardholder identifier." type: "string" minLength: 8 maxLength: 36 examples: - "3d6e2278-855d-4886-befe-4fbf7230fc5d" dynamicLinking: $ref: '#/components/schemas/DynamicLinking' authenticationMeans: description: | 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. type: "string" examples: - "EXTMOBAPP" authenticationMeansData: $ref: '#/components/schemas/AuthenticationMeansData' credentials: allOf: - $ref: '#/components/schemas/TypeValue' - examples: - { "type": "plain", "value": "{\"METHOD:SSN\":[{\"value\":\"[{\\\"ssn\\\":\\\"9876543210\\\"}]\"}]}" } callbackURL: description: "The web service callback URL used to asynchronously return the result of the authentication." type: "string" format: "url" minLength: 1 maxLength: 2048 examples: - "tst.callback.worldline.com" callbackSite: description: "The APM server site name which will receive the callback request (linked to `callbackURL`)." type: "string" enum: - "VDM" - "DCL" examples: - "VDM" trustedEnrollmentRequest: description: "Is the enrolment request applied to trusted beneficiary." type: "boolean" freeContext: $ref: '#/components/schemas/FreeContext' oobAppURLInd: description: "The URL indicator of the authentication OOB application allowing the switch between merchant app to the bank app." type: "string" InitiateRequestMessage: description: "Initiate authentication request." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/InitiateRequest' signature: $ref: '#/components/schemas/Signature' InitiateResponse: description: "Initiate authentication response payload." type: "object" properties: authenticationMeansData: $ref: '#/components/schemas/AuthenticationMeansData' trialLeft: description: "The number of remaining attempts before the authentication will be refused." type: "integer" examples: - 2 transactionId: $ref: '#/components/schemas/TransactionId' freeContext: $ref: '#/components/schemas/FreeContext' devices: description: "The devices list returned by the bank." type: "array" items: $ref: '#/components/schemas/Device' InitiateResponseMessage: description: "Initiate authentication response." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/InitiateResponse' signature: $ref: '#/components/schemas/Signature' Merchant: description: "The merchant information." type: "object" properties: id: description: "The merchant identifier." type: "string" minLength: 1 maxLength: 255 examples: - "123456" name: description: "The merchant name." type: "string" minLength: 1 maxLength: 1024 examples: - "merchant_çéàùöô" country: description: "The merchant country code (ISO 3166)." type: "string" minLength: 3 maxLength: 3 examples: - "250" url: description: "The merchant URL." type: "string" minLength: 1 maxLength: 2048 examples: - "www.nrt.fr" Principal: allOf: - description: "The principal information." - $ref: '#/components/schemas/TypeValue' - examples: - { "type": "pan", "value": "4976700000000106" } Result: description: "The result of the authentication." type: "object" required: - "resultCode" properties: resultCode: description: "Is the authentication successful." type: "string" enum: - "SUCCESS" - "FAILURE" examples: - "FAILURE" trialLeft: description: "The number of trials left to try again." type: "integer" examples: - 2 SessionId: description: "The unique identifier of the authentication session." type: "string" format: "uuid" minLength: 36 maxLength: 36 examples: - "2e84b4c7-b830-4bd1-9145-fb681f0a0979" Signature: description: | 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 type: "string" examples: - "eyJraWQiOiJzaWduIiwidHlwIjoiSk9TRStKU09OIiwiYWxnIjoiUlMyNTYifQ..QslvRsAf7favTzmZACC6l1UbjySjezKwCIJ0T-qxWkla0GjACsp-5TzannnBoTYzpZfa9BasNVRe1UZyTKEF8ViQX_LL_XnMoDttzB15zCoKkLhgcTOqSmrUa2p_hPOTnmL40TAnlykqNA0MlOQ9nox3K7a-rlfAG4FVXypyaHN71rCBfMQiw5eY-57e3DEdcjDAIWMxKh2zaM4HZ43K2fc1DQHGB-k9aTljOZAEhe6D7dgTYV0EGAHzRw51x15xnPD7_z-sJGpun9iVZpf8fHu9dTn5lhMChQvEBqElxWpm6fET7Izm8hqMa1oUkf2l5ue9h-WotzIbzE4PQuLOxw" TransactionId: description: "The bank's unique identifier of the authentication transaction." type: "string" minLength: 1 maxLength: 50 examples: - "3840000010b96e4ef00e" TypeValue: description: "A pair of a type and a value (potentially encrypted)." type: "object" required: - "type" - "value" properties: type: description: "The type." type: "string" value: description: "The value." type: "string" minLength: 1 maxLength: 255 UpdateRequest: description: "Update authentication request payload." type: "object" required: - "principal" - "sessionId" properties: principal: $ref: '#/components/schemas/Principal' expiry: $ref: '#/components/schemas/Expiry' sessionId: $ref: '#/components/schemas/SessionId' transactionId: $ref: '#/components/schemas/TransactionId' chosenDevice: $ref: '#/components/schemas/Device' freeContext: $ref: '#/components/schemas/FreeContext' UpdateRequestMessage: description: "Update authentication request." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/UpdateRequest' signature: $ref: '#/components/schemas/Signature' UpdateResponse: description: "Update authentication response payload." type: "object" properties: result: $ref: '#/components/schemas/Result' freeContext: $ref: '#/components/schemas/FreeContext' UpdateResponseMessage: description: "Updated authentication response." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/UpdateResponse' signature: $ref: '#/components/schemas/Signature' ValidateRequest: description: "Validate authentication request payload" type: "object" required: - "principal" - "sessionId" properties: principal: $ref: '#/components/schemas/Principal' expiry: $ref: '#/components/schemas/Expiry' sessionId: $ref: '#/components/schemas/SessionId' transactionId: $ref: '#/components/schemas/TransactionId' userInputs: allOf: - description: "The information filled by the cardholder to be authenticated, and which must be checked by the bank. The value is a serialized JSON object." - $ref: '#/components/schemas/TypeValue' - examples: - { "type": "plain", "value": "{\"PWD\":{\"value\":\"azerty\"}}" } freeContext: $ref: '#/components/schemas/FreeContext' ValidateRequestMessage: description: "Validate authentication request." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ValidateRequest' signature: $ref: '#/components/schemas/Signature' ValidateResponse: description: "Validate authentication response payload." type: "object" properties: result: $ref: '#/components/schemas/Result' authenticationMethod: description: | The method used to authenticate the cardholder, corresponding to the 2-digits 3DS2 protocol's authenticationMethod. Possible values are: - `01`: Static passcode; - `02`: SMS OTP; - `03`: Key fob or EMV card reader OTP; - `04`: App OTP; - `05`: OTP other; - `06`: KBA; - `07`: OOB biometrics; - `08`: OOB login; - `09`: OOB other; - `10`: Other; - `11`-`79`: Reserved for EMVCo future use; - `80`-`99`: Reserved for DS use. type: "string" minLength: 2 maxLength: 2 freeContext: $ref: '#/components/schemas/FreeContext' ValidateResponseMessage: description: "Validate authentication response." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ValidateResponse' signature: $ref: '#/components/schemas/Signature'