Betaallinks

Betaallinks zijn herbruikbare URL's waarmee klanten een bestelling kunnen betalen. In tegenstelling tot standaardbestellingen die verlopen na een enkele mislukte poging, ondersteunen betaallinks meerdere herhaalpogingen, wat ze ideaal maakt voor facturen, e-mailbetalingen en scenario's waarin de klant mogelijk niet direct betaalt.

Belangrijkste kenmerken

Herbruikbaar: Klanten kunnen tot 25 keer opnieuw proberen te betalen als eerdere pogingen mislukken.
Langlevend: Standaard verlooptijd is 30 dagen (configureerbaar via expiration_period).
Deelbaar: Stuur de link via e-mail, sms, chat of integreer deze op uw website.

Een betaallink aanmaken

Stuur een POST-verzoek naar /v1/paymentlinks/:

POST /v1/paymentlinks/

curl -X POST https://api.costplus.online/v1/paymentlinks/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_id": "invoice-1234",
    "amount": 995,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

De respons bevat de payment_url om te delen met de klant en een uniek id voor tracking:

Respons (201 Created)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "new",
  "reason": "Payment Link was created, not yet visited",
  "orders": {},
  "created": "2026-01-15T12:00:00.000000Z"
}

Sla het id op — u gebruikt dit later om de status van de betaallink te controleren.

Verplichte velden

Veld	Beschrijving
`merchant_order_id`	Uw eigen referentie-ID voor de betaallink
`amount`	Bedrag in centen (bijv. 9,95 EUR = `995`)
`currency`	ISO 4217-valutacode (bijv. `EUR`, `GBP`)

Optionele velden

Veld	Beschrijving
`description`	Beschrijving die aan de klant wordt getoond
`expiration_period`	ISO 8601-duur. Standaard is `P30D` (30 dagen)
`return_url`	URL om de klant naartoe te verwijzen na een geslaagde betaling
`failure_url`	URL om de klant naartoe te verwijzen bij annulering, verloop of fout
`webhook_url`	URL om statuswijzigingsmeldingen te ontvangen
`customer`	Klantgegevensobject (naam, e-mail, enz.)

Als u zowel return_url als failure_url opgeeft, worden klanten doorverwezen naar failure_url wanneer de bestellingsstatus cancelled, expired of error is. Anders gaan alle doorverwijzingen naar return_url.

Een betaallink ophalen

Stuur een GET-verzoek naar /v1/paymentlinks/{id}/ met het betaallink-id uit de aanmaakrespons:

GET /v1/paymentlinks/{id}/

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/paymentlinks/e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1/

De respons bevat de huidige status en verwijzingen naar alle bestellingen die vanuit de link zijn aangemaakt, gegroepeerd op status:

Respons (voltooid voorbeeld)

{
  "id": "e6eecc6a-47c5-4948-bcc0-d8b73f5c55a1",
  "merchant_order_id": "invoice-1234",
  "amount": 995,
  "currency": "EUR",
  "description": "Invoice #1234",
  "expiration_period": "P30D",
  "payment_url": "https://pay.costplus.online/paymentlinks/e6eecc6a.../",
  "status": "completed",
  "reason": "Completed",
  "completed": "2026-01-15T12:05:30.123456+00:00",
  "completed_order_id": "3bb663cc-2a20-400d-8bf6-18d9695d0c66",
  "orders": {
    "error": ["0d79014c-0aaa-4fd6-87c5-c8cfa5f5ac69"],
    "completed": ["3bb663cc-2a20-400d-8bf6-18d9695d0c66"]
  }
}

In dit voorbeeld deed de klant een mislukte poging (bestelling 0d79014c... met status error) voordat het lukte (bestelling 3bb663cc... met status completed). U kunt volledige details van elke bestelling ophalen via GET /v1/orders/{order_id}/.

Betaallinkstatussen

Status	Beschrijving
`new`	De link is aangemaakt maar er is nog geen betalingspoging gedaan.
`processing`	Er is een betalingspoging gaande.
`all_unsuccessful`	Alle betalingspogingen tot nu toe zijn mislukt. De klant kan nog opnieuw proberen (tot 25 pogingen).
`completed`	Betaling is geslaagd. De link is niet langer actief.
`expired`	De link is verlopen voordat een geslaagde betaling is gedaan.

De status all_unsuccessful is geen definitieve status. De klant kan nog steeds proberen te betalen totdat de betaling slaagt, het maximale aantal pogingen (25) is bereikt of de link verloopt.

Zodra een betaallink de status completed of expired bereikt, kan deze niet meer worden gebruikt. Maak een nieuwe betaallink aan als de klant opnieuw moet betalen.

Voorbeeldworkflow

Maak een betaallink aan via POST /v1/paymentlinks/.
Deel de geretourneerde payment_url met uw klant (bijv. via e-mail, sms of factuur).
De klant opent de link en voltooit de betaling.
Cost+ stuurt een webhook naar uw webhook_url wanneer de status verandert.
Verifieer de betaallinkstatus via GET /v1/paymentlinks/{id}/.
Verwerk de bestelling zodra de status completed is.

Gerelateerde eindpunten

Betaallink aanmaken — een herbruikbare betaallink aanmaken
Betaallink ophalen — de huidige status van een betaallink ophalen

On this page