Link di Pagamento

I link di pagamento sono URL riutilizzabili che consentono ai clienti di pagare un ordine. A differenza degli ordini standard che scadono dopo un singolo tentativo fallito, i link di pagamento supportano più tentativi di ripetizione, rendendoli ideali per fatture, pagamenti via email e scenari in cui il cliente potrebbe non pagare immediatamente.

Caratteristiche Principali

Riutilizzabili: I clienti possono ritentare il pagamento fino a 25 volte se i tentativi precedenti falliscono.
Lunga durata: La scadenza predefinita è di 30 giorni (configurabile tramite expiration_period).
Condivisibili: Invia il link via email, SMS, chat o incorporalo nel tuo sito web.

Creare un Link di Pagamento

Invia una richiesta POST a /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"
  }'

La risposta include il payment_url da condividere con il cliente e un id univoco per il tracciamento:

Risposta (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"
}

Salva l'id — lo utilizzerai per controllare lo stato del link di pagamento in seguito.

Campi Obbligatori

Campo	Descrizione
`merchant_order_id`	Il tuo ID di riferimento per il link di pagamento
`amount`	Importo in centesimi (es. 9,95 EUR = `995`)
`currency`	Codice valuta ISO 4217 (es. `EUR`, `GBP`)

Campi Opzionali

Campo	Descrizione
`description`	Descrizione mostrata al cliente
`expiration_period`	Durata ISO 8601. Il valore predefinito è `P30D` (30 giorni)
`return_url`	URL a cui reindirizzare il cliente dopo un pagamento riuscito
`failure_url`	URL a cui reindirizzare il cliente in caso di annullamento, scadenza o errore
`webhook_url`	URL per ricevere le notifiche di cambio stato
`customer`	Oggetto con i dati del cliente (nome, email, ecc.)

Se fornisci sia return_url che failure_url, i clienti vengono reindirizzati a failure_url quando lo stato dell'ordine è cancelled, expired o error. Altrimenti, tutti i reindirizzamenti vanno a return_url.

Recuperare un Link di Pagamento

Invia una richiesta GET a /v1/paymentlinks/{id}/ utilizzando l'id del link di pagamento dalla risposta di creazione:

GET /v1/paymentlinks/{id}/

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

La risposta include lo stato attuale e i riferimenti a tutti gli ordini creati dal link, raggruppati per stato:

Risposta (esempio completato)

{
  "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 questo esempio, il cliente ha effettuato un tentativo fallito (ordine 0d79014c... con stato error) prima di riuscire (ordine 3bb663cc... con stato completed). Puoi recuperare i dettagli completi di qualsiasi ordine tramite GET /v1/orders/{order_id}/.

Stati del Link di Pagamento

Stato	Descrizione
`new`	Il link è stato creato ma nessun tentativo di pagamento è stato effettuato.
`processing`	Un tentativo di pagamento è attualmente in corso.
`all_unsuccessful`	Tutti i tentativi di pagamento finora sono falliti. Il cliente può ancora riprovare (fino a 25 tentativi).
`completed`	Il pagamento è riuscito. Il link non è più attivo.
`expired`	Il link è scaduto prima che un pagamento riuscisse.

Lo stato all_unsuccessful non è uno stato finale. Il cliente può ancora tentare di pagare fino a quando il pagamento non riesce, viene raggiunto il numero massimo di tentativi (25) o il link scade.

Una volta che un link di pagamento raggiunge lo stato completed o expired, non può più essere utilizzato. Crea un nuovo link di pagamento se il cliente deve pagare di nuovo.

Flusso di Esempio

Crea un link di pagamento tramite POST /v1/paymentlinks/.
Condividi il payment_url restituito con il tuo cliente (es. via email, SMS o fattura).
Il cliente apre il link e completa il pagamento.
Cost+ invia un webhook al tuo webhook_url quando lo stato cambia.
Verifica lo stato del link di pagamento tramite GET /v1/paymentlinks/{id}/.
Evadi l'ordine una volta che lo stato è completed.

Endpoint Correlati

Crea Link di Pagamento — crea un link di pagamento riutilizzabile
Ottieni Link di Pagamento — recupera lo stato attuale di un link di pagamento

On this page