Payments

• Configured in each product issuance: provider (stripe, mercadopago, rebill or manual) and mode: single payment, recurring or usage.
• A product can offer several providers at checkout; the chosen one arrives in data.payment.provider. If it is not enabled for the product, the API answers 422.
• Each provider's credentials are connected separately for Sandbox and Production. A sandbox policy never uses production credentials.
• The chosen provider is stored on the policy: changing the list later does not move issued policies.

The full card number is never stored: only the last 4 digits, the brand and the holder. The CVV is never requested, stored or sent.

• Online single payment: the policy is issued pending_payment and the response carries payment with kind: payment. Stripe returns clientSecret and publishableKey (Payment Element); MercadoPago, redirectUrl (Checkout Pro).
• Recurring or usage with a provider (Stripe, Mercado Pago or Rebill): the policy is issued pending_payment with payment_method_status: pending and is never active before it's collected. Recurring (known amount): payment charges the first period and saves the card (Stripe: kind: payment with firstCharge: true; Mercado Pago / Rebill: the subscription, which charges the first period when authorized); it becomes active once that first charge is confirmed. Usage (amount unknown until period close): the card is only validated, with no charge (Stripe: kind: setup; Mercado Pago: subscription authorized with its first charge at period close; Rebill: subscription with a trial, a $0 approval); it becomes active once validated. There is never a token charge. A declined first charge leaves the policy payment_failed (not active) and can be retried. If the product has conditions, they're resolved first and only then does this step open.
• A declined attempt (single payment, first period or card validation) leaves the policy payment_failed with payment_status: failed: it shows as "Payment declined" in the portal, the client portal and Approvals → Declined payments, and can be filtered in the policy list. The intermediary (or the admins) and the insured are notified once per attempt with the reason and the link to retry. The same link stays valid and an approved payment activates the policy right away.
• Every response with payment includes a statusToken to check the status without an API key.
• Confirmations arrive through each provider webhooks, per environment.

{
  "id": "b2a7…",
  "policy_number_internal": "TEST-POL-0007",
  "status": "pending_payment",
  "payment": {
    "kind": "payment",
    "provider": "mercadopago",
    "environment": "test",
    "redirectUrl": "https://www.mercadopago.com.ar/checkout/…",
    "statusToken": "v1.…"
  }
}

curl -X POST https://api.quore.app/api/integrations/payments/status \
  -H "Content-Type: application/json" \
  -d '{ "token": "STATUS_TOKEN" }'

{
  "policyId": "b2a7…",
  "policyStatus": "active",
  "paymentMethodStatus": null,
  "paymentStatus": "paid"
}

For usage-billed products you report consumption as it happens; at the end of each period it is added up and the premium is computed. Requires a secret key.

curl -X POST https://api.quore.app/api/policies/POLICY_ID/usage-events \
  -H "x-api-key: sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 12.5,
    "unit": "km",
    "occurredAt": "2026-10-26T13:45:00Z",
    "externalRef": "viaje-88421",
    "metadata": { "deviceId": "scooter-17" }
  }'

curl -X POST https://api.quore.app/api/policies/by-external-ref/FLOTA-001/usage-events \
  -H "x-api-key: sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "quantity": 3, "unit": "km", "occurredAt": "2026-10-26T14:10:00Z" }'

• Answers 201 with the recorded event.
• By your own identifier: by-external-ref finds the policy by its externalRef, taken on issuance from the variable the product defines for it.
• A unit different from the product one: 400. Cancelled, expired, rejected or lapsed policy, or usage after the end of the term: 422.
• An event that arrives after its period closed is charged once in the next period, as an adjustment.
• Periods are fixed day windows or calendar months, depending on the product.

• Recurring products charge the first period at signup (the policy activates with that charge) and then create one billing cycle per period, charged to the saved payment method.
• A declined charge is retried 1, 3 and 7 days after the due date, within the grace period; then it is failed.
• Without a registered payment method or when authentication is required, the cycle is pending_action: administrators are notified, and the insured when they must act.
• After several failed cycles the policy lapses for non-payment and stops accepting usage.
• No cycle starts after the end of the term; MercadoPago and Rebill subscriptions are cancelled when the term ends.