---
title: "Create 3RI Authentication"
method: POST
path: "/3ds/3ri"
tags: ["3DS Authentication"]
---

# Create 3RI Authentication

`POST /3ds/3ri`

## Request

- Base URL: `https://eu-west-1.api.silverflow.com/v1`
- URL: `https://eu-west-1.api.silverflow.com/v1/3ds/3ri`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
- TypeScript: <https://skmtc.dev/silverflow/apis/silverflow-api/docs/3ds/3ri/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a new 3RI authentication. Also known as merchant-initiated authentications, allows merchants to authenticate a transaction without the direct involvement of the cardholder.

Requires the `threeDs:Create` permission.

Diners support is <a class="experimental-tag-link" href="https://docs.silverflow.com/guides/api-lifecycle#tag/EXPERIMENTAL-Tag"><span class="tag experimental-tag">EXPERIMENTAL</span></a>. 

Standalone merchant info (`merchantInfo`) is <a class="experimental-tag-link" href="https://docs.silverflow.com/guides/api-lifecycle#tag/EXPERIMENTAL-Tag"><span class="tag experimental-tag">EXPERIMENTAL</span></a>.

## Request body

- union
  - ThreeRiRequestWithMerchantAcceptor: Initiate a 3RI authentication using an existing merchant acceptor. This requires prior onboarding of the merchant acceptor in the Silverflow system.
    - `merchantAcceptorResolver` MerchantAcceptorResolver, required: The resolver is used to select the appropriate merchant acceptor for doing the authentication.
      - `merchantAcceptorKey` string, required: Uniquely identifies a merchant acceptor.
    - `card` union, required: This field represents the card. The card credentials can either be passed directly in the request or be referenced using a `key`.
      - InputCard: Card data
        - `number` string, password, required: Full digits of the card or network token.
        - `expiryMonth` integer, required: The month the card or network token expires. January is 1
        - `expiryYear` integer, required: The year the card or network token expires including the century
        - `cvc` string: The CVC of the card
        - `holderName` string: The name of the cardholder as displayed on the card. It will be truncated if longer than 45 characters. The name needs to comply with the following regular expression: `^[\x20-\x7E\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$` More information here: [Cardholder name restrictions](charges.html#section/Appendix-A-Cardholder-Name-Restrictions)
      - CardByProcessorTokenKey
        - `processorTokenKey` string, required: The key to a card stored using [Processor Tokenization](#tag/Processor-Tokenization).
        - `cvc` string: The CVC of the card
    - `threeRiIndicator` 'recurring' | 'ucof' | 'installment' | 'standing-order', required: Indicates the type of 3RI request. This property provides additional information to the ACS to determine the best approach for handling a 3RI request.
    - `amount` Amount, required: An amount encoded as an object with a `value` in minor units and a `currency` code.
      - `value` integer, required: The amount in minor units. For example `$12.34` should be encoded as `1234`. Note that not all currencies have 2 minor units. Some have three or zero.
      - `currency` string, required
    - `cardholderInformation` CardholderInformation: Extra information about the cardholder.
      - `email` string: The email address associated with the cardholder account. This address is either entered by the cardholder or is on file with the 3DS Requester.
      - `phone` object: Phone numbers associated with the account. They follow the [ITU-E.164 standard](https://en.wikipedia.org/wiki/E.164).
        - `work` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
        - `mobile` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
        - `home` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
    - `billingAddress` AddressInput: A physical postal address
      - `countryCode` union, required: ISO 3166-1 country code
        - object
          - `alpha3` string, required: ISO 3166-1 alpha-3 country code
        - object
          - `alpha2` string, required: ISO 3166-1 alpha-2 country code
        - object
          - `numeric` string, required: ISO 3166-1 numeric country code
      - `stateOrProvince` string: The state (US) or province (non-US) of the address.
      - `city` string, required: The city of the address.
      - `line1` string, required: Address line 1
      - `line2` string: Address line 2
      - `postalCode` string, required: The postal code of the address, allowing spaces and dashes
    - `transactionReference` string: Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction.
    - `threeDsPriorAuthenticationInfo` ThreeDsPriorAuthenticationInfo, required: References the initial 3DS transaction to set up this sequence.
      - `authMethod` 'frictionless' | 'challenge', required: The authentication method used.
      - `dateTime` string, iso-8601-date-time, required: The date and time of the authentication.
      - `acsTransId` string, required: The ACS (Access Control Server) transaction ID.
      - `dsTransId` string, required: The DS (Directory Server) transaction ID.
    - `recurringExpiry` string, date: The date at which the recurring authorization expires. This property is required for `threeRiIndicator = "recurring"`, `"installment"`, or `"standing-order"`. For other cases, it will default to `2050-12-31`, indicating no expiry date is specified. Format: YYYY-MM-DD.
    - `recurringFrequency` integer: Number of days between recurring authorizations. This property is required for `threeRiIndicator = "recurring"`, `"installment"`, or `"standing-order"`. For other cases, it will default to `1`, indicating that the frequency of payments is not specified.
    - `installmentTerms` integer: Maximum number of authorizations for an installment payment. Required for and only allowed when `threeRiIndicator = "installment"`. Must be greater than 1 and at most 3 digits (max value 999).
  - ThreeRiRequestWithMerchantInfo: Initiate a 3RI authentication by providing merchant information directly. This allows performing 3RI without requiring merchant acceptor onboarding.
    - `merchantInfo` MerchantInfoRequest, required: Merchant details provided directly in the request, as an alternative to providing a `merchantAcceptorKey`.
      - `acquirerBin` string: 6-11 digit Bank Identification Number assigned by the card network. Required for all card networks except AMEX. For AMEX populate this with the SE Number or leave blank depending on the model, see [3DS Guide](https://docs.silverflow.com/guides/3d-secure#tag/Supporting-Different-AMEX-Models).
      - `merchantId` string, required: Merchant identifier (MID) assigned by the acquirer. For AMEX populate this with the Seller ID or SE Number depending on the model, see [3DS Guide](https://docs.silverflow.com/guides/3d-secure#tag/Supporting-Different-AMEX-Models).
      - `mcc` string, required: 4-digit ISO 18245 merchant category code
      - `merchantName` string, required: Merchant's doing-business-as name
      - `merchantCountryCode` union, required: ISO 3166-1 country code. Can be provided in alpha-2, alpha-3, or numeric format
        - SchemasCountryCodeAlpha3
          - `alpha3` string, required: ISO 3166-1 alpha-3 country code
        - SchemasCountryCodeAlpha2
          - `alpha2` string, required: ISO 3166-1 alpha-2 country code
        - SchemasCountryCodeNumeric
          - `numeric` string, required: ISO 3166-1 numeric country code
      - `websiteUrl` string, required: Merchant's website URL
      - `network` 'american-express' | 'bancontact' | 'diners' | 'mastercard' | 'visa', required: The card network to query for PAN information. Diners support is <a class="experimental-tag-link" href="https://docs.silverflow.com/guides/api-lifecycle#tag/EXPERIMENTAL-Tag"><span class="tag experimental-tag">EXPERIMENTAL</span></a>.
    - `card` union, required: This field represents the card. The card credentials can either be passed directly in the request or be referenced using a `key`.
      - InputCard: Card data
        - `number` string, password, required: Full digits of the card or network token.
        - `expiryMonth` integer, required: The month the card or network token expires. January is 1
        - `expiryYear` integer, required: The year the card or network token expires including the century
        - `cvc` string: The CVC of the card
        - `holderName` string: The name of the cardholder as displayed on the card. It will be truncated if longer than 45 characters. The name needs to comply with the following regular expression: `^[\x20-\x7E\u00C0-\u00D6\u00D8-\u00F6\u00F8-\u00FF]+$` More information here: [Cardholder name restrictions](charges.html#section/Appendix-A-Cardholder-Name-Restrictions)
      - CardByProcessorTokenKey
        - `processorTokenKey` string, required: The key to a card stored using [Processor Tokenization](#tag/Processor-Tokenization).
        - `cvc` string: The CVC of the card
    - `threeRiIndicator` 'recurring' | 'ucof' | 'installment' | 'standing-order', required: Indicates the type of 3RI request. This property provides additional information to the ACS to determine the best approach for handling a 3RI request.
    - `amount` Amount, required: An amount encoded as an object with a `value` in minor units and a `currency` code.
      - `value` integer, required: The amount in minor units. For example `$12.34` should be encoded as `1234`. Note that not all currencies have 2 minor units. Some have three or zero.
      - `currency` string, required
    - `cardholderInformation` CardholderInformation: Extra information about the cardholder.
      - `email` string: The email address associated with the cardholder account. This address is either entered by the cardholder or is on file with the 3DS Requester.
      - `phone` object: Phone numbers associated with the account. They follow the [ITU-E.164 standard](https://en.wikipedia.org/wiki/E.164).
        - `work` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
        - `mobile` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
        - `home` PhoneNumber
          - `countryCode` string, required: Country code should be between 1 to 3 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
          - `number` string, required: Phone number should be between 1 and 15 digits, more information [here](https://en.wikipedia.org/wiki/E.164).
    - `billingAddress` AddressInput: A physical postal address
      - `countryCode` union, required: ISO 3166-1 country code
        - object
          - `alpha3` string, required: ISO 3166-1 alpha-3 country code
        - object
          - `alpha2` string, required: ISO 3166-1 alpha-2 country code
        - object
          - `numeric` string, required: ISO 3166-1 numeric country code
      - `stateOrProvince` string: The state (US) or province (non-US) of the address.
      - `city` string, required: The city of the address.
      - `line1` string, required: Address line 1
      - `line2` string: Address line 2
      - `postalCode` string, required: The postal code of the address, allowing spaces and dashes
    - `transactionReference` string: Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction.
    - `threeDsPriorAuthenticationInfo` ThreeDsPriorAuthenticationInfo, required: References the initial 3DS transaction to set up this sequence.
      - `authMethod` 'frictionless' | 'challenge', required: The authentication method used.
      - `dateTime` string, iso-8601-date-time, required: The date and time of the authentication.
      - `acsTransId` string, required: The ACS (Access Control Server) transaction ID.
      - `dsTransId` string, required: The DS (Directory Server) transaction ID.
    - `recurringExpiry` string, date: The date at which the recurring authorization expires. This property is required for `threeRiIndicator = "recurring"`, `"installment"`, or `"standing-order"`. For other cases, it will default to `2050-12-31`, indicating no expiry date is specified. Format: YYYY-MM-DD.
    - `recurringFrequency` integer: Number of days between recurring authorizations. This property is required for `threeRiIndicator = "recurring"`, `"installment"`, or `"standing-order"`. For other cases, it will default to `1`, indicating that the frequency of payments is not specified.
    - `installmentTerms` integer: Maximum number of authorizations for an installment payment. Required for and only allowed when `threeRiIndicator = "installment"`. Must be greater than 1 and at most 3 digits (max value 999).

## Response `201`

The 3RI authentication entity

- ThreeRiResponse
  - `key` string, required: Uniquely identifies a 3DS authentication.
  - `merchantAcceptorRef` SchemasAcceptorRef: Reference key and status of the acceptor
    - `key` string, required: Uniquely identifies a merchant acceptor.
    - `version` integer, required: The version of this object
  - `merchantInfo` MerchantInfoResponse: Merchant details as stored and returned in the response. The `merchantCountryCode` is returned as a complete ISO 3166-1 country code object containing all representations.
    - `acquirerBin` string: 6-11 digit Bank Identification Number assigned by the card network. Required for all card networks except AMEX.
    - `merchantId` string, required: Merchant identifier (MID) assigned by the acquirer.
    - `mcc` string, required: 4-digit ISO 18245 merchant category code
    - `merchantName` string, required: Merchant's doing-business-as name
    - `merchantCountryCode` object, required
      - `alpha3` string, required: ISO 3166-1 alpha-3 country code
      - `alpha2` string, required: ISO 3166-1 alpha-2 country code
      - `numeric` string, required: ISO 3166-1 numeric country code
    - `websiteUrl` string, required: Merchant's website URL
    - `network` 'american-express' | 'bancontact' | 'diners' | 'mastercard' | 'visa', required: The card network to query for PAN information. Diners support is <a class="experimental-tag-link" href="https://docs.silverflow.com/guides/api-lifecycle#tag/EXPERIMENTAL-Tag"><span class="tag experimental-tag">EXPERIMENTAL</span></a>.
  - `amount` union, required: An amount encoded as an object with a `value` in minor units and a `currency` code. The amount is unknown for entities older than 2023-03-30.
    - Amount: An amount encoded as an object with a `value` in minor units and a `currency` code.
      - `value` integer, required: The amount in minor units. For example `$12.34` should be encoded as `1234`. Note that not all currencies have 2 minor units. Some have three or zero.
      - `currency` string, required
    - UnknownAmount
      - `value` -1, required: The value of the amount is unknown.
      - `currency` 'unknown', required: The currency code is unknown.
  - `network` 'american-express' | 'bancontact' | 'diners' | 'mastercard' | 'visa' | 'unknown', required: The card network that was used for the authentication. It is `unknown` for entities older than 2024-04-11.
  - `protocolVersion` '2.2.0', required: The 3DS protocol version which has been used to perform 3DS. For 3RI it's always 2.2.0
  - `deviceChannel` '3ri', required: Indicates the type of the interface used to initiate the transaction.
  - `result` 'authenticated' | 'non-authenticated', required: Authentication result.
  - `ares` ThreeRiARes, required: The issuer's response to the 3DS request.
    - `threeDSServerTransID` string, required: Universally unique transaction identifier assigned by the 3DS server to identify a single transaction. This identifier is assigned by Silverflow.
    - `messageExtension` MessageExtension[]: Carries additional data that is not defined within the 3DS protocol. This field is usually used for card network specific data.
      - `name` string, required
      - `id` string, required
      - `criticalityIndicator` boolean, required
      - `data` unknown, required
    - `messageType` 'ARes', required
    - `dsTransID` string, uuid, required: Universally unique transaction identifier assigned by the DS to identify a single transaction.
    - `acsTransID` string, uuid, required: Universally unique transaction identifier assigned by the ACS to identify a single transaction. Each DS can provide a unique ID to each ACS on an individual basis.
    - `transStatus` 'Y' | 'N' | 'R', required: Indicates whether a transaction is authenticated or not. - `Y` indicates authenticated - `N` indicates not authenticated - `R` indicates rejected
    - `messageVersion` '2.2.0', required: The 3DS protocol version which has been used to perform 3DS. For 3RI it's always 2.2.0.
    - `transStatusReason` string: Provides information on why the `transStatus` field has the specified value.
    - `cardholderInfo` string: Text provided by the ACS/issuer to cardholder during a frictionless or decoupled transaction.
    - `acsChallengeMandated` string: Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable.
    - `dsReferenceNumber` string, required: EMVCo-assigned unique identifier to track approved DS.
    - `acsReferenceNumber` string, required: Unique identifier assigned by the EMVCo secretariat upon testing and approval.
    - `acsOperatorID` string: DS assigned ACS identifier.
    - `acsDecConInd` string: Indicates whether the ACS confirms utilisation of decoupled authentication and agrees to utilize decoupled authentication to authenticate the cardholder.
    - `authenticationType` string: Indicates the type of authentication method the issuer will use to challenge the cardholder, whether in the ARes message or what was used by the ACS when in the RReq message.
    - `eci` string: Payment system-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder.
    - `whiteListStatus` string: Enables the communication of trusted beneficiary/whitelist status between the ACS, the DS and the 3DS requestor.
    - `whiteListStatusSource` string: This data element will be populated by the system setting Whitelist Status. Required if Whitelist Status is present.
    - `authenticationValue` string: The result value from the 3DS transaction received from the ACS. This value is no longer present on responses after 45 days have passed after the authentication. Note that Mastercard and Visa use a different underlying format. This property will only be present in the ARes if `transStatus` is `Y`, `A` and conditionally (by DS rules) `I`.
  - `transactionReference` string: Unique ID assigned by the merchant or payment service provider for the transaction. Used to identify the transaction.
  - `fraudLiability` 'acquirer' | 'issuer', required: Which party is liable in case of fraud.
  - `threeRiIndicator` 'recurring' | 'ucof' | 'installment' | 'standing-order', required: Indicates the type of 3RI request. This property provides additional information to the ACS to determine the best approach for handling a 3RI request.
  - `created` string, iso-8601-date-time, required: The date and time this object was created
  - `version` integer, required: The version of this object

## Other responses

- `400`: Bad Request
- `401`: Authentication Required
- `409`: Conflict
- `422`: Unprocessable Content
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/silverflow/apis/silverflow-api.md) - [All operations](https://skmtc.dev/silverflow/apis/silverflow-api/llms.txt) - [OpenAPI document](https://skmtc.dev/silverflow/apis/silverflow-api/revisions/43ecbe4fd6ea?raw)