Richieste di Stato

Ogni pagamento in Cost+ è rappresentato da un ordine che contiene una o più transazioni. Puoi controllare lo stato attuale di qualsiasi ordine interrogando l'API, tramite polling o affidandoti ai webhook.

Recupero dello Stato dell'Ordine

Invia una richiesta GET a /v1/orders/\{id\}/ per recuperare l'oggetto ordine completo incluso il suo stato attuale e tutte le transazioni associate.

GET /v1/orders/b9ae6.../

Sebbene il polling funzioni per controllare lo stato dell'ordine, i webhook sono l'approccio consigliato per le integrazioni in produzione. Forniscono notifiche in tempo reale senza il sovraccarico di chiamate API ripetute.

Stati dell'Ordine

Un ordine progredisce attraverso i seguenti stati:

Stato	Finale	Descrizione
`new`	No	L'ordine è appena stato creato. Nessun tentativo di pagamento è stato effettuato.
`processing`	No	Un tentativo di pagamento è in corso. Il cliente potrebbe stare completando il 3D Secure o un altro passaggio di verifica.
`error`	No	Il tentativo di pagamento è fallito. Il cliente può riprovare con lo stesso metodo o con uno diverso.
`completed`	Sì	Il pagamento è riuscito. Puoi evadere l'ordine.
`cancelled`	Sì	L'ordine è stato annullato, dal cliente o tramite l'API.
`expired`	Sì	L'ordine è scaduto prima che venisse effettuato un pagamento riuscito. Il periodo di scadenza predefinito è 30 minuti.

Solo gli stati contrassegnati come Finale = Sì sono terminali. Gli ordini con stato new, processing o error possono ancora passare a completed.

Esempio: Ordine in Elaborazione

Quando un cliente ha avviato il pagamento ma non è ancora completo:

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

Esempio: Ordine Completato

Una volta che il pagamento è riuscito, l'ordine raggiunge lo stato 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"]
}

Dettagli della Transazione

Ogni transazione all'interno di un ordine contiene i seguenti campi principali:

Campo	Descrizione
`payment_method`	Il metodo di pagamento utilizzato (es. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Il circuito o l'emittente (es. `visa`, `mastercard`, `amex`)
`payment_method_details`	Un oggetto con dettagli specifici del metodo, come le ultime quattro cifre della carta, scadenza e nome del titolare
`status`	Lo stato di questa specifica transazione
`amount`	L'importo della transazione in centesimi
`currency`	La valuta della transazione

Non fare affidamento esclusivamente sul reindirizzamento del cliente al tuo return_url come conferma del pagamento. Verifica sempre lo stato dell'ordine tramite l'API o attraverso un webhook prima di evadere un ordine.

Endpoint Correlati

Ottieni Ordine — recupera l'oggetto ordine completo e il suo stato attuale
Lista Ordini — elenca gli ordini con filtro per intervallo di date