Card 3DS or requires_action - Dollr Developer Docs

Symptom

POST /v1/executions/collection returns:

{
  "status": "PROCESSING",
  "requires_action": true,
  "client_secret": "pi_xxx_secret_xxx"
}

Or the payment stays in PROCESSING and the customer did not complete card authentication.

Cause

International cards often require 3D Secure (3DS). Dollr returns client_secret so your frontend can complete authentication with Stripe.js.

Hosted checkout handles 3DS automatically — this article applies to API-embedded card integrations only.

Fix

Pass client_secret to Stripe.js on your frontend:

const stripe = Stripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);
const { error, paymentIntent } = await stripe.confirmCardPayment(client_secret);

if (error) {
  console.error(error.message); // Show to customer
} else if (paymentIntent?.status === "succeeded") {
  // Poll Dollr status — do not assume success from Stripe alone
}

Poll Dollr execution status with your stored reference_id:

GET /v1/status/collection/{reference_id}

Do not call execute again with a new reference_id while status is PROCESSING.

Common failures

Stripe error	Action
`authentication_required`	Customer must complete 3DS — call `confirmCardPayment`
`card_declined`	Ask customer to try another card
Missing publishable key	Set `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` from Environments

Last modified on June 23, 2026