Comerciantes

Usa los endpoints de factura para cobrar a tus clientes en cualquier token soportado y recibir uno diferente en tu propia billetera. p3p maneja el enrutamiento cross-chain.

Cómo funciona

1

Regístrate como partnerObtén tu ID de partner desde el panel

2

Crea una facturaPOST /invoice/create

3

El cliente pagaA la `deposit_address`

4

Recibes los fondosLiquidados directamente a tu billetera

p3p nunca toma custodia de tus fondos más allá de los pocos segundos necesarios para enrutar el swap. Los reembolsos, cuando corresponda, van automáticamente al remitente del depósito.

1. Conviértete en comerciante

Regístrate en el Panel de Partner usando una billetera que controles. Usa tu ID de Partner asignado como opts.partner_id (en /exchange/create) o como wallet_merchant (en /invoice/create) para atribuir transacciones a tu cuenta.

No hay formulario de registro, ni confirmación de correo, ni token API. La billetera es la credencial.

Trata tu billetera de comerciante como una clave API

Cualquiera que controle la billetera controla la cuenta del comerciante. Usa una billetera dedicada para tu negocio, separada de tus fondos personales.

2. Crear una factura

Dos formas de hacerlo.

Programáticamente (recomendado)

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) // muéstralo a tu cliente

Respuesta:

{
  "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 compartible (sin integración necesaria)

Para un botón de checkout, código QR o enlace para compartir, puedes construir la factura desde una URL:

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

Ejemplos:

# el cliente paga 100 USDT en TON, tú recibes USDT en TON
https://api.p3p.xyz/invoice/create/0xYourMerchantWallet/100:usdt.ton/usdt.ton

# el cliente paga 50 TON, tú recibes USDT en TON
https://api.p3p.xyz/invoice/create/acme/50:ton.ton/usdt.ton

# forma simple: paga y recibe el mismo activo
https://api.p3p.xyz/invoice/create/acme/100:usdt.ton

:merchantId puede ser:

• el ID de partner devuelto durante el registro,
• un name de partner si configuraste uno, o
• una dirección de billetera ya registrada como comerciante.

3. Mostrar la dirección de depósito

Renderiza invoice.deposit_address y invoice.amount_from en tu UI, idealmente como código QR:

import QRCode from "qrcode"

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

El cliente envía amount_from de token_from a esa dirección. Cualquier otra cosa (cantidad incorrecta, token incorrecto, ventana expirada) se reembolsa automáticamente.

4. Confirmar el pago

Consulta /check/:id exactamente como un exchange regular:

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)
// los fondos ahora están en wallet_merchant

5. Inspeccionar tus ganancias

Tres endpoints de partner son de solo lectura y no requieren autenticación más allá de conocer el partnerId. Las ganancias se liquidan según tu configuración de pago (ya sea instantáneamente por swap o mediante retiros programados en USDT) — configura esto en el Panel de Partner.

Endpoint	Devuelve
GET /partners/:partnerId/stats	Volumen, número de transacciones, participación de ingresos
GET /partners/:partnerId/exchanges	Todos los exchanges acreditados a este partner
GET /partners/:partnerId/invoices	Todas las facturas creadas para este partner

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

Consejos y trampas

• Una billetera por cadena: un partner acumula billeteras, una por cadena. Usa la billetera correcta para la cadena de destino en wallet_merchant.
• Misma cadena + mismo token: omite el motor de swap y actúa como una dirección de reenvío simple — útil para enlaces simples "págame X USDT en TON".
• Ventana de depósito: las facturas comparten la ventana estándar de ~6 minutos. Si el cliente tarda más, llama a /check/:id?bump=true para refrescarla.
• Reembolsos: solo disponibles cuando se detecta el depósito pero el swap falla. Para facturas sin wallet_refund, los fondos intentan reembolsarse a la dirección del remitente detectada en cadena.

---

Referencia de endpoints

Todos los endpoints de comerciante son abiertos — no se requiere encabezado api-key. Tu billetera es la credencial.

1. Crear Factura2. Crear URL de Factura Compartible3. Obtener Estadísticas de Partner4. Obtener Exchanges del Partner5. Obtener Facturas del Partner

1. Crear Factura

POST /invoice/create

Campo	Tipo	Requerido	Descripción
chain_from	string	sí	Cadena desde la que paga el cliente
token_from	string	sí	Token con el que paga el cliente
amount_from	string	sí	Cantidad que paga el cliente
chain_to	string	sí	Cadena en la que recibes los fondos
token_to	string	sí	Token que recibes
wallet_merchant	string	sí	Tu billetera en la cadena destino

Devuelve un objeto de factura incluyendo id, deposit_address, amount_from, amount_to, rate y duration.

2. Crear URL de Factura Compartible

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

URL de factura compartible — ponla en un código QR o un botón.

• merchantId — id de partner, nombre de partner, o una billetera ya registrada como comerciante
• pathFrom — <amount>:<token>.<chain> (ej. 100:usdt.ton)
• pathTo — opcional, <token>.<chain> si quieres convertir; por defecto pathFrom

Devuelve el mismo objeto que POST /invoice/create.

3. Obtener Estadísticas de Partner

GET /partners/:partnerId/stats

Volumen agregado, número de transacciones y participación de ingresos de por vida para la billetera del partner.

4. Obtener Exchanges del Partner

GET /partners/:partnerId/exchanges

Lista paginada de exchanges acreditados al partner.

5. Obtener Facturas del Partner

GET /partners/:partnerId/invoices

Lista paginada de facturas creadas para el partner.

Errores

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

Código	Significado
invalid_json	El cuerpo de la solicitud no es JSON válido
merchant_id_required	Endpoint GET de factura llamado sin identificador de comerciante
partner_not_found	Ningún partner coincide con el merchantId dado
merchant_wallet_not_found	El partner existe pero no tiene billetera en la cadena destino
amount_too_small	Cantidad por debajo del mínimo del proveedor
amount_too_big	Cantidad por encima del máximo del proveedor