Cost+Docs

Mearthosnú

Glac le do chéad íocaíocht i 5 nóiméad

Treorófar tú tríd an treoir seo chun íocaíocht thástála a chruthú agus a chríochnú ag úsáid API Cost+. Faoi dheireadh, beidh comhtháthú oibre agat ar féidir leat tógáil air.

Réamhriachtanais

  • Cuntas Cost+ le suíomh gréasáin gaineamhchláir — cruthaigh ceann sa Tairseach Ceannaithe
  • D'eochair API gaineamhchláir (le fáil faoi Suíomhanna Gréasáin → do shuíomh gréasáin gaineamhchláir → Comhtháthú)

Níl tú cinnte conas d'eochair API a fháil? Féach ar Do Chomhtháthú a Thástáil le haghaidh treoracha socraithe mionsonraithe.

Céim 1: Ordú a Chruthú

Seol iarratas POST chun ordú íocaíochta a chruthú. Cuir d'eochair API gaineamhchláir in ionad YOUR_API_KEY:

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

Is slánuimhir é an amount i mionaonad ISO 4217 an airgeadra. I gcás EUR, ciallaíonn 1295 12.95 EUR.

Seolann an API an réad ordaithe iomlán ar ais. Is iad na réimsí tábhachtacha ná id, status, agus an payment_url taobh istigh den idirbheart:

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

Braitheann cruth an fhreagra ar an méid a sheolann tú:

  • Le heagar transactions (an mearthosach seo): tá payment_url dá chuid féin ag gach réad idirbhirt. Atreoraigh an custaiméir ann.
  • Gan transactions: tá order_url ag barr-leibhéal san ordú ina ionad sin, agus roghnaíonn an custaiméir modh íocaíochta ar leathanach óstáilte Cost+. Féach an treoir don Hosted Payment Page don sreabhadh sin.

Sábháil an id — beidh sé ag teastáil uait i gCéim 3.

Céim 2: An Íocaíocht Thástála a Chríochnú

  1. Oscail an payment_url ón bhfreagra i do bhrabhsálaí
  2. Ar an leathanach íocaíochta, cuir isteach sonraí an chárta tástála:
RéimseLuach
Uimhir chárta4111 1111 1111 1111
ÉagAon dáta amach anseo (m.sh. 12/28)
CVCAon 3 dhigit (m.sh. 123)
  1. Seol an íocaíocht
  2. Atreorófar ar ais tú chuig do return_url

Ná bí ag brath ar an atreorú amháin chun íocaíocht a dhearbhú. D'fhéadfadh an custaiméir a mbrabhsálaí a dhúnadh sula n-atreorófar iad. Fíoraigh i gcónaí tríd an API (Céim 3) nó webhookeanna (Céim 4).

Céim 3: An Íocaíocht a Fhíorú

Faigh an t-ordú chun a dhearbhú gur críochnaíodh é:

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

Breathnaíonn íocaíocht rathúil mar seo:

Response (completed)
{
  "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"
      }
    }
  ]
}

Tá status an ordaithe "completed" — d'éirigh leis an íocaíocht.

Céim 4: An Webhook a Láimhseáil (Molta)

Nuair a athraíonn stádas na híocaíochta, seolann Cost+ iarratas POST chuig do webhook_url:

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

Nuair a fhaigheann tú é seo:

  1. Glaoigh GET /v1/orders/{order_id}/ chun an stádas reatha a fhíorú (ná bí ag brath ar an sonraí webhook amháin riamh)
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil
  3. Comhlíon an t-ordú má tá an stádas "completed"

Le haghaidh forbartha áitiúil, úsáid tollán cosúil le ngrok chun do fhreastalaí áitiúil a nochtadh agus webhookeanna a fháil.

Féach ar an treoir Webhookeanna le haghaidh loighic atrialacha, dea-chleachtais, agus sonraí sonraí.

Rogha Eile: Naisc Íocaíochta

Mura bhfuil loighic atreoraithe ar thaobh an fhreastalaí ag teastáil uait, tugann naisc íocaíochta cosán níos simplí. Cruthaigh nasc, roinn an URL le do chustaiméir, agus seiceáil an stádas níos déanaí.

Create a payment link
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ítear payment_url san fhreagra ar féidir leat é a roinnt trí ríomhphost, SMS, nó comhrá. Is féidir leis an gcustaiméir iarracht a dhéanamh an íocaíocht a dhéanamh arís agus arís eile (suas le 25 uair) go dtí go n-éagann an nasc nó go n-éiríonn leis an íocaíocht.

Féach ar an treoir Naisc Íocaíochta le haghaidh an tsreabha oibre iomláin.

Céard Atá ar Aghaidh?

Tá do chéad íocaíocht críochnaithe agat. Seo na chéad chéimeanna eile:

Críochphointí Gaolmhara

On this page