Greitas startas

Šis gidas padės jums sukurti ir atlikti testinį mokėjimą naudojant Cost+ API. Pabaigoje turėsite veikiančią integraciją, kurią galėsite plėtoti.

Būtinosios sąlygos

• Cost+ paskyra su testavimo svetaine — sukurkite ją prekybininko portale
• Jūsų testavimo API raktas (randamas Websites → jūsų testavimo svetainė → Integration)

1 žingsnis: Sukurkite užsakymą

Siųskite POST užklausą, kad sukurtumėte mokėjimo užsakymą. Pakeiskite YOUR_API_KEY savo testavimo API raktu:

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

API grąžina pilną užsakymo objektą. Svarbiausi laukai yra id, status ir payment_url operacijos objekte:

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

Išsaugokite id — jis prireiks 3 žingsnyje.

2 žingsnis: Atlikite testinį mokėjimą

1. Atidarykite payment_url iš atsakymo savo naršyklėje
2. Mokėjimo puslapyje įveskite testinės kortelės duomenis:

3. Patvirtinkite mokėjimą
4. Būsite nukreipti atgal į savo return_url

3 žingsnis: Patikrinkite mokėjimą

Gaukite užsakymą, kad patvirtintumėte jo užbaigimą:

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

Sėkmingas mokėjimas atrodo taip:

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

Užsakymo status yra "completed" — mokėjimas sėkmingas.

4 žingsnis: Apdorokite Webhook (rekomenduojama)

Kai mokėjimo būsena pasikeičia, Cost+ siunčia POST užklausą į jūsų webhook_url:

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

Kai gaunate šį pranešimą:

1. Iškvieskite GET /v1/orders/{order_id}/, kad patikrintumėte esamą būseną (niekada nepasitikėkite vien webhook turiniu)
2. Grąžinkite HTTP 200, kad patvirtintumėte gavimą
3. Įvykdykite užsakymą, jei būsena yra "completed"

Žiūrėkite Webhooks gidą dėl pakartotinių bandymų logikos, geriausių praktikų ir turinio formatų.

Alternatyva: mokėjimo nuorodos

Jei jums nereikia serverio pusės peradresavimo logikos, mokėjimo nuorodos siūlo paprastesnį kelią. Sukurkite nuorodą, pasidalinkite URL su klientu ir patikrinkite būseną vėliau.

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

Atsakyme pateikiamas payment_url, kurį galite dalintis el. paštu, SMS ar pokalbiu. Klientas gali bandyti mokėti kelis kartus (iki 25), kol nuoroda baigiasi arba mokėjimas pavyksta.

Žiūrėkite Mokėjimo nuorodų gidą pilnam darbo eigai.

Kas toliau?

Atlikote pirmąjį mokėjimą. Štai kur eiti toliau:

• Mokėjimo puslapis (HPP) — pilna HPP nuoroda su visais užklausos laukais ir parinktimis
• Periodiniai mokėjimai — nustatykite prenumeratas ir suplanuotą atsiskaitymą
• Mokėjimas vienu paspaudimu — greitas atsiskaitymas grįžtantiems klientams
• Autorizacija / Surinkimas / Anuliavimas — pirmiausia autorizuokite, surinkite vėliau (pvz., siunčiant)
• Grąžinimai — apdorokite pilnus ir dalinius grąžinimus
• SDK — oficialios bibliotekos Node.js, Python, PHP, Java/Kotlin, C#/.NET ir Ruby
• Įskiepiai — paruoštos integracijos Shopify, WooCommerce, Magento ir kt.

Susiję galiniai taškai

• Sukurti užsakymą — pilna API nuoroda užsakymo kūrimui
• Gauti užsakymą — gauti užsakymo detales ir būseną
• Sukurti mokėjimo nuorodą — sukurti pakartotinai naudojamas mokėjimo nuorodas