Idempotent per disseny
La mateixa clau amb el mateix cos retorna el mateix enllaç: una crida repetida mai no crea un segon pagament.
Desenvolupadors
FastTrackPay és un punt de l'API de pagaments de Wealthreader: HTTPS i JSON. Enviï el pagament, redirigeixi el seu client i rebi l'avís amb la seva referència.
Per començar, activem els pagaments i el seu perfil de pagament a la seva clau d'API de Wealthreader. Si ja utilitza l'API, és la mateixa clau.
Un POST amb la seva clau d'API, una clau d'idempotència que també és la seva referència i el cos del pagament: import, divisa, beneficiari, concepte, prioritat i URL d'avís.
# Crear el pagament
curl 'https://api.wealthreader.com/payments/?action=fast-track' \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: invoice-F-2026-104" \
-H "Content-Type: application/json" \
-d '{
"amount": "2450.00",
"currency": "EUR",
"beneficiary": {
"name": "Empresa Exemple, S.L.",
"iban": "ES9121000418450200051332"
},
"reference": "Factura F-2026-104",
"priority": "instant",
"notification_url": "https://example.com/payments/notice"
}'
La resposta porta l'URL del pagament i el seu identificador. Redirigeixi el seu client a l'URL: caduca al cap de pocs minuts (15 per defecte), així que creï'l quan vagi a pagar.
{
"url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Quan el pagament arriba a un estat final, enviem un POST al seu notification_url amb outcome ok o ko i la seva referència a customer_reference. Respongui amb un codi 2xx.
L'avís pot arribar més d'una vegada i no va signat: abans de lliurar res de valor, confirmi l'estat amb POST /payments/?action=status.
{
"outcome": "ok",
"payment_status": "settled",
"customer_reference": "invoice-F-2026-104",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Capçaleres, camps, estats i errors de POST /payments/?action=fast-track. El detall complet és a la guia.
| Capçalera | Validació |
|---|---|
X-API-Key | La seva clau d'API de Wealthreader, amb els pagaments actius. |
Idempotency-Key | De 16 a 128 caràcters: lletres, números i . _ : -. És la seva referència del pagament i torna a l'avís com a customer_reference. |
| Camp | Validació | Obligatori |
|---|---|---|
amount | Import en euros com a cadena, amb fins a dos decimals: "2450.00". Mínim 0.01. | Sí |
currency | EUR. | Sí |
beneficiary.name | Nom del beneficiari, d'1 a 140 caràcters. | Sí |
beneficiary.iban | IBAN del beneficiari, sense espais i amb dígits de control vàlids. No cal donar-lo d'alta abans. | Sí |
reference | Concepte que veurà el seu client i que arriba a l'extracte, fins a 140 caràcters. | Sí |
priority | instant per a transferència immediata o normal per a transferència estàndard. | Sí |
notification_url | URL https públic al qual enviem l'avís ok o ko. | Sí |
logo | URL https públic del logotip de la seva empresa en SVG, que la pàgina de pagament mostra al costat del beneficiari. | No |
payment_status | Significat | outcome |
|---|---|---|
settled |
El banc ha liquidat el pagament. | ok |
rejected |
El banc ha rebutjat el pagament, també per l'import o per no admetre la immediata. | ko |
cancelled |
S'ha cancel·lat abans de completar-se. | ko |
expired |
La sessió de pagament ha caducat sense completar-se. | ko |
failed |
El pagament no s'ha pogut completar. | ko |
pending |
En curs: encara no és un estat final. | Encara sense avís |
| HTTP | Codi | Significat |
|---|---|---|
400 |
idempotency_key_required |
Falta la capçalera Idempotency-Key o la seva longitud no és vàlida. |
401 |
invalid_api_key |
Clau d'API no vàlida. |
403 |
payments_not_allowed, payment_profile_required |
La seva clau no té els pagaments actius o li falta el perfil de pagament. |
409 |
idempotency_conflict |
Ha reutilitzat una Idempotency-Key amb altres dades. |
422 |
invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url |
Cos no vàlid: un camp de més o que falta, o un import, beneficiari o URL d'avís incorrectes. |
429 |
api_limit_reached |
Ha arribat al límit de crides. |
503 |
payments_disabled |
Els pagaments no estan disponibles en aquest moment. |
Els errors responen amb un JSON amb success a false i el codi de la taula a error.code.
La mateixa clau amb el mateix cos retorna el mateix enllaç: una crida repetida mai no crea un segon pagament.
Triï en cada pagament la transferència immediata o l'estàndard. Si el banc no accepta la immediata, l'avís arriba com a ko.
Enviï l'URL del seu logotip en SVG i la pàgina de pagament el mostra al costat del nom del beneficiari.
El seu client revisa l'import, el beneficiari i el concepte, tria el seu banc i autoritza. De moment, la pàgina es mostra en castellà.
Obrir la guia Pagaments Fast Track (s'obre en una pestanya nova) Obrir la referència de l'API (s'obre en una pestanya nova) Sol·licitar accés
Li mostrem FastTrackPay amb els cobraments del seu negoci.