Maksuaikomukset

Maksuaikomus (payment intent) on pyyntösi periä asiakkaalta fiat-valuutassa määritetty summa. Siihen kuuluvat isännöity kassaistunto, maksun perivä käsittelijän lasku (live-maksuissa lasku alustan Bitcart-tilillä) sekä koko tilahistoria. Laskut ja maksulinkit luovat maksuaikomuksia taustalla. Maksuaikomuksia voi luoda, kun tilisi on aktivoitu.

POST/v1/payment-intentslive · tilin aktivoinnin jälkeen

Luominen

Kenttä	Pakollinen	Huomiot
store_id	kyllä	Organisaatiosi kauppa
amount	kyllä	Desimaalimerkkijono, jossa on enintään valuutan alayksikön mukainen määrä desimaaleja: "59.90"
currency	kyllä	EUR, USD, BRL tai GBP (tilityksen viitevaluutta)
allowed_networks	ei	Jätä pois live-maksuista: ne tarjoavat kaikki alustan hyväksymät varat, ja kenttä torjutaan koodilla allowed_networks_unsupported. (Vain pelkkään seurantaan perustuvassa käsittelyssä: osajoukko käyttöön otetuista verkoista, joille kaupalla on aktiivinen lompakko)
allowed_methods	ei	["crypto"] (oletus; fiat-maksutavat eivät ole saatavilla)
merchant_order_id	ei	Oma viitteesi (≤ 200 merkkiä); haettavissa
description	ei	Näytetään asiakkaalle (≤ 500 merkkiä)
customer.email / customer.reference	ei	Minimoitu data: vain se, mitä tarvitset täsmäytykseen
metadata	ei	Enintään 20 merkkijonomuotoista avain–arvo-paria omaan käyttöösi
return_url / cancel_url	ei	Minne kassa ohjaa asiakkaan lopuksi
expires_in_seconds	ei	300–86 400, oletus 3 600

Vastaus sisältää kentät id, status (created), livemode, expires_at, checkout_session_id, checkout_url ja processor. Live-maksuissa processor kuvaa laskua alustan Bitcart-tilillä (name: "bitcart", custodial: true, laskun tila, maksutavat sen jälkeen, kun kassa on avannut laskun, sekä tieto siitä, onko vastaanotettu summa hyvitetty (credited) saldoosi); quote, payment_instructions ja totals kuuluvat pelkkään seurantaan perustuvaan käsittelyyn ja pysyvät arvossa null.

Summat validoidaan tiukasti: ei etumerkkejä, ei eksponentteja, ei ylimääräisiä desimaaleja — mitään ei pyöristetä hiljaisesti.

Lukeminen

GET /v1/payment-intents/{id} palauttaa aikomuksen seuraavine kenttineen:

• processor — live-maksuissa Bitcart-lasku: tila, poikkeustila, maksutavat, maksettu vara ja summa, transaktiotiivisteet sekä tieto siitä, onko summa hyvitetty saldoosi.
• quote, payment_instructions ja totals — vain pelkkään seurantaan perustuvassa käsittelyssä: lukittu tarjous (katso Hintatarjoukset), osoite ja tarkka maksettava summa sekä odotettu, vastaanotettu ja vahvistettu summa.
• required_confirmations, detected_at, confirmed_at, resolution.
• fulfillable — true vain, kun odotettu summa on lopullinen lohkoketjussa (confirmed, overpaid tai ratkaistu hyväksytyksi).

Toimita vasta, kun maksu on toimitettavissa

Älä toimita tuotteita sen perusteella, että siirto on nähty. Tiloissa detected ja confirming siirto voidaan vielä korvata, järjestää uudelleen tai käyttää kahteen kertaan. Odota arvoa fulfillable: true ja tarkista tilanne kutsulla GET /v1/payment-intents/{id} ennen jokaista webhookin käynnistämää peruuttamatonta toimenpidettä.

GET /v1/payment-intents/{id}/timeline palauttaa vain lisäyksiä sallivan luettelon tilasiirtymistä syineen, tekijöineen ja todisteineen (siirtojen tunnisteet, vahvistusmäärät, tarjouksen tunniste, hyväksynnät). Itse siirrot ovat saatavilla kutsulla GET /v1/transactions?payment_intent_id=….

Peruminen

POST /v1/payment-intents/{id}/cancel peruu aikomuksen ennen kuin yhtään siirtoa on havaittu. Kun siirto on nähty, rajapinta palauttaa virheen conflict_error: rahaa voi jo olla matkalla, ja aikomuksen on edettävä tilakoneen mukaisesti.

Tarkistustilojen ratkaiseminen

Jotkin lopputulokset vaativat ihmisen päätöksen: underpaid, overpaid, late_payment, manual_review. Kirjaa päätöksesi kutsulla POST /v1/payment-intents/{id}/resolve:

{ "resolution": "accepted_partial", "note": "Customer confirmed by email; shipping the partial order." }

resolution	Käytä, kun
accepted	Hyväksyt maksun sellaisenaan
accepted_partial	Hyväksyt alimaksun
accepted_overpayment	Hyväksyt ylimaksun (ja hoidat ylijäämän asiakkaan kanssa)
refunded_offchain	Palautit varat omasta lompakostasi
rejected	Et hyväksy maksua

note (≥ 10 merkkiä) tallennetaan auditointijälkeen. Ratkaisu ei koskaan muokkaa tai poista lohkoketjutodisteita — alkuperäiset havainnot ja siirtymät säilyvät ennallaan.

Aikomusten webhookit

payment_intent.created, invoice.awaiting_payment, payment.detected, payment.confirming, payment.confirmed, payment.expired, payment.review_required, payment.reorged, payment.resolved, payment.canceled. Katso Webhookit.