Tilakyselyt

Jokainen maksu Cost+:ssa esitetään tilauksena, joka sisältää yhden tai useamman tapahtuman. Voit tarkistaa minkä tahansa tilauksen nykyisen tilan kyselemällä API:lta joko pollaamalla tai käyttämällä webhookeja.

Tilauksen tilan hakeminen

Lähetä GET-pyyntö osoitteeseen /v1/orders/\{id\}/ hakeaksesi täydellisen tilausobjektin, mukaan lukien sen nykyinen tila ja kaikki liittyvät tapahtumat.

GET /v1/orders/b9ae6.../

Vaikka pollaaminen toimii tilauksen tilan tarkistamiseen, webhookit ovat suositeltava tapa tuotantointegraatioissa. Ne tarjoavat reaaliaikaiset ilmoitukset ilman toistuvien API-kutsujen kuormitusta.

Tilausten tilat

Tilaus etenee seuraavien tilojen kautta:

Tila	Lopullinen	Kuvaus
`new`	Ei	Tilaus on juuri luotu. Maksuyritystä ei ole vielä tehty.
`processing`	Ei	Maksuyritys on käynnissä. Asiakas saattaa suorittaa 3D Secure -todennusta tai muuta vahvistusvaihetta.
`error`	Ei	Maksuyritys epäonnistui. Asiakas voi yrittää uudelleen samalla tai eri maksutavalla.
`completed`	Kyllä	Maksu onnistui. Voit toimittaa tilauksen.
`cancelled`	Kyllä	Tilaus peruutettiin joko asiakkaan tai API:n toimesta.
`expired`	Kyllä	Tilaus vanheni ennen onnistunutta maksua. Oletusvanhenemisaika on 30 minuuttia.

Vain Lopullinen = Kyllä -merkityt tilat ovat lopullisia. Tiloissa new, processing tai error olevat tilaukset voivat edelleen siirtyä tilaan completed.

Esimerkki: Tilaus käsittelyssä

Kun asiakas on aloittanut maksun, mutta se ei ole vielä valmis:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:01:30.000000+00:00",
  "completed": null,
  "expiration_period": "PT30M",
  "status": "processing",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "status": "processing",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Esimerkki: Valmis tilaus

Kun maksu on onnistunut, tilaus saavuttaa completed-tilan:

{
  "id": "b9ae6...",
  "project_id": "proj_abc123",
  "merchant_order_id": "my-order-id-1",
  "created": "2024-01-01T12:00:00.000000+00:00",
  "modified": "2024-01-01T12:02:15.000000+00:00",
  "completed": "2024-01-01T12:02:15.000000+00:00",
  "expiration_period": "PT30M",
  "status": "completed",
  "currency": "EUR",
  "amount": 1295,
  "description": "My amazing order",
  "return_url": "https://www.example.com",
  "payment_url": "https://pay.costplus.com/...",
  "webhook_url": "https://www.example.com/webhook",
  "transactions": [
    {
      "id": "txn_001...",
      "payment_method": "credit-card",
      "payment_method_brand": "visa",
      "payment_method_details": {
        "card_last_four": "4242",
        "card_expiry_month": 12,
        "card_expiry_year": 2026,
        "card_holder_name": "J. Smith"
      },
      "status": "completed",
      "amount": 1295,
      "currency": "EUR"
    }
  ],
  "flags": ["is-test"]
}

Tapahtuman tiedot

Jokainen tilauksen sisällä oleva tapahtuma sisältää seuraavat tärkeimmät kentät:

Kenttä	Kuvaus
`payment_method`	Käytetty maksutapa (esim. `credit-card`, `ideal`, `apple-pay`)
`payment_method_brand`	Brändi tai myöntäjä (esim. `visa`, `mastercard`, `amex`)
`payment_method_details`	Objekti, joka sisältää maksutapakohtaiset tiedot, kuten kortin neljä viimeistä numeroa, voimassaolopäivän ja kortinhaltijan nimen
`status`	Tämän yksittäisen tapahtuman tila
`amount`	Tapahtuman summa senteissä
`currency`	Tapahtuman valuutta

Älä luota pelkästään asiakkaan uudelleenohjaukseen return_url-osoitteeseesi maksun vahvistuksena. Vahvista aina tilauksen tila API:n tai webhookin kautta ennen tilauksen toimittamista.

Liittyvät päätepisteet

Hae tilaus — hae täydellinen tilausobjekti ja sen nykyinen tila
Listaa tilaukset — listaa tilaukset päivämäärävälin mukaan suodatettuna