Cost+Docs

Bidu Malajr

Aċċetta l-ewwel ħlas tiegħek fi 5 minuti

Din il-gwida tmexxik pass pass biex toħloq u tlesti ħlas ta' test bl-użu tal-API ta' Cost+. Fl-aħħar, ikollok integrazzjoni li taħdem li tista' tibni fuqha.

Prerekwiżiti

Mhux żgur kif tikseb iċ-ċavetta API tiegħek? Ara Ittestjar tal-Integrazzjoni għal istruzzjonijiet dettaljati dwar is-setup.

Pass 1: Oħloq Ordni

Ibgħat talba POST biex toħloq ordni ta' ħlas. Ibdel YOUR_API_KEY biċ-ċavetta API sandbox tiegħek:

Oħloq ordni
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"
      }
    ]
  }'

Iż-amount huwa numru sħiħ fl-unità minuri ISO 4217 tal-munita. Għal EUR, 1295 tfisser 12.95 EUR.

L-API tirritorna l-oġġett sħiħ tal-ordni. L-oqsma ewlenin huma id, status, u l-payment_url ġewwa t-tranżazzjoni:

Risposta
{
  "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://api.costplus.online/pay/4851e31c.../select-payment-method/credit-card/d291f03f...",
      "is_capturable": false,
      "expiration_period": "PT30M"
    }
  ]
}

Il-forma tar-rispons tiddependi fuq dak li tibgħat:

  • B'array transactions (din il-quickstart): kull oġġett ta' tranżazzjoni fih payment_url tiegħu stess. Idderiġi lill-klijent hemmhekk.
  • Mingħajr transactions: l-ordni għandu minflok order_url fl-ogħla livell, u l-klijent jagħżel metodu ta' ħlas fuq il-paġna ospitata minn Cost+. Ara l-gwida Hosted Payment Page għal dan il-fluss.

Issejvja l-id — se jkollok bżonnha fil-Pass 3.

Pass 2: Lesti l-Ħlas ta' Test

  1. Iftaħ il-payment_url mir-risposta fil-browser tiegħek
  2. Fuq il-paġna tal-ħlas, daħħal id-dettalji tal-karta tat-test:
QasamValur
Numru tal-karta4111 1111 1111 1111
SkadenzaKwalunkwe data futura (eż. 12/28)
CVCKwalunkwe 3 ċifri (eż. 123)
  1. Issottometti l-ħlas
  2. Se tiġi ridirezzjonat lura lejn ir-return_url tiegħek

Tiddependix biss fuq ir-redirect biex tikkonferma l-ħlas. Il-klijent jista' jagħlaq il-browser qabel ma jiġi ridirezzjonat. Dejjem ivverifika permezz tal-API (Pass 3) jew webhooks (Pass 4).

Pass 3: Ivverifika l-Ħlas

Iġbed l-ordni biex tikkonferma li tlestiet:

Iċċekkja l-istatus tal-ordni
curl -u YOUR_API_KEY: \
  https://api.costplus.online/v1/orders/4851e31c-4137-4e91-95ef-1df945ee76a2/

Ħlas li rnexxielu jidher hekk:

Risposta (kompluta)
{
  "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"
      }
    }
  ]
}

L-istatus tal-ordni hija "completed" — il-ħlas irnexxielu.

Pass 4: Ittratta l-Webhook (Rakkomandat)

Meta l-istatus tal-ħlas tinbidel, Cost+ tibgħat talba POST lejn il-webhook_url tiegħek:

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

Meta tirċievi dan:

  1. Sejjaħ GET /v1/orders/{order_id}/ biex tivverifika l-istatus kurrenti (qatt tafda l-payload tal-webhook waħdu)
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta
  3. Issodisfa l-ordni jekk l-istatus hija "completed"

Għall-iżvilupp lokali, uża tunnel bħal ngrok biex tesponi s-server lokali tiegħek u tirċievi webhooks.

Ara l-gwida tal-Webhooks għal-loġika tar-retry, l-aħjar prattiċi, u dettalji tal-payload.

Jekk m'għandekx bżonn loġika ta' redirect fuq is-server, links tal-ħlas joffru triq aktar sempliċi. Oħloq link, aqsam l-URL mal-klijent tiegħek, u ċċekkja l-istatus aktar tard.

Oħloq link tal-ħlas
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"
  }'

Ir-risposta tinkludi payment_url li tista' taqsam permezz ta' email, SMS, jew chat. Il-klijent jista' jipprova l-ħlas diversi drabi (sa 25) sakemm il-link jiskadi jew il-ħlas jirnexxielu.

Ara l-gwida tal-Links tal-Ħlas għall-workflow sħiħ.

X'Jmiss?

Lestejt l-ewwel ħlas tiegħek. Hawn fejn tista' tmur minn hawn:

Endpoints Relatati

On this page