Pagina di Pagamento Ospitata (HPP)

La Pagina di Pagamento Ospitata (HPP) è il modulo di pagamento conforme PCI DSS di Cost+. Ti consente di accettare pagamenti senza gestire dati sensibili delle carte sui tuoi server. Crei un ordine tramite l'API, reindirizzi il cliente alla pagina ospitata e il cliente torna sul tuo sito dopo il pagamento.

Come Funziona

1. Il tuo server crea un ordine chiamando POST /v1/orders/.
2. L'API restituisce un URL che punta alla pagina di pagamento ospitata.
3. Reindirizzi il cliente alla pagina di pagamento.
4. Il cliente completa il pagamento sulla pagina ospitata Cost+.
5. Il cliente viene reindirizzato al tuo return_url (o failure_url per i pagamenti falliti).
6. Cost+ invia una notifica webhook al tuo webhook_url con lo stato dell'ordine.

Creare un Ordine

Esistono due approcci per utilizzare l'HPP:

Approccio 1: Mostrare Tutti i Metodi di Pagamento (Il più semplice)

Crea un ordine senza specificare transactions. La risposta include un order_url — il cliente viene reindirizzato lì e vede tutti i metodi di pagamento abilitati per il tuo account:

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://api.costplus.online/pay/43114fde.../select-payment-method/",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook"
}

Reindirizza il cliente all'order_url. Sulla pagina ospitata vengono mostrati tutti i metodi di pagamento abilitati.

Approccio 2: Preselezionare i Metodi di Pagamento

Crea un ordine con un array transactions per controllare quali metodi di pagamento appaiono e in quale ordine. Ogni transazione include un payment_method, e la risposta restituisce un payment_url all'interno dell'oggetto transazione:

{
  "currency": "EUR",
  "amount": 1295,
  "merchant_order_id": "my-order-id-1",
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    { "payment_method": "credit-card" }
  ]
}

{
  "id": "4851e31c-4137-4e91-95ef-1df945ee76a2",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "transactions": [
    {
      "id": "d291f03f-a406-428a-967a-4895a46e03fd",
      "payment_method": "credit-card",
      "status": "new",
      "payment_url": "https://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f.../"
    }
  ]
}

Reindirizza il cliente al payment_url dalla transazione.

Campi della Richiesta

Metodi di Pagamento Multipli

Esistono due modi per controllare quali metodi di pagamento appaiono sulla pagina ospitata:

Opzione A: payment_methods (filtro singolo). Passa un array a elemento singolo per limitare l'ordine a un metodo di pagamento. Ometti completamente il campo per mostrare tutti i metodi abilitati per il tuo account.

Opzione B: array transactions (consigliato per più metodi). Aggiungi una voce per metodo di pagamento. Ogni transazione ottiene il proprio payment_url e i metodi vengono visualizzati in ordine di array sulla pagina ospitata:

"transactions": [
  { "payment_method": "credit-card" },
  { "payment_method": "apple-pay" }
]

URL di Ritorno

Dopo il pagamento, il cliente viene reindirizzato in base allo stato dell'ordine e agli URL forniti:

• Quando sono impostati sia return_url che failure_url:

  • cancelled, expired o error → il cliente viene reindirizzato a failure_url
  • Tutti gli altri stati → il cliente viene reindirizzato a return_url

• Quando è impostato solo return_url:

  • Tutti gli stati → il cliente viene reindirizzato a return_url

Comportamento del Pulsante Annulla

La pagina di pagamento ospitata include un pulsante di annullamento. Quando il cliente lo clicca, viene reindirizzato a failure_url (se fornito) o return_url. Lo stato dell'ordine passerà a cancelled. Verifica sempre lo stato dell'ordine tramite l'API o i webhook piuttosto che fare affidamento solo sul reindirizzamento.

Endpoint Correlati

• Crea Ordine — crea un ordine di pagamento e ricevi il payment_url
• Ottieni Ordine — controlla lo stato dell'ordine dopo il pagamento