Kauppiaan opas · nsn-002
BTCPay-ilmoitus tuli, mutta tilaus ei päivittynyt: kauppiaan täsmäytys
Versiosidonnainen BTCPay-dokumentaatio: todellista palvelinta, integraatiota tai maksua ei ole testattu. Varmista oman asennuksesi versio ja toiminta erikseen.
Tämä on BTCPay Serveriä käyttävän kauppiaan ja integraation ylläpitäjän selvitysohje tilanteeseen, jossa ilmoituksen ja verkkokaupan tilauksen tiedot näyttävät ristiriitaisilta. Se ei ole valmis integraatiototeutus. Mitään palvelinta, tilausta, palautusta tai todellista webhookia ei ole testattu.
Selvitä katkos lukien, älä suorittaen
- Kohdista lasku ja tilaus. Tarkista valtuutetusta näkymästä, että käsittelet samaa tilausta ja laskua. BTCPayn opas neuvoo tallentamaan laskutunnisteen tilauksen yhteyteen; sen mukaan webhookin
invoiceIdviittaa kyseiseen laskuun.[1] Jos yhteys puuttuu tai on epäselvä, pyydä integraation ylläpitäjää selvittämään se. - Erota tapahtuma nykytilasta. Tarkista vastaanotetun ilmoituksen tapahtumatyyppi ja vertaa sitä laskun nykyiseen
status- jaadditionalStatus-arvoon sekä tilauksen omaan tilaan. Opas suosittelee tarvittaessa hakemaan laskun nykytilan ja huomioimaan molemmat kentät.[1] Ilmoitus ja nykyinen tilannekuva ovat eri asioita; älä tee toimituspäätöstä yhden ilmoituksen nimen perusteella. - Pyydä ylläpitäjää selvittämään käsittelyketju. Onko ilmoitus vastaanotettu, onko sen aitous tarkistettu ja mihin kohtaan käsittely pysähtyi? BTCPay neuvoo tarkistamaan webhookin allekirjoituksen.[1] Tämä lähde ei osoita, että sinun integraatiosi tarkistus tai tilauspäivitys toimii oikein.
- Erota virheellinen viesti ja toistettu toimitus. Jos allekirjoitus on virheellinen tai aitoutta ei voida varmistaa, älä luota ilmoitukseen tai tee sen perusteella tilaus-, toimitus- tai palautustoimia. Aidonkaan ilmoituksen allekirjoitus ei osoita oikeaa kauppa–tilaus-kohdistusta, nykytilaa tai turvallista uudelleenkäsittelyä. Pidä seuraukselliset toimet keskeytettyinä myös, jos kohdistus tai nykytila on epäselvä. Ylläpitäjä tarkistaa allekirjoituksen saaduista viestitavuista kyseisen version
BTCPay-Sig-määrityksen ja suojatun salaisuuden avulla; älä paljasta salaisuutta.[1][5] - Keskeytä epävarma uudelleenkäsittely. Ennen minkään tilaus- tai toimitustoimen uusintaa selvitä jo tehdyt toimet oman järjestelmän vastuuhenkilön kanssa. Dokumentaatio mainitsee laskunäkymän
Redeliver-testitoiminnon,[1] mutta tässä ei pyydetä käyttämään sitä tuotannossa: uusi ilmoitus voi johtaa integraation omiin jatkotoimiin. Uusintatestaus kuuluu eristettyyn testijärjestelmään, kun vaikutukset on etukäteen selvitetty.
Epäonnistunut toimitus voi toistua, jos automaattinen uudelleentoimitus on kyseisessä asennuksessa käytössä; manuaalinen Redeliver on erillinen toiminto.[1][5] Aito toistettu ilmoitus ei ole sama asia kuin virheellinen allekirjoitus: tarkista jo tehdyt tilaus-, toimitus- ja palautustoimet ennen harkittua uusintaa. Älä oleta, että toimitukset ovat taattuja, järjestyksessä tai valmiiksi duplikaateista puhdistettuja.
Käsittele selvitystiedot vain valtuutettujen henkilöiden kesken. Älä jaa webhook-salaisuutta, API-avaimia, asiakkaiden tietoja tai koko ilmoitussisältöä julkiseen tikettiin. Tarpeettomia henkilötietoja ei pidä kerätä tai kirjata; BTCPayn ohje korostaa asiakastietojen minimointia laskun metadatassa.[1]
Tavoitteena on tunnistaa, missä kohdassa laskun ja tilauksen tieto eriytyy, ei luvata, että saman toimituksen toistaminen estyy. Tämä opas ei määritä idempotenssiavainta, uusintajärjestystä tai varmaa korjausta: kehittäjän on testattava vastaanotin ja tilausjärjestelmä yhdessä eristetyssä ympäristössä: aidot toistot, virheelliset allekirjoitukset, myöhäiset ja eri järjestyksessä tulevat ilmoitukset sekä jo suoritetut tilaus-, toimitus- ja palautustoimet. Testi arvioi oman yhdistelmän toimintaa, ei todista kaikkien versioiden idempotenssia eikä maksun onnistumista. Jos itse lasku on osittain tai myöhässä maksettu tai liikamaksettu, katso opas nsn-001-c3.
Rajaus
Integraatio-oppaan lähteenä on 17.10.2025 päivätyn dokumentaatiomuutoksen lukittu versio; Greenfield v1 -rajapintamäärittely on muuttuva lähde, jota tarkasteltiin 28.10.2026 ja jota ei ole sidottu palvelinjulkaisuun.[1][5] Kumpikaan ei todista minkään asennetun BTCPay-version toimintaa. Tarkista oman version ja liitännäisen dokumentaatio, allekirjoituksen toteutus ja tietosuojakäytännöt ennen soveltamista. Suomen saatavuutta ei ole selvitetty.