Skip to main content
Use this page while you are validating your checkout before production.

​
Sandbox checklist

  • load https://js.pagou.ai/payments/v3.js
  • call Pagou.setEnvironment("sandbox")
  • use sandbox public and secret credentials
  • create transactions against https://api-sandbox.pagou.ai
  • verify webhook handling before treating browser success as production-ready

​
What to test

​
Basic card submit

Confirm that:
  • the card field mounts
  • ready enables your submit button
  • elements.submit() reaches your backend
  • your backend returns the transaction payload

​
3DS required flow

Confirm that:
  • the browser receives next_action
  • automatic handling opens the 3DS modal when enabled
  • manual handling works through Pagou.handleNextAction(...)
  • your checkout remains pending until backend confirmation

​
Challenge interruption

Confirm your UI behavior when:
  • the customer closes the modal
  • the challenge times out
  • the browser loses the final response

​
Webhook-first completion

Confirm your order state machine behaves correctly when the webhook finalizes the payment before the checkout UI finishes updating.

​
Common mistakes

​
Backend strips next_action

Symptom:
  • the transaction reaches three_ds_required
  • the browser does not continue the challenge
Fix:
  • return the Pagou transaction payload intact
  • preserve id, status, and next_action

​
Treating browser success as fulfillment

Symptom:
  • orders are marked paid before webhook-confirmed final state
Fix:
  • fulfill only from final backend-confirmed states such as captured or paid

​
Duplicate submissions

Symptom:
  • multiple payment attempts are created from the same checkout click
Fix:
  • disable the submit button while elements.submit() is running
  • keep the form locked during challenge handling

​
Manual flow forgets to continue requires_action

Symptom:
  • your checkout stalls after submit when auto modal is disabled
Fix:
  • check for result.status === "requires_action"
  • call Pagou.handleNextAction(result.transaction.next_action)

​
Origin or environment mismatch

Symptom:
  • session creation or tokenization fails unexpectedly
Fix:
  • use the correct environment in both script setup and backend API host
  • pass the actual checkout origin when creating Elements

​
Recovery strategy

When the checkout outcome is uncertain:
  1. keep the order pending
  2. use the stored transaction ID
  3. query GET /v2/transactions/{id}
  4. let webhook or reconciliation drive the final state