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://api.costplus.online/pay/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://api.costplus.online/pay/4851e31c.../select-payment-method/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 unitatea minoră ISO 4217 a monedei. 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	Filtrați la o singură metodă de plată (de exemplu, `["credit-card"]`). Omiteți pentru a afișa toate metodele activate. Pentru mai multe metode specifice, utilizați în schimb matricea `transactions`
`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 un număr întreg în unitatea minoră ISO 4217 a monedei. Pentru EUR, 1295 înseamnă 12,95 EUR; Monedele cu zero și trei zecimale folosesc propriul exponent ISO 4217. Trecerea unei valori zecimale precum 1295.00 sau 12.95 va duce la o eroare sau o taxare incorectă.

Metode de plată multiple

Există două moduri de a controla ce metode de plată apar pe pagina găzduită:

Opțiunea A — payment_methods (filtru unic). Transmite o matrice cu un singur element pentru a restricționa comanda la o singură metodă de plată. Omiteți în întregime câmpul pentru a afișa toate metodele activate pentru contul dvs.

Opțiunea B — matrice transactions (recomandat pentru mai multe metode). Adăugați o intrare pentru fiecare metodă de plată. Fiecare tranzacție primește propriul payment_url, iar metodele apar în ordinea matricei pe pagina găzduită:

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

Câmpul payment_methods al comenzilor acceptă cel mult o valoare. Pentru a oferi mai multe metode specifice, utilizați întotdeauna matricea transactions. Dacă aveți nevoie de un link reutilizabil cu mai multe metode de plată, luați în considerare Link-uri de plată, care acceptă o matrice payment_methods adevărată.

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ă

Pagina de plată găzduită (HPP)

On this page