Pikaopas

Tämä opas ohjaa sinut testmaksun luomisen ja suorittamisen läpi Cost+ API:n avulla. Lopussa sinulla on toimiva integraatio, jonka päälle voit rakentaa.

Edellytykset

• Cost+-tili, jossa on sandbox-verkkosivusto — luo sellainen kauppiasportaalissa
• Sandbox-API-avaimesi (löytyy kohdasta Websites → sandbox-verkkosivustosi → Integration)

Vaihe 1: Luo tilaus

Lähetä POST-pyyntö maksutilauksen luomiseksi. Korvaa YOUR_API_KEY sandbox-API-avaimellasi:

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 palauttaa täydellisen tilausobjektin. Tärkeimmät kentät ovat id, status ja tapahtuman sisällä oleva payment_url:

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

Tallenna id — tarvitset sitä vaiheessa 3.

Vaihe 2: Suorita testimaksu

1. Avaa vastauksen payment_url selaimessasi
2. Syötä maksusivulle testikortin tiedot:

3. Lähetä maksu
4. Sinut ohjataan takaisin return_url-osoitteeseesi

Vaihe 3: Vahvista maksu

Hae tilaus varmistaaksesi, että se on suoritettu:

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

Onnistunut maksu näyttää tältä:

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

Tilauksen status on "completed" — maksu onnistui.

Vaihe 4: Käsittele webhook (suositeltava)

Kun maksun tila muuttuu, Cost+ lähettää POST-pyynnön webhook_url-osoitteeseesi:

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

Kun vastaanotat tämän:

1. Kutsu GET /v1/orders/{order_id}/ varmistaaksesi nykyisen tilan (älä koskaan luota pelkästään webhook-dataan)
2. Palauta HTTP 200 vastaanottokuittauksena
3. Toimita tilaus, jos tila on "completed"

Katso Webhookit-opas uudelleenyrityslogiikasta, parhaista käytännöistä ja datan rakenteesta.

Vaihtoehto: Maksulinkit

Jos et tarvitse palvelinpuolen uudelleenohjausta, maksulinkit tarjoavat yksinkertaisemman tavan. Luo linkki, jaa URL asiakkaallesi ja tarkista tila myöhemmin.

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

Vastaus sisältää payment_url-osoitteen, jonka voit jakaa sähköpostitse, tekstiviestillä tai chatissa. Asiakas voi yrittää maksua useita kertoja (enintään 25), kunnes linkki vanhenee tai maksu onnistuu.

Katso Maksulinkit-opas täydellisestä työnkulusta.

Mitä seuraavaksi?

Olet suorittanut ensimmäisen maksusi. Tässä jatkosuuntia:

• Isännöity maksusivu — täydellinen HPP-viite kaikkine pyyntökenttineen ja vaihtoehtoihin
• Toistuvat maksut — tilausten ja ajoitetun laskutuksen käyttöönotto
• Yhden klikkauksen maksut — nopea kassa palaavaille asiakkaille
• Valtuutus / Veloitus / Mitätöinti — valtuuta ensin, veloita myöhemmin (esim. toimituksen yhteydessä)
• Palautukset — täysien ja osittaisten palautusten käsittely
• SDK:t — viralliset kirjastot Node.js:lle, Pythonille, PHP:lle, Java/Kotlinille, C#/.NET:lle ja Rubylle
• Lisäosat — valmiit integraatiot Shopifylle, WooCommercelle, Magentolle ja muille

Liittyvät päätepisteet

• Luo tilaus — täydellinen API-viite tilauksen luomiseen
• Hae tilaus — hae tilauksen tiedot ja tila
• Luo maksulinkki — luo uudelleenkäytettäviä maksulinkkejä