Flýtiræsing

Þessi leiðbeining leiðir þig í gegnum stofnun og framkvæmd prófunargreiðslu með Cost+ API. Í lokin muntu hafa virka samþættingu sem þú getur byggt á.

Forsendur

• Cost+ reikningur með sandbox-vefsíðu — stofnaðu einn í gátt söluaðila
• API lykillinn þinn fyrir sandbox (finnst undir Vefsíður → sandbox-vefsíðan þín → Samþætting)

Skref 1: Stofnaðu pöntun

Sendu POST-beiðni til að stofna greiðslupöntun. Skiptu YOUR_API_KEY út fyrir sandbox API lykilinn þinn:

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 skilar heildarpöntunarhlutunum. Lykillreitirnir eru id, status og payment_url innan færslunnar:

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

Vistaðu id — þú munt þurfa á því að halda í skrefi 3.

Skref 2: Ljúktu prófunargreiðslunni

1. Opnaðu payment_url úr svarinu í vafranum þínum
2. Á greiðslusíðunni, sláðu inn prófunarkortaupplýsingarnar:

3. Staðfestu greiðsluna
4. Þér verður vísað aftur á return_url þitt

Skref 3: Staðfestu greiðsluna

Sæktu pöntunina til að staðfesta að hún hafi verið lokið:

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

Vel heppnuð greiðsla lítur svona út:

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

Staða pöntunar er "completed" — greiðslan tókst.

Skref 4: Meðhöndlaðu webhook-inn (ráðlagt)

Þegar greiðslustaðan breytist sendir Cost+ POST-beiðni á webhook_url þitt:

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

Þegar þú tekur á móti þessu:

1. Kallaðu á GET /v1/orders/{order_id}/ til að staðfesta núverandi stöðu (treystu aldrei webhook-gagnagrunni einum)
2. Skilaðu HTTP 200 til staðfestingar á móttöku
3. Uppfylltu pöntunina ef staðan er "completed"

Sjá webhook-leiðbeininguna fyrir endurtilraunarrök, bestu venjur og upplýsingar um gagnagrunna.

Valkostur: Greiðslutenglar

Ef þú þarft ekki endurbeiningarrök á þjónahlið, bjóða greiðslutenglar einfaldari leið. Stofnaðu tengil, deildu URL-inu með viðskiptavininum og athugaðu stöðuna síðar.

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

Svarið inniheldur payment_url sem þú getur deilt með tölvupósti, SMS eða spjalli. Viðskiptavinurinn getur reynt greiðslu mörgum sinnum (allt að 25) þar til tengillinn rennur út eða greiðsla tekst.

Sjá leiðbeininguna um greiðslutengla fyrir fullt verkflæði.

Hvað næst?

Þú hefur lokið fyrstu greiðslunni. Hér er hvert á að halda:

• Hýst greiðslusíða — full HPP tilvísun með öllum beiðnireitum og valkostum
• Endurteknar greiðslur — settu upp áskriftir og áætlaða innheimtu
• Greiðslur með einum smelli — fljótleg afgreiðsla fyrir endurkomu viðskiptavini
• Heimild / söfnun / ógilding — heimilaðu fyrst, safnaðu síðar (t.d. við sendingu)
• Endurgreiðslur — vinndu úr fullum og hluta endurgreiðslum
• SDK — opinber söfn fyrir Node.js, Python, PHP, Java/Kotlin, C#/.NET og Ruby
• Viðbætur — tilbúnar samþættingar fyrir Shopify, WooCommerce, Magento og fleira

Tengdir endapunktar

• Stofna pöntun — full API tilvísun fyrir stofnun pöntunar
• Sækja pöntun — sækja upplýsingar og stöðu pöntunar
• Stofna greiðslutengil — stofna endurnýtanlega greiðslutengla