> ## Documentation Index > Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt > Use this file to discover all available pages before exploring further. # Initiate 3DS authentication > Creates a 3D Secure authentication object. The response may include `fingerprintingUrl` (render in a hidden iframe and listen for postMessage) or `challengeUrl` (render in a visible iframe for user challenge). **Authentication:** Uses the merchant's **public/publishable key** (`pk_...`) in the Authorization header as Basic auth username. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/three-ds/authenticate openapi: 3.0.0 info: title: FastPay API version: 1.0.0 description: >- API for creating and managing payment charges. ## Authentication This API uses **Basic Authentication** for direct API access, such as creating charges. Use your API key as the username and an empty string as password. The header should be formatted as: `Authorization: Basic {base64(apiKey:)}`. For example: ``` Authorization: Basic YWxleG91dG9uOiIi ``` ## Webhooks FastPay sends webhooks to notify your application about charge status changes in real-time. Webhooks are sent via HTTP POST requests to your configured webhook endpoints. ### Webhook Events The following webhook events are available for charges: - `charge.created` - Sent when a new charge is created - `charge.pending` - Sent when a charge is pending payment - `charge.paid` - Sent when a charge is successfully paid - `charge.updated` - Sent when a charge is updated ### Webhook Payload Structure All webhook payloads follow this structure: ```json { "id": "webhook_event_id", "event": "charge.paid", "data": { // Complete charge object } } ``` ### Webhook Delivery - Webhooks are sent via HTTP POST requests - Content-Type: `application/json` - Retry logic is implemented for failed deliveries - Webhook events are stored in the database for audit purposes - Delivery logs are maintained for debugging and monitoring ### Webhook Security - Webhooks are sent to pre-configured endpoints - Endpoints can be enabled/disabled per merchant - Event filtering is supported (only receive specific events) - Failed deliveries are retried with exponential backoff servers: - url: https://api-global.fastpaybrasil.com description: Produção e Sandbox (diferenciados pela API key) security: [] paths: /v1/three-ds/authenticate: post: tags: - 3D Secure summary: Initiate 3DS authentication description: >- Creates a 3D Secure authentication object. The response may include `fingerprintingUrl` (render in a hidden iframe and listen for postMessage) or `challengeUrl` (render in a visible iframe for user challenge). **Authentication:** Uses the merchant's **public/publishable key** (`pk_...`) in the Authorization header as Basic auth username. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ThreeDSAuthenticateRequest' responses: '200': description: Authentication initiated successfully content: application/json: schema: $ref: '#/components/schemas/ThreeDSAuthenticateResponse' '404': description: No 3DS provider configured for this merchant content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - basic: [] components: schemas: ThreeDSAuthenticateRequest: type: object required: - amount - currency - card - browser properties: amount: type: number description: Transaction amount in the currency of the transaction example: 100 currency: type: string description: ISO 4217 currency code example: BRL card: type: object required: - number - expirationMonth - expirationYear properties: number: type: string description: Card number example: '4111111111111111' holderName: type: string description: Cardholder name example: John Doe expirationMonth: type: string description: Expiration month (1-12, 1-2 digits) example: '12' expirationYear: type: string description: Expiration year (4 digits) example: '2025' browser: $ref: '#/components/schemas/BrowserInfo' ThreeDSAuthenticateResponse: type: object properties: authenticationId: type: string description: 3DS Authentication ID — pass this to submit/cancel/challenge-result example: tdsa_1QmCRMJM0r9zBvr4OVmMRa6X status: type: string enum: - requires_submission - requires_challenge - succeeded - failed - error - canceled - processing description: Current authentication status example: requires_submission fingerprintingUrl: type: string nullable: true description: |- URL to render in a hidden iframe. Listen for postMessage events with `fingerprintingResult` and then call POST /v1/three-ds/submit. example: >- https://hooks.stripe.com/three_d_secure/fingerprint/acct_xxx/tdsa_xxx challengeUrl: type: string nullable: true description: >- URL to render in a visible iframe when status is `requires_challenge`. example: https://hooks.stripe.com/three_d_secure/challenge/acct_xxx/tdsa_xxx outcome: type: string nullable: true enum: - authenticated - informational - attempt_acknowledged - rejected - denied - abandoned - not_supported - processing_error - internal_error - canceled description: Authentication outcome (only present in terminal states) example: authenticated ErrorResponse: type: object properties: statusCode: type: integer description: HTTP status code example: 422 message: type: string description: Descriptive error message example: SubMerchant is not active error: type: string description: Error type example: Unprocessable Entity BrowserInfo: type: object description: >- Browser data collected from the customer's browser for 3DS authentication. required: - userAgent - ipAddress properties: userAgent: type: string description: Browser user agent string example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ipAddress: type: string description: Customer IP address example: 177.128.144.97 acceptHeader: type: string description: Browser Accept header value example: text/html,application/xhtml+xml language: type: string description: Browser language example: pt-BR timezoneOffset: type: integer description: Timezone offset in minutes from UTC example: -180 javascriptEnabled: type: boolean description: Whether JavaScript is enabled example: true javaEnabled: type: boolean description: Whether Java is enabled example: false screenWidth: type: integer description: Screen width in pixels example: 1920 screenHeight: type: integer description: Screen height in pixels example: 1080 colorDepth: type: integer description: Screen color depth in bits example: 24 securitySchemes: basic: type: http scheme: basic description: |- HTTP Basic authentication. Use your secret key as the username and an empty string as password. The API key should be base64 encoded in the format 'username:' when sending the Authorization header. ````