openapi: "3.1.0" info: title: "Referential WS Client" description: "REST API for referential operations where Hub is the client." version: "25R1.0" paths: /echo: post: operationId: "echo" description: "Echo function to test the availability of the web service. `header`'s `keyTag` and `iv` are not used in this operation." requestBody: description: "Echo request." required: true content: application/json: schema: $ref: '#/components/schemas/EchoMessage' responses: "200": description: "OK." content: application/json: schema: $ref: '#/components/schemas/EchoMessage' "400": description: "Bad Request." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "403": description: "Forbidden." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /getCardWithCredentials: post: description: "Get a card with its credentials. In case of success, the server should only return success code HTTP 200. In case of error, no retry will be triggered on client side." operationId: "getCardWithCredentials" parameters: - name: "Authorization" in: "header" description: "OAuth2 Authorization." schema: type: "string" requestBody: description: "Request ClientRequest." required: true content: application/json: schema: $ref: '#/components/schemas/MessageClientRequestBody' responses: "200": description: "OK." content: application/json: schema: $ref: '#/components/schemas/MessageGetCardResponse' "400": description: "Bad Request." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "401": description: "Unauthorized." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "403": description: "Forbidden." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "404": description: "Not Found." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /updateCardCredentials: post: operationId: "updateCardCredentials" description: "Update a card with its credentials. In case of error, no retry will be triggered on client side." parameters: - name: "Authorization" in: "header" description: "OAuth2 Authorization." schema: type: "string" requestBody: description: "Request ClientRequest." required: true content: application/json: schema: $ref: '#/components/schemas/MessageClientRequestBody' responses: "200": description: "OK." content: application/json: schema: $ref: '#/components/schemas/MessageUpdateCardResponse' "400": description: "Bad Request." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "401": description: "Unauthorized." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "403": description: "Forbidden." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' "404": description: "Not Found." content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: Amount: description: "Transaction Amount converted in Euro." type: "object" required: - "amount" - "currency" - "exponent" properties: amount: description: "Amount without exponent." type: "string" format: "Numeric string" minLength: 1 maxLength: 48 examples: - "2000" exponent: description: "Exponent of the amount." type: "string" minLength: 1 maxLength: 1 format: "Numeric string" examples: - "2" currency: $ref: '#/components/schemas/Currency' ClientRequestBody: description: "ClientRequestBody DTO resource representation." type: "object" required: - "cardHolderId" - "dynamicLinking" - "principal" properties: cardHolderId: description: "Cardholder identifier." type: "string" minLength: 8 maxLength: 36 format: "String of 8 to 36 characters - Alphanumeric and '-' (not mandatory, but UUID format is also acceptable)" examples: - "2b7bdce2-b647-43e8-9e32-049605531c4a" dynamicLinking: $ref: '#/components/schemas/DynamicLinking' principal: allOf: - $ref: '#/components/schemas/TypeValue' - properties: type: enum: - "pan" - "encryptedPan" - "cardId" - "tokenPan" value: maxLength: 255 - examples: - { "type": "pan", "value": "4976700000000114" } expiry: allOf: - $ref: '#/components/schemas/TypeValue' - properties: type: enum: - "plain" - "encrypted" value: maxLength: 255 - examples: - { "type": "plain", "value": "2020-01" } credentials: allOf: - $ref: '#/components/schemas/TypeValue' - properties: type: enum: - "plain" - "encrypted" - examples: - { "type": "plain", "value": "{\"METHOD:PWD\":[{\"value\":\"f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9\",\"algorithm\":\"SHA-256\"}]}" } freeContext: type: "object" description: "Free map of key-value pairs to add specific information." additionalProperties: type: "string" ClientResponseBody: description: "ClientResponseBody DTO resource representation." type: "object" properties: availableMeans: description: "List of available means." type: "array" items: description: "Authentication means." type: "string" examples: - "TA" - "EXTOTP" examples: - ["TA", "EXTOTP"] cardData: description: "Optional field to provide more card information." type: "string" cardId: description: "Card identifier." type: "string" minLength: 2 maxLength: 36 format: "String of 2 to 36 characters - Alphanumeric and '-'" examples: - "58ba0332-69d3-4c48-a954-f91071dffe29" cardholderId: description: "Cardholder identifier." type: "string" minLength: 8 maxLength: 36 format: "String of 8 to 36 characters - Alphanumeric and ‘-‘" examples: - "7e946be6-8ba9-4102-9e4f-8068b493e325" credentials: allOf: - $ref: '#/components/schemas/TypeValue' - examples: - { "type": "plain", "value": "{\"METHOD:PWD\":[{\"value\":\"f2d81a260dea8a100dd517984e53c56a7523d96942a834b9cdc249bd4e8c7aa9\",\"algorithm\":\"SHA-256\"}]}" } deletedTime: description: "Deleted time." type: "string" format: "yyyy-MM-dd HH:mm:ss,SSS" examples: - "2016-11-16 06:43:19.77" label: description: "Label to associate to the card." type: "string" examples: - "STD BANK SMS" language: description: "Language of the customer, as per the ISO 639-1 standard." type: "string" minLength: 2 maxLength: 2 examples: - "en" freeContext: description: "Free list of field key/value to add specific information." type: "object" format: "Map of key-value pairs with String 'key' and String 'value' objects" additionalProperties: type: "string" Currency: description: "Currency information." type: "object" required: - "code" - "label" properties: code: description: "Currency code. Numeric code ISO 4217." type: "string" format: "Numeric string" minLength: 3 maxLength: 3 examples: - "978" label: description: "Currency label. Alphabetic code ISO 4217 (String of 3 alpha characters)" type: "string" minLength: 3 maxLength: 3 examples: - "EUR" DynamicLinking: description: "All information of the transaction which could be displayed at cardholder during the authentication process." type: "object" required: - "xid" properties: xid: description: "Transaction XID (unique identifier of the transaction)." type: "string" minLength: 36 maxLength: 36 examples: - "1234567890" binAcquirer: description: "Bin Acquirer." type: "string" minLength: 1 maxLength: 11 examples: - "700004" browserIP: description: "IP address of the Browser used during purchase (IPV4 IPV6)." type: "string" minLength: 1 maxLength: 45 examples: - "155.155.155.155" cardType: description: "Card (network) type." type: "string" enum: - "CREDIT" - "DEBIT" examples: - "CREDIT" convertedAmount: $ref: '#/components/schemas/Amount' transactionAmount: $ref: '#/components/schemas/Amount' deviceChannel: description: "Indicates the type of channel interface being used to initiate the transaction. 3DS (Corresponding to EMV 3-D Secure Protocol specification)" minLength: 2 maxLength: 2 type: "string" examples: - "02" deviceOs: description: "The device OS is provided in INSE message by ACS since 23R1." type: "string" examples: - "Android" - "IOS" amountInd: description: | Amount Indicator of the Recurring indicator, available since 24R2. - **01**: Fixed purchase amount - **02**: Variable Purchase amount - **03–79**: Reserved for EMVCo future use (values invalid until defined by EMVCo) - **80–99**: Reserved for DS use type: "string" minLength: 2 maxLength: 2 examples: - "01" frequencyInd: description: | Frequency Indicator of the Recurring indicator, available since 24R2 - **01**: Fixed Frequency - **02**: Variable or Unknown Frequency - **03–79**: Reserved for EMVCo future use (values invalid until defined by EMVCo) - **80–99**: Reserved for DS use type: "string" minLength: 2 maxLength: 2 examples: - "01" maskedPan: description: "Masked PAN from INSE, available since 23R3." type: "string" minLength: 13 maxLength: 19 examples: - "497670xxxxxxxx14" maskedVPan: description: "Masked Virtual PAN from INSE, available since 23R3." type: "string" minLength: 13 maxLength: 19 examples: - "817080xxxxxxxx16" merchant: $ref: '#/components/schemas/Merchant' messageCategory: description: | Identifies the category of the message for a specific use case. - **01**: PA - **02**: NPA - **03–79**: Reserved for EMVCo future use (values invalid until defined by EMVCo) - **80–99**: Reserved for DS use type: "string" minLength: 2 maxLength: 2 examples: - "01" network: description: "DS network of the purchase Transaction." type: "string" minLength: 1 maxLength: 50 enum: - "BANCONTACT" - "CB" - "MAESTRO" - "MASTERCARD" - "VISA" examples: - "MASTERCARD" purchaseDate: description: "Date and time of the authentication converted into UTC. Date provided by merchant in AReq message." type: "string" format: "yyyyMMddHHmmss" examples: - "20191223141802" purchaseInstalData: description: "Indicates the maximum number of authorizations permitted for instalment payments, available since 24R2" type: "string" maxLength: 3 examples: - "2" - "02" - "002" recurringDate: description: "Effective date of the new authorised amount following the first / promotional payment in a recurring or instalment transaction, available since 24R2" type: "string" minLength: 8 maxLength: 8 format: "yyyyMMdd" examples: - "20241223" recurringExpiry: description: "Date after which no further authorisations are performed, available since 24R2" type: "string" minLength: 8 maxLength: 8 format: "yyyyMMdd" examples: - "20251223" recurringFrequency: description: "Indicates the minimum number of days between authorizations for a recurring or instalment transaction, available since 24R2" type: "string" maxLength: 4 examples: - "31" - "031" - "0031" threeDSRequestorAuthenticationInd: description: | Indicates the type of Authentication request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request. - **01**: Payment transaction - **02**: Recurring transaction - **03**: Instalment transaction - **04**: Add card - **05**: Maintain card - **06**: Cardholder verification as part of EMV token ID&V - **07–79**: Reserved for EMVCo future use (values invalid until defined by EMVCo) - **80–99**: Reserved for DS use type: "string" minLength: 2 maxLength: 2 examples: - "01" threeDSRequestorDecMaxTime: description: "Indicates 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)." type: "string" minLength: 1 maxLength: 5 format: "Numeric String between 1 and 10080." examples: - "180" threeDSRequestorDecReqInd: description: | Indicates whether the 3DS Requestor requests the ACS to utilise decoupled authentication and agrees to utilise decoupled authentication if the ACS confirms its use. - **Y**: Decoupled authentication is supported and preferred if challenge is necessary - **N**: Do not use decoupled authentication Note: if the element is not provided, the expected action is for the ACS to interpret as N, do not use decoupled authentication. type: "string" minLength: 1 maxLength: 1 format: "'Y' or 'N'" pattern: "^[YN]$" examples: - "Y" - "N" threeRIInd: description: | Indicates the type of 3RI request. This data element provides additional information to the ACS to determine the best approach for handing an authentication request - **01**: Recurring transaction - **02**: Instalment transaction - **03**: Add card - **04**: Maintain card information - **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 (values invalid until defined by EMVCo) - **80–99**: Reserved for DS use type: "string" minLength: 2 maxLength: 2 examples: - "01" transactionDate: description: "Date of the transaction." type: "string" format: "String of characters complying with the ISO 8601 datetime format (yyyy-MM-ddTHH:mm:ss)" examples: - "2023-09-23T14:18:02" ua: description: "User Agent of the Browser used during 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" EchoBody: description: "EchoBody DTO resource representation." type: "object" required: - "timestamp" properties: timestamp: description: "Timestamp." type: "string" format: "yyyy-MM-dd HH:mm:ss.SSS" examples: - "2016-11-16 06:43:19.773" EchoMessage: description: "EchoMessage DTO resource representation." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/EchoBody' footer: $ref: '#/components/schemas/Footer' ErrorResponse: description: "Error response DTO resource representation." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: description: "Error response body." type: "object" required: - "errorCode" properties: errorCode: description: | Code on 5 digits to detail the error. Here is the list of defined functional error codes and their meaning:
Click to expand | HTTP code | Error code | Description | | --- | --- | --- | | 400 | **400**01 | Invalid issuer or sub-issuer code | | 400 | **400**02 | Invalid service | | 400 | **400**03 | Invalid requestId | | 400 | **400**04 | Invalid keyTag | | 400 | **400**11 | Invalid principal value or type | | 400 | **400**12 | Invalid expiry value or type | | 400 | **400**14 | Invalid credentials value or type | | 400 | **400**30 | Invalid algorithm or keyInfo | | 401 | **401**01 | Oauth empty date | | 401 | **401**02 | Oauth invalid date | | 401 | **401**03 | Signature client id not provided | | 401 | **401**04 | Invalid signature | | 401 | **401**05 | Invalid access token | | 401 | **401**06 | Invalid payload | | 401 | **401**07 | Invalid access token scope | | 401 | **401**08 | Expired access token | | 403 | **403**03 | Card not enrolled | | 403 | **403**11 | Card blocked | | 403 | **403**12 | Card temporary blocked | | 403 | **403**31 | Invalid signature | | 404 | **404**01 | Card not found |
type: "integer" minimum: 10000 maximum: 99999 format: "int32" examples: - 40001 errorInfo: description: "External error code." type: "string" footer: $ref: '#/components/schemas/Footer' Footer: description: "Not used." deprecated: true type: "object" properties: signature: $ref: '#/components/schemas/Signature' examples: - {} Header: description: "Metadata of the message." type: "object" required: - "requestId" - "service" - "issuerCode" - "subIssuerCode" properties: requestId: description: "Unique identifier of the request." type: "string" format: "uuid" examples: - "d6156f8a-a504-48c4-8f5a-722606bd3d91" service: description: "Service code (defined during project)." type: "string" minLength: 1 maxLength: 255 examples: - "ACS_H0A" issuerCode: description: "Issuer code." type: "string" minLength: 5 maxLength: 5 examples: - "66666" subIssuerCode: description: "Sub-issuer code." type: "string" minLength: 5 maxLength: 5 examples: - "66666" keyTag: description: "Key indicator shared between client and server. If `keyTag` is provided, then this reference should be used to encrypt / decrypt sensitive data (PAN, expiry date)." type: "string" minLength: 2 maxLength: 2 examples: - "01" iv: oneOf: - description: "IV value used for **CBC** encryption. IV is provided only if HUB's IV configuration is set to \"RANDOM\"." type: "string" minLength: 32 maxLength: 32 examples: - "d6156f8aa50448c48f5a722606bd3d91" - description: "IV value used for **GCM** encryption. IV is provided only if HUB's IV configuration is set to \"RANDOM\"." type: "string" minLength: 24 maxLength: 24 examples: - "d6156f8aa50448c48f5a7226" Merchant: description: "Merchant information." type: "object" properties: id: description: "ID of the merchant." type: "string" minLength: 1 maxLength: 255 examples: - "123456789" name: description: "Name of the merchant." type: "string" minLength: 1 maxLength: 1024 examples: - "MY SHOPPING" url: description: "URL of the merchant." type: "string" minLength: 1 maxLength: 2048 examples: - "www.myshopping.com" country: description: "Country code of the merchant." type: "string" minLength: 3 maxLength: 3 format: "ISO 3166 standard" examples: - "250" MessageClientRequestBody: description: "Generic container for every message." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ClientRequestBody' footer: $ref: '#/components/schemas/Footer' signature: $ref: '#/components/schemas/RootSignature' MessageClientResponseBody: description: "Generic container for every message." type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ClientResponseBody' footer: $ref: '#/components/schemas/Footer' signature: $ref: '#/components/schemas/RootSignature' MessageGetCardResponse: type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ClientResponseBody' footer: $ref: '#/components/schemas/Footer' signature: $ref: '#/components/schemas/RootSignature' MessageUpdateCardResponse: type: "object" required: - "header" - "body" properties: header: $ref: '#/components/schemas/Header' body: $ref: '#/components/schemas/ClientResponseBody' footer: $ref: '#/components/schemas/Footer' signature: $ref: '#/components/schemas/RootSignature' Signature: description: "Not used. For signature feature, please refer to the `signature` field at the root of the messages." deprecated: true type: "object" properties: algorithm: description: "Algorithm." type: "string" keyInfo: description: "Key info." type: "string" value: description: "Value." type: "string" TypeValue: description: "Type and value pair." type: "object" required: - "type" - "value" properties: type: description: "Type." type: "string" format: "enum" value: description: "Value." type: "string" minLength: 1 RootSignature: description: "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" type: "string"