Recibir pagos en Bitcoin (BTC)

#Cómo funciona un pago en Bitcoin

Un pago en Bitcoin en CryptoLike pasa por cuatro pasos y tres estados: new (Nuevo), pending (Pendiente) y paid (Pagado). La página de pago, la API y los webhooks muestran el mismo estado, así que la lógica de tus pedidos lee un solo campo. El cliente no necesita una cuenta en CryptoLike, solo una billetera Bitcoin que pueda enviar a una dirección bc1.

1. Creas el pago con POST /v1/invoices, el plugin para WooCommerce, el módulo para Magento 2 o un enlace de pago. Estado: new.
2. El cliente ve qué enviar: el monto exacto en BTC, la red (Bitcoin), la dirección con código QR y el tiempo restante.
3. Se detecta la transferencia. Estado: pending, «Pago detectado. Esperando confirmación.»
4. El pago se confirma. Tras 3 confirmaciones el estado pasa a paid, los fondos están en tu saldo y llega un webhook invoice.paid firmado.

#Lo que el cliente debe saber sobre Bitcoin

CryptoLike asigna a cada pago en Bitcoin su propia dirección SegWit nativa, que empieza por bc1q. La billetera del cliente suma la comisión de red de Bitcoin en BTC al monto, y el monto de la página de pago tiene que llegar completo. Solo el BTC nativo en la red Bitcoin llega al pago.

• Dirección. En minúsculas, empieza por bc1q y sirve solo para este pago.
• Comisión de red. La fija la billetera del remitente y se paga en BTC. Con una comisión más alta, la transferencia suele entrar antes en un bloque.
• Monto exacto. Si una billetera o un exchange descuenta su comisión del monto, el pago llega incompleto y queda en underpaid (Pago insuficiente). Envía la diferencia a la misma dirección antes de que se acabe el tiempo.
• Transferencias tardías. Una transferencia confirmada después de que el pago venció se acredita igualmente en tu saldo, marcada con late_payment: true y con un webhook invoice.late_payment. Acuerda con el cliente si entregas el pedido o le reembolsas.
• Red. Envía solo BTC nativo en la red Bitcoin. Los tokens vinculados a Bitcoin en otras redes nunca llegan al pago y no se pueden recuperar.

#Crea un pago en Bitcoin

Para crear un pago en Bitcoin en CryptoLike, toma el id del activo con ticker BTC y network btc de GET /v1/currencies y pásalo como coin_id a POST /v1/invoices. Pon el precio en BTC, como en el ejemplo, o en USD o EUR: en ese caso CryptoLike convierte al tipo de cambio actual y lo deja fijado durante el plazo del pago.

COIN_ID=$(curl -s https://api.cryptolike.net/v1/currencies \
  | jq -r '.currencies[] | select(.ticker=="BTC" and .network=="btc") | .id')

BODY='{"amount":"0.0015","currency":"BTC","coin_id":"'"$COIN_ID"'","order_id":"A-1003"}'
curl -s https://api.cryptolike.net/v1/invoices \
  -H "Content-Type: application/json" -H "Idempotency-Key: order-A-1003" \
  -H "X-API-Key: $KEY_ID" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" -d "$BODY"

La respuesta trae address, payer_amount y checkout_url: envía al cliente a esa página. Firma de las solicitudes: autenticación de la API; todos los campos: referencia de la API.

#Preguntas frecuentes

#¿Cuántas confirmaciones necesita un pago en Bitcoin?

CryptoLike acredita BTC tras 3 confirmaciones de la red Bitcoin. El umbral se define para cada activo, lo devuelve GET /v1/currencies y el cliente ve el avance en la página de pago. Más información sobre las confirmaciones.

#¿Qué pasa si el cliente envía BTC por otra red?

Solo el BTC nativo en la red Bitcoin llega al pago. Los tokens vinculados a Bitcoin en otras redes no llegan y no se pueden recuperar. Si el cliente tiene stablecoins, crea un pago en USDT en TRON o en USDT en Ethereum.

#¿Puedo poner el precio en USD?

Sí. Envía currency: "USD" con el coin_id de BTC: CryptoLike convierte al tipo de cambio actual y lo deja fijado durante el plazo del pago. Si no hay un tipo de cambio reciente, la API responde 503: reintenta o pon el precio del pago en BTC.

#¿Qué pasa si el cliente envía de menos?

El pago queda en underpaid (Pago insuficiente) y remaining_amount muestra lo que falta. Una recarga a la misma dirección antes de que se acabe el tiempo lo completa; una diferencia pequeña dentro de la tolerancia de tu cuenta se considera igualmente paid. Consulta pagos insuficientes.

#¿Cómo funcionan los retiros en Bitcoin?

Con POST /v1/withdrawals y los campos coin_id, amount, to_address y tu payout_id, o con un CSV de hasta 1,000 filas en el panel (pagos masivos). Las direcciones de destino pueden empezar por 1, 3, bc1q o bc1p. Antes, POST /v1/withdrawals/estimate muestra la comisión de la plataforma, la comisión de red reservada y el total a debitar. Los retiros requieren una cuenta verificada; las comisiones están en la página de precios.