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

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

La pagina di pagamento ospitata è completamente conforme PCI DSS. Non dovrai mai gestire numeri di carta grezzi o dati di pagamento sensibili sui tuoi server.

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:

Richiesta

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

Risposta

{
  "id": "43114fde-da30-4115-8004-b7f808f9b25c",
  "status": "new",
  "currency": "EUR",
  "amount": 1295,
  "order_url": "https://pay.costplus.online/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:

Richiesta

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

Risposta

{
  "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://pay.costplus.online/4851e31c.../credit-card/d291f03f.../"
    }
  ]
}

Reindirizza il cliente al payment_url dalla transazione.

Se fornisci una sola voce nell'array transactions, il cliente viene portato direttamente a quel metodo di pagamento senza vedere una schermata di selezione. L'array flags contiene "is-test" quando si utilizza una chiave API sandbox.

Campi della Richiesta

Campo	Obbligatorio	Descrizione
`currency`	Sì	Codice valuta ISO 4217 (es. `EUR`, `GBP`, `SEK`)
`amount`	Sì	Importo in centesimi. Ad esempio, 12,95 EUR è rappresentato come `1295`
`merchant_order_id`	No	Il tuo ID di riferimento per l'ordine
`return_url`	No	URL a cui reindirizzare il cliente dopo il pagamento (predefinito per tutti gli stati)
`failure_url`	No	URL a cui reindirizzare il cliente in caso di stato `cancelled`, `expired` o `error` (vedi URL di Ritorno sotto)
`locale`	No	Lingua della pagina di pagamento. Supportate: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	No	Descrizione dell'ordine, mostrata al cliente
`payment_methods`	No	Filter to a single payment method (e.g. `["credit-card"]`). Omit to show all enabled methods. For multiple specific methods, use the `transactions` array instead
`webhook_url`	No	URL per ricevere le notifiche di cambio stato
`expiration_period`	No	Durata ISO 8601 per la scadenza dell'ordine. Il valore predefinito è `PT30M` (30 minuti)

Il campo amount è sempre nell'unità valutaria più piccola (centesimi). Passare 1295 significa 12,95 nella valuta specificata. Passare 1295.00 o 12.95 risulterà in un errore o in un addebito errato.

Metodi di Pagamento Multipli

Per offrire più metodi di pagamento specifici, aggiungi più voci all'array transactions. L'ordine sulla pagina ospitata corrisponde all'ordine dell'array:

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

The payment_methods field on orders accepts at most one value. To offer multiple specific methods, always use the transactions array. If you need a reusable link with multiple payment methods, consider Payment Links instead, which support a true payment_methods array.

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

Usa failure_url per mostrare una pagina di riprova o supporto per i pagamenti falliti, mentre return_url mostra una conferma dell'ordine. Se hai bisogno di una sola destinazione, return_url da solo è sufficiente.

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

On this page