Pornire rapidă

Acest ghid vă prezintă crearea și finalizarea unei plăți de test folosind API-ul Cost+. La final, veți avea o integrare funcțională pe care o puteți dezvolta mai departe.

Cerințe preliminare

Un cont Cost+ cu un site web sandbox — creați unul în portalul comerciantului
Cheia API sandbox (se găsește la Site-uri web → site-ul dvs. sandbox → Integrare)

Nu știți cum să obțineți cheia API? Consultați Testarea integrării pentru instrucțiuni detaliate de configurare.

Pasul 1: Creați o comandă

Trimiteți o cerere POST pentru a crea o comandă de plată. Înlocuiți YOUR_API_KEY cu cheia API sandbox:

Create an order

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

Câmpul amount este exprimat în cea mai mică unitate monetară (cenți). 1295 înseamnă 12,95 EUR.

API-ul returnează obiectul complet al comenzii. Câmpurile cheie sunt id, status și payment_url din tranzacție:

Response

{
  "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ți id — veți avea nevoie de el la Pasul 3.

Pasul 2: Finalizați plata de test

Deschideți payment_url din răspuns în browser
Pe pagina de plată, introduceți datele cardului de test:

Câmp	Valoare
Număr card	`4111 1111 1111 1111`
Expirare	Orice dată viitoare (de ex. `12/28`)
CVC	Orice 3 cifre (de ex. `123`)

Trimiteți plata
Veți fi redirecționat înapoi la return_url

Nu vă bazați doar pe redirecționare pentru a confirma plata. Clientul poate închide browserul înainte de redirecționare. Verificați întotdeauna prin API (Pasul 3) sau webhook-uri (Pasul 4).

Pasul 3: Verificați plata

Preluați comanda pentru a confirma finalizarea:

Check order status

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

O plată reușită arată astfel:

Response (completed)

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

Statusul comenzii este "completed" — plata a fost efectuată cu succes.

Pasul 4: Gestionați webhook-ul (Recomandat)

Când statusul plății se schimbă, Cost+ trimite o cerere POST la webhook_url:

Webhook payload

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

Când primiți acest webhook:

Apelați GET /v1/orders/{order_id}/ pentru a verifica statusul curent (nu aveți încredere doar în payload-ul webhook-ului)
Returnați HTTP 200 pentru a confirma recepția
Onorați comanda dacă statusul este "completed"

Pentru dezvoltare locală, folosiți un tunel precum ngrok pentru a expune serverul local și a primi webhook-uri.

Consultați ghidul Webhook-uri pentru logica de reîncercare, bune practici și detalii despre payload.

Alternativă: Linkuri de plată

Dacă nu aveți nevoie de logica de redirecționare pe server, linkurile de plată oferă o cale mai simplă. Creați un link, partajați URL-ul cu clientul și verificați statusul ulterior.

Create a payment link

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

Răspunsul include un payment_url pe care îl puteți partaja prin email, SMS sau chat. Clientul poate încerca plata de mai multe ori (până la 25) până când linkul expiră sau plata reușește.

Consultați ghidul Linkuri de plată pentru fluxul complet.

Ce urmează?

Ați finalizat prima plată. Iată unde puteți continua:

Pagina de plată găzduită — referința completă HPP cu toate câmpurile și opțiunile de cerere
Plăți recurente — configurați abonamente și facturare programată
Plăți cu un click — checkout rapid pentru clienții care revin
Autorizare / Captură / Anulare — autorizați mai întâi, capturați ulterior (de ex. la expediere)
Rambursări — procesați rambursări totale și parțiale
SDK-uri — biblioteci oficiale pentru Node.js, Python, PHP, Java/Kotlin, C#/.NET și Ruby
Plugin-uri — integrări predefinite pentru Shopify, WooCommerce, Magento și altele

Endpoint-uri asociate

Creare comandă — referința completă API pentru crearea comenzilor
Obținere comandă — preluarea detaliilor și statusului comenzii
Creare link de plată — crearea de linkuri de plată reutilizabile

On this page