Kiirstart

See juhend juhendab teid testmakse loomise ja lõpuleviimise kaudu Cost+ API abil. Lõpuks on teil toimiv integratsioon, mille peale edasi ehitada.

Eeldused

Cost+ konto liivakasti veebilehega — looge see kaupmehe portaalis
Teie liivakasti API võti (leitav jaotises Veebilehed → teie liivakasti veebileht → Integratsioon)

Pole kindel, kuidas oma API võtit leida? Vaadake lehte Integratsiooni testimine üksikasjalike seadistusjuhiste saamiseks.

1. samm: Looge tellimus

Saatke POST päring makse tellimuse loomiseks. Asendage YOUR_API_KEY oma liivakasti API võtmega:

Tellimuse loomine

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

amount on väikseimas valuutaühikus (sendid). 1295 tähendab 12,95 EUR.

API tagastab täieliku tellimuse objekti. Olulisemad väljad on id, status ja tehingu sees olev payment_url:

Vastus

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

Salvestage id — seda läheb vaja 3. sammus.

2. samm: Viige testmakse lõpule

Avage vastuses olev payment_url oma brauseris
Makselehel sisestage testkaardi andmed:

Väli	Väärtus
Kaardinumber	`4111 1111 1111 1111`
Kehtivus	Suvaline tulevane kuupäev (nt `12/28`)
CVC	Suvaline 3-kohaline number (nt `123`)

Esitage makse
Teid suunatakse tagasi teie return_url-ile

Ärge tuginege makse kinnitamisel ainult ümbersuunamisele. Klient võib enne ümbersuunamist brauseri sulgeda. Kontrollige alati API (3. samm) või veebihaakide (4. samm) kaudu.

3. samm: Kinnitage makse

Pärige tellimus, et kinnitada selle lõpuleviimine:

Tellimuse oleku kontrollimine

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

Edukas makse näeb välja selline:

Vastus (lõpule viidud)

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

Tellimuse status on "completed" — makse oli edukas.

4. samm: Käsitlege veebihaaki (soovitatav)

Kui makse olek muutub, saadab Cost+ POST päringu teie webhook_url-ile:

Veebihaagi andmed

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

Kui selle kätte saate:

Kutsuge GET /v1/orders/{order_id}/, et kontrollida praegust olekut (ärge kunagi usaldage ainult veebihaagi andmeid)
Tagastage HTTP 200 kättesaamise kinnitamiseks
Täitke tellimus, kui olek on "completed"

Kohalikuks arenduseks kasutage tunnelit nagu ngrok, et paljastada oma kohalik server ja vastu võtta veebihaake.

Vaadake veebihaakide juhendit korduskatsete loogika, parimate tavade ja andmevormingute kohta.

Alternatiiv: Makselingid

Kui te ei vaja serveripoolset ümbersuunamisloogikat, pakuvad makselingid lihtsamat viisi. Looge link, jagage URL-i oma kliendiga ja kontrollige olekut hiljem.

Makselingi loomine

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

Vastus sisaldab payment_url-i, mida saate jagada e-posti, SMS-i või vestluse kaudu. Klient saab makset proovida mitu korda (kuni 25), kuni link aegub või makse õnnestub.

Vaadake makselinkide juhendit täieliku töövoo kohta.

Mis edasi?

Olete oma esimese makse lõpule viinud. Siit saate edasi minna:

Hostitud makseleht — täielik HPP viide kõigi päringuväljadega ja valikutega
Korduvmaksed — seadistage tellimused ja ajastatud arveldamine
Ühe klõpsuga maksed — kiire maksmine tagasitulevatele klientidele
Autoriseerimine / hõivamine / tühistamine — autoriseerige kõigepealt, hõivake hiljem (nt saatmisel)
Tagasimaksed — töötlege täielikke ja osalisi tagasimakseid
SDK-d — ametlikud teegid Node.js, Python, PHP, Java/Kotlin, C#/.NET ja Ruby jaoks
Pluginad — valmisintegratsioonid Shopify, WooCommerce, Magento ja muude jaoks

Seotud lõpp-punktid

Tellimuse loomine — täielik API viide tellimuse loomiseks
Tellimuse pärimine — tellimuse üksikasjade ja oleku pärimine
Makselingi loomine — korduvkasutatavate makselinkide loomine

On this page