Statusverzoeken

Elke betaling in Cost+ wordt weergegeven als een bestelling die een of meer transacties bevat. U kunt de huidige status van elke bestelling opvragen via de API, hetzij door polling of door te vertrouwen op webhooks.

Bestellingsstatus ophalen

Stuur een GET-verzoek naar /v1/orders/\{id\}/ om het volledige bestellingsobject op te halen, inclusief de huidige status en alle bijbehorende transacties.

GET /v1/orders/b9ae6.../

Hoewel polling werkt voor het controleren van de bestellingsstatus, zijn webhooks de aanbevolen aanpak voor productie-integraties. Ze bieden real-time meldingen zonder de overhead van herhaalde API-aanroepen.

Bestellingsstatussen

Een bestelling doorloopt de volgende statussen:

Status	Definitief	Beschrijving
`new`	Nee	Bestelling is zojuist aangemaakt. Er is nog geen betalingspoging gedaan.
`processing`	Nee	Er is een betalingspoging gaande. De klant kan 3D Secure of een andere verificatiestap aan het voltooien zijn.
`error`	Nee	De betalingspoging is mislukt. De klant kan opnieuw proberen met dezelfde of een andere betaalmethode.
`completed`	Ja	Betaling is geslaagd. U kunt de bestelling verwerken.
`cancelled`	Ja	De bestelling is geannuleerd, door de klant of via de API.
`expired`	Ja	De bestelling is verlopen voordat een geslaagde betaling is gedaan. De standaard verloopperiode is 30 minuten.

Alleen statussen gemarkeerd als Definitief = Ja zijn eindstatussen. Bestellingen met de status new, processing of error kunnen nog steeds overgaan naar completed.

Voorbeeld: Bestelling in verwerking

Wanneer een klant een betaling heeft geinitieerd maar deze nog niet is voltooid:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Voorbeeld: Voltooide bestelling

Zodra de betaling is geslaagd, bereikt de bestelling de status completed:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Transactiedetails

Elke transactie binnen een bestelling bevat de volgende belangrijke velden:

Veld	Beschrijving
`payment_method`	De gebruikte betaalmethode (bijv. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Het merk of de uitgever (bijv. `visa`, `mastercard`, `amex`)
`payment_method_details`	Een object met methode-specifieke details zoals de laatste vier cijfers van de kaart, vervaldatum en naam van de kaarthouder
`status`	De status van deze specifieke transactie
`amount`	Het transactiebedrag in centen
`currency`	De transactievaluta

Vertrouw niet uitsluitend op het feit dat de klant wordt doorverwezen naar uw return_url als bevestiging van betaling. Verifieer altijd de bestellingsstatus via de API of via een webhook voordat u een bestelling verwerkt.

Gerelateerde eindpunten

Bestelling ophalen — het volledige bestellingsobject en de huidige status ophalen
Bestellingen weergeven — bestellingen weergeven met datumbereikfiltering