Modtag kryptobetalinger

Paysell er en betalingsudbyder, ikke en tegnebog. Du håndterer aldrig private nøgler, overvåger ikke blockchainen, og bestemmer ikke, hvornår en transaktion er endelig — det tager vi os af.

Hver faktura får sin egen modtageradresse. Når en køber betaler den, venter vi på, at netværket bekræfter overførslen, trækker vores gebyr fra og krediterer resten til din saldo. Du hæver til enhver adresse, du ønsker.

Seks trin, de fleste af dem vores:

1. 1

   Din kunde klikker på betal

   Din server kalder vores API med beløbet og din egen ordrereference.

2. 2

   Vi udleverer en adresse

   En frisk modtageradresse tages fra en forudgenereret pulje og knyttes til denne faktura. Én adresse tilhører præcis én åben faktura, og sådan matches en betaling til den.

3. 3

   Kunden sender mønterne

   De scanner QR-koden eller kopierer adressen. Send dem til den payment_url, vi returnerer, og siden klarer alt for dig — beløb, adresse, QR, nedtælling, live status.

4. 4

   Vi registrerer overførslen

   To uafhængige kilder til blockchain-data forespørges, og deres svar sammenlignes. Hvis de er uenige, stopper vi i stedet for at vælge det mest bekvemme svar.

5. 5

   Vi venter på endelighed

   Optagelse i masterchain plus tre blokke oveni. Cirka femten sekunder — en betaling, der ser afregnet ud og derefter forsvinder, ville være dit tab, så vi tager ikke den risiko.

6. 6

   Krediteret, og du får besked

   Gebyret trækkes fra, resten lander på din saldo, og en signeret webhook går til din server med dit order_id.

Fra betaling til callback: cirka et minut — omkring femten sekunder med netværksbekræftelser, resten er vores gennemgang af overvågede adresser.

Gebyret er 0,2 %, fastsat for din butik på registreringstidspunktet. Hvis standardsatsen ændres senere, ændres din ikke — den er skrevet ind i hver faktura som et tal, ikke som en reference til en indstilling.

Gebyret tages fra det, der rent faktisk ankommer, ikke fra det, fakturaen bad om. Fakturér 5 USDT og modtag 20, så beregnes gebyret af 20. Betales der for lidt, beregnes det af det, der kom ind.

Invoice:   5.000000 USDT
Received: 20.000000 USDT   (the buyer sent more)
Fee 0.2%:  0.040000 USDT   (on 20, not on 5)
Credited: 19.960000 USDT

Overbetaling krediteres fuldt ud — vi beholder ikke differencen. Underbetaling holder fakturaen åben, så køberen kan efterbetale til samme adresse.

Fem trin. To er klik i dit kontoområde, ét er en enkelt anmodning fra din server, og de sidste to sker af sig selv.

1. 1

   Opret en butik

   I dit kontoområde. Den begynder at modtage betalinger med det samme — uden at vente på godkendelse. Verifikation foregår stille i baggrunden og begrænser kun udbetalinger, ikke indgående betalinger.

2. 2

   Udsted en API-nøgle

   Din butik → API-nøgler → Ny nøgle. Nøglen og webhook-hemmeligheden vises kun én gang og aldrig igen. Opbevar dem, som du ville opbevare en databaseadgangskode, og send dem aldrig til en browser.

3. 3

   Opret en faktura

   Én anmodning fra din server, ét link tilbage. De fire kodeeksempler nedenfor sender alle nøjagtig det samme.

4. 4

   Send køberen til payment_url

   Det er hele betalingssiden — beløb, adresse, QR-kode, nedtælling, status i realtid — og der er intet at bygge. Se Betalingssiden for, hvad køberen rent faktisk ser.

5. 5

   Vent på webhooken

   Når pengene er bekræftet på kæden og krediteret, laver vi en POST med en signeret payment.credited-hændelse til din server. Verificér signaturen, og markér derefter ordren som betalt — men kun når data.status er paid eller overpaid. Se Webhooks.

The same request, four ways

curl -X POST https://paysell.me/api/merchant/v1/invoices \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": "USDT_TON",
    "amount": "5",
    "order_id": "order-1042",
    "idempotency_key": "order-1042"
  }'

Omdiriger køberen til payment_url i svaret. Du er færdig — resten ankommer som en webhook.

What to do next

• Write the webhook receiver — Webhooks and A complete receiver. Nothing else on this page matters as much: it is what turns a payment into a paid order.
• Handle underpaid and overpaid, not just paid — see Status reference.
• Read Typical mistakes, then walk the go-live checklist before you point real customers at it.

Hver anmodning bærer din nøgle i Authorization-headeren:

Authorization: Bearer sk_live_IH4SNdnYsv-yabTuPCVln4vOvvGoEyxA

Hver nøgle, der udstedes her, starter med sk_live_. Præfikset sk_test_ findes kun i en installation, der peger på testnetværket, og en sådan installation tilbydes ikke — se Test. Vi gemmer en envejs-hash, ikke selve nøglen, så ingen, os inklusive, kan vise den til dig igen. Mistet den? Udsted en ny, og tilbagekald den gamle.

Butikken udledes af nøglen, derfor tager ingen anmodning nogensinde et butiks-id. En nøgle kan kun handle på sin egen butik.

Stien bærer en version: /api/merchant/v1/…. Inden for en version tilføjer vi kun felter — intet omdøbes, og intet skifter stille betydning. En ændring, der ville bryde din kode, får et nyt præfiks, /v2, og /v1 kører videre i en annonceret periode.

This is the whole merchant API. Balances, payouts and history are not in it — they live in your account area, where a person is looking at them.

Every path is relative to https://paysell.me/api/merchant/v1. There is no list endpoint and no refund endpoint — see Refunds.

Anmodningstekst

Svar · 201

{
  "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
  "payment_url": "https://paysell.me/pay/12c22c1a-a496-4c1e-abe3-72661ef8706e",
  "address": "UQAvDJp7QDwqRcuNQBiK2GhBt71Xh1_UMYPCzMkQAoBPmZKl",
  "asset": "USDT_TON",
  "amount": "5",
  "amount_minor": "5000000",
  "status": "pending",
  "paid": "0",
  "paid_minor": "0",
  "order_id": "order-1042",
  "description": "Pro subscription",
  "expires_at": "2026-09-06T17:20:55Z",
  "created_at": "2026-09-06T15:20:55Z"
}

Sådan bruger du det i din ordre

Samme form som ovenfor, hvor status, paid og paid_minor afspejler nutiden: paid er, hvor meget der er kommet ind i normale enheder, paid_minor det samme som et heltal i mindste enhed. Nyttig som en reserveløsning, når en webhook blev overset, eller på en kvitteringsside.

Forespørg højst hvert par sekunder, og betragt webhooks som den primære kanal. Fakturaer, der tilhører en anden butik, svarer 404 — ikke 403, så et id ikke kan afsøges for eksistens.

Lukker en faktura, der stadig er åben — pending eller underpaid — og frigiver dens adresse. Brug det, når kunden forlader betalingssiden: adresser er en begrænset ressource, og at returnere dem holder puljen sund.

En faktura, der ikke længere er åben, svarer 409. At annullere en underpaid faktura sender ikke mønter tilbage til nogen: penge, der allerede er krediteret, bliver på din saldo, og det eneste, der lukkes, er muligheden for at efterbetale.

Angiv en webhook-URL, når du opretter en nøgle. Vi laver en POST dertil, når en betaling er krediteret — og når en indbetaling, der blev holdt tilbage til et ekstra tjek, bliver afvist. Hver levering er signeret, og vi bliver ved med at prøve igen i omkring halvandet døgn, indtil du svarer 2xx. Frigiv varen ved status: paid eller overpaid — ikke fordi kaldet blot er kommet frem.

Hændelser

Hvad der ankommer

{
  "event_id": "99f74f58-efbb-4af1-b0a3-76b0073f9e6b",
  "type": "payment.credited",
  "data": {
    "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
    "order_id": "order-1042",
    "asset": "USDT_TON",
    "amount": "5000000",
    "credited": "4905000",
    "fee": "95000",
    "status": "paid",
    "paid_minor": "5000000",
    "tx_hash": "97a1f0…"
  }
}

{
  "event_id": "0a1b2c3d-4e5f-4a6b-8c9d-0e1f2a3b4c5d",
  "type": "payment.rejected",
  "data": {
    "invoice_id": "12c22c1a-a496-4c1e-abe3-72661ef8706e",
    "order_id": "order-1042",
    "asset": "USDT_TON",
    "amount": "5000000",
    "tx_hash": "97a1f0…",
    "reason": "could not be matched to any order"
  }
}

Feltmapping

Headere på hver levering

X-Paysell-Event:      payment.credited
X-Paysell-Event-Id:   99f74f58-efbb-4af1-b0a3-76b0073f9e6b
X-Paysell-Timestamp:  1789000000
X-Paysell-Signature:  sha256=6f1c0e6a…

Verificering af signaturen

Hver anmodning signeres med webhook-hemmeligheden, der blev vist én gang, da du oprettede nøglen. Signaturen er HMAC-SHA256(secret, "{timestamp}.{raw_body}") — tidsstemplet fra X-Paysell-Timestamp, et bogstaveligt punktum og derefter body-bytene. Tjek den, før du handler: uden det kan enhver, der lærer din URL at kende, forsyne dig med en betalt ordre.

Python:

import hmac, hashlib, time

def is_ours(body: bytes, signature: str, timestamp: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:      # ±5 minutes
        return False
    signed = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    # compare_digest, not ==: a plain comparison leaks the answer through timing
    return hmac.compare_digest("sha256=" + expected, signature)

Node.js:

const crypto = require("node:crypto")

function isOurs(body, signature, timestamp, secret) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false  // ±5 min
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(timestamp + ".").update(body)   // body is the raw Buffer, not a parsed object
    .digest("hex")
  const a = Buffer.from(expected), b = Buffer.from(signature)
  // timingSafeEqual throws when the lengths differ, so check that first
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Signér de rå body-bytes, nøjagtigt som modtaget. Hvis du parser JSON'en og serialiserer den igen, ændres bytene — nøglerækkefølge, mellemrum — og signaturen vil ikke stemme. Sammenlign i konstant tid (hmac.compare_digest, crypto.timingSafeEqual): et almindeligt == vender hurtigere tilbage ved en forkert første byte, og den forskel er nok til at gætte en signatur én byte ad gangen.

Tidsstempelvinduet

Afvis alt, hvis tidsstempel ligger mere end fem minutter fra dit eget ur, i begge retninger. Tidsstemplet ligger inde i den signerede streng netop for at det ikke kan redigeres uden at ødelægge signaturen; vinduet er det, der gør dette til beskyttelse. Uden det forbliver en anmodning, der er opsnappet én gang, gyldig for evigt og kan afspilles igen når som helst — signaturen alene udløber aldrig. Hold din servers ur på NTP, ellers begynder dette tjek at afvise gyldige leveringer.

Dubletter

Den samme hændelse kan ankomme mere end én gang. Det er ikke en fejl: vi prøver igen, indtil du svarer 2xx, og en levering, der lykkedes, men hvis svar aldrig nåede os, sendes igen. Registrer X-Paysell-Event-Id (den kommer også som event_id i body'en), og sørg for, at den anden ankomst ikke gør noget.

Gentagne forsøg

Det første forsøg sendes, så snart betalingen er krediteret. Hvis det mislykkes — timeout, afvist forbindelse, TLS-fejl, en omdirigering eller en hvilken som helst ikke-2xx-status — prøver vi igen efter en fast plan:

1 min → 5 min → 15 min → 1 t → 6 t → 24 t

Syv forsøg i alt, fordelt over cirka 31 timer. De tidlige ligger tæt på hinanden, fordi den sædvanlige årsag er en modtager, der var ved at genstarte og allerede er tilbage; de sene ligger spredt, fordi det ikke gavner nogen at hamre løs på en server, der har været nede i et døgn.

Efter det sidste forsøg markeres leveringen som dropped, og vi stopper af os selv. Den er ikke tabt: betalingsrækken i dit kontoområde viser tilstanden, antallet af forsøg og fejlklassen, med en Send igen-knap, der starter et helt nyt forløb med alle syv forsøg. Din anden udvej er GET /api/merchant/v1/invoices/{invoice_id} — fakturaen kender altid sin egen status.

Hvordan en webhook-URL skal se ud

URL'en tjekkes, når du gemmer den, og igen før hver eneste levering. En URL, der ikke består tjekket, besvares med 422 og code: "webhook_url_rejected" ved lagringen, og markerer leveringen som failed — uden gentagne forsøg — hvis den begynder at fejle senere. Reglerne:

• Kun `https://`, og port 443. En webhook bærer betalingsoplysninger; over almindelig http kan de læses af alle på vejen.
• Et domænenavn, ikke en IP-adresse. Du skal alligevel bruge et certifikat, og der udstedes ikke certifikater til bare IP-adresser.
• Ingen `localhost`, og intet .local-, .internal-, .corp-, .lan- eller .test-navn — vores servere kan ikke nå dit netværk, og et navn, der slår op inde i vores, er præcis det, vi ikke må kalde.
• Ingen legitimationsoplysninger i URL'en (https://user:pass@…). Læg dit eget token i stien eller i en query-parameter, hvis du har brug for et.
• Alle adresser, navnet slår op til, skal være offentlige — både A og AAAA. Private adresser, loopback, link-local og CGNAT-intervaller afvises, og tjekket gentages før hver levering, så det virker heller ikke at pege posten mod 127.0.0.1 senere.
• Omdirigeringer er en fejl, ikke et hop. Vi følger dem ikke: den adresse, du gav os, er tjekket, og den i en Location-header er ikke.

Svar hurtigt

Enhver 2xx duer, inden for ti sekunder — det er hele vores timeout, forbindelsen inklusive. Svar først, og lav det langsomme arbejde bagefter; et endpoint, der venter på sin egen database, før det svarer, ender med at blive registreret som en timeout og forsøgt igen, og så behandler du den samme hændelse to gange. Alt andet — en 4xx, en 5xx, en omdirigering, et hæng — tæller som et mislykket forsøg og går tilbage i planen ovenfor.

Levering, ærligt talt

Det, der er garanteret, er leveringsmekanismen: syv forsøg over cirka 31 timer, en manuel gensendelse fra dit kontoområde, og et faktura-endpoint, der altid kender den rigtige status. Byg dit flow, så en webhook, der aldrig ankommer, ikke koster dig noget — læs fakturaen på din kvitteringsside, eller afstem åbne fakturaer én gang i timen. Webhooks er den hurtige vej, ikke den eneste vej.

The snippets above verify one signature. This is the whole endpoint: raw body, signature check, deduplication by event_id, a fast 2xx, and the one condition that is allowed to mark an order paid.

Node.js with Express. express.raw is the part people get wrong: express.json() hands you a parsed object, and bytes you re-serialise from it are not the bytes we signed.

const express = require("express")
const crypto = require("node:crypto")

const app = express()
const SECRET = process.env.PAYSELL_WEBHOOK_SECRET

function isOurs(body, signature, timestamp) {
  const sentAt = Number(timestamp)
  if (!Number.isFinite(sentAt)) return false
  if (Math.abs(Date.now() / 1000 - sentAt) > 300) return false   // ±5 minutes

  const expected = "sha256=" + crypto
    .createHmac("sha256", SECRET)
    .update(timestamp + ".").update(body)      // raw Buffer, not a parsed object
    .digest("hex")

  const a = Buffer.from(expected), b = Buffer.from(signature ?? "")
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

app.post(
  "/paysell/webhook",
  express.raw({ type: "application/json" }),   // NOT express.json()
  async (req, res) => {
    const signature = req.get("X-Paysell-Signature")
    const timestamp = req.get("X-Paysell-Timestamp")
    if (!isOurs(req.body, signature, timestamp)) return res.sendStatus(401)

    const event = JSON.parse(req.body.toString("utf8"))

    // Answer first: 10 seconds is the whole timeout, connection included.
    res.sendStatus(200)

    // Deduplicate. In real code this is a unique column, not a Set.
    if (await alreadyHandled(event.event_id)) return
    await remember(event.event_id)

    if (event.type !== "payment.credited") return
    const { order_id, status, credited, asset, tx_hash } = event.data

    // The only condition that may release the goods.
    if (status !== "paid" && status !== "overpaid") return
    await markOrderPaid(order_id, { credited, asset, tx_hash })
  }
)

Python with Flask. request.get_data() is the raw body; request.form and request.json are not.

import hashlib
import hmac
import json
import os
import time

from flask import Flask, request

app = Flask(__name__)
SECRET = os.environ["PAYSELL_WEBHOOK_SECRET"]


def is_ours(body: bytes, signature: str, timestamp: str) -> bool:
    try:
        sent_at = int(timestamp)
    except (TypeError, ValueError):
        return False
    if abs(time.time() - sent_at) > 300:              # ±5 minutes
        return False

    signed = timestamp.encode() + b"." + body
    expected = hmac.new(SECRET.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, signature)


@app.post("/paysell/webhook")
def paysell_webhook():
    body = request.get_data()                          # raw bytes, unparsed
    if not is_ours(body, request.headers.get("X-Paysell-Signature", ""),
                   request.headers.get("X-Paysell-Timestamp", "")):
        return "", 401

    event = json.loads(body)

    # Deduplicate. In real code this is a unique column, not a set.
    if already_handled(event["event_id"]):
        return "", 200                                 # a repeat is still a success
    remember(event["event_id"])

    if event["type"] == "payment.credited":
        data = event["data"]
        # The only condition that may release the goods.
        if data["status"] in ("paid", "overpaid"):
            mark_order_paid(data["order_id"], data)

    return "", 200                                     # 2xx within 10 seconds

What the code is doing, and why

• Verify before anything acts on the body. An unsigned request that reaches your business logic is a paid order for whoever found your URL.
• Answer 2xx first, work afterwards. Ten seconds is the whole timeout, connection included. A handler that waits for its own database gets recorded as a timeout and retried, and you process the same event twice.
• Deduplicate on `event_id` in storage that survives a restart. The in-memory set in the examples keeps them short; a real one is a unique column in your database.
• Mark the order paid only on `status: paid` or `overpaid`. underpaid means part of the money arrived and the invoice is still open, and a deposit in the wrong coin never makes an invoice paid either.
• Answer 2xx to a duplicate too. A repeat that gets a 4xx looks like a failure to us and comes back again on the schedule.

payment.rejected arrives at the same endpoint. It means a deposit held for an additional check was declined and the money will not be credited: release nothing, and if the invoice was already paid by an earlier transfer, this event is about the extra deposit, not about that payment.

Faktura

Betaling

Synlig i dit kontoområde; nyttig når du støtter en kunde midt i en betaling.

Når en betaling går til `review`

Nogle indbetalinger holdes tilbage til et ekstra tjek i stedet for at blive krediteret med det samme: et usædvanligt stort beløb, mønter der ankommer til en adresse uden en åben faktura, eller de to blockchain-kilder, vi spørger, er uenige om, hvad der skete. Intet går tabt — pengene venter på en afgørelse, og webhooken udløses, så snart den foreligger, hvilket kan være minutter eller timer senere. Betragt et manglende kald på en betaling, der vises som review, som normalt frem for som en fejl. Hvis det har betydning for en ordre, så spørg support og oplys tx_hash.

Send beløb i møntens normale enheder, som streng — "1.5" er halvanden. Ikke et JSON-tal og ikke den mindste enhed.

En streng og ikke et tal, fordi JSON-tal er IEEE-754-doubles, og et stort beløb i nanoton holder op med at kunne rummes præcist i et sådant. Flere decimaler end mønten har giver 422, aldrig en tavs afrunding af dine penge. Webhooks går den modsatte vej: der er amount, fee og credited heltal i mindste enhed, for den side læses af kode, ikke af et menneske.

// Send amounts in the coin's normal units, as a string:
const amount = "1.5"   // one and a half TON or USDT

// In responses, amount is that same human string; amount_minor is the
// integer in smallest units — use it for exact maths, as a string or BigInt:
BigInt(invoice.amount_minor)  // e.g. 1500000n

Minimummet er ikke bureaukrati. Vores gebyr er en procentdel, men at opkræve en betaling koster et fast beløb: at flytte USDT ud af en modtageradresse betyder at finansiere den med gas først, fra vores egen lomme. Under et par dollars dækker gebyret ikke håndteringen, og at acceptere en sådan betaling ville betyde at kreditere dig penge, det ikke kan betale sig at flytte.

Maksimum handler ikke om store forhandlere — det er en fælde for en enhedsfejl. Send "5000000", hvor du mente "5", og ellers ville du få en faktura på fem millioner dollars: køberen ser et absurd beløb og går. En rigtig ordre rammer aldrig dette loft; en fejl rammer det altid. Begge lofter er indstillinger (invoice_max_ton, invoice_max_usdt) og kan hæves for din butik — bare spørg.

Timegrænsen og grænsen for åbne fakturaer beskytter begge adressepuljen. Hver åben faktura optager en modtageradresse, og en løbsk løkke på ét websted ville ellers dræne puljen for alle andre. En ny butik må have 20 fakturaer åbne ad gangen; kvoten vokser med én for hver faktura, den faktisk har fået betalt, op til et loft på 200. underpaid tæller som åben — den holder stadig sin adresse og venter på resten. Annullerer du en opgivet faktura, frigives dens adresse med det samme. Gentagelser med samme idempotency_key tæller ikke mod timegrænsen.

Anmodningsgrænsen er 120 pr. minut pr. API-nøgle — to kald i sekundet, et godt stykke over ethvert reelt ordreflow. En 429 bærer en Retry-After-header i sekunder: vent så længe frem for at prøve igen i en tæt løkke, hvilket kun skubber vinduet længere ud.

Fejl returneres som JSON, i to former. Alt, hvad vi eller behandlingskernen afgør, lægger et {code, message}-par under detail. En anmodnings-body, der ikke består valideringen, lægger i stedet en liste af feltfejl der. Tjek, hvilken af dem du fik, før du læser detail.code — og forgren på `code`, aldrig på `message`: ordlyden kan ændre sig når som helst, koden gør ikke.

{
  "detail": {
    "code": "invalid_input",
    "message": "invoice amount below the minimum: 0.010000 USDT_TON, minimum 3.000000 USDT_TON"
  }
}

{
  "detail": [
    {
      "type": "string_type",
      "loc": ["body", "amount"],
      "msg": "Input should be a valid string",
      "input": 5
    }
  ]
}

Koder

Den form, vi selv afgør, er {"detail": {"code": …, "message": …}}. Det er de koder, merchant-API'et returnerer.

En 502 betyder ikke, at fakturaen ikke blev oprettet — anmodningen kan være gået igennem med svaret tabt på vejen tilbage. Prøv igen med samme idempotency_key, og du får enten den eksisterende faktura eller en ny, aldrig to.

payment_url points at https://paysell.me/pay/{invoice_id}. One page, no account, no login, mobile first, and nothing for you to build.

On the page

• Your shop's name, the amount and the coin, large, with the invoice's description underneath.
• A countdown to expires_at — plus the 24-hour grace period when the invoice is underpaid.
• The invoice's short id with a copy button, so a buyer can quote it to your support.
• Wallet buttons: Tonkeeper and MyTonWallet open with the address and the amount already filled in. Other reveals a QR code and the address with a copy button.
• A warning that only this invoice's coin, on the TON network, may be sent — anything else is lost.

How the page reacts

If you build your own

You gain your own branding and take on all of the above: the exact address string, the right coin, the countdown with its grace period, the underpayment case, and polling. GET /api/merchant/v1/public/invoices/{invoice_id} is the same unauthenticated read the hosted page uses — rate limited per IP, so poll it no more often than every few seconds. Print the address exactly as returned.

None of these are exotic. Every one of them has cost somebody a day.

• Sending the amount as a number

  {"amount": 5} is a 422. It has to be the string "5": JSON numbers are IEEE-754 doubles, and a large sum in nanotons stops being exactly representable in one.

• Sending the smallest unit

  "5000000" for 5 USDT is a mistake in units, and the upper invoice limit exists to catch it. Smallest units are what comes back in webhooks, not what goes out in requests.

• Treating the webhook's arrival as payment

  Read data.status. underpaid is not paid, and a deposit in a coin the invoice did not ask for never makes it paid either. Release the goods on paid or overpaid, on nothing else.

• Not checking the timestamp

  A signature on its own never expires. Without the ±5 minute window on X-Paysell-Timestamp, a delivery captured once can be replayed at any time and will still verify.

• Verifying the signature over re-serialised JSON

  Parse the body and serialise it again and the bytes change — key order, spacing — and the HMAC no longer matches. Sign the raw bytes exactly as received.

• No deduplication

  The same event_id will arrive twice sooner or later: we retry until you answer 2xx, and a response lost on the way back looks like a failure from here. The second arrival must do nothing.

• Using the Idempotency-Key header

  This API reads idempotency_key from the request body; the header is not read at all. A retry without the field opens a second invoice for the same order.

• Assuming detail is always an object

  It is {code, message} for anything we or the core decide, and a list of field errors when the body itself fails validation. Check which one you got before reading detail.code.

Refunderinger går gennem support, ikke gennem et API-kald. En refusion er en ny overførsel til en adresse, som et menneske har oplyst, og en betalingsudbyder, der sender penge tilbage automatisk ved et API-kald, er en betalingsudbyder, som kan bringes til at sende penge til en angribers adresse. Derfor er det bevidst manuelt.

For at refundere en køber skal du oprette en supportsag fra dit kontoområde med invoice_id eller tx_hash, beløbet og den adresse, der skal sendes til. En operatør tjekker betalingen, flytter pengene ud af din saldo og svarer i samme sag. Regn med, at det tager en arbejdsdag, ikke et minut.

To konsekvenser, det er værd at indrette sig efter. Overbetaling krediteres dig fuldt ud — vi beholder intet af den — så det er din beslutning at sende differencen tilbage til en køber, der sendte for meget, og det går ad samme vej. Og en underbetalt faktura er ikke en refusionssag, mens den stadig er åben: pengene står på din saldo, adressen overvåges stadig, og køberen kan simpelthen efterbetale. Først efter henstandsperioden, når fakturaen bliver expired med penge på, er der en beslutning at træffe.

Nøglerne her er live: hver udstedt nøgle er en sk_live_-nøgle mod produktionskernen og TON-mainnet. Der er ikke noget separat testmiljø, og det har en fordel: du gennemløber præcis den vej, dine rigtige ordrer kommer til at tage.

Så test, som du ville teste alt andet, der rører rigtige penge: med små beløb. Opret en faktura på minimum (0.1 TON eller 3 USDT), betal den fra din egen tegnebog, og se hele vejen igennem — betalingssiden, webhooken, signaturtjekket, din ordre der skifter til betalt. Gebyret gælder, og mønterne flytter sig rigtigt.

De dele, du kan afprøve uden at bruge noget: at oprette og læse en faktura, at annullere en, 422 ved et forkert opbygget beløb, 401 ved en forkert nøgle, og din egen signaturverificering — signér en eksempel-body med din hemmelighed, og send den til din egen handler. Det, der reelt kræver en rigtig betaling, er kun det sidste trin: en faktisk payment.credited-webhook.

Planlæg integrationen, så den ikke afhænger af en sandkasse eller en simuleret betaling: den live vej er hurtigere — og mere retvisende — at verificere.

Everything on this page also exists in a form a model can read directly. Point your assistant at one of these instead of pasting screenshots of documentation into a chat.

The three files

A prompt to start from

Copy this, replace the stack, and hand it to your assistant. It names the four things that go wrong most often, so the answer does not have to be corrected afterwards.

Read https://paysell.me/llms-full.txt and implement Paysell payments in my <stack>:
create invoices (POST /api/merchant/v1/invoices, Bearer sk_live_ key, amount as a
decimal string in normal units), redirect the buyer to payment_url, verify webhook
signatures (HMAC-SHA256 over "{timestamp}.{raw_body}", header X-Paysell-Signature,
reject anything whose X-Paysell-Timestamp is more than 300 seconds off), deduplicate
by event_id, answer 2xx within 10 seconds, and mark orders paid only on a
payment.credited event whose data.status is "paid" or "overpaid".

Feeding it to a specific tool

• Agents with web access — Claude Code, Cursor, Windsurf and the like: give them the /llms-full.txt link. One fetch, no setup.
• A chat window — ChatGPT, Claude, Gemini: paste the contents of /llms-full.txt into the conversation or attach it as a file. It is written to fit in one message.
• OpenAPI tooling — client generators, Postman, an agent's tool schema: point it at https://paysell.me/openapi.json. Its servers entry already carries the production base URL, so generated calls go to the right place.

• Nøglen er kun på serversiden, aldrig i browser-JavaScript.
• Webhook-signaturen verificeres mod "{timestamp}.{raw_body}", i konstant tid.
• Leveringer, der er ældre end fem minutter, afvises, og serverens ur er på NTP.
• Et gentaget X-Paysell-Event-Id gør intet anden gang.
• Webhooken svarer 2xx inden for ti sekunder; det langsomme arbejde sker bagefter.
• Webhook-URL'en er et https://-domæne på port 443, uden en omdirigering foran.
• En mistet webhook kan overleves: faktura-endpointet læses på kvitteringssiden eller ved en afstemningsgennemgang.
• idempotency_key genereres én gang pr. ordre og genbruges ved gentagelser.
• Beløb sendes som strenge i normale enheder; tallene fra webhooken læses som mindste enheder.
• Adressen vises nøjagtigt som returneret, uændret.
• overpaid og underpaid håndteres, ikke kun paid; expired kan stadig indeholde paid_minor.
• Varen frigives ved status: paid eller overpaid, aldrig fordi kaldet blot er kommet frem.
• 429 håndteres ved at vente Retry-After ud, ikke ved at prøve igen med det samme.
• Saldi læses fra os, spores ikke separat som sandhed.