Marchands

Utilise les endpoints invoice pour facturer tes clients dans n'importe quel token supporté et recevoir un token différent dans ton propre portefeuille. p3p gère le routage cross-chain.

Comment ça marche

1

Inscris-toi en tant que partnerObtiens ton ID de partner depuis le tableau de bord

2

Crée une facturePOST /invoice/create

3

Le client paieVers la `deposit_address`

4

Tu reçois les fondsRéglés directement vers ton portefeuille

p3p ne prend jamais la garde de tes fonds au-delà des quelques secondes nécessaires pour router le swap. Les remboursements, le cas échéant, vont automatiquement à l'expéditeur du dépôt.

1. Devenir un marchand

Inscris-toi sur le Tableau de Bord Partner en utilisant un portefeuille que tu contrôles. Utilise ton ID Partner attribué comme opts.partner_id (dans /exchange/create) ou comme wallet_merchant (dans /invoice/create) pour attribuer les transactions à ton compte.

Pas de formulaire d'inscription, pas de confirmation par email et pas de token API. Le portefeuille est le justificatif.

Traite ton portefeuille marchand comme une clé API

Quiconque contrôle le portefeuille contrôle le compte marchand. Utilise un portefeuille dédié à ton entreprise, séparé des fonds personnels.

2. Créer une facture

Deux façons de le faire.

Programmatique (recommandé)

POST /invoice/create

const invoice = await fetch("https://api.p3p.xyz/invoice/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    chain_from: "eth",  token_from: "usdt", amount_from: "50",
    chain_to:   "ton",  token_to:   "usdt",
    wallet_merchant: "UQYourMerchantTonWallet"
  }),
}).then(r => r.json())

console.log(invoice.deposit_address) // affiche-le à ton client

Réponse :

{
  "id": "in_ab12cd...",
  "invoice": true,
  "chain_from": "eth",  "token_from": "usdt", "amount_from": "50",
  "chain_to":   "ton",  "token_to":   "usdt",
  "amount_to":  "50.0",
  "wallet_merchant": "UQYourMerchantTonWallet",
  "deposit_address": "0xDepositAddressForCustomer",
  "rate":     "1.0",
  "duration": 60
}

URL partageable (pas d'intégration nécessaire)

Pour un bouton de checkout, un code QR ou un lien à partager, tu peux construire la facture à partir d'une URL :

https://api.p3p.xyz/invoice/create/:merchantId/:pathFrom/:pathTo?

Exemples :

# le client paie 100 USDT sur TON, tu reçois USDT sur TON
https://api.p3p.xyz/invoice/create/0xYourMerchantWallet/100:usdt.ton/usdt.ton

# le client paie 50 TON, tu reçois USDT sur TON
https://api.p3p.xyz/invoice/create/acme/50:ton.ton/usdt.ton

# forme simple : payer et recevoir le même actif
https://api.p3p.xyz/invoice/create/acme/100:usdt.ton

:merchantId peut être :

• l'id partner retourné pendant l'inscription,
• un name partner si tu en as défini un, ou
• une adresse de portefeuille déjà enregistrée comme marchand.

3. Afficher l'adresse de dépôt

Affiche invoice.deposit_address et invoice.amount_from dans ton UI, idéalement comme code QR :

import QRCode from "qrcode"

const dataUrl = await QRCode.toDataURL(
  `${invoice.chain_from}:${invoice.deposit_address}?amount=${invoice.amount_from}`
)

Le client envoie amount_from de token_from à cette adresse. Tout le reste (mauvais montant, mauvais token, fenêtre expirée) est automatiquement remboursé.

4. Confirmer le paiement

Sonde /check/:id exactement comme un exchange normal :

async function waitForInvoicePayment(id: string) {
  while (true) {
    const s = await fetch(`https://api.p3p.xyz/check/${id}`).then(r => r.json())
    if (s.status === "complete") return s
    if (s.status === "failed" || s.status === "refunded") throw new Error(s.status)
    await new Promise(r => setTimeout(r, 4000))
  }
}

await waitForInvoicePayment(invoice.id)
// les fonds sont maintenant dans wallet_merchant

5. Inspecter tes gains

Trois endpoints partner sont en lecture seule et ne nécessitent aucune authentification au-delà de connaître le partnerId. Les gains sont réglés selon tes paramètres de paiement configurés (soit instantanément par swap, soit via des retraits programmés en USDT) — configure cela dans le Tableau de Bord Partner.

Endpoint	Retourne
GET /partners/:partnerId/stats	Volume, nombre de transactions, part de revenus
GET /partners/:partnerId/exchanges	Tous les exchanges crédités à ce partner
GET /partners/:partnerId/invoices	Toutes les factures créées pour ce partner

curl https://api.p3p.xyz/partners/0xYourMerchantWallet/stats

Conseils et pièges

• Un portefeuille par chaîne : un partner accumule les portefeuilles, un par chaîne. Utilise le bon portefeuille pour la chaîne de destination dans wallet_merchant.
• Même chaîne + même token : contourne le moteur de swap et agit comme une simple adresse de transfert — utile pour des liens simples "paie-moi X USDT sur TON".
• Fenêtre de dépôt : les factures partagent la fenêtre standard de ~6 minutes. Si le client prend plus de temps, appelle /check/:id?bump=true pour la rafraîchir.
• Remboursements : disponibles uniquement lorsque le dépôt est détecté mais que le swap échoue. Pour les factures sans wallet_refund, les fonds tentent de se rembourser à l'adresse de l'expéditeur détectée on-chain.

---

Référence des endpoints

Tous les endpoints marchand sont ouverts — pas d'en-tête api-key requis. Ton portefeuille est le justificatif.

1. Créer une Facture2. Créer une URL de Facture Partageable3. Obtenir les Stats Partner4. Obtenir les Exchanges du Partner5. Obtenir les Factures du Partner

1. Créer une Facture

POST /invoice/create

Champ	Type	Requis	Description
chain_from	string	oui	Chaîne depuis laquelle le client paie
token_from	string	oui	Token avec lequel le client paie
amount_from	string	oui	Montant que le client paie
chain_to	string	oui	Chaîne sur laquelle tu reçois les fonds
token_to	string	oui	Token que tu reçois
wallet_merchant	string	oui	Ton portefeuille sur la chaîne de destination

Retourne un objet facture incluant id, deposit_address, amount_from, amount_to, rate et duration.

2. Créer une URL de Facture Partageable

GET /invoice/create/:merchantId/:pathFrom/:pathTo?

URL de facture partageable — mets-la dans un code QR ou un bouton.

• merchantId — id partner, nom partner, ou un portefeuille déjà enregistré comme marchand
• pathFrom — <amount>:<token>.<chain> (ex. 100:usdt.ton)
• pathTo — optionnel, <token>.<chain> si tu veux convertir ; par défaut pathFrom

Retourne le même objet que POST /invoice/create.

3. Obtenir les Stats Partner

GET /partners/:partnerId/stats

Volume agrégé, nombre de transactions et part de revenus à vie pour le portefeuille partner.

4. Obtenir les Exchanges du Partner

GET /partners/:partnerId/exchanges

Liste paginée des exchanges crédités au partner.

5. Obtenir les Factures du Partner

GET /partners/:partnerId/invoices

Liste paginée des factures créées pour le partner.

Erreurs

{ "error": "merchant_id_required", "message": "..." }

Code	Signification
invalid_json	Le corps de la requête n'est pas du JSON valide
merchant_id_required	Endpoint GET de facture appelé sans identifiant marchand
partner_not_found	Aucun partner ne correspond au merchantId donné
merchant_wallet_not_found	Le partner existe mais n'a pas de portefeuille sur la chaîne de destination
amount_too_small	Montant inférieur au minimum du fournisseur
amount_too_big	Montant supérieur au maximum du fournisseur