Accept payments
Hosted checkout
Wegopay hosts the payment page, card entry, 3D Secure and wallets. You create the payment and send the customer to its checkoutUrl.
Create the payment
Send POST /v1/payments with an Idempotency-Key. See the API reference for every field.
| Field | Required | Notes |
|---|---|---|
amountCents | Yes | Integer cents, 500–100000000. |
currency | Yes | USD. |
reference | Yes | Your order label, 1–255 characters. Not checked for uniqueness: keep orders unique in your own database. |
successUrl | Yes | Absolute HTTPS URL, without credentials or a fragment. Where the customer returns after paying. |
cancelUrl | Yes | Absolute HTTPS URL for a customer who leaves checkout. |
customer | No | email, name, documentNumber (11–14 digits), phone (10–15 digits). |
metadata | No | JSON object, up to 100 keys and 16 KB. Do not put card or identity data here. |
paymentMethod | No | card or wallet. Opens that method only. |
locale | No | en (default), es or pt. |
embeddingOrigin | No | The website that will embed this checkout. See embedding below. |
Unknown fields are rejected with 422 validation_failed, which names the field in error.field.
Redirect the customer
Redirect to data.checkoutUrl exactly as returned. Treat the URL as a secret: anyone with it can open this payment. Query parameters added to it, such as tracking tags, are ignored and cannot change the payment.
- A session lasts about 30 minutes (see
expiresAt) and allows five card attempts. - The customer returns to
successUrlorcancelUrl. Neither proves the outcome. - Keep the order pending until you read
status: "paid". See payment status.
Checkout options
Preselect a payment method
If the customer already chose a method on your site, send "paymentMethod": "card" or "paymentMethod": "wallet". Checkout opens that method and does not offer the other. The method must be enabled for your key; otherwise creation returns 422 with error.field: "paymentMethod". The field is part of idempotency, so retry with the same body.
Language
Set locale to en, es or pt. The choice persists across reloads and customer actions. Pages hosted by card networks or wallet providers use their own language.
Customer details
Send the payer’s real name and email when you have them. Join first and last names with a space; any script is accepted. For wallet payments, documentNumber and phone are optional and are forwarded when present. They are not returned in API responses.
Embed the checkout
Use a card-enabled key’s checkoutUrl as an iframe source:
<iframe
src="CHECKOUT_URL_RETURNED_BY_WEGOPAY"
title="Secure Wegopay checkout"
style="width:100%;height:850px;border:0"
allow="payment"
referrerpolicy="no-referrer"
></iframe>- Your website must be on the key’s allowed embedding origins, which Wegopay configures. With more than 20 allowed origins, send
embeddingOriginon create to choose the one that will embed this checkout. - The receipt stays inside the frame and there is no message to the parent page. Update your page once your backend has verified the payment.
- Wallet-only checkouts must open as a normal page. In a mixed checkout, wallet opens in a new tab.
- Keep a normal checkout link next to the iframe in case the browser blocks third-party storage. Do not use a
credentiallessor extra-sandboxed iframe.
Payment methods and origins per key
Wegopay administrators set your merchant defaults and per-key overrides. Ask Wegopay to change them:
- Payment methods: cards, wallet, both or none. A key can never enable a method disabled for your merchant.
- Embedding origins: exact HTTPS origins, with no wildcards, paths or IP addresses. An empty list blocks embedding.
Dashboard → API Keys shows each key’s effective settings. A common setup is a card-only key for an embedded form and a wallet-only key for a redirect button. Create each payment with the key for its flow, and use a distinct idempotency key per flow.
Changes apply to new attempts