Accetta pagamenti in criptovalute

Paysell è un processore di pagamenti, non un wallet. Non gestisci mai chiavi private, non monitori la blockchain e non decidi quando una transazione è definitiva — questa parte la gestiamo noi.

Ogni fattura ha il proprio indirizzo di ricezione. Quando un acquirente paga, attendiamo che la rete confermi il trasferimento, detraiamo la nostra commissione e accreditiamo il resto sul tuo saldo. Puoi prelevare verso qualsiasi indirizzo desideri.

Sei passaggi, la maggior parte a nostro carico:

1. 1

   Il cliente clicca su paga

   Il tuo server chiama la nostra API con l'importo e il tuo riferimento d'ordine.

2. 2

   Forniamo un indirizzo

   Un nuovo indirizzo di ricezione viene preso da un pool pre-generato e associato a questa fattura. Un indirizzo appartiene a un'unica fattura aperta, ed è così che un pagamento viene ricondotto ad essa.

3. 3

   Il cliente invia le monete

   Scannerizza il QR code o copia l'indirizzo. Indirizzalo verso il payment_url che restituiamo e la pagina è già pronta per te — importo, indirizzo, QR, conto alla rovescia, stato in tempo reale.

4. 4

   Rileviamo il trasferimento

   Vengono interrogate due fonti indipendenti di dati blockchain e le loro risposte confrontate. Se non concordano, ci fermiamo invece di scegliere la risposta più comoda.

5. 5

   Attendiamo la finalità

   Inclusione nella masterchain più tre blocchi sopra. Circa quindici secondi — un pagamento che sembra concluso ma poi scompare sarebbe una tua perdita, quindi non corriamo quel rischio.

6. 6

   Accreditato, e te lo comunichiamo

   La commissione viene detratta, il resto finisce sul tuo saldo e un webhook firmato viene inviato al tuo server con il tuo order_id.

Circa un minuto dal pagamento al callback: circa quindici secondi di conferme di rete, il resto è la nostra scansione degli indirizzi monitorati.

La commissione è del 0,2%, fissata per il tuo negozio nel momento in cui viene registrato. Se in seguito la tariffa standard cambia, la tua resta invariata — è scritta in ogni fattura come numero, non come riferimento a un'impostazione.

La commissione viene prelevata da ciò che arriva effettivamente, non da quanto richiesto nella fattura. Fatturi 5 USDT e ne ricevi 20, la commissione viene calcolata su 20. In caso di pagamento insufficiente, viene calcolata su quanto è arrivato.

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

Il pagamento in eccesso viene accreditato per intero — non tratteniamo la differenza. Il pagamento insufficiente lascia la fattura aperta affinché l'acquirente possa integrare verso lo stesso indirizzo.

Cinque passaggi. Due sono clic nella tua area cliente, uno è una singola richiesta dal tuo server, e gli ultimi due avvengono da soli.

1. 1

   Crea un negozio

   Nella tua area cliente. Inizia ad accettare pagamenti immediatamente — nessuna attesa per la revisione. La verifica avviene silenziosamente in background e limita solo i prelievi, non i pagamenti in entrata.

2. 2

   Genera una chiave API

   Il tuo negozio → Chiavi API → Nuova chiave. La chiave e il segreto del webhook vengono mostrati una sola volta e mai più. Conservali come faresti con la password di un database, e non inviarli mai a un browser.

3. 3

   Crea una fattura

   Una richiesta dal tuo server, un link in risposta. I quattro esempi qui sotto inviano tutti esattamente la stessa cosa.

4. 4

   Manda l'acquirente al payment_url

   Questo è tutto il checkout — importo, indirizzo, QR code, conto alla rovescia, stato in tempo reale — e non c'è nulla da costruire. Vedi Checkout per ciò che l'acquirente vede davvero.

5. 5

   Aspetta il webhook

   Una volta che il denaro è confermato on-chain e accreditato, inviamo in POST un evento payment.credited firmato al tuo server. Verifica la firma, poi segna l'ordine come pagato — ma solo quando data.status è paid o overpaid. Vedi Webhook.

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"
  }'

Reindirizza l'acquirente al payment_url nella risposta. Hai finito — il resto arriva come 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.

Ogni richiesta porta la tua chiave nell'header Authorization:

Authorization: Bearer sk_live_IH4SNdnYsv-yabTuPCVln4vOvvGoEyxA

Ogni chiave emessa qui inizia con sk_live_. Il prefisso sk_test_ esiste solo su un deployment puntato alla rete di test, e nessun deployment del genere viene offerto — vedi Test. Conserviamo un hash unidirezionale, non la chiave stessa, quindi nessuno, noi compresi, può mostrartela di nuovo. L'hai persa? Generane una nuova e revoca la vecchia.

Il negozio viene derivato dalla chiave, motivo per cui nessuna richiesta include mai un id di negozio. Una chiave può agire solo sul proprio negozio.

Il percorso porta una versione: /api/merchant/v1/…. All'interno di una versione aggiungiamo solo campi: nulla viene rinominato né cambia significato in silenzio. Una modifica che romperebbe il tuo codice riceve un nuovo prefisso, /v2, e /v1 continua a funzionare per un periodo annunciato.

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.

Corpo della richiesta

Risposta · 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"
}

Come collegarlo al tuo ordine

Stessa struttura di sopra, con status, paid e paid_minor che riflettono la situazione attuale: paid è quanto è arrivato in unità normali, paid_minor la stessa cifra come intero nell'unità minima. Utile come fallback quando un webhook è stato mancato, oppure in una pagina di ringraziamento.

Interrogala al massimo ogni pochi secondi, e considera i webhook il canale primario. Le fatture appartenenti a un altro negozio rispondono 404, non 403 — così un id non può essere sondato per verificarne l'esistenza.

Chiude una fattura ancora aperta — pending o underpaid — e libera il suo indirizzo. Usalo quando il cliente abbandona il checkout: gli indirizzi sono una risorsa limitata, e restituirli mantiene sano il pool.

Una fattura che non è più aperta risponde 409. Annullare una fattura underpaid non restituisce monete a nessuno: il denaro già accreditato resta sul tuo saldo, e ciò che si chiude è soltanto la possibilità di integrare.

Imposta una URL di webhook quando crei la chiave. Ci facciamo un POST quando un pagamento viene accreditato — e quando un versamento trattenuto per un controllo aggiuntivo viene rifiutato. Ogni consegna è firmata, e continuiamo a ritentare per circa un giorno e mezzo finché non rispondi 2xx. Consegna la merce su status: paid o overpaid, non al semplice arrivo della chiamata.

Eventi

Cosa arriva

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

Mappatura dei campi

Header presenti in ogni consegna

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

Verificare la firma

Ogni richiesta è firmata con il segreto webhook mostrato una sola volta alla creazione della chiave. La firma è HMAC-SHA256(secret, "{timestamp}.{raw_body}") — il timestamp preso da X-Paysell-Timestamp, un punto letterale, poi i byte del corpo. Verificala prima di agire: senza questo, chiunque scopra il tuo URL può consegnarti un ordine risultante pagato.

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)
}

Firma i byte grezzi del corpo, esattamente come ricevuti. Se analizzi il JSON e lo riserializzi i byte cambiano — ordine delle chiavi, spaziatura — e la firma non corrisponderà. Confronta a tempo costante (hmac.compare_digest, crypto.timingSafeEqual): un semplice == torna più in fretta quando il primo byte è sbagliato, e quella differenza basta per indovinare una firma un byte alla volta.

La finestra del timestamp

Rifiuta tutto ciò il cui timestamp dista più di cinque minuti dal tuo orologio, in entrambe le direzioni. Il timestamp sta dentro la stringa firmata proprio perché non possa essere modificato senza rompere la firma; è la finestra a trasformare tutto questo in protezione. Senza di essa una richiesta catturata una volta resta valida per sempre e può essere riprodotta in qualsiasi momento — la firma da sola non scade mai. Tieni l'orologio del tuo server su NTP, altrimenti questo controllo comincerà a rifiutare consegne buone.

Duplicati

Lo stesso evento può arrivare più di una volta. Non è un bug: ritentiamo finché non rispondi 2xx, e una consegna riuscita la cui risposta non ci è mai arrivata viene inviata di nuovo. Registra X-Paysell-Event-Id (arriva anche come event_id nel corpo) e fa' in modo che il secondo arrivo non faccia nulla.

Tentativi ripetuti

Il primo tentativo parte appena il pagamento viene accreditato. Se fallisce — timeout, connessione rifiutata, errore TLS, un redirect o qualsiasi stato non 2xx — ritentiamo secondo una scaletta fissa:

1 min → 5 min → 15 min → 1 h → 6 h → 24 h

Sette tentativi in tutto, distribuiti su circa 31 ore. I primi sono ravvicinati perché la causa abituale è un ricevente che si stava riavviando ed è già tornato su; gli ultimi sono radi perché martellare un server fermo da un giorno non aiuta nessuno.

Dopo l'ultimo tentativo la consegna viene marcata dropped e ci fermiamo da soli. Non è persa: la riga del pagamento nella tua area cliente mostra lo stato, il numero di tentativi e la classe dell'errore, con un pulsante Invia di nuovo che avvia una nuova serie di tutti e sette i tentativi. L'altra risorsa che hai è GET /api/merchant/v1/invoices/{invoice_id} — la fattura conosce sempre il proprio stato.

Che aspetto deve avere una URL di webhook

La URL viene controllata quando la salvi, e di nuovo prima di ogni singola consegna. Una URL che non passa il controllo riceve 422 e code: "webhook_url_rejected" al salvataggio, e marca la consegna come failed — senza tentativi ripetuti — se comincia a fallire più tardi. Le regole:

• Solo `https://`, e porta 443. Un webhook trasporta i dettagli di un pagamento; in http in chiaro sono leggibili da chiunque stia sul percorso.
• Un nome di dominio, non un indirizzo IP. Un certificato ti serve comunque, e i certificati non vengono emessi per IP nudi.
• Niente `localhost`, e nessun nome .local, .internal, .corp, .lan o .test — i nostri server non raggiungono la tua rete, e un nome che risolve dentro la nostra è esattamente ciò che non dobbiamo chiamare.
• Nessuna credenziale nella URL (https://user:pass@…). Se ti serve, metti un tuo token nel percorso o in un parametro di query.
• Ogni indirizzo a cui il nome risolve deve essere pubblico — sia A sia AAAA. Gli intervalli privati, di loopback, link-local e CGNAT vengono rifiutati, e il controllo si ripete prima di ogni consegna, quindi puntare il record su 127.0.0.1 in un secondo momento non funziona.
• Un redirect è un fallimento, non un salto. Non lo seguiamo: l'indirizzo che ci hai dato è stato controllato, quello nell'header Location no.

Rispondi rapidamente

Va bene qualsiasi 2xx, entro dieci secondi — è tutto il nostro timeout, connessione compresa. Rispondi per primo, fai il lavoro lento dopo; un endpoint che aspetta il proprio database prima di rispondere prima o poi verrà registrato come timeout e ritentato, e ti ritroverai a processare due volte lo stesso evento. Qualsiasi altra cosa — un 4xx, un 5xx, un redirect, un blocco — conta come tentativo fallito e rientra nella scaletta qui sopra.

La consegna, onestamente

Ciò che è garantito è il meccanismo di consegna: sette tentativi in circa 31 ore, un reinvio manuale dalla tua area cliente, e un endpoint fattura che conosce sempre lo stato reale. Costruisci il flusso in modo che un webhook che non arriva mai non ti costi nulla — leggi la fattura nella tua pagina di ringraziamento, oppure riconcilia le fatture aperte una volta all'ora. I webhook sono la via veloce, non l'unica via.

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.

Fattura

Pagamento

Visibile nella tua area cliente; utile per assistere un cliente durante il pagamento.

Quando un pagamento finisce in `review`

Alcuni depositi vengono trattenuti per un controllo aggiuntivo invece di essere accreditati subito: una somma insolitamente grande, monete arrivate a un indirizzo senza fattura aperta, oppure le due fonti blockchain che interroghiamo che non concordano su ciò che è successo. Niente va perso — il denaro attende una decisione e il webhook scatta non appena c'è, cosa che può richiedere minuti od ore. Tratta come normale, e non come un guasto, l'assenza di callback su un pagamento mostrato come review. Se è rilevante per un ordine, scrivi al supporto citando il tx_hash.

Invia gli importi nelle unità normali della moneta, come stringa — "1.5" è uno e mezzo. Non un numero JSON e non l'unità minima.

Una stringa e non un numero, perché i numeri JSON sono double IEEE-754 e una somma grande in nanoton smette di esservi rappresentabile esattamente. Più decimali di quanti ne abbia la moneta è un 422, mai un arrotondamento silenzioso del tuo denaro. Nei webhook è il contrario: lì amount, fee e credited sono interi nell'unità minima, perché quel lato lo legge il codice, non una persona.

// 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

Il minimo non è burocrazia. La nostra commissione è percentuale, ma incassare un pagamento ha un costo fisso: spostare USDT da un indirizzo di ricezione significa prima rifornirlo di gas, a nostre spese. Sotto pochi dollari la commissione non copre la gestione, e accettare un pagamento simile significherebbe accreditarti denaro il cui spostamento è antieconomico.

Il massimo non riguarda i negozi grandi: è una trappola per l'errore di unità. Invia "5000000" dove intendevi "5" e altrimenti otterresti una fattura da cinque milioni di dollari: l'acquirente vede una cifra assurda e se ne va. Un ordine vero non tocca mai questo tetto; un errore sempre. Entrambi i tetti sono impostazioni (invoice_max_ton, invoice_max_usdt) e possono essere alzati per il tuo negozio — basta chiedere.

Il tetto orario e quello sulle fatture aperte proteggono entrambi il pool di indirizzi. Ogni fattura aperta occupa un indirizzo di ricezione, e un loop fuori controllo su un sito prosciugherebbe altrimenti il pool per tutti. Un negozio nuovo può tenere 20 fatture aperte insieme; la disponibilità cresce di uno per ogni fattura che ha davvero incassato, fino a un tetto di 200. underpaid conta come aperta — sta ancora occupando il suo indirizzo, in attesa del resto. Annullare una fattura abbandonata restituisce subito il suo indirizzo. I tentativi ripetuti con lo stesso idempotency_key non pesano sul tetto orario.

Il limite di richieste è 120 al minuto per chiave API — due chiamate al secondo, ben oltre qualsiasi flusso d'ordini reale. Un 429 porta un header Retry-After in secondi: aspetta quel tempo invece di ritentare in un loop stretto, che non fa altro che spostare la finestra più avanti.

Gli errori tornano in JSON, in due forme. Tutto ciò che decidiamo noi o il core di elaborazione mette una coppia {code, message} sotto detail. Un corpo di richiesta che non passa la validazione ci mette invece una lista di errori di campo. Verifica quale delle due hai ricevuto prima di leggere detail.code — e ramifica su `code`, mai su `message`: la formulazione può cambiare in qualsiasi momento, il codice no.

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

Codici

La forma decisa da noi è {"detail": {"code": …, "message": …}}. Questi sono i codici restituiti dall'API merchant.

Un 502 non significa che la fattura non sia stata creata — la richiesta potrebbe essere andata a buon fine con la risposta persa nel percorso di ritorno. Riprova con la stessa idempotency_key e otterrai o la fattura esistente o una nuova, mai due.

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.

I rimborsi passano dal supporto, non da una chiamata API. Un rimborso è un nuovo trasferimento verso un indirizzo fornito da una persona, e un processore di pagamenti che rimanda indietro denaro automaticamente su chiamata API è un processore che si può indurre a mandare denaro all'indirizzo di un attaccante. Perciò è manuale di proposito.

Per rimborsare un acquirente, apri un ticket di supporto dalla tua area cliente con l'invoice_id o il tx_hash, l'importo e l'indirizzo di destinazione. Un operatore verifica il pagamento, sposta il denaro fuori dal tuo saldo e risponde nello stesso ticket. Aspettati che richieda una giornata lavorativa, non un minuto.

Due conseguenze su cui vale la pena progettare. L'eccedenza ti viene accreditata per intero — noi non ne tratteniamo nulla — quindi restituire la differenza a un acquirente che ha inviato troppo è una tua scelta e segue la stessa via. E una fattura underpaid non è un caso di rimborso finché è ancora aperta: il denaro è sul tuo saldo, l'indirizzo è ancora sorvegliato e l'acquirente può semplicemente integrare. Solo dopo il periodo di grazia, quando la fattura passa a expired con del denaro sopra, c'è una decisione da prendere.

Qui le chiavi sono reali: ogni chiave emessa è una chiave sk_live_ contro il core di produzione e la mainnet TON. Non esiste un ambiente di test separato, e c'è un lato positivo: percorri esattamente la strada che faranno i tuoi ordini veri.

Quindi fai le prove come le faresti con qualsiasi cosa tocchi denaro vero: su importi piccoli. Crea una fattura del minimo (0.1 TON o 3 USDT), pagala dal tuo wallet e osserva tutto il percorso — la pagina di pagamento, il webhook, la verifica della firma, il tuo ordine che passa a pagato. La commissione si applica, e le monete si muovono davvero.

Le parti che puoi esercitare senza spendere nulla: creare e leggere una fattura, annullarla, il 422 su un importo malformato, il 401 su una chiave sbagliata e la tua verifica della firma — firma un corpo di esempio con il tuo segreto e passalo al tuo stesso handler. Ciò che richiede davvero un pagamento reale è solo l'ultimo passo: un vero webhook payment.credited.

Pianifica l'integrazione in modo che non dipenda da una sandbox o da un pagamento simulato: il percorso reale si verifica più in fretta — e più onestamente.

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.

• La chiave è solo lato server, mai nel JavaScript del browser.
• La firma del webhook è verificata contro "{timestamp}.{raw_body}", a tempo costante.
• Le consegne più vecchie di cinque minuti vengono rifiutate, e l'orologio del server è su NTP.
• Un X-Paysell-Event-Id ripetuto non fa nulla la seconda volta.
• Il webhook risponde 2xx entro dieci secondi; il lavoro lento avviene dopo.
• La URL del webhook è un dominio https:// sulla porta 443, senza redirect davanti.
• Un webhook mancato è sopravvivibile: l'endpoint fattura viene letto nella pagina di ringraziamento o in una passata di riconciliazione.
• idempotency_key è generato una volta per ordine e riutilizzato nei tentativi successivi.
• Gli importi escono come stringhe in unità normali; i numeri del webhook si leggono in unità minime.
• L'indirizzo è mostrato esattamente come restituito, senza modifiche.
• overpaid e underpaid sono gestiti, non solo paid; expired può comunque portare paid_minor.
• La merce si consegna su status: paid o overpaid, mai al semplice arrivo della chiamata.
• Il 429 si gestisce aspettando il Retry-After, non ritentando subito.
• I saldi vengono letti da noi, non tracciati separatamente come verità.