Integración
Uno de los principales puntos de interacción con la Anchor Platform es notificar a la Anchor Platform sobre eventos relacionados con la transacción.
En general, querrás proporcionar actualizaciones para los siguientes eventos:
- Tu negocio está procesando la información KYC proporcionada por el usuario
- Tu negocio está listo para recibir fondos del usuario
- Tu negocio ha recibido fondos del usuario
- Tu negocio ha enviado fondos al usuario
- Tu negocio ha procesado un reembolso para la transacción del usuario
- Tu negocio experimentó un error inesperado
Esto se hace realizando solicitudes JSON-RPC al endpoint de la API de la plataforma. Las solicitudes JSON-RPC te permiten actualizar el estado de la transacción. Para mover la transacción a un estado específico, es necesario realizar una solicitud JSON-RPC correspondiente y pasar los datos que requiere este método RPC.
La API JSON-RPC de la Anchor Platform está diseñada para notificar a la plataforma sobre cambios en el estado de la transacción. Dado esto, la API será llamada cada vez que un usuario o el anchor realice alguna acción que avance el estado de la transacción en el flujo.
La comunicación desde la Anchor Platform sobre actualizaciones de transacciones, actualizaciones de clientes y creación de cotizaciones se maneja a través del servicio de eventos. Esta es una característica opcional que necesita configurarse por separado de la integración SEP-6. Para más información, consulta Manejo de Eventos.
Puedes encontrar más información sobre el flujo y los estados de las transacciones en el documento del protocolo SEP-24
Callbacks
La Anchor Platform depende del servidor del negocio para proporcionar y almacenar información sobre cotizaciones.
Cotizaciones y Tarifas
Para admitir el exchange de activos no equivalentes, la Anchor Platform expone una API compatible con SEP-38 para proporcionar cotizaciones para el exchange. La API de cotizaciones se utiliza para proporcionar al usuario la cantidad esperada del activo que recibirá a cambio del activo que está enviando. La API de cotizaciones también se utiliza para proporcionar al usuario las tarifas esperadas para la transacción. Por lo tanto, tu servidor de negocio debe implementar la API de tarifas para proporcionar cotizaciones a la Anchor Platform.
Asegurando la API de la Plataforma
Por defecto, los endpoint de la API de la Plataforma, como GET /transactions
y GET /transactions/:id
, no están protegidos y son accesibles para cualquiera que tenga acceso al servidor, incluidas las aplicaciones de billeteras.
Se recomienda mantener el servidor de la Plataforma accesible solo desde la red privada. Sin embargo, es posible que desees agregar una capa adicional de protección asegurando la API.
Usando la clave de API
Para habilitar la autenticación por clave API, modifica tu archivo dev.env
:
- bash
# dev.env
PLATFORM_API_AUTH_TYPE=api_key
# Will be used as API key
SECRET_PLATFORM_API_AUTH_SECRET="your API key that business server will use"
Una vez habilitado, todas las solicitudes deben incluir un encabezado válido X-Api-Key
, configurado con la clave API establecida.
Usando JWT
Para habilitar la autenticación JWT, modifica tu archivo dev.env
:
- bash
# dev.env
PLATFORM_API_AUTH_TYPE=jwt
# Will be used to sign the JWT token
SECRET_PLATFORM_API_AUTH_SECRET="your secret that business server will use"
Anchor Platform utiliza el algoritmo HMAC SHA-256 (HS256) para firmar los tokens JWT. Asegúrate de que SECRET_PLATFORM_API_AUTH_SECRET
tenga al menos 32 caracteres para mayor seguridad.
Una vez habilitado, todas las solicitudes deben incluir un encabezado Authorization
válido con el formato Bearer <JWT token>
.
Realizando solicitudes JSON-RPC
Antes de hacer solicitudes JSON-RPC, primero vamos a crear una plantilla para hacer una solicitud a la Anchor Platform.
- bash
# call-json-rpc.sh
#!/usr/bin/env bash
curl localhost:8085 \
-X POST \
-H 'Content-Type: application/json' \
--data "@$1"
Este pequeño script hará una solicitud JSON-RPC a la Anchor Platform alojada en el puerto predeterminado (8085). Los datos de la transacción JSON almacenados en el archivo proporcionado se utilizarán como cuerpo (las solicitudes deben ser un array).
Solicitud JSON-RPC
El objeto Request debe contener los siguientes atributos:
ATRIBUTOTIPO DE DATO
DESCRIPCIÓN
jsonrpccadena
Una cadena que especifica la versión del protocolo JSON-RPC. DEBE ser exactamente "2.0"
métodocadena
Una cadena que contiene el nombre del método a invocar. Lista de métodos disponibles que puedes ver en [Métodos JSON-RPC][json-rpc-methods]
paramsobjeto
Un valor estructurado que contiene los valores de los parámetros, correspondientes a la llamada del método, que se utilizarán durante la invocación del método
idcadena
Un identificador establecido por el cliente. El servidor responderá con el mismo valor en el objeto de respuesta
Es posible proporcionar varias actualizaciones en una única solicitud JSON-RPC (colocando múltiples objetos de solicitud JSON-RPC). Cuando se hace una actualización de esta manera, todas las actualizaciones se realizarán secuencialmente.
Lo más importante es que cada solicitud JSON-RPC no es atómica. Si una actualización falla, todas las actualizaciones anteriores SE aplicarán y todas las actualizaciones subsiguientes SE procesarán y aplicarán también.
Respuesta JSON-RPC
La respuesta se expresa como un único objeto JSON, con los siguientes atributos:
ATRIBUTOTIPO DE DATO
DESCRIPCIÓN
jsonrpccadena
Una cadena que especifica la versión del protocolo JSON-RPC. Está fijado en "2,0"
resultadoobjeto
Un valor estructurado que contiene los detalles de la transacción actualizada
idcadena
Un identificador enviado por el cliente
errorobjeto
Un valor estructurado que contiene los detalles del error
Mostrar atributos secundarios
idcadena
Identificación única de la transacción para la que ocurrió un error
códigonúmero
Un número que indica el tipo de error que ocurrió. Consulta la lista de códigos de error a continuación
mensajecadena
Una cadena que proporciona una breve descripción del error
datoscadena
Un valor primitivo o estructurado que contiene información adicional sobre el error
Códigos de Error
Código de error | Significado |
---|---|
-32600 | El JSON enviado no es un objeto Request válido |
-32601 | El método no existe / no está disponible |
-32602 | Parámetro(s) del método inválido(s) |
-32603 | Error interno de JSON-RPC |
También haremos referencia a una variable $transaction_id
. Esta es una identificación de la transacción que se devuelve desde la Anchor Platform en una solicitud de inicio de retirada de fondos o depósito. Puedes obtener el ID de la transacción conectando la billetera de prueba a tu instancia local de Anchor Platform.
Actualizando transacciones de depósito a través de JSON-RPC
El diagrama de flujo de depósito SEP-24 define la secuencia / reglas de la transición de estado de la transacción y un conjunto de métodos JSON-RPC que deben ser llamados para cambiar ese estado. No puedes definir el estado que quieres establecer para una transacción específica en tus solicitudes. Cada método JSON-RPC define las estructuras de datos que espera en la solicitud. Si la solicitud no contiene atributos requeridos, la Anchor Platform devolverá un error y no cambiará el estado de la transacción.
Los estados en verde son obligatorios y definen la forma más corta.
Los estados en amarillo son opcionales y pueden ser omitidos.
Los estados en rojo significan que la transacción está en estado de error o ha caducado.
Listo para Recibir Fondos
El primer paso del flujo de depósito después de iniciar el depósito en sí es recopilar KYC. Normalmente se hace en la aplicación web, pero también puede ser proporcionado opcionalmente por la aplicación de billetera, utilizando SEP-9. Una vez que se haya recopilado la KYC necesaria, se debe realizar una solicitud JSON-RPC request_offchain_funds
.
- JSON
// request-offchain-funds.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "request_offchain_funds",
"params": {
"transaction_id": "<transaction_id>",
"message": "Request offchain funds",
"amount_in": {
"amount": 10,
"asset": "iso4217:USD"
},
"amount_out": {
"amount": 9,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
},
"fee_details": {
"total": 1,
"asset": "iso4217:USD"
},
"amount_expected": {
"amount": 10
}
}
}
]
amount_in
es la cantidad que el usuario tiene que enviar al negocio.amount_out
es la cantidad que el usuario recibirá.fee_details
es la cantidad total de tarifas cobradas por el negocio.asset
es parte del campoamount_x
y está en formato SEP-38. En este ejemplo, está configurado como USD, asumiendo que el usuario hizo una transferencia bancaria al sistema utilizando USD.
La información sobre las cantidades (entrada/salida/tarifa) es requerida si quieres mover la transacción del estado incomplete
al estado pending_user_transfer_start
. Si el estado de la transacción cambia de pending_anchor
a pending_user_transfer_start
, puedes omitir definir las cantidades.
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh request-offchain-funds.json
Cuando el proceso KYC es largo (por ejemplo, verificación de ID), se aconseja primero establecer el estado de la transacción en pending_anchor
utilizando la solicitud JSON-RPC notify_interactive_flow_completed
. Esto indicará al usuario que KYC está siendo procesado.
Procesando la Información KYC
Este paso es opcional. La mayoría de los negocios no lo utilizan. Puedes omitirlo e ir al siguiente paso.
Usar este estado es recomendable cuando la verificación KYC puede necesitar ser realizada de forma asíncrona.
Debes especificar los campos amount_x
.
- JSON
// kyc-in-process.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_interactive_flow_completed",
"params": {
"transaction_id": "<transaction_id>",
"message": "Interactive flow completed.",
"amount_in": {
"amount": 10,
"asset": "iso4217:USD"
},
"amount_out": {
"amount": 9,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
},
"fee_details": {
"total": 1,
"asset": "iso4217:USD"
},
"amount_expected": {
"amount": 10
}
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh kyc-in-process.json
Fondos Recibidos
Si se recibieron fondos offchain, querrás proporcionar información actualizada sobre la transacción.
- JSON
// offchain-funds-received.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_offchain_funds_received",
"params": {
"transaction_id": "<transaction_id>",
"message": "Offchain funds received",
"funds_received_at": "2023-07-04T12:34:56Z",
"external_transaction_id": "7...9",
"amount_in": {
"amount": 10
},
"amount_out": {
"amount": 9
},
"fee_details": {
"total": 1
},
"amount_expected": {
"amount": 10
}
}
}
]
funds_received_at
es la fecha y hora de recepción de fondosexternal_transaction_id
es el ID de la transacción en la red externa
Los campos de cantidad son opcionales. Si se omiten, se tomarán los valores de las solicitudes JSON-RPC anteriores.
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh offchain-funds-received.json
Esperando Fondos del Usuario
En un mundo real, el proceso de confirmación de la transferencia puede llevar tiempo. En tales casos, las transacciones deben establecerse en un nuevo estado que indique que se ha recibido la confirmación de la transferencia, pero que los fondos no se han recibido aún.
- JSON
// offchain-funds-sent.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_offchain_funds_sent",
"params": {
"transaction_id": "<transaction_id>",
"message": "Offchain funds sent",
"funds_received_at": "2023-07-04T12:34:56Z",
"external_transaction_id": "7...9"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh offchain-funds-sent.json
Enviando Fondos Onchain
A continuación, envía una transacción a la red Stellar para cumplir con la solicitud del usuario. Después de completar la transacción, es necesario enviar la solicitud JSON-RPC notify_onchain_funds_sent
para notificar al usuario que los fondos han sido enviados con éxito.
- JSON
// onchain-funds-sent.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_onchain_funds_sent",
"params": {
"transaction_id": "<transaction_id>",
"message": "Onchain funds sent",
"stellar_transaction_id": "7...9"
}
}
]
stellar_transaction_id
es el ID de transacción en la red Stellar de la transferencia
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh onchain-funds-sent.json
Después de esta solicitud JSON-RPC, la transacción se transferirá al estado completed
.
Enviando el Pago a Través del Servicio de Custodia
La Anchor Platform proporciona la posibilidad de enviar un pago a través de servicios de custodia, como Fireblocks. Para realizar un pago a través del servicio de custodia, es necesario hacer la siguiente solicitud JSON-RPC:
- JSON
// do-stellar-payment.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "do_stellar_payment",
"params": {
"transaction_id": "<transaction_id>",
"message": "Custody payment started"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh do-stellar-payment.json
Después del procesamiento exitoso del pago en un servicio de custodia, la Anchor Platform automáticamente realizará la solicitud JSON-RPC notify_onchain_funds_sent
y el estado de la transacción cambiará a completed
.
Una cuenta de usuario puede no estar lista para recibir fondos. Puedes verificar que la cuenta ha establecido una línea de confianza. De lo contrario, puedes establecer el estado de la transacción en pending_trust
para indicar que el anchor está esperando que el usuario establezca la línea de confianza.
Si la integración de custodia está habilitada, la Anchor Platform realizará esta validación automáticamente por ti.
Confianza Pendiente
Este estado debe establecerse si un pago requiere una línea de confianza de activo que no fue configurada por el usuario. Hay dos formas en las que la transacción puede moverse al estado pending_trust
. La primera es el procesamiento de un pago a través de un servicio de custodia en caso de que se detecte que la línea de confianza no está configurada. La segunda es cuando el negocio mismo detecta que falta la línea de confianza y quiere notificar al usuario que debe ser configurada. Para mover la transacción al estado pending_trust
, es necesario hacer la siguiente solicitud JSON-RPC:
- JSON
// request-trust.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "request_trust",
"params": {
"transaction_id": "<transaction_id>",
"message": "Asset trustine not configured"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh request-trust.json
El pago a través del servicio de custodia verifica periódicamente si se configuró la línea de confianza. Si se configuró, automáticamente enviará un pago a un servicio de custodia y cambiará el estado de la transacción a pending_stellar
.
Configuración de Confianza
Este estado debe establecerse si el negocio ha detectado que la línea de confianza fue o no fue configurada por el usuario.
- JSON
// trust-set.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_trust_set",
"params": {
"transaction_id": "<transaction_id>",
"message": "Asset trustine set",
"success": "true"
}
}
]
success
flag que define si la línea de confianza fue o no fue configurada por el usuario
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh trust-set.json
Dependiendo del flag success
, el estado de la transacción cambiará a pending_stellar
si se configuró la línea de confianza, o a pending_anchor
si no se configuró.
Enviando Reembolso a Través del Servicio de Custodia
Hay una posibilidad de enviar fondos de vuelta al usuario (reembolso). Puedes reembolsar la suma total (reembolso completo) o hacer un conjunto de reembolsos parciales. Además, si el usuario envió más dinero del esperado, puedes reembolsar una parte de la suma al usuario y enviar el resto como fondos onchain.
- JSON
// refund-sent.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_refund_sent",
"params": {
"transaction_id": "<transaction_id>",
"message": "Refund sent",
"refund": {
"id": "1c186184-09ee-486c-82a6-aa7a0ab1119c",
"amount": {
"amount": 10,
"asset": "iso4217:USD"
},
"amount_fee": {
"amount": 1,
"asset": "iso4217:USD"
}
}
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh refund-sent.json
Si la suma de reembolsos es menor que amount_in
, el estado de la transacción se establecerá en pending_anchor
. Solo si la suma de reembolsos es igual a amount_in
, el estado de la transacción se establecerá en refunded
.
Reembolso Pendiente
Es similar a Reembolso enviado, pero maneja un caso cuando un reembolso ha sido enviado a la red externa pero no está aún confirmado. El estado de la transacción se establece en pending_external
. Este es el estado que se establecerá cuando se esté esperando a que Bitcoin u otra red de criptomonedas externa complete una transacción, o cuando se esté esperando una transferencia bancaria.
Error de Transacción
Si encuentras un error irrecuperable al procesar la transacción, es necesario establecer el estado de la transacción en error
. Puedes usar el campo de mensaje para describir los detalles del error.
- JSON
// transaction-error.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_transaction_error",
"params": {
"transaction_id": "<transaction_id>",
"message": "Error occurred"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh transaction-error.json
Si un usuario ha realizado una transferencia, debes hacer una recuperación de la transacción, y luego puedes intentar nuevamente procesar la transacción o iniciar un reembolso.
Transacción Caducada
Tu negocio puede querer manejar transacciones abandonadas caducando aquellas que han permanecido inactivas durante un período determinado. Para lograr esto, verifica el estado de la transacción utilizando el endpoint GET /transactions
y ordena los resultados por la marca de tiempo de user_action_required_by
. Si la marca de tiempo ha pasado, ejecuta manualmente la lógica apropiada, como caducar la transacción o iniciar un reembolso automático, según el estado actual de la transacción. Por ejemplo, para caducar transacciones, el negocio debería cambiar el estado de la transacción a expired
:
- JSON
// transaction-expired.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_transaction_expired",
"params": {
"transaction_id": "<transaction_id>",
"message": "Transaction expired"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh transaction-expired.json
Este método JSON-RPC no puede ser usado después de que el usuario haya realizado una transferencia.
Transacción en Espera
En raras ocasiones, puedes querer pausar la transacción actual y solicitar más información al usuario (después de que se haya recibido la transferencia). Esto podría usarse para casos de cumplimiento.
- JSON
// transaction-hold.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_transaction_on_hold",
"params": {
"transaction_id": "<transaction_id>",
"message": "Transaction is on hold. Please contact customer support to resolve the hold."
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh transaction-hold.json
Recuperación de Transacción
El estado de la transacción puede cambiar de error/expired
a pending_anchor
. Después de la recuperación, puedes reembolsar los activos recibidos o proceder con el procesamiento de la transacción. Para recuperar una transacción, es necesario hacer la siguiente solicitud JSON-RPC:
- JSON
// transaction-recovery.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_transaction_recovery",
"params": {
"transaction_id": "<transaction_id>",
"message": "Transaction recovered"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh transaction-recovery.json
Actualizando transacciones de retirada de fondos a través de JSON-RPC
Este diagrama define una secuencia/reglas de transición del estado de las transacciones para el flujo de retirada de fondos SEP-24.
Los estados en verde son obligatorios y definen el camino más corto.
Los estados en amarillo son opcionales y se pueden omitir.
Los estados en rojo significan que la transacción está en un estado de error o ha caducado.
Una vez que el flujo de depósito ha finalizado, implementar la retirada de fondos es sencillo. Algunas partes del flujo son similares y se pueden reutilizar.
El punto de partida tanto para la retirada como para el depósito es el mismo.
Listo para recibir fondos
Similar al depósito, el siguiente paso es notificar al usuario que el anchor está listo para recibir fondos. Sin embargo, como tu servicio estará recibiendo transacciones a través de la red Stellar, la actualización se verá diferente.
- JSON
// request-onchain-funds.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "request_onchain_funds",
"params": {
"transaction_id": "<transaction_id>",
"message": "Request onchain funds",
"amount_in": {
"amount": 10,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
},
"amount_out": {
"amount": 9,
"asset": "iso4217:USD"
},
"fee_details": {
"total": 1,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
},
"amount_expected": {
"amount": 10
},
"destination_account": "GD...G",
"memo": "12345",
"memo_type": "id"
}
}
]
memo
Valor del memo para adjuntar a la transacciónmemo_type
Tipo de memo que el anchor debe adjuntar a la transaccióndestination_account
Cuenta de destino
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh request-onchain-funds.json
Configurar memo
, memo_type
y destination_account
es opcional.
Si la integración con un custodio de terceros está habilitada, la Anchor Platform puede generar memo
, memo_type
y destination_address
si se elige un correspondiente deposit_info_generator_type
. Además, puedes proporcionar memo
y memo_type
a la solicitud como se muestra arriba. Ten en cuenta que el memo debe ser único, esto es lo que ayuda a asociar las transacciones Stellar con las transacciones SEP.
Si tu negocio gestiona los activos, la Anchor Platform puede generar memos para ti. Cuando el estado cambia a pending_user_transfer_start
, la Anchor Platform establece automáticamente memo
y memo_type
(solo si no se incluye en la solicitud).
La cuenta Stellar que se utilizará para recibir fondos debe estar configurada.
Procesando la Información KYC
Este paso es opcional, y es similar a Procesando la Información KYC del flujo de depósitos.
Fondos Recibidos
Si se recibieron fondos en cadena, necesitas proporcionar los montos y cambiar el estado de la transacción a pending_anchor
.
- JSON
// onchain-funds-received.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_onchain_funds_received",
"params": {
"transaction_id": "<transaction_id>",
"message": "Onchain funds received",
"stellar_transaction_id": "7...9",
"amount_in": {
"amount": 10
},
"amount_out": {
"amount": 9
},
"fee_details": {
"total": 1
}
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh onchain-funds-received.json
Este método será llamado automáticamente por el servidor de custodia si la integración de custodia está habilitada.
Monto Actualizado
Si se recibieron fondos en cadena, pero por alguna razón el amount_in
difiere del especificado en el flujo interactivo (amount_expected
), puedes actualizar amount_out
y fee_details
para que correspondan al amount_in
real. El estado de la transacción en este caso no cambiará y será igual a pending_anchor
.
- JSON
// amounts-updated.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_amounts_updated",
"params": {
"transaction_id": "<transaction_id>",
"message": "Amounts updated",
"amount_out": {
"amount": 9
},
"fee_details": {
"total": 1
}
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh amounts-updated.json
Solo amount_out
y fee_details
pueden ser actualizados usando esta solicitud JSON-RPC, y no necesitas especificar los activos de los montos.
Fondos Enviados Fuera de la Cadena
Para completar la transacción y cambiar su estado a completed
, necesitas hacer la solicitud JSON-RPC notify_offchain_funds_sent
.
- JSON
// offchain-funds-sent.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_offchain_funds_sent",
"params": {
"transaction_id": "<transaction_id>",
"message": "Offchain funds sent",
"funds_sent_at": "2023-07-04T12:34:56Z",
"external_transaction_id": "a...c"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh offchain-funds-sent.json
Fondos Fuera de la Cadena Disponibles
Puedes cambiar el estado de la transacción a pending_user_transfer_complete
si se enviaron fondos fuera de la cadena, y si está listo para que el usuario / destinatario lo recoja.
- JSON
// offchain-funds-available.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_offchain_funds_available",
"params": {
"transaction_id": "<transaction_id>",
"message": "Offchain funds available",
"external_transaction_id": "a...c"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh offchain-funds-available.json
Fondos Fuera de la Cadena Pendientes
Otra opción es mover el estado de la transacción a pending_external
. Este estado significa que el pago ha sido enviado a una red externa, pero aún no está confirmado.
- JSON
// offchain-funds-pending.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "notify_offchain_funds_pending",
"params": {
"transaction_id": "<transaction_id>",
"message": "Offchain funds pending",
"external_transaction_id": "a...c"
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh offchain-funds-pending.json
Reembolso Enviado
La lógica de reembolso funciona de la misma manera que para el flujo de depósito. Para más detalles, ver Reembolso Enviado del flujo de depósito.
Envío de Reembolso a Través del Servicio de Custodia
La integración con un servicio de custodia te permite hacer un reembolso a través de un servicio de custodia, como Fireblocks.
- JSON
// do-stellar-refund.json
[
{
"id": 1,
"jsonrpc": "2.0",
"method": "do_stellar_refund",
"params": {
"transaction_id": "<transaction_id>",
"message": "Do stellar refund",
"refund": {
"amount": {
"amount": 9,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
},
"amount_fee": {
"amount": 1,
"asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
}
}
}
}
]
Para procesar esto, necesitas ejecutar:
- bash
./call-json-rpc.sh do-stellar-refund.json
Al igual que con el flujo de depósito, puedes hacer un reembolso completo o un conjunto de reembolsos parciales. La transacción permanecerá en estado pending_anchor
hasta que la suma de los reembolsos sea menor que amount_in
. Si la suma de reembolsos es igual a amount_in
, la Anchor Platform cambiará automáticamente el estado de la transacción a refunded
.
Error de Transacción
Funciona de la misma manera que para el flujo de depósito. Para más detalles, ver Error de Transacción del flujo de depósito.
Transacción Caducada
Funciona de la misma manera que para el flujo de depósito. Para más detalles, ver Transacción Caducada del flujo de depósito.
Transacción En Espera
Funciona de la misma manera que para el flujo de depósito. Para más detalles, ver Transacción En Espera del flujo de depósito.
Recuperación de Transacción
Funciona de la misma manera que para el flujo de depósito. Para más detalles, ver Recuperación de Transacción del flujo de depósito.
Seguimiento de Transacciones Stellar
Usar el Observador de Pagos te permite delegar este paso a la Anchor Platform. Para habilitar el Observador de Pagos, usa la --stellar-observer
flag en la sección de comandos del archivo de composición.
El Observador de Pagos hará un seguimiento de todas las transacciones enviadas a la cuenta de distribución. Cuando la transacción con el memo esperado sea detectada en la red, el estado cambiará automáticamente a pending_anchor
y el evento será emitido (si se utiliza Kafka).
Para actualizar los estados de las transacciones, el observador realiza las solicitudes JSON-RPC correspondientes a la plataforma. Debería usar la siguiente URL.
- bash
# dev.env
PLATFORM_API_BASE_URL=http://platform-server:8085
El Observador de Pagos no validará los montos. Es tu responsabilidad verificar que el monto enviado por el usuario sea correcto.
Si ya tienes un sistema que monitorea los pagos, asegúrate de que la lógica del sistema iguale la descripción a continuación:
Primero, espera a que la transacción sea incluida en el ledger (usando un SDK). Esta transacción debe tener el memo esperado y la dirección de destino (cuenta de distribución). Una vez que esta transacción haya sido detectada y verificada, notifica al usuario que los fondos han sido recibidos usando la solicitud JSON-RPC notify_onchain_funds_received.
El servicio de custodia de Fireblocks hará un seguimiento automáticamente de las transacciones y notificará al usuario que los fondos han sido recibidos. Consulta la documentación del servicio de custodia de Fireblocks para más detalles.