> ## Documentation Index > Fetch the complete documentation index at: https://docs.tagada.io/llms.txt > Use this file to discover all available pages before exploring further. # Create 3DS session from external authentication values (bring your own 3DS) > You already run 3-D Secure with your own MPI / 3DS server and only want Tagada to charge. Report the final authentication values (ECI, CAVV/AAV, DS transaction id, protocol version) and Tagada stores them as an already-authenticated 3DS session. Pass the returned `id` as `threedsSessionId` to `POST /payments/process` (or `/checkout/pay-v2`): the values are forwarded verbatim to the acquirer — no challenge, no redirect, no Tagada-side authentication. **When to use it** - You collect cards and run 3DS in your own PCI environment and use Tagada as one PSP among others. - You authenticated once (3RI / `type: merchant`) and charge later as a MIT — pair it with `initiatedBy: 'merchant'` on the charge. **Rules** - Only `transStatus` `Y` (authenticated) and `A` (attempted, network stand-in) create a usable session; `N` / `U` / `R` / `I` are stored as failed and the charge is declined at the 3DS step. - `dsTransID` is required for a 3DS 2.x result with `Y` / `A` — acquirers reject the charge without it. - The values are forwarded as-is; the acquirer validates the CAVV. Liability shift follows the scheme rules for the ECI you report, not a Tagada decision. **Acquirer support** — the target processor must accept externally-authenticated values: NMI, RouteSense, Mastercard MPGS, Adyen (`mpiData`), Airwallex (`external_three_ds`). Hosted-3DS PSPs (Stripe, Checkout.com) ignore them and run their own 3DS. The processor must have `enable3DS` on and the payment flow `threeDsEnabled`. Also used by the internal payment sandbox to replay specific 3DS outcomes. **Requires:** org:admin role ## OpenAPI ````yaml /openapi.json post /api/public/v1/threeds/create-from-values openapi: 3.0.3 info: title: TagadaPay API description: >- # TagadaPay API Documentation Welcome to the TagadaPay API. This REST API lets you process payments, manage subscriptions, handle customers, deploy plugins, and orchestrate checkout funnels — all programmatically. ## Authentication Authenticate every request with a Bearer token. Get your API key from the [TagadaPay Dashboard](https://app.tagada.io). ``` Authorization: Bearer your-api-key ``` All requests must be made over HTTPS with `Content-Type: application/json`. ## Rate Limits | Plan | Requests/min | Burst | |------|-------------|-------| | Standard | 100 | 150 | | Premium | 500 | 750 | Exceeding the limit returns `429 Too Many Requests`. ## Errors | Code | Meaning | |------|---------| | 400 | Bad request — invalid parameters | | 401 | Unauthorized — missing or invalid API key | | 403 | Forbidden — insufficient permissions | | 404 | Not found | | 409 | Conflict | | 429 | Rate limited | | 500 | Server error | ## Support - Email: api-support@tagada.io - Docs: [docs.tagadapay.com](https://docs.tagadapay.com) version: 1.0.0 servers: - url: https://api.tagada.io/ description: Production - url: https://api.tagada.dev/ description: Sandbox / Development security: - bearerAuth: [] tags: - name: auth description: Test your API key and verify authentication. - name: stores description: Create and manage stores within your account. - name: products description: Create products with variants, prices, and currency options. - name: customers description: Manage customer records, addresses, and payment instruments. - name: orders description: List and retrieve orders with line items, payments, and metadata. - name: payments description: Process, list, refund, void, and dispute payments. - name: subscriptions description: >- Create and manage recurring subscriptions — billing, cancellation, rebilling, and processor changes. - name: payment-flows description: Configure payment routing strategies with cascading processor fallbacks. - name: payment-instruments description: >- Manage stored payment methods — cards, bank accounts, and tokenized instruments. - name: processors description: List connected payment processors (Stripe, NMI, Checkout.com, etc.). - name: promotions description: Create and manage discount promotions with rules and conditions. - name: promotion-codes description: Generate and manage reusable promotion/coupon codes. - name: block-rules description: >- Configure fraud prevention rules to block transactions by IP, email, card BIN, country, etc. - name: webhooks description: Register webhook endpoints to receive real-time event notifications. - name: events description: Query application events, statistics, and audit logs. - name: domains description: Add, verify, and manage custom domains for your checkout and funnels. - name: funnels description: >- Create and manage checkout funnels with routing, A/B testing, and CDN deployment. - name: funnel-sessions description: Retrieve funnel session data for analytics and debugging. - name: funnel-tracking description: Track funnel step events for conversion analytics. - name: plugins description: Deploy, manage, and configure checkout plugins. - name: plugins-v2 description: >- V2 plugin system — deploy, mount, split-test, fork, promote, and manage plugin instances. - name: checkout description: >- Initialize checkout sessions and process payments through the hosted checkout. - name: 3ds description: >- 3D Secure authentication — create sessions, authenticate, and handle challenges. - name: builder description: Generate and validate builder session tokens for the visual page editor. - name: health description: API health check endpoint. - name: test description: Test and debugging utilities for the event system (sandbox only). paths: /api/public/v1/threeds/create-from-values: post: tags: - 3ds summary: >- Create 3DS session from external authentication values (bring your own 3DS) description: >- You already run 3-D Secure with your own MPI / 3DS server and only want Tagada to charge. Report the final authentication values (ECI, CAVV/AAV, DS transaction id, protocol version) and Tagada stores them as an already-authenticated 3DS session. Pass the returned `id` as `threedsSessionId` to `POST /payments/process` (or `/checkout/pay-v2`): the values are forwarded verbatim to the acquirer — no challenge, no redirect, no Tagada-side authentication. **When to use it** - You collect cards and run 3DS in your own PCI environment and use Tagada as one PSP among others. - You authenticated once (3RI / `type: merchant`) and charge later as a MIT — pair it with `initiatedBy: 'merchant'` on the charge. **Rules** - Only `transStatus` `Y` (authenticated) and `A` (attempted, network stand-in) create a usable session; `N` / `U` / `R` / `I` are stored as failed and the charge is declined at the 3DS step. - `dsTransID` is required for a 3DS 2.x result with `Y` / `A` — acquirers reject the charge without it. - The values are forwarded as-is; the acquirer validates the CAVV. Liability shift follows the scheme rules for the ECI you report, not a Tagada decision. **Acquirer support** — the target processor must accept externally-authenticated values: NMI, RouteSense, Mastercard MPGS, Adyen (`mpiData`), Airwallex (`external_three_ds`). Hosted-3DS PSPs (Stripe, Checkout.com) ignore them and run their own 3DS. The processor must have `enable3DS` on and the payment flow `threeDsEnabled`. Also used by the internal payment sandbox to replay specific 3DS outcomes. **Requires:** org:admin role operationId: post-api-public-v1-threeds-create-from-values parameters: [] requestBody: required: true content: application/json: schema: type: object properties: eci: type: string pattern: ^\d{2}$ description: >- Electronic Commerce Indicator returned by the 3DS server (e.g. 05 / 06 Visa, 02 / 01 Mastercard) authenticationValue: type: string minLength: 1 maxLength: 128 description: >- CAVV (Visa, Amex, Discover) or AAV (Mastercard), base64 as returned by the 3DS server transStatus: type: string enum: - 'Y' - A - 'N' - U - R - I default: 'Y' description: >- Final EMVCo transaction status: Y authenticated, A attempted (stand-in), N failed, U unavailable, R rejected, I informational. Only Y and A produce a usable session. dsTransID: type: string minLength: 1 maxLength: 36 description: >- Directory Server transaction id (UUID). Required for 3DS 2.x results with transStatus Y or A. acsTransID: type: string minLength: 1 maxLength: 36 description: ACS transaction id (UUID), when your 3DS server exposes it threeDSServerTransID: type: string minLength: 1 maxLength: 36 description: >- 3DS Server transaction id (UUID), when your 3DS server exposes it messageVersion: type: string pattern: ^(1\.0\.2|2\.\d\.\d)$ default: 2.2.0 description: >- EMVCo 3DS protocol version used for the authentication (e.g. 2.2.0) cardBrand: type: string maxLength: 32 description: >- Card brand the authentication ran on (visa, mastercard, amex…) type: type: string enum: - customer - merchant default: customer description: >- customer for a cardholder-present (CIT) authentication, merchant for a 3RI / MIT authentication required: - eci - authenticationValue additionalProperties: false examples: frictionless: summary: Visa, 3DS 2.2 frictionless (Y) value: eci: '05' authenticationValue: AAABBIIFmAAAAAAAAAWYAAAAAAA= transStatus: 'Y' dsTransID: dd21fcc9-6725-4a82-9591-ce603405b0db acsTransID: 4f1b6a0e-1b6d-4a7c-9a4e-2f7f0d5e1c22 messageVersion: 2.2.0 cardBrand: visa attempted: summary: Mastercard, attempted / stand-in (A) value: eci: '01' authenticationValue: kBMIQaJvIhEUgwQH9EFvuVIAAAA= transStatus: A dsTransID: 2b4d0a1e-5c6f-4e8a-9b0c-1d2e3f4a5b6c messageVersion: 2.2.0 cardBrand: mastercard merchantInitiated: summary: 3RI authentication for a later MIT charge value: type: merchant eci: '05' authenticationValue: AAABBIIFmAAAAAAAAAWYAAAAAAA= transStatus: 'Y' dsTransID: dd21fcc9-6725-4a82-9591-ce603405b0db messageVersion: 2.2.0 responses: '200': description: Successful response content: application/json: schema: {} default: $ref: '#/components/responses/error' security: - bearerAuth: [] components: responses: error: description: Error response content: application/json: schema: type: object properties: message: type: string code: type: string issues: type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'Enter your API key as: `Bearer your-api-key`' ````