Idempotent van ontwerp
Dezelfde sleutel met dezelfde body geeft dezelfde link terug: een herhaalde aanroep maakt nooit een tweede betaling aan.
Ontwikkelaars
FastTrackPay is een endpoint van de betalings-API van Wealthreader: HTTPS en JSON. Verstuur de betaling, stuur uw klant door en ontvang de melding met uw referentie.
Om te beginnen activeren wij betalingen en uw betaalprofiel op uw Wealthreader-API-sleutel. Gebruikt u de API al, dan is het dezelfde sleutel.
Een POST met uw API-sleutel, een idempotentiesleutel die tegelijk uw referentie is, en de body van de betaling: bedrag, valuta, begunstigde, omschrijving, prioriteit en meldings-URL.
# De betaling aanmaken
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": "Voorbeeldbedrijf B.V.",
"iban": "ES9121000418450200051332"
},
"reference": "Factuur F-2026-104",
"priority": "instant",
"notification_url": "https://example.com/payments/notice"
}'
Het antwoord bevat de URL van de betaling en het ID ervan. Stuur uw klant door naar de URL: die verloopt na enkele minuten (standaard 15), dus maak hem pas aan wanneer de klant gaat betalen.
{
"url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Zodra de betaling een eindstatus bereikt, sturen wij een POST naar uw notification_url met outcome ok of ko en uw referentie in customer_reference. Antwoord met een 2xx-code.
De melding kan meer dan eens binnenkomen en is niet ondertekend: bevestig de status met POST /payments/?action=status voordat u iets waardevols levert.
{
"outcome": "ok",
"payment_status": "settled",
"customer_reference": "invoice-F-2026-104",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Headers, velden, statussen en fouten van POST /payments/?action=fast-track. De volledige details staan in de handleiding.
| Header | Validatie |
|---|---|
X-API-Key | Uw Wealthreader-API-sleutel, met betalingen geactiveerd. |
Idempotency-Key | 16 tot 128 tekens: letters, cijfers en . _ : -. Dit is uw referentie voor de betaling en komt in de melding terug als customer_reference. |
| Veld | Validatie | Verplicht |
|---|---|---|
amount | Bedrag in euro als string, met maximaal twee decimalen: "2450.00". Minimaal 0.01. | Ja |
currency | EUR. | Ja |
beneficiary.name | Naam van de begunstigde, 1 tot 140 tekens. | Ja |
beneficiary.iban | IBAN van de begunstigde, zonder spaties en met geldige controlecijfers. Vooraf registreren is niet nodig. | Ja |
reference | Omschrijving die uw klant ziet en die op het rekeningafschrift verschijnt, maximaal 140 tekens. | Ja |
priority | instant voor een instant overboeking of normal voor een standaardoverboeking. | Ja |
notification_url | Openbare https-URL waarnaar wij de melding ok of ko sturen. | Ja |
logo | Openbare https-URL van het logo van uw bedrijf in SVG, dat de betaalpagina naast de begunstigde toont. | Nee |
payment_status | Betekenis | outcome |
|---|---|---|
settled |
De bank heeft de betaling afgewikkeld. | ok |
rejected |
De bank heeft de betaling geweigerd, ook vanwege het bedrag of omdat ze geen instant overboeking accepteert. | ko |
cancelled |
De betaling is geannuleerd voordat ze was voltooid. | ko |
expired |
De betaalsessie is verlopen zonder te worden voltooid. | ko |
failed |
De betaling kon niet worden voltooid. | ko |
pending |
Bezig: nog geen eindstatus. | Nog geen melding |
| HTTP | Code | Betekenis |
|---|---|---|
400 |
idempotency_key_required |
De header Idempotency-Key ontbreekt of de lengte is ongeldig. |
401 |
invalid_api_key |
Ongeldige API-sleutel. |
403 |
payments_not_allowed, payment_profile_required |
Uw sleutel heeft geen betalingen geactiveerd of het betaalprofiel ontbreekt. |
409 |
idempotency_conflict |
U hebt een Idempotency-Key hergebruikt met andere gegevens. |
422 |
invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url |
Ongeldige body: een veld te veel of te weinig, of een onjuist bedrag, onjuiste begunstigde of onjuiste meldings-URL. |
429 |
api_limit_reached |
U hebt de limiet van aanroepen bereikt. |
503 |
payments_disabled |
Betalingen zijn op dit moment niet beschikbaar. |
Fouten geven een JSON terug met success op false en de code uit de tabel in error.code.
Dezelfde sleutel met dezelfde body geeft dezelfde link terug: een herhaalde aanroep maakt nooit een tweede betaling aan.
Kies per betaling voor een instant of een standaardoverboeking. Accepteert de bank geen instant overboeking, dan komt de melding binnen als ko.
Stuur de URL van uw logo in SVG mee en de betaalpagina toont het naast de naam van de begunstigde.
Uw klant controleert het bedrag, de begunstigde en de omschrijving, kiest zijn bank en keurt goed. Voorlopig wordt de pagina in het Spaans getoond.
Open de gids Fast Track-betalingen (opent in een nieuw tabblad) Open de API-referentie (opent in een nieuw tabblad) Toegang aanvragen
Wij tonen FastTrackPay aan de hand van de betalingen van uw bedrijf.