Cómo empezar a aceptar pagos en criptomonedas con la API «New Address» de Bcon

Aceptar criptomonedas en tu página web puede parecer complicado. Sin embargo, con una pasarela de pago como Bcon, el proceso se vuelve estructurado y predecible. Antes de empezar, es importante elegir un monedero fiable para recibir tus fondos. Si no estás seguro de cuál es la mejor opción para tus necesidades, puedes consultar nuestra guía sobre cómo elegir el mejor monedero de criptomonedas.

En este artículo aprenderás:

Cómo funciona la pasarela
Cómo se identifican los pagos
Lo que necesitas antes de conectar tu página web
Cómo funciona la nueva función de la API de direcciones
Cómo utilizar correctamente todos los parámetros
La diferencia entre las cadenas BTC y EVM
Cómo funciona la caducidad de las facturas

Cómo funciona la pasarela de pago criptográfico de Bcon

Antes de escribir código, debes comprender la lógica.

Una pasarela de pago con criptomonedas realiza cuatro funciones principales:

Crea una dirección de pago única para una factura
Supervisa la cadena de bloques
Detecta las transacciones entrantes
Envía una llamada de retorno (notificación) a tu página web

Cuando un cliente realiza un pedido:

Tu página web genera una factura a través de la API
La pasarela genera una dirección de criptomoneda
El cliente envía criptomonedas a esa dirección
La pasarela detecta el pago
La pasarela envía una llamada de retorno a tu servidor
Marca el pedido como pagado

Y ya está.

2. Lo que necesitas antes de conectarte

Para conectar tu página web a Bcon, necesitas:

Un monedero para recibir fondos

Esta es TU cartera.
Aquí es donde quieres recibir criptomonedas. (Metamask, Trustwallet, Exodus o cualquier otra)

La configuración depende del tipo de cadena de bloques:

Para Bitcoin → debes proporcionar una xpub
Para las cadenas EVM (Ethereum, BSC) y otras como SOL, TRX → debes proporcionar una dirección de monedero habitual

A continuación explicaremos la diferencia.

Una URL de devolución de llamada

Esta es una URL de tu servidor.

Ejemplo:

https://yourstore.com/callback.php

Cuando cambie el estado del pago, Bcon enviará una solicitud POST a esta URL.

Sin una llamada de retorno, tu página web no sabrá que se ha realizado el pago.

Clave API

Por cada tienda blockchain creada en el panel de Bcon, recibirás una clave API independiente.

Importante:

Bitcoin → su propia clave API
Ethereum → su propia clave API
Binance → su propia clave API
Tron → su propia clave API

Debes enviarlo en el encabezado:

Autorización: Portador YOUR_API_KEY

3. Bitcoin frente a las cadenas EVM frente a Tron y Solana: una diferencia importante

Esto es MUY importante para entender cómo se identifican los pagos.

Bitcoin (BTC)

Captura de pantalla de la configuración de la clave pública

Bitcoin utiliza xpub (clave pública ampliada).

Importante:

xpub NO permite acceder a fondos
Solo puede generar direcciones
Se puede enviar sin problema a Gateway

Cómo funciona:

Para cada factura:

Bcon genera una NUEVA dirección BTC a partir de tu xpub
Cada factura tiene su propia dirección única

Ejemplo:

Factura 1 → Dirección A
Factura 2 → Dirección B
Factura 3 → Dirección C

Esto hace que la identificación sea MUY fácil.

Si llegan 0,005 BTC a la dirección B →
el sistema lo detecta → se trata de la factura n.º 2.

Ethereum, BSC (cadenas EVM), Tron y Solana

Las cadenas EVM, así como Tron y Solana, NO utilizan xpub.

Opción 1: un monedero para varias facturas

Cómo funciona

Ilustración de una opción de integración

Todos los clientes envían los pagos a la misma dirección de monedero.

Si se crean varias facturas con el mismo importe al mismo tiempo, el sistema no puede determinar a qué factura corresponde el pago.

Ejemplo:

Factura n.º 101 → 100 USDT
Factura n.º 102 → 100 USDT

Ambos clientes reciben la misma dirección de monedero.

Si se recibe un pago de 100 USDT, el sistema no puede identificar qué factura debe cerrarse.

Cómo se resuelve el problema

El sistema ajusta automáticamente el importe de las facturas adicionales añadiendo pequeños valores decimales.

Ejemplo:

Factura n.º 101 → 100,00 USDT
Factura n.º 102 → 100,01 USDT
Factura n.º 103 → 100,02 USDT

Ahora el sistema puede identificar la factura correcta a partir del importe exacto del pago.

El cliente debe enviar el importe exacto que figura en la factura.

Si el cliente envía:

menos,
además,
o una cantidad redondeada,

Es posible que el sistema no pueda determinar de inmediato qué factura se ha pagado.

Opción 2 — Varias carteras (recomendado)

Cómo funciona

Configurarás varias direcciones de monedero.

Ejemplo:

Cartera 1
Cartera 2
Cartera 3
Cartera 4
Cartera 5

Cada nueva factura se asigna, por orden de rotación, a la siguiente cartera disponible.

Si se crean 5 facturas al mismo tiempo:

Factura	Cartera
N.º 101	Cartera 1
N.º 102	Cartera 2
N.º 103	Cartera 3
N.º 104	Cartera 4
N.º 105	Cartera 5

Ahora, aunque el importe del pago difiera ligeramente del importe de la factura, el sistema sigue sabiendo qué factura corresponde a cada monedero.

Tras el pago

Cuándo:

una vez pagada la factura,
o si vence el plazo de pago,

El sistema desactiva la supervisión de esa cartera y la dirección queda disponible para volver a utilizarse.

¿Qué pasa si hay más facturas que carteras?

Ejemplo:

5 carteras
20 facturas simultáneas

Una vez que todas las carteras están ocupadas, el sistema empieza a reutilizar direcciones.

En ese momento, se activa automáticamente el mecanismo exclusivo de importes decimales de la Opción 1 para las facturas que compartan la misma cartera.

Cartera	Factura	Importe
Cartera 1	N.º 101	100,00
Cartera 1	N.º 106	100,01

En términos sencillos

Una sola cartera → configuración más sencilla, pero mayor probabilidad de que se produzcan conflictos en la identificación de los pagos.
Varias carteras → detección de pagos más fiable y menos casos en los que sea necesario modificar los importes.
Cuantas más carteras haya, más facturas se podrán procesar simultáneamente sin necesidad de utilizar importes decimales únicos.

¿Qué opción deberías elegir?

Una cartera es adecuada si:

tienes un número reducido de pagos simultáneos;
los importes de las facturas suelen variar;
quieres que la configuración sea lo más sencilla posible.

Se recomienda utilizar varias carteras si:

procesas muchas facturas a la vez;
Es frecuente que se den importes idénticos en las facturas;
Es importante que la detección de pagos automáticos sea fiable;
quieres reducir al mínimo los pagos no identificados.

Diagrama de la lógica de facturación en Bcon Global — Lógica de gestión de facturas

4. Uso de la API «Nueva dirección»

Punto final:

POST https://external-api.bcon.global/api/v2/address

Ejemplo en PHP:

define("BCON_APIKEY", "YOUR_API_KEY");

$curl = curl_init();
curl_setopt_array($curl, array(
 CURLOPT_URL => 'https://external-api.bcon.global/api/v2/address',
 CURLOPT_RETURNTRANSFER => true,
 CURLOPT_CUSTOMREQUEST => 'POST',
 CURLOPT_HTTPHEADER => array(
   'Accept: application/json',
   'Content-Type: application/json',
   'Authorization: Bearer '.BCON_APIKEY
 ),
 CURLOPT_POSTFIELDS => json_encode([
   "payment_currency" => "USDC",
   "origin_amount" => "15",
   "origin_currency" => "USD",
   "external_id" => "A1001",
   "chain" => "ethereum"
 ]),
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

5. Comprensión de todos los parámetros

Vamos a explicarlo todo con claridad.

Parámetros obligatorios

1. moneda_de_pago

Símbolo del token.

Ejemplos:

BTC

USDT

USDC

Esto determina la forma de pago que utilizará el cliente.

2. importe_original

Importe en moneda fiduciaria.

Ejemplo: 15

3. moneda_de_origen

Código de la moneda fiduciaria.

Ejemplos:

USD
EUR
UAH

Si el precio de tu producto es de 15 dólares:

origin_currency = USD

origin_amount = 15

El sistema convierte automáticamente el importe en tokens.

Ejemplo de resultado:

0,00032 BTC

Lógica de conversión automática

Si utilizas:

moneda_de_pago
importe_de_origen
moneda_de_origen

El sistema calcula el importe en criptomonedas según el tipo de cambio de mercado.

Parámetros opcionales

importe_del_pago

Esto anula la conversión.

Úsalo cuando:

Quieres saber la cantidad exacta en criptomonedas
No quieres que se realice la conversión automática

Ejemplo:

“payment_currency” => “BTC”,

“payment_amount” => “0,01”

Ahora se ignora «origin_amount». La factura será EXACTAMENTE de 0,01 BTC.

external_id

Es muy importante. Este es tu número de factura.

Ejemplo:

“external_id” => “A1001”

Normas:

Debe ser único para cada tienda
Longitud máxima: 8 caracteres
Devuelto en la función de llamada de retorno

Cuando se reciba la llamada de retorno:

En lugar de buscar por importe, se busca por external_id.

cadena

Define el concepto de cadena de bloques.

Disponible:

bitcoin
Ethereum
Binance
Solana
tron

Ejemplo:

“cadena” => “bitcoin”

Debe coincidir con «payment_currency».

6. Ejemplos prácticos

Ejemplo 1: Conversión automática (USD → BTC)

Vendes un producto por 100 dólares.

"payment_currency" => "BTC",
"origin_amount" => "100",
"origin_currency" => "USD",
"external_id" => "B2001",
"chain" => "bitcoin"

El sistema calcula:

0,0021 BTC

El cliente paga en BTC.

Ejemplo 2: importe fijo en criptomonedas

Quieres una cantidad fija de 50 USDT.

"payment_currency" => "USDT",
"payment_amount" => "50",
"external_id" => "C3001",
"chain" => "tron"

No se ha utilizado ninguna conversión.

Ejemplo 3: dos facturas de EVM por el mismo importe

Dos facturas:

50 USD

El sistema puede generar:

Factura 1 → 50,00 USDT
Factura 2 → 50,01 USDT

El cliente debe enviar el importe exacto.

7. Cómo funciona la devolución de llamada

Diagrama de configuración de la llamada de retorno de la API

Cuando cambia el estado del pago, el sistema Bcon envía una solicitud POST a tu URL de callback.

Esta solicitud contiene información importante sobre la transacción. Tu servidor debe leer estos datos y actualizar el estado del pedido en tu base de datos.

La función de devolución de llamada devolverá los siguientes campos:

Estado: el estado
de la transacción
- confirmed = 2
- parcialmente_confirmado = 1
- sin_confirmar = 0
Addr: la dirección de destino a la que se envió
el pago
Importe: el importe
del pago recibido
Txid: el identificador de la transacción en la cadena
de bloques

External_id: el valor que especificaste al crear la factura (se utiliza para el seguimiento)

Ejemplo de JSON de llamada de retorno

{
 "status": 2,
 "addr": "0x1234abcd...",
 "value": "15000000",
 "txid": "0x98fa76bc54...",
 "external_id": "A1001"
}

Qué significa el estado

0 (sin confirmar) → Transacción detectada, pero aún
no confirmada
1 (parcialmente_confirmada) → La transacción tiene algunas confirmaciones
2 (confirmada) → La transacción está totalmente confirmada y el pago es definitivo

En la mayoría de los casos, solo debes marcar el pedido como pagado cuando el estado sea 2.

Notas técnicas importantes

1️⃣ Regla de éxito de la devolución de llamada

Una llamada de retorno solo se considera correcta cuando el servidor devuelve:

Estado HTTP 200

Si tu servidor no devuelve un código HTTP 200, es posible que el sistema vuelva a intentar enviar la llamada de retorno.

2️⃣ Unidades de saldo en BTC

Para pagos con Bitcoin:

El campo «Valor» se muestra en satoshis, no en BTC.

Recordatorio:

1 BTC = 100 000 000 satoshis

Ejemplo:

Si el valor es 50 000 000
, eso significa que:

0,5 BTC

En el caso de las cadenas EVM (Ethereum, BSC, Tron), el valor se rige por las normas de la unidad más pequeña nativa de la cadena de bloques.

Ejemplo sencillo en PHP para gestionar una función de devolución de llamada

$data = json_decode(file_get_contents("php://input"), true);
$status = $data['status'];
$external_id = $data['external_id'];
if ($status == 2) {
   // Mark order as paid in database
}

8. Buenas prácticas

✔ Utiliza siempre un
«external_id» ✔ Verifica siempre la llamada
de retorno ✔ Exige siempre el pago
exacto ✔ Utiliza siempre una clave API distinta para cada cadena
✔ No reveles claves
privadas ✔ Para BTC: utiliza «xpub» únicamente. A la hora de plantearse cómo configurar los pagos con criptomonedas, es fundamental conocer los distintos procesadores de pagos disponibles y sus comisiones. Además, asegúrate de que tu plataforma cumpla con la normativa local relativa a las transacciones con criptomonedas. Esto te ayudará a generar confianza entre tus clientes y, al mismo tiempo, a proteger tu negocio.

9. Resumen

El uso de la función «Nueva dirección» de Bcon te permite:

Generar automáticamente direcciones de pago
Calcular automáticamente los importes en criptomonedas
Realizar un seguimiento automático de los pagos
Recibir llamadas de respuesta automáticamente

Diferencias clave:

Bitcoin:

Utiliza xpub
Genera una dirección única por factura
Identificación perfecta

EVM:

Una dirección de monedero
Diferenciación de importes utilizada
Se requiere el pago exacto

Si entiendes que:

importe_de_origen
moneda_de_origen
moneda_de_pago
importe_del_pago
external_id
cadena

De este modo, tendrás un control total sobre la lógica de creación de facturas.