Pagaments

Pagaments Fast Track

Si trieu aquesta via, no cal que munteu el widget ni que seguiu la resta de les seccions de pagaments. Un sol POST retorna la URL de pagament, i Wealthreader avisa el vostre servidor quan el resultat és OK o KO. Com a reserva, deseu el payment_intent_id de la resposta: amb ell podeu consultar l'estat si l'avís no arriba.

El pagador obre aquesta URL i autoritza el pagament al seu banc. Per sota es crea la mateixa intenció immutable que a la resta de l'API: l'import, el destinatari i el concepte queden fixats abans d'arribar al navegador, i la capçalera Idempotency-Key evita un segon càrrec si la crida s'interromp.

Crear el pagament

POST /payments/?action=fast-track

Capçaleres obligatòries: Content-Type: application/json, X-API-Key i Idempotency-Key. La clau té de 16 a 128 caràcters, comença per una lletra o un número i només admet lletres, números i . _ : -; un UUID v4 és vàlid. Si falta o la seva longitud no és vàlida, la resposta és 400 idempotency_key_required; si utilitza altres caràcters, 422 invalid_customer_reference. Aquesta clau és també la referència del comerç: no cal enviar-la al cos. Si repetiu la mateixa clau amb el mateix cos, rebeu una altra vegada la mateixa URL. Si la reutilitzeu amb altres dades, la resposta és 409 idempotency_conflict.

Camp	Tipus	Descripció
`amount`	Cadena	Import en unitats principals, com a cadena JSON. `"15.50"` són 15,50. També s'admet un enter sense decimals (`"15"`). Com a màxim dos decimals: `"15.5"` i `"15.50"` són el mateix import. Mínim `0.01`. El màxim està limitat al límit que cada client tingui configurat al seu banc. Fora d'aquestes regles de format, `422 invalid_amount`.
`currency`	Cadena	Divisa ISO 4217. En aquesta versió, `EUR`.
`beneficiary`	Objecte	Destinatari: `name` (d'1 a 140 caràcters) i `iban` (sense espais, amb dígit de control).
`reference`	Cadena	Concepte de l'extracte, fins a 140 caràcters.
`priority`	Cadena	`normal` o `instant`.
`notification_url`	Cadena	URL `https` pública a la qual s'avisa l'OK o el KO.
`logo`	Cadena	Opcional. URL `https` pública del logotip del vostre comerç en SVG: el camí ha d'acabar en `.svg` (admet paràmetres de consulta), sense credencials ni adreces privades, fins a 2048 caràcters ASCII. La pàgina de pagament el mostra damunt del resum, al costat del nom del beneficiari; sense `logo`, no hi ha capçalera de comerç. Wealthreader no descarrega la URL: la carrega el navegador del pagador. Qualsevol altre valor respon `422 invalid_logo`.

Tots els camps són obligatoris excepte logo. El cos és una llista blanca. Un camp de més, o un d'obligatori que falti, respon 422 invalid_request. logo forma part del pagament: repetir la mateixa Idempotency-Key amb un altre logo també és 409 idempotency_conflict.

Una transferència immediata no té un límit propi en aquesta API. El banc rebutja la que no pot acceptar, també per import, i aquest rebuig arriba com a KO al 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"
  }'

La resposta, amb 201 la primera vegada i 200 si la clau ja existia, conté la URL i l'identificador del pagament:

{
  "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"
}

Redirigiu el pagador a la URL. El token viu al fragment, caduca amb el widget (habitualment 15 minuts) i no s'ha de registrar als vostres logs. Deseu payment_intent_id juntament amb la vostra comanda.

Avís d'OK o KO

Quan Wealthreader comprova l'estat del pagament i el troba en un estat final, fa un POST a notification_url amb Content-Type: application/json i 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 és ok només si el banc ha liquidat el pagament (settled). rejected, cancelled, expired i failed s'avisen com a ko. Un resultat ambigu (reconciliation_required) no és final i no s'avisa.
customer_reference és la vostra Idempotency-Key, i payment_intent_id, l'identificador retornat en crear el pagament.
Responeu 2xx per donar l'avís per lliurat. Wealthreader espera com a màxim 3 segons i no segueix redireccions.
El mateix avís pot arribar més d'una vegada: tracteu customer_reference més outcome com a idempotents.
Una URL que no sigui https pública es rebutja en crear el pagament i es torna a comprovar abans de cada enviament.

Quan arriba. L'estat es comprova mentre el pagador continua a la pàgina de pagament, que el consulta fins al resultat final o fins que caduca la sessió de pagament, i cada vegada que consulteu POST /payments/?action=status. No hi ha cap enviament programat a part: si el pagador tanca la pàgina abans que el banc conclogui, o si el vostre servidor no respon 2xx, l'avís s'envia en la comprovació següent. Per això, si no heu rebut l'avís uns minuts després de redirigir el pagador, consulteu l'estat amb el payment_intent_id; aquesta consulta també dispara l'avís pendent. Vegeu Estats, consultes periòdiques i conciliació.

L'avís no va signat. Abans de lliurar un bé o servei valuós, confirmeu el resultat amb POST /payments/?action=status fent servir la vostra X-API-Key i el payment_intent_id: només payment_status: settled en aquesta resposta és una confirmació financera.

Última actualització 2026-11-08