> ## Documentation Index > Fetch the complete documentation index at: https://docs.cheqpay.mx/llms.txt > Use this file to discover all available pages before exploring further. # Initiate 3DS payer authentication > Initiates 3D Secure (3DS) payer authentication for a payment order. This endpoint must be called when a payment order is in PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED status. It processes device information and returns authentication details for completing the 3DS challenge. ## OpenAPI ````yaml /api-reference/orchestrator-openapi.json post /v2/payment-orders/{id}/payer-authentication openapi: 3.0.0 info: title: Payment Orchestrator API description: API documentation for the Payment Orchestrator service version: 1.0.0 servers: - url: https://api.sandbox.cheqpay.mx/pos description: Sandbox environment - url: https://prod.cheqpay.mx/pos description: Production environment security: - ApiKeyAuth: [] MerchantIdAuth: [] tags: - name: Customer description: Customer management endpoints (v1) - name: Customer V2 description: >- Customer management endpoints (v2) - merchant-scoped, no external ID required - name: Payment Order description: Payment order management endpoints - name: Checkout description: Payment checkout endpoints - name: Payment Method description: Payment method management endpoints - name: Subscription Plan description: Subscription plan management endpoints for recurring payments - name: Subscription description: Subscription management endpoints for recurring billing - name: Subscription Invoice description: Subscription invoice management endpoints paths: /v2/payment-orders/{id}/payer-authentication: post: tags: - Payment Order summary: Initiate 3DS payer authentication description: >- Initiates 3D Secure (3DS) payer authentication for a payment order. This endpoint must be called when a payment order is in PAYER_AUTHENTICATION_DEVICE_DATA_REQUIRED status. It processes device information and returns authentication details for completing the 3DS challenge. parameters: - name: id in: path required: true schema: type: string format: uuid description: Payment order ID requestBody: required: true content: application/json: schema: type: object required: - deviceInformation - collectionReferenceId - returnUrl properties: deviceInformation: type: object required: - ipAddress - userAgent - userAgentBrowserValue - httpAcceptBrowserValue - httpBrowserLanguage - httpBrowserJavaScriptEnabled - httpBrowserScreenWidth - httpBrowserScreenHeight properties: ipAddress: type: string description: Customer's IP address example: 192.168.1.1 userAgent: type: string description: Browser user agent string example: Mozilla/5.0 userAgentBrowserValue: type: string description: Browser type and version example: Chrome/120.0 httpAcceptBrowserValue: type: string description: HTTP Accept header value example: text/html,application/xhtml+xml httpBrowserLanguage: type: string description: Browser language setting example: en-US httpBrowserJavaScriptEnabled: type: boolean description: Whether JavaScript is enabled in the browser example: true httpBrowserScreenWidth: type: string description: Browser screen width in pixels example: '1920' httpBrowserScreenHeight: type: string description: Browser screen height in pixels example: '1080' collectionReferenceId: type: string description: Reference ID for the device data collection example: col_123456789 returnUrl: type: string format: uri-reference description: URL to redirect the user after authentication example: https://example.com/return example: deviceInformation: ipAddress: 192.168.1.1 userAgent: Mozilla/5.0 userAgentBrowserValue: Chrome/120.0 httpAcceptBrowserValue: text/html,application/xhtml+xml httpBrowserLanguage: en-US httpBrowserJavaScriptEnabled: true httpBrowserScreenWidth: '1920' httpBrowserScreenHeight: '1080' collectionReferenceId: col_123456789 returnUrl: https://example.com/return responses: '200': description: Payer authentication initiated successfully content: application/json: schema: type: object required: - id - status properties: id: type: string format: uuid description: Payment order ID example: 123e4567-e89b-12d3-a456-426614174000 externalId: type: string description: External payment order ID example: ORDER-123 status: type: string enum: - PENDING - PROCESSING - REFERENCE_GENERATED - AUTHORIZED - PARTIALLY_AUTHORIZED - ACTION_REQUIRED - PAYER_AUTHENTICATION_CHALLENGE_REQUIRED - COMPLETED - PARTIALLY_PAID - CANCELLATION_REQUESTED - CANCELLED - FAILED - REFUND_PROCESSING - PARTIALLY_REFUNDED - REFUNDED description: >- Payment order status (typically PAYER_AUTHENTICATION_CHALLENGE_REQUIRED after this call) example: PAYER_AUTHENTICATION_CHALLENGE_REQUIRED amount: type: number description: Payment amount example: 250 currency: type: string description: Currency code example: MXN customer: type: object description: Customer details payerAuthentication: type: object description: 3DS authentication details properties: id: type: string description: Payer authentication session ID example: payer-auth-123 url: type: string format: uri-reference description: URL for 3DS challenge (if required) example: https://bank.example.com/authenticate jwt: type: string description: JWT token for authentication (if required) example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... example: id: 123e4567-e89b-12d3-a456-426614174000 externalId: ORDER-123 status: PAYER_AUTHENTICATION_CHALLENGE_REQUIRED amount: 250 currency: MXN payerAuthentication: id: payer-auth-123 url: https://bank.example.com/authenticate jwt: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... '400': description: Validation failed or payment order in invalid status content: application/json: schema: oneOf: - $ref: '#/components/schemas/ValidationError' - type: object properties: message: type: string example: x-merchant-id header is required '401': description: Unauthorized - invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/UnauthorizedError' '404': description: Payment order not found content: application/json: schema: $ref: '#/components/schemas/NotFoundError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/InternalError' components: schemas: ValidationError: type: object description: Validation error response required: - message - errors properties: message: type: string description: Error message example: Validation failed errors: type: array description: List of validation errors items: type: object properties: field: type: string description: Field that failed validation example: name message: type: string description: Validation error message example: Required example: message: Validation failed errors: - field: name message: Required UnauthorizedError: type: object description: Unauthorized error response properties: message: type: string description: Error message example: Invalid api key example: message: Invalid api key NotFoundError: type: object description: Not found error response properties: message: type: string description: Error message example: Merchant not found example: message: Merchant not found InternalError: type: object description: Error response properties: message: type: string description: Error message example: Error message example: message: Error message securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for authentication (required) MerchantIdAuth: type: apiKey in: header name: x-merchant-id description: Merchant ID for identifying the merchant (required) ````