Creando una factura

post https://api.cryptomus.com/v1/payment Copiar

Pedido

Parámetros de consulta

Nombre	Tipo de parámetro	Valor por defecto	Definición
amount*	string	-	El monto a pagar.Si hay centavos en la cantidad, envíelos con un separador '. Ejemplo: 10.28
currency*	string	-	Código de moneda
order_id*	stringmin: 1max: 100alpha_dash	-	ID de pedido en su sistemaEl parámetro debe ser una cadena que consiste en caracteres alfabéticos, números, subrayadores y guiones. No debe contener espacios o caracteres especiales.El Order_id debe ser único dentro de las facturas comerciales/billeteras estáticas/pagos de recurrenciaCuando encontramos una factura existente con order_id , devolvemos sus detalles, no se creará una nueva factura.
network	string	null	Código de red blockchain
url_return	stringmin: 6max: 255url	null	Antes de pagar, el usuario puede hacer clic en el botón en el formulario de pago y regresar a la página de la tienda en esta URL.
url_success	stringmin: 6max: 255url	null	Después de un pago exitoso, el usuario puede hacer clic en el botón en el formulario de pago y regresar a esta URL.
url_callback	stringmin: 6max: 255url	null	URL a la que se enviarán los webhooks con estado de pago
is_payment_multiple	boolean	true	Si el usuario puede pagar el monto restante. Esto es útil cuando el usuario no ha pagado el monto total de la factura por una transacción, y desea permitirle pagar hasta el monto total. Si deshabilita esta función, la factura finalizará después de recibir el primer pago y recibirá fondos para su saldo.
lifetime	integermin: 300max: 43200	3600	La vida útil de la factura emitida (en segundos)
to_currency	string	-	El parámetro se utiliza para especificar la moneda de destino para convertir la cantidad de factura. Al crear una factura, proporciona una cantidad y moneda, y la API convertirá esa cantidad al valor equivalente en la to_currency.Por ejemplo, para crear una factura para 20 USD en bitcoin: amount: 20 currency: USD to_currency : btcLa API convertirá el monto de 20 USD a su equivalente en BTC en función del tipo de cambio actual y el usuario pagará en BTCEl to_currency siempre debe ser el código de criptomoneda, no un código de moneda fiduciaria.
subtract	integermin: 0max: 100	0	Porcentaje de la comisión de pago cobrada al clienteSi tiene una tarifa del 1%, si crea una factura para 100 USDT con SUXTROT = 100 (el cliente paga el 100% de la comisión), el cliente tendrá que pagar 101 USDT.
accuracy_payment_percent	numericmin: 0max: 5	0	Inexactitud aceptable en el pago.Por ejemplo, si pasa el valor 5, la factura se marcará como pagada incluso si el cliente ha pagado solo el 95% del monto.El monto del pago real se acreditará al saldo
additional_data	stringmax: 255	null	Información adicional para usted (no se muestra al cliente)
currencies	array	Se utiliza la variedad de monedas disponibles desde la configuración de su comerciante (si el parámetro no está configurado, todas las criptomonedas compatibles se utilizan por defecto).Las monedas disponibles se establecen en la sección Configuración del comerciante.	Lista de monedas permitidas para el pago. Esto es útil si desea limitar la lista de monedas que sus clientes pueden usar para pagar facturas. Estructura
except_currencies	array	null	Lista de monedas excluidas para el pago Estructura
from_referral_code	string	null	El comerciante que hace la solicitud se conecta a un referente por código.Por ejemplo, usted es una aplicación que genera facturas a través de la API de Cryptomus y sus clientes son otras tiendas. Ingresan su clave API e ID de comerciante en su solicitud, y usted envía solicitudes con sus credenciales y aprobando su código de referencia.Por lo tanto, sus clientes se convierten en referencias en su cuenta de Cryptomus y recibirá ingresos de su facturación.
discount_percent	integermin: -99max: 90	null	Números positivos: le permite establecer un descuento. Para establecer un descuento del 5% para el pago, debe aprobar un valor: 5Números negativos: le permite establecer una comisión adicional personalizada.Para establecer una comisión adicional del 10% para el pago, debe aprobar un valor: -10El porcentaje de descuento al crear una factura se tiene en cuenta solo si la factura tiene una criptomoneda específica.
is_refresh	boolean	false	Usando este parámetro, puede actualizar la vida útil y obtener una nueva dirección para la factura si la vida útil ha expirado.Para hacer eso, debe pasar todos los parámetros requeridos, y la factura con Order_ID pasada se actualizará.Solo address, payment_status y expired_at se cambian. No se cambian otros campos, independientemente de los parámetros aprobados.

: Tipo de parámetro
string
Definición
El monto a pagar.Si hay centavos en la cantidad, envíelos con un separador '.
Ejemplo: 10.28
: Tipo de parámetro
string
Definición
Código de moneda
: Tipo de parámetro
stringmin: 1max: 100alpha_dash
Definición
ID de pedido en su sistemaEl parámetro debe ser una cadena que consiste en caracteres alfabéticos, números, subrayadores y guiones. No debe contener espacios o caracteres especiales.El Order_id debe ser único dentro de las facturas comerciales/billeteras estáticas/pagos de recurrenciaCuando encontramos una factura existente con order_id , devolvemos sus detalles, no se creará una nueva factura.
: Tipo de parámetro
string
Valor por defecto
null
Definición
Código de red blockchain
: Tipo de parámetro
stringmin: 6max: 255url
Valor por defecto
null
Definición
Antes de pagar, el usuario puede hacer clic en el botón en el formulario de pago y regresar a la página de la tienda en esta URL.
: Tipo de parámetro
stringmin: 6max: 255url
Valor por defecto
null
Definición
Después de un pago exitoso, el usuario puede hacer clic en el botón en el formulario de pago y regresar a esta URL.
: Tipo de parámetro
stringmin: 6max: 255url
Valor por defecto
null
Definición
URL a la que se enviarán los webhooks con estado de pago
: Tipo de parámetro
boolean
Valor por defecto
true
Definición
Si el usuario puede pagar el monto restante. Esto es útil cuando el usuario no ha pagado el monto total de la factura por una transacción, y desea permitirle pagar hasta el monto total. Si deshabilita esta función, la factura finalizará después de recibir el primer pago y recibirá fondos para su saldo.
: Tipo de parámetro
integermin: 300max: 43200
Valor por defecto
3600
Definición
La vida útil de la factura emitida (en segundos)
: Tipo de parámetro
string
Definición
El parámetro se utiliza para especificar la moneda de destino para convertir la cantidad de factura. Al crear una factura, proporciona una cantidad y moneda, y la API convertirá esa cantidad al valor equivalente en la to_currency.Por ejemplo, para crear una factura para 20 USD en bitcoin:
amount: 20
currency: USD
to_currency : btcLa API convertirá el monto de 20 USD a su equivalente en BTC en función del tipo de cambio actual y el usuario pagará en BTCEl to_currency siempre debe ser el código de criptomoneda, no un código de moneda fiduciaria.
: Tipo de parámetro
integermin: 0max: 100
Valor por defecto
0
Definición
Porcentaje de la comisión de pago cobrada al clienteSi tiene una tarifa del 1%, si crea una factura para 100 USDT con SUXTROT = 100 (el cliente paga el 100% de la comisión), el cliente tendrá que pagar 101 USDT.
: Tipo de parámetro
numericmin: 0max: 5
Valor por defecto
0
Definición
Inexactitud aceptable en el pago.Por ejemplo, si pasa el valor 5, la factura se marcará como pagada incluso si el cliente ha pagado solo el 95% del monto.El monto del pago real se acreditará al saldo
: Tipo de parámetro
stringmax: 255
Valor por defecto
null
Definición
Información adicional para usted (no se muestra al cliente)
: Tipo de parámetro
array
Valor por defecto
Se utiliza la variedad de monedas disponibles desde la configuración de su comerciante (si el parámetro no está configurado, todas las criptomonedas compatibles se utilizan por defecto).Las monedas disponibles se establecen en la sección Configuración del comerciante.
Definición
Lista de monedas permitidas para el pago. Esto es útil si desea limitar la lista de monedas que sus clientes pueden usar para pagar facturas. Estructura
: Tipo de parámetro
array
Valor por defecto
null
Definición
Lista de monedas excluidas para el pago Estructura
: Tipo de parámetro
string
Valor por defecto
null
Definición
El comerciante que hace la solicitud se conecta a un referente por código.Por ejemplo, usted es una aplicación que genera facturas a través de la API de Cryptomus y sus clientes son otras tiendas.
Ingresan su clave API e ID de comerciante en su solicitud, y usted envía solicitudes con sus credenciales y aprobando su código de referencia.Por lo tanto, sus clientes se convierten en referencias en su cuenta de Cryptomus y recibirá ingresos de su facturación.
: Tipo de parámetro
integermin: -99max: 90
Valor por defecto
null
Definición
Números positivos:
le permite establecer un descuento.
Para establecer un descuento del 5% para el pago, debe aprobar un valor: 5Números negativos:
le permite establecer una comisión adicional personalizada.Para establecer una comisión adicional del 10% para el pago, debe aprobar un valor: -10El porcentaje de descuento al crear una factura se tiene en cuenta solo si la factura tiene una criptomoneda específica.
: Tipo de parámetro
boolean
Valor por defecto
false
Definición
Usando este parámetro, puede actualizar la vida útil y obtener una nueva dirección para la factura si la vida útil ha expirado.Para hacer eso, debe pasar todos los parámetros requeridos, y la factura con Order_ID pasada se actualizará.Solo address, payment_status y expired_at se cambian. No se cambian otros campos, independientemente de los parámetros aprobados.

* - parámetro obligatorio

Estructura de Monedas

Nombre	Definición
currency*	Código de moneda
network	Código de red blockchain

: Definición
Código de moneda
: Definición
Código de red blockchain

* - parámetro obligatorio

Estructura de except_currencies

Nombre	Definición
currency*	Código de moneda
network	Código de red blockchain

: Definición
Código de moneda
: Definición
Código de red blockchain

* - parámetro obligatorio

La factura tendrá una criptomoneda y dirección específicas en el momento de la creación solo si el parámetro de moneda o to_currency es una criptomoneda y el parámetro de red se pasa (o una criptomoneda tiene solo una red, por ejemplo BTC).

Ejemplo de solicitud

A continuación se muestra un ejemplo de muestra con el número mínimo requerido de parámetros. En este caso, se creará una factura con la moneda Fiat USD. En la página de pago, el usuario podrá seleccionar la criptomoneda y la red para pagar esta factura.


curl https://api.cryptomus.com/v1/payment \
-X POST \
-H 'merchant: 8b03432e-385b-4670-8d06-064591096795' \
-H 'sign: fe99035f86fa436181717b302b95bacff1' \
-H 'Content-Type: application/json' \
-d '{
	"amount": "15",
	"currency": "USD",
	"order_id": "1"
}'

Copiar

Respuesta

Parámetros de respuesta

Nombre	Tipo de parámetro	Definición
uuid	string	Factura uuid
order_id	string\|null	ID de pedido en su sistema
amount	string	La cantidad de la factura
payment_amount	string\|null	Monto pagado por el cliente
payment_amount_usd	string\|null	Monto realmente pagado por el cliente en USD
payer_amount	string\|null	El monto en payer_currency que el cliente debe pagar, incluido un descuento o una comisión adicional.
payer_amount_exchange_rate	string\|null	Tipo de cambio aplicado cuando se realizó el pago
discount_percent	integer\|null	Porcentaje de descuento o comisión adicional, que se aprobó en los parámetros de solicitud
discount	string	Cantidad real de descuento o comisión adicional en criptomonedas.Por ejemplo, si el monto de la factura es de 15 USDT y descuento_percent es -5, el valor de descuento será -0.75es decir, la amount + discount = payer_amount
payer_currency	string\|null	La moneda en la que el cliente debe realizar el pago.
currency	string	Código de moneda de factura
comments	string\|null	Comentario
merchant_amount	string\|null	Cantidad en Crypto que se acreditará a su saldo. Si no se especifica la factura payer_currency, el valor será nulo.
network	string\|null	Código de red blockchain
address	string\|null	Dirección de billetera para el pago
from	string\|null	La dirección de la billetera de la que se realizó el pago
txid	string\|null	Hachís
payment_status	string	Estado de pago Todos los estados de pago
url	string	Página de pago de URL
expired_at	integer\|null	Marca de tiempo de vencimiento de la factura
status	string	Estado de pago Todos los estados de pago
is_final	boolean	Si la factura está finalizada.Cuando se finaliza la factura, es imposible pagar una factura (se paga o vence)
additional_data	string\|null	Información adicional
created_at	string\|null	Fecha de creación de la factura. La zona horaria es UTC+3
updated_at	string\|null	Última fecha de actualización actualizada. La zona horaria es UTC+3
commission	string\|null	Cantidad de la Comisión Cryptomus
address_qr_code	string\|null	Código QR de dirección
convert		La información sobre la moneda a la que el pago se convertirá automáticamente. La conversión se realiza desde payer_currency a USDTPresente si se pasa convert_currency_code
convert.to_currency	string	El código de moneda al que se convertirá el pago
convert.commission	string	Tarifa de conversión
convert.rate	string\|null	Tasa de conversión
convert.amount	string\|null	Cantidad de conversión to_currency que se agregó al saldo del comerciante, con todas las comisiones restadas.
convert_from		Información sobre la moneda desde la que se realizó un pago incorrecto.Presente si el pago es incorrecto
convert_from.from_currency	string	De la moneda
convert_from.from_amount	string\|null	Monto desde
convert_from.from_network	string\|null	Código de red blockchain

: Tipo de parámetro
string
Definición
Factura uuid
: Tipo de parámetro
string|null
Definición
ID de pedido en su sistema
: Tipo de parámetro
string
Definición
La cantidad de la factura
: Tipo de parámetro
string|null
Definición
Monto pagado por el cliente
: Tipo de parámetro
string|null
Definición
Monto realmente pagado por el cliente en USD
: Tipo de parámetro
string|null
Definición
El monto en payer_currency que el cliente debe pagar, incluido un descuento o una comisión adicional.
: Tipo de parámetro
string|null
Definición
Tipo de cambio aplicado cuando se realizó el pago
: Tipo de parámetro
integer|null
Definición
Porcentaje de descuento o comisión adicional, que se aprobó en los parámetros de solicitud
: Tipo de parámetro
string
Definición
Cantidad real de descuento o comisión adicional en criptomonedas.Por ejemplo, si el monto de la factura es de 15 USDT y descuento_percent es -5, el valor de descuento será -0.75es decir, la amount + discount = payer_amount
: Tipo de parámetro
string|null
Definición
La moneda en la que el cliente debe realizar el pago.
: Tipo de parámetro
string
Definición
Código de moneda de factura
: Tipo de parámetro
string|null
Definición
Comentario
: Tipo de parámetro
string|null
Definición
Cantidad en Crypto que se acreditará a su saldo. Si no se especifica la factura payer_currency, el valor será nulo.
: Tipo de parámetro
string|null
Definición
Código de red blockchain
: Tipo de parámetro
string|null
Definición
Dirección de billetera para el pago
: Tipo de parámetro
string|null
Definición
La dirección de la billetera de la que se realizó el pago
: Tipo de parámetro
string|null
Definición
Hachís
: Tipo de parámetro
string
Definición
Estado de pago Todos los estados de pago
: Tipo de parámetro
string
Definición
Página de pago de URL
: Tipo de parámetro
integer|null
Definición
Marca de tiempo de vencimiento de la factura
: Tipo de parámetro
string
Definición
Estado de pago Todos los estados de pago
: Tipo de parámetro
boolean
Definición
Si la factura está finalizada.Cuando se finaliza la factura, es imposible pagar una factura (se paga o vence)
: Tipo de parámetro
string|null
Definición
Información adicional
: Tipo de parámetro
string|null
Definición
Fecha de creación de la factura. La zona horaria es UTC+3
: Tipo de parámetro
string|null
Definición
Última fecha de actualización actualizada. La zona horaria es UTC+3
: Tipo de parámetro
string|null
Definición
Cantidad de la Comisión Cryptomus
: Tipo de parámetro
string|null
Definición
Código QR de dirección
: Definición
La información sobre la moneda a la que el pago se convertirá automáticamente. La conversión se realiza desde payer_currency a USDTPresente si se pasa convert_currency_code
: Tipo de parámetro
string
Definición
El código de moneda al que se convertirá el pago
: Tipo de parámetro
string
Definición
Tarifa de conversión
: Tipo de parámetro
string|null
Definición
Tasa de conversión
: Tipo de parámetro
string|null
Definición
Cantidad de conversión to_currency que se agregó al saldo del comerciante, con todas las comisiones restadas.
: Definición
Información sobre la moneda desde la que se realizó un pago incorrecto.Presente si el pago es incorrecto
: Tipo de parámetro
string
Definición
De la moneda
: Tipo de parámetro
string|null
Definición
Monto desde
: Tipo de parámetro
string|null
Definición
Código de red blockchain

Ejemplo de respuesta


1{
2	"state": 0,
3	"result": {
4		"uuid": "26109ba0-b05b-4ee0-93d1-fd62c822ce95",
5		"order_id": "1",
6		"amount": "15.00",
7		"payment_amount": null,
8		"payment_amount_usd": null,
9		"payer_amount": null,
10		"payer_amount_exchange_rate": null,
11		"discount_percent": null,
12		"discount": "0.00000000",
13		"payer_currency": null,
14		"currency": "USD",
15		"comments": null,
16		"merchant_amount": null,
17		"network": null,
18		"address": null,
19		"from": null,
20		"txid": null,
21		"payment_status": "check",
22		"url": "https://pay.cryptomus.com/pay/26109ba0-b05b-4ee0-93d1-fd62c822ce95",
23		"expired_at": 1689098133,
24		"status": "check",
25		"is_final": false,
26		"additional_data": null,
27		"created_at": "2023-07-11T20:23:52+03:00",
28		"updated_at": "2023-07-11T21:24:17+03:00",
29		"commission": null,
30		"address_qr_code": null
31	}
32}

Copiar

Más ejemplos

Solicite datos para crear una factura para 20 USDT en la red Tron. La factura tendrá una dirección en el momento de la creación.


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1",
5	"network": "tron"
6}

Copiar

Solicite datos para crear una factura para 25 USD y permita a los clientes pagar solo por USDT en cualquier red.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT"
6}

Copiar

Solicite datos para crear una factura para 25 USD y permita a los clientes pagar solo por USDT en Tron Network. La factura tendrá una dirección en el momento de la creación.


1{
2	"amount": "25",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "USDT",
6	"network": "tron"
7}

Copiar

Solicite datos para crear una factura para 20 USDT y permitir a los clientes pagar en todas las redes disponibles


1{
2	"amount": "20",
3	"currency": "USDT",
4	"order_id": "1"
5}

Copiar

Solicite datos para crear una factura para 20 USD y permita a los clientes pagar solo en bitcoin. La factura tendrá una dirección en el momento de la creación.


1{
2	"amount": "20",
3	"currency": "USD",
4	"order_id": "1",
5	"to_currency": "BTC"
6}

Copiar

Solicite datos para crear una factura para 0.5 BTC y permita a los clientes pagar solo en bitcoin. La factura tendrá una dirección en el momento de la creación.


1{
2	"amount": "0.5",
3	"currency": "BTC",
4	"order_id": "1"
5}

Copiar

Posibles errores

Errores de validación

código : 422

Ejemplos de respuestas:

Si se requiere algún parámetro y no se pasa:


1{
2	"state": 1,
3	"errors": {
4		"amount": ["validation.required"]
5	}
6}

Copiar

Si proporcionó el código de red que no es compatible


1{
2    "state": 1,
3    "message": "The network was not found"
4}

Copiar

Si no admitimos el código de divisas que proporcionó en el parámetro moneda :


1{
2    "state": 1,
3    "message": "The currency was not found"
4}

Copiar

Si sus pagos están bloqueados. En este caso, debe comunicarse con el soporte.


1{
2    "state": 1,
3    "message": "You are forbidden"
4}

Copiar

Si no encontramos el servicio de pago de la moneda que se pasó en to_currency parámetro:


1{
2    "state": 1,
3    "message": "Not found service to_currency"
4}

Copiar

Si accidentalmente sucede algo al convertir a to_currency :


1{
2    "state": 1,
3    "message": "Error convert to_currency"
4}

Copiar

Si el monto del pago es menor que el monto mínimo compatible con la criptomoneda, recibirá este mensaje de error:


1{
2    "state": 1,
3    "message": "Minimum amount 0.5 USDT"
4}

Copiar

Si el monto del pago es mayor que el monto máximo compatible para la criptomoneda, recibirá este mensaje de error:


1{
2    "state": 1,
3    "message": "Maximum amount 10000000 USDT"
4}

Copiar

Si no tendrá una billetera comercial activa con una criptomoneda del pago, recibirá este error:


1{
2    "state": 1,
3    "message": "Wallet not found"
4}

Copiar

Si se produce un trabajo técnico y el pago no está disponible temporalmente, puede recibir estos mensajes de error:


1{
2    "state": 1,
3    "message": "Gateway error"
4}

Copiar


1{
2    "state": 1,
3    "message": "The terminal was not found"
4}

Copiar


1{
2    "state": 1,
3    "message": "Server error"
4}

Copiar

Error Interno del Servidor

código : 500

Ejemplos de respuestas:


1{
2	"message": "Server error, #1",
3	"code": 500,
4	"error": null
5}

Copiar