Payments

Fast Track payments

If you choose this route, you do not need to mount the widget or follow the rest of the payments sections. A single POST returns the payment URL, and Wealthreader notifies your server when the result is OK or KO. As a fallback, store the payment_intent_id from the response: with it you can check the status if the notification does not arrive.

The payer opens that URL and authorizes the payment at their bank. Under the hood, the same immutable intent is created as in the rest of the API: the amount, the beneficiary and the remittance information are fixed before reaching the browser, and the Idempotency-Key header prevents a second charge if the call is interrupted.

Create the payment

POST /payments/?action=fast-track

Required headers: Content-Type: application/json, X-API-Key and Idempotency-Key. The key is 16 to 128 characters long, starts with a letter or digit and only allows letters, digits and . _ : -; a UUID v4 is valid. If it is missing or its length is invalid, the response is 400 idempotency_key_required; if it uses other characters, 422 invalid_customer_reference. That key is also the merchant reference: you do not need to send it in the body. If you repeat the same key with the same body, you receive the same URL again. If you reuse it with different data, the response is 409 idempotency_conflict.

Field	Type	Description
`amount`	String	Amount in major units, as a JSON string. `"15.50"` is 15.50. An integer without decimals (`"15"`) is also accepted. At most two decimal places: `"15.5"` and `"15.50"` are the same amount. Minimum `0.01`. The maximum is capped at the limit each customer has configured at their bank. Outside these format rules, `422 invalid_amount`.
`currency`	String	ISO 4217 currency. In this version, `EUR`.
`beneficiary`	Object	Beneficiary: `name` (1 to 140 characters) and `iban` (no spaces, with check digits).
`reference`	String	Remittance information shown on the statement, up to 140 characters.
`priority`	String	`normal` or `instant`.
`notification_url`	String	Public `https` URL to which the OK or KO notification is sent.
`logo`	String	Optional. Public `https` URL of your merchant logo in SVG: the path must end in `.svg` (query parameters are allowed), with no credentials or private addresses, up to 2048 ASCII characters. The payment page displays it above the summary, next to the beneficiary name; without `logo`, there is no merchant header. Wealthreader does not download the URL: the payer's browser loads it. Any other value returns `422 invalid_logo`.

All fields are required except logo. The body is an allowlist. An extra field, or a missing required one, returns 422 invalid_request. logo is part of the payment: repeating the same Idempotency-Key with a different logo also returns 409 idempotency_conflict.

An instant payment has no specific cap in this API. The bank rejects any payment it cannot accept, including because of the amount, and that rejection arrives as a KO at the notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

The response, with 201 the first time and 200 if the key already existed, contains the URL and the payment identifier:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Redirect the payer to the URL. The token lives in the fragment, expires with the widget (usually 15 minutes) and must not be recorded in your logs. Store payment_intent_id together with your order.

OK or KO notification

When Wealthreader checks the payment status and finds it in a final state, it sends a POST to notification_url with Content-Type: application/json and User-Agent: WealthReader-Payments:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome is ok only if the bank has settled the payment (settled). rejected, cancelled, expired and failed are notified as ko. An ambiguous result (reconciliation_required) is not final and is not notified.
customer_reference is your Idempotency-Key, and payment_intent_id is the identifier returned when the payment was created.
Respond with 2xx to mark the notification as delivered. Wealthreader waits at most 3 seconds and does not follow redirects.
The same notification may arrive more than once: treat customer_reference plus outcome as idempotent.
A URL that is not public https is rejected when the payment is created and is checked again before each delivery.

When it arrives. The status is checked while the payer is still on the payment page, which polls it until the final result or until the payment session expires, and every time you call POST /payments/?action=status. There is no separate scheduled delivery: if the payer closes the page before the bank concludes, or if your server does not respond with 2xx, the notification is sent at the next check. Therefore, if you have not received the notification a few minutes after redirecting the payer, check the status with the payment_intent_id; that query also triggers the pending notification. See Statuses, polling and reconciliation.

The notification is not signed. Before delivering a valuable good or service, confirm the result with POST /payments/?action=status using your X-API-Key and the payment_intent_id: only payment_status: settled in that response is a financial confirmation.

Last updated 2026-11-08