Collect with Card - Dollr Developer Docs

Build your own checkout UI with Stripe Elements and Dollr’s collection API. Dollr routes cards through Stripe — you do not connect your own Stripe account.

Prefer less integration work? Use Hosted checkout — customers enter card details on Dollr’s page with no Stripe setup on your side.

API Reference: Card provider info · Collect

Prerequisites

Published invoice or order (or checkout source)
Dollr Stripe publishable key from Environments (NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY)
@stripe/stripe-js and @stripe/react-stripe-js in your frontend
Server-side Dollr API credentials

Flow overview

POST /v1/sessions/checkout
Stripe Elements → stripe.createPaymentMethod() → paymentMethod.id
GET /v1/predictions/card-provider-info?payment_method_id=pm_xxx
POST /v1/payment-accounts/create with CREDIT_CARD / STRIPE (no phone number)
POST /v1/executions/collection
If requires_action, complete 3DS with client_secret
Poll GET /v1/status/collection/{reference_id}

Step 1 — Checkout session

curl -X POST "https://api.heydollr.app/v1/sessions/checkout" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source_id": 101, "source_type": "INVOICE"}'

Step 2 — Stripe Elements (frontend)

import { loadStripe } from "@stripe/stripe-js";
import { Elements, CardNumberElement, useStripe, useElements } from "@stripe/react-stripe-js";

const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

// Inside your form submit handler:
const stripe = useStripe();
const elements = useElements();
const cardNumber = elements.getElement(CardNumberElement);

const { paymentMethod, error } = await stripe.createPaymentMethod({
  type: "card",
  card: cardNumber,
  billing_details: { name: accountName },
});

if (error) throw error;
const paymentMethodId = paymentMethod.id; // pm_xxx — send to your server

Card data never touches your server — Stripe tokenizes it in the browser.

Step 3 — Card provider prediction (server)

curl "https://api.heydollr.app/v1/predictions/card-provider-info?payment_method_id=pm_xxx&operation_type=COLLECTION&provider=STRIPE" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Confirms payment_method, gateway_provider, currencies, and brand.

Step 4 — Payment account

Create a new payment account per card attempt (do not reuse MoMo-style caching):

curl -X POST "https://api.heydollr.app/v1/payment-accounts/create?operation_type=COLLECTION" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "Customer Card",
    "provider": "STRIPE",
    "method": "CREDIT_CARD",
    "party_id": 42
  }'

For cards, omit insensitive_account_number. The Stripe payment_method_id is used at prediction time — Dollr links routing via provider + method.

Step 5 — Execute collection

curl -X POST "https://api.heydollr.app/v1/executions/collection" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "55",
    "payment_account_id": "18",
    "currency": "USD",
    "reference_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Pass currency as the payer currency — see Currency & FX.

Step 6 — Handle 3D Secure

if (execution.requires_action && execution.client_secret) {
  const { error } = await stripe.confirmCardPayment(execution.client_secret);
  if (error) { /* show error */ }
}

See Card 3DS failed.

Step 7 — Poll status

curl "https://api.heydollr.app/v1/status/collection/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Preview fees

curl "https://api.heydollr.app/v1/predictions/amount-and-fees?base_amount=250&base_currency=USD&target_currency=USD&payment_method=CREDIT_CARD&operation_type=COLLECTION&provider=STRIPE&fee_bearer=PAYER" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Hosted checkout — no Stripe integration required
Currency & FX · Environments
Payment status patterns

​Prerequisites

​Flow overview

​Step 1 — Checkout session

​Step 2 — Stripe Elements (frontend)

​Step 3 — Card provider prediction (server)

​Step 4 — Payment account

​Step 5 — Execute collection

​Step 6 — Handle 3D Secure

​Step 7 — Poll status

​Preview fees

​Related

Prerequisites

Flow overview

Step 1 — Checkout session

Step 2 — Stripe Elements (frontend)

Step 3 — Card provider prediction (server)

Step 4 — Payment account

Step 5 — Execute collection

Step 6 — Handle 3D Secure

Step 7 — Poll status

Preview fees

Related