API de pagos

La API de pagos es el motor central para mover valor dentro de la red de Linka. Soporta pagos individuales, pagos masivos y liquidaciones transfronterizas con varios pasos.

Conceptos principales

• Objeto payment: representa una transferencia individual desde un origen hacia un destino.
• Liquidacion: confirma la finalidad de los fondos en la cuenta de destino.
• Idempotencia: todas las solicitudes POST soportan llaves de idempotencia para evitar duplicados.

Crear un pago

Usa este endpoint para iniciar una transferencia entre wallets de Linka o hacia una direccion externa.

POST https://api.linka.xyz/v1/payments

Headers

Cuerpo de la solicitud

{
  "amount": "100.00",
  "currency": "USDC",
  "source_wallet": "wal_orig_123",
  "recipient": "wal_dest_456",
  "description": "Invoice #8872",
  "metadata": {
    "internal_id": "inv_99"
  }
}

Respuesta

{
  "id": "pay_123456789",
  "object": "payment",
  "amount": "100.00",
  "currency": "USDC",
  "status": "pending",
  "source": "wal_orig_123",
  "destination": "wal_dest_456",
  "created_at": "2024-01-01T12:00:00Z"
}

Listar pagos

Consulta una lista paginada de pagos asociados con tu cuenta.

GET https://api.linka.xyz/v1/payments?limit=10&offset=0

Parametros de consulta

• status: filtra por pending, completed o failed.
• currency: filtra por codigo de moneda, por ejemplo USDC o MXN.
• recipient_id: filtra por un destinatario especifico.

Eventos webhook

Cuando un pago cambia de estado, Linka envia una notificacion a la URL de webhook configurada:

• payment.created: se dispara al crear el pago.
• payment.succeeded: se dispara cuando los fondos llegan al destino.
• payment.failed: se dispara si la transaccion es rechazada o falla on-chain.

[!WARNING] Verifica siempre la Idempotency-Key cuando reintentes solicitudes por errores de red.