Guida Rapida

Questa guida ti accompagna nella creazione e nel completamento di un pagamento di test utilizzando l'API Cost+. Al termine, avrai un'integrazione funzionante su cui costruire.

Prerequisiti

• Un account Cost+ con un sito web sandbox — creane uno nel Portale Commerciante
• La tua chiave API sandbox (disponibile sotto Siti Web → il tuo sito web sandbox → Integrazione)

Passaggio 1: Creare un Ordine

Invia una richiesta POST per creare un ordine di pagamento. Sostituisci YOUR_API_KEY con la tua chiave API sandbox:

curl -X POST https://api.costplus.online/v1/orders/ \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "EUR",
    "amount": 1295,
    "merchant_order_id": "my-first-order",
    "description": "Test order",
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "transactions": [
      {
        "payment_method": "credit-card"
      }
    ]
  }'

L'API restituisce l'oggetto ordine completo. I campi chiave sono id, status e il payment_url all'interno della transazione:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "description": "Test order",
  "return_url": "https://example.com/return",
  "webhook_url": "https://example.com/webhook",
  "created": "2026-01-15T12:00:05.433502+00:00",
  "modified": "2026-01-15T12:00:05.553125+00:00",
  "expiration_period": "PT1H",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "amount": 1295,
      "currency": "EUR",
      "payment_url": "https://pay.costplus.online/4851e31c.../credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Salva l'id — ti servirà nel Passaggio 3.

Passaggio 2: Completare il Pagamento di Test

1. Apri il payment_url dalla risposta nel tuo browser
2. Nella pagina di pagamento, inserisci i dati della carta di test:

3. Invia il pagamento
4. Verrai reindirizzato al tuo return_url

Passaggio 3: Verificare il Pagamento

Recupera l'ordine per confermare che è stato completato:

curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Un pagamento riuscito appare così:

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-first-order",
  "completed": "2026-01-15T12:02:30.123456+00:00",
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "completed",
      "amount": 1295,
      "currency": "EUR",
      "payment_method_details": {
        "truncated_pan": "1111",
        "card_expiry": "122028"
      }
    }
  ]
}

Lo status dell'ordine è "completed" — il pagamento è riuscito.

Passaggio 4: Gestire il Webhook (Consigliato)

Quando lo stato del pagamento cambia, Cost+ invia una richiesta POST al tuo webhook_url:

{
  "event": "status_changed",
  "order_id": "4851e31c-4137-4e91-95ef-1df945ee76a2"
}

Quando lo ricevi:

1. Chiama GET /v1/orders/{order_id}/ per verificare lo stato attuale (non fidarti mai solo del payload del webhook)
2. Restituisci HTTP 200 per confermare la ricezione
3. Evadi l'ordine se lo stato è "completed"

Consulta la guida Webhook per la logica di retry, le best practice e i dettagli del payload.

Alternativa: Link di Pagamento

Se non hai bisogno della logica di reindirizzamento lato server, i link di pagamento offrono un percorso più semplice. Crea un link, condividi l'URL con il tuo cliente e controlla lo stato successivamente.

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": 2500,
    "currency": "EUR",
    "description": "Invoice #1234"
  }'

La risposta include un payment_url che puoi condividere via email, SMS o chat. Il cliente può tentare il pagamento più volte (fino a 25) finché il link non scade o il pagamento non riesce.

Consulta la guida Link di Pagamento per il flusso completo.

Prossimi Passi

Hai completato il tuo primo pagamento. Ecco dove proseguire:

• Pagina di Pagamento Ospitata — riferimento completo HPP con tutti i campi e le opzioni della richiesta
• Pagamenti Ricorrenti — configura abbonamenti e fatturazione programmata
• Pagamenti con Un Clic — checkout veloce per i clienti di ritorno
• Autorizzazione / Cattura / Annullamento — autorizza prima, cattura dopo (es. alla spedizione)
• Rimborsi — elabora rimborsi totali e parziali
• SDK — librerie ufficiali per Node.js, Python, PHP, Java/Kotlin, C#/.NET e Ruby
• Plugin — integrazioni predefinite per Shopify, WooCommerce, Magento e altro

Endpoint Correlati

• Crea Ordine — riferimento API completo per la creazione dell'ordine
• Ottieni Ordine — recupera i dettagli e lo stato dell'ordine
• Crea Link di Pagamento — crea link di pagamento riutilizzabili