Pagina de plată găzduită (HPP)

Pagina de plată găzduită (HPP) este formularul de plată conform PCI DSS al Cost+. Vă permite să acceptați plăți fără a gestiona date sensibile ale cardurilor pe propriile servere. Creați o comandă prin API, redirecționați clientul către pagina găzduită, iar acesta revine pe site-ul dvs. după plată.

Cum funcționează

Serverul dvs. creează o comandă apelând POST /v1/orders/.
API-ul returnează un URL care indică pagina de plată găzduită.
Redirecționați clientul către pagina de plată.
Clientul finalizează plata pe pagina găzduită Cost+.
Clientul este redirecționat înapoi la return_url (sau failure_url pentru plăți eșuate).
Cost+ trimite o notificare webhook la webhook_url cu statusul comenzii.

Pagina de plată găzduită este complet conformă PCI DSS. Nu trebuie niciodată să gestionați numere de card sau date sensibile de plată pe serverele dvs.

Crearea unei comenzi

Există două abordări pentru utilizarea HPP:

Abordarea 1: Afișați toate metodele de plată (Cea mai simplă)

Creați o comandă fără a specifica transactions. Răspunsul include un order_url — clientul este redirecționat acolo și vede toate metodele de plată activate pentru contul dvs.:

Request

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

Response

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

Redirecționați clientul la order_url. Pe pagina găzduită, sunt afișate toate metodele de plată activate.

Abordarea 2: Preselectați metodele de plată

Creați o comandă cu un array transactions pentru a controla ce metode de plată apar și în ce ordine. Fiecare tranzacție include un payment_method, iar răspunsul returnează un payment_url în obiectul tranzacției:

Request

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

Response

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

Redirecționați clientul la payment_url din tranzacție.

Dacă furnizați o singură intrare în array-ul transactions, clientul este direcționat direct la acea metodă de plată fără a vedea un ecran de selecție. Array-ul flags conține "is-test" când se folosește o cheie API sandbox.

Câmpuri ale cererii

Câmp	Obligatoriu	Descriere
`currency`	Da	Cod valutar ISO 4217 (de ex., `EUR`, `GBP`, `SEK`)
`amount`	Da	Suma în cenți. De exemplu, 12,95 EUR este reprezentat ca `1295`
`merchant_order_id`	Nu	ID-ul dvs. de referință propriu pentru comandă
`return_url`	Nu	URL pentru redirecționarea clientului după plată (implicit pentru toate statusurile)
`failure_url`	Nu	URL pentru redirecționarea clientului la statusul `cancelled`, `expired` sau `error` (vezi URL-uri de redirecționare mai jos)
`locale`	Nu	Limba paginii de plată. Suportate: `en-GB`, `de-DE`, `nl-NL`, `nl-BE`, `fr-BE`, `sv-SE`, `no-NO`, `da-DK`
`description`	Nu	Descrierea comenzii, afișată clientului
`payment_methods`	Nu	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`	Nu	URL pentru a primi notificări de schimbare a statusului
`expiration_period`	Nu	Durată ISO 8601 pentru expirarea comenzii. Implicit este `PT30M` (30 minute)

Câmpul amount este întotdeauna în cea mai mică unitate monetară (cenți). Transmiterea 1295 înseamnă 12,95 în moneda dată. Transmiterea 1295.00 sau 12.95 va rezulta într-o eroare sau o taxare incorectă.

Metode de plată multiple

Pentru a oferi mai multe metode de plată specifice, adăugați mai multe intrări în array-ul transactions. Ordinea pe pagina găzduită corespunde ordinii din 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-uri de redirecționare

După plată, clientul este redirecționat în funcție de statusul comenzii și de URL-urile furnizate:

Când sunt setate atât return_url cât și failure_url:
- cancelled, expired sau error → clientul este redirecționat la failure_url
- Toate celelalte statusuri → clientul este redirecționat la return_url
Când este setat doar return_url:
- Toate statusurile → clientul este redirecționat la return_url

Folosiți failure_url pentru a afișa o pagină de reîncercare sau suport pentru plăți eșuate, în timp ce return_url afișează o confirmare a comenzii. Dacă aveți nevoie de o singură destinație, doar return_url este suficient.

Comportamentul butonului de anulare

Pagina de plată găzduită include un buton de anulare. Când clientul apasă pe el, este redirecționat la failure_url (dacă este furnizat) sau return_url. Statusul comenzii va trece la cancelled. Verificați întotdeauna statusul comenzii prin API sau webhook-uri, în loc să vă bazați doar pe redirecționare.

Endpoint-uri asociate

Creare comandă — creați o comandă de plată și primiți payment_url
Obținere comandă — verificați statusul comenzii după plată

On this page