Versión: 3,1

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 haciendo 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 de 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 función opcional que debe configurarse por separado de la integración SEP-6. Para más información, consulta [Manejo de eventos][event-handling].

Puedes encontrar más información sobre el flujo de transacciones y estados en el documento del protocolo SEP-24

Callbacks

La Anchor Platform se basa en el servidor de negocios para proporcionar y almacenar información sobre cotizaciones.

Cotizaciones y tarifas

Para admitir el intercambio de activos no equivalentes, la Anchor Platform expone una API compatible con SEP-38 para proporcionar cotizaciones para el intercambio. La API de cotizaciones se utiliza para proporcionar al usuario el monto esperado 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 negocios debe implementar la [API de tarifas][rate-callback] para proporcionar cotizaciones a la Anchor Platform.

Asegurando la API de la plataforma

advertencia

De manera predeterminada, los puntos finales de la API de la Platform, como GET /transactions y GET /transactions/:id, no están protegidos y son accesibles por cualquier persona que tenga acceso al servidor, incluidas las aplicaciones de cartera.

información

Se recomienda mantener el servidor de la Platform accesible solo desde la red privada. Sin embargo, puede que desees agregar una capa adicional de protección a través de la seguridad de la API.

Usando la clave 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 habilitada, todas las solicitudes deben incluir un encabezado válido X-Api-Key, configurado con la clave API.

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>.

Haciendo 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 transacción JSON almacenados en el archivo proporcionado se usarán como cuerpo (las solicitudes deben ser un arreglo).

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 [JSON-RPC Methods][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á durante la invocación del método

idcadena

Un identificador establecido por el cliente. El servidor responderá con el mismo valor en el objeto Response

consejo

Es posible proporcionar múltiples actualizaciones en una sola solicitud JSON-RPC (colocando múltiples objetos de solicitud JSON-RPC). Cuando se realiza una actualización de esta manera, todas las actualizaciones se realizarán de forma secuencial.

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 DATOS

DESCRIPCIÓN

jsonrpccadena

Una cadena que especifica la versión del protocolo JSON-RPC. Se establece 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

Identificador único de la transacción para la cual ocurrió un error

códigonúmero

Un número que indica el tipo de error que ocurrió. Consulta una 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 no válido(s)
-32603	Error interno de JSON-RPC

consejo

También haremos referencia a una variable $transaction_id. Esta es una identificación de la transacción que se está devolviendo desde la Anchor Platform en una solicitud de inicio de retiro o depósito. Puedes obtener el ID de la transacción conectando la billetera de prueba a tu instancia local de la 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 del 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 deseas establecer para una transacción específica en tus solicitudes. Cada método JSON-RPC define estructuras de datos que espera en la solicitud. Si la solicitud no contiene los atributos requeridos, la Anchor Platform devolverá un error y no cambiará el estado de la transacción.

consejo

Los estados en verde son obligatorios y definen la manera más corta.

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.

Listo para recibir fondos

El primer paso del flujo de depósito después de iniciar el propio depósito es recopilar KYC. Generalmente se realiza en la aplicación web, pero también puede ser proporcionado opcionalmente por la aplicación de billetera, usando SEP-9. Una vez que se recopila el KYC necesario, se debe hacer 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 debe enviar al negocio.
amount_out es la cantidad que el usuario recibirá.
fee_details es el monto total de tarifas cobradas por el negocio.
asset es parte del campo amount_x y está en formato SEP-38. En este ejemplo, se establece en USD, asumiendo que el usuario hizo una transferencia bancaria al sistema usando USD.

La información sobre las cantidades (en/salida/tarifa) es requerida si quieres mover la transacción de incompleta a pendiente_transferencia_usuario_inicio. Si el estado de la transacción se cambia de pendiente_ancla a pendiente_transferencia_usuario_inicio, puedes omitir la definición de las cantidades.

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh request-offchain-funds.json

consejo

Cuando el proceso de KYC es largo (por ejemplo, verificación de ID), se aconseja primero establecer el estado de la transacción en pendiente_ancla utilizando la solicitud JSON-RPC notify_interactive_flow_completed. Esto indicará al usuario que KYC está siendo procesado.

Procesando información KYC

consejo

Este paso es opcional. La mayoría de los negocios no lo utilizan. Puedes omitirlo e ir al siguiente paso.

Usar este estado se recomienda cuando la verificación KYC pueda necesitar ser realizada de manera 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 fuera de la cadena, querrás proporcionar la información de transacción actualizada.

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 la recepción de fondos
external_transaction_id es el ID de la transacción en la red externa

Los campos de monto son opcionales. Si se omiten, se tomarán los valores de solicitudes JSON-RPC anteriores.

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh offchain-funds-received.json

Esperando fondos del usuario

En el mundo real, el proceso de confirmación de la transferencia puede tomar 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 los fondos en sí aún no se han recibido.

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 en la cadena

A continuación, envía una transacción en la red Stellar para cumplir con la solicitud del usuario. Después de la finalización de 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 la 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 será transferida al estado completada.

Enviando 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 hacer un pago a través del servicio de custodia, es necesario realizar 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 realizará automáticamente la solicitud JSON-RPC notify_onchain_funds_sent y el estado de la transacción cambiará a completada.

advertencia

Una cuenta de usuario puede no estar lista para recibir fondos. Puedes verificar que la cuenta ha establecido un trustline. De lo contrario, puedes establecer el estado de la transacción en pendiente_confianza para indicar que el anchor está esperando que el usuario establezca el trustline.

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 un trustline de activo que no fue configurado por el usuario. Hay dos formas en las que la transacción puede moverse al estado pendiente_confianza. La primera es procesando un pago a través del servicio de custodia en caso de que detecte que el trustline no está configurado. La segunda es cuando el negocio mismo detecta que falta el trustline y quiere notificar al usuario que debe ser configurado. Para mover la transacción al estado pendiente_confianza, es necesario realizar 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

información

El pago a través del servicio de custodia verifica periódicamente si se configuró el trustline. Si se configuró, enviará automáticamente un pago a un servicio de custodia y cambiará el estado de la transacción a pendiente_stellar.

Confianza Establecida

Este estado debe establecerse si el negocio ha detectado que el trustline fue o no configurado 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"
    }
  }
]

El flag success que define si el trustline fue o no configurado por el usuario

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh trust-set.json

información

Dependiendo del flag success, el estado de la transacción cambiará a pendiente_stellar si el trustline fue establecido, o a pendiente_ancla si no lo fue.

Enviando reembolso a través del servicio de custodia

Hay una posibilidad de enviar fondos de regreso al usuario (reembolso). Puedes reembolsar la suma completa (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 de regreso al usuario y enviar el resto como fondos en la cadena.

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

información

Si el total de reembolsos es menor que amount_in, el estado de la transacción se establecerá en pendiente_ancla. Solo si el total de reembolsos es igual a amount_in, el estado de la transacción se establecerá en reembolsado.

Reembolso Pendiente

Es similar a Reembolso enviado, pero maneja un caso cuando se ha enviado un reembolso a una red externa pero aún no está confirmado. El estado de la transacción se establece en pendiente_externo. Este es el estado que se establecerá al esperar que Bitcoin u otra red de criptomonedas externa complete una transacción, o al esperar 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

consejo

Si un usuario ha hecho una transferencia, deberías hacer una recuperación de la transacción, y luego puedes repetir el procesamiento de 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 cierto período. Para lograr esto, verifica el estado de la transacción utilizando el endpoint GET /transactions y ordena los resultados por la marca de tiempo 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 una transacción, el negocio debería cambiar el estado de la transacción a caducado:

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

consejo

Este método JSON-RPC no puede ser utilizado después de que el usuario haya realizado una transferencia.

Transacción en espera

En raras ocasiones, puedes querer pausar una transacción actual y solicitar más información del 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 transacciones

El estado de la transacción se puede cambiar de error/caducado a pendiente_ancla. 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 realizar 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 la transacción de retirada de fondos a través de JSON-RPC

Este diagrama define una secuencia/reglas de transición de estado de la transacción para el flujo de retirada SEP-24.

consejo

Los estados en verde son obligatorios y definen el camino más corto.

Los estados en amarillo son opcionales y pueden ser omitidos.

Los estados en rojo significan que la transacción está en un estado de error o que ha caducado.

Una vez que se complete el flujo de depósito, implementar la retirada será sencillo. Algunas partes del flujo son similares y pueden ser reutilizadas.

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, dado que tu servicio recibirá 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ón
memo_type Tipo de memo que el anchor debe adjuntar a la transacción
destination_account Cuenta de destino

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh request-onchain-funds.json

consejo

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 deposit_info_generator_type correspondiente. Además, puedes proporcionar memo y memo_type a la solicitud como se muestra arriba. Nota que el memo debe ser único, esto es lo que ayuda a asociar las transacciones de 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 el memo y memo_type (solo si no se incluyen en la solicitud).

nota

La cuenta Stellar que se utilizará para recibir fondos debe estar configurada.

Procesando Información KYC

Este paso es opcional, y es similar a Procesando Información KYC del flujo de depósito.

Fondos Recibidos

Si se recibieron fondos on-chain, debes proporcionar 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

consejo

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 on-chain, 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

nota

Solo amount_out y fee_details pueden ser actualizados usando esta solicitud JSON-RPC, y no necesitas especificar los activos de los montos.

Fondos Off-chain Enviados

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 Off-chain Disponibles

Puedes mover el estado de la transacción a pending_user_transfer_complete si se enviaron fondos off-chain, 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 Off-chain Pendientes

Otra opción es mover el estado de la transacción a pending_external. Este estado significa que el pago se ha 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 del reembolso funciona de la misma manera que para el flujo de depósito. Para más detalles, consulta Reembolso Enviado del flujo de depósito.

Envío de Reembolso a través de 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

nota

Al igual que en 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 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, consulta 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, consulta 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, consulta 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, consulta 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 el --stellar-observer flag en la sección de comandos del archivo de composición.

El Observador de Pagos rastreará 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 se emitirá el evento (si se utiliza Kafka).

Para actualizar los estados de las transacciones, el observador realiza las solicitudes JSON-RPC correspondientes a la plataforma. Debe usar la siguiente URL.

bash

# dev.env
PLATFORM_API_BASE_URL=http://platform-server:8085

advertencia

El Observador de Pagos no validará los montos. Es tu responsabilidad verificar que el monto enviado por el usuario sea correcto.

información

Si ya tienes un sistema que monitorea los pagos, asegúrate de que la lógica del sistema coincida con la descripción a continuación:

Primero, espera a que la transacción sea incluida en el libro mayor (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.

consejo

El servicio de custodia de Fireblocks rastreará automáticamente 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.

Callbacks​

Cotizaciones y tarifas​

Asegurando la API de la plataforma​

Usando la clave API​

Usando JWT​

Haciendo solicitudes JSON-RPC​

Solicitud JSON-RPC​

Respuesta JSON-RPC​

Códigos de error​

Actualizando transacciones de depósito a través de JSON-RPC​

Listo para recibir fondos​

Procesando información KYC​

Fondos Recibidos​

Esperando fondos del usuario​

Enviando fondos en la cadena​

Enviando pago a través del servicio de custodia​

Confianza Pendiente​

Confianza Establecida​

Enviando reembolso a través del servicio de custodia​

Reembolso Pendiente​

Error de transacción​

Transacción caducada​

Transacción en espera​

Recuperación de transacciones​

Actualizando la transacción de retirada de fondos a través de JSON-RPC​

Listo para recibir fondos​

Procesando Información KYC​

Fondos Recibidos​

Monto Actualizado​

Fondos Off-chain Enviados​

Fondos Off-chain Disponibles​

Fondos Off-chain Pendientes​

Reembolso Enviado​

Envío de Reembolso a través de Servicio de Custodia​

Error de Transacción​

Transacción Caducada​

Transacción En Espera​

Recuperación de Transacción​

Seguimiento de Transacciones Stellar​

Callbacks

Cotizaciones y tarifas

Asegurando la API de la plataforma

Usando la clave API

Usando JWT

Haciendo solicitudes JSON-RPC

Solicitud JSON-RPC

Respuesta JSON-RPC

Códigos de error

Actualizando transacciones de depósito a través de JSON-RPC

Listo para recibir fondos

Procesando información KYC

Fondos Recibidos

Esperando fondos del usuario

Enviando fondos en la cadena

Enviando pago a través del servicio de custodia

Confianza Pendiente

Confianza Establecida

Enviando reembolso a través del servicio de custodia

Reembolso Pendiente

Error de transacción

Transacción caducada

Transacción en espera

Recuperación de transacciones

Actualizando la transacción de retirada de fondos a través de JSON-RPC

Listo para recibir fondos

Procesando Información KYC

Fondos Recibidos

Monto Actualizado

Fondos Off-chain Enviados

Fondos Off-chain Disponibles

Fondos Off-chain Pendientes

Reembolso Enviado

Envío de Reembolso a través de Servicio de Custodia

Error de Transacción

Transacción Caducada

Transacción En Espera

Recuperación de Transacción

Seguimiento de Transacciones Stellar