Versión: 2,10

Integración

Uno de los puntos principales de interacción con la Anchor Platform es notificar a la Plataforma sobre eventos relacionados con las transacciones.

En general, querrás proporcionar actualizaciones para los siguientes eventos.

Tu negocio requiere que el usuario envíe información KYC para procesar una transacción
Tu negocio actualizó las cantidades de entrada/salida/tarifa para una transacción
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 realiza haciendo solicitudes JSON-RPC al punto final 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 hacer una solicitud JSON-RPC correspondiente y pasar los datos requeridos por el método RPC.

La API JSON-RPC de Anchor Platform está diseñada para notificar a la plataforma sobre cambios en el estado de la transacción. Dado eso, 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 función opcional que debe configurarse separadamente de la integración SEP-6. Para más información, consulta [Manejo de Eventos][event-handling].

Puedes encontrar más sobre el flujo y los estados de las transacciones en el documento del protocolo SEP-6.

Callbacks

La Anchor Platform depende del servidor del negocio para proporcionar y almacenar la información sobre clientes y cotizaciones.

Información del Cliente

La Anchor Platform no almacena información del cliente. En cambio, reenvía todas las solicitudes SEP-12 de clientes al servidor del negocio. El servidor del negocio es responsable de almacenar y gestionar esta información. Por lo tanto, tu servidor del negocio debe implementar las APIs de cliente para manejar las actualizaciones KYC.

Cotizaciones y Tarifas

Para admitir el exchange de activos no equivalentes, la Anchor Platform expone una API compatible con SEP-38 para proveer cotizaciones para el exchange. La API de cotizaciones se usa para proveer al usuario la cantidad esperada del activo que recibirá a cambio del activo que envía. La API de cotizaciones también se utiliza para proveer al usuario las tarifas esperadas para la transacción. Por lo tanto, tu servidor del negocio debe implementar la API de tarifas para proveer cotizaciones a la Anchor Platform.

Seguridad de la API de la Plataforma

advertencia

Por defecto, los endpoints de la API de la Plataforma, como GET /transactions y GET /transactions/:id, no están protegidos y son accesibles para cualquier persona que tenga acceso al servidor, incluidas las aplicaciones de billeteras.

información

Se recomienda mantener el servidor de la Plataforma accesible solo desde la red privada. Sin embargo, puede que desees añadir una capa adicional de protección mediante la seguridad de la API.

Uso de Clave API

Para habilitar la autenticación de clave API, modifica tu archivo dev.env:

bash

# dev.env
PLATFORM_SERVER_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 X-Api-Key válido, configurado con la clave API configurada.

Uso de JWT

Para habilitar la autenticación JWT, modifica tu archivo dev.env:

bash

# dev.env
PLATFORM_SERVER_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 que se hospeda 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 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 parámetros, correspondientes a la llamada al 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 Response

consejo

Es posible proporcionar múltiples actualizaciones en una única 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 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 posteriores SE PROCESARÁN y APLICARÁN también.

Respuesta JSON-RPC

La respuesta se expresa como un solo objeto JSON, con los siguientes atributos:

ATRIBUTOTIPO DE DATO

DESCRIPCIÓN

jsonrpccadena

Una cadena que especifica la versión del protocolo JSON-RPC. It's set to "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

Id ú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ó. Por favor, 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	Invalid method parameter(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 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.

Actualización de la Transacción de Depósito (Exchange) Via JSON-RPC

El diagrama del flujo de depósito SEP-6 define las secuencias/reglas de la transición de estado de la transacción y un conjunto de métodos JSON-RPC que deben llamarse 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 los atributos requeridos, la Anchor Platform devolverá un error y no cambiará el estado de la transacción.

El flujo de exchange de depósito es el mismo que el flujo de depósito, excepto que las cantidades no necesitan recalcularse al solicitar fondos offchain, si el usuario ha proporcionado una cotización firme del anchor.

consejo

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

Los estados en amarillo son opcionales y pueden omitirse.

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

Verificando la Información KYC

Aunque Anchor Platform no requiere que un cliente tenga su información KYC recopilada antes de iniciar un depósito, tu negocio puede querer recoger esta información antes de que el cliente haga una transferencia. Al escuchar los eventos de transacción creada, o consultando el endpoint GET /transactions, puedes determinar si una transacción requiere que el cliente actualice su información. Los campos SEP-9 requeridos pueden comunicarse al usuario devolviendo un estado NEEDS_INFO con los campos requeridos en el atributo fields.

Después de que el usuario haya enviado su información KYC, llama al método JSON-RPC notify_customer_info_updated para actualizar el estado de la transacción. Además, llama a este método cada vez que cambie el estado SEP-12 de un cliente, como cuando la información del cliente está siendo validada y el estado cambia de NEEDS_INFO a PROCESSING. Esto asegura que cualquier cliente configurado con una URL de callback sea notificado del estado más reciente del cliente, permitiendo que el cliente solicite al usuario que actualice su información.

JSON

// notify-customer-info-updated.json
[
  {
    "id": 1,
    "jsonrpc": "2.0",
    "method": "notify_customer_info_updated",
    "params": {
      "transaction_id": "<transaction_id>",
      "message": "Customer info updated",
      "customer_id": "45f8884d-d6e1-477f-a680-503179263359",
      "customer_type": "sep6-deposit" // or sep6-withdrawal
    }
  }
]

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh notify-customer-info-updated.json

Listo para Recibir Fondos

Después de que el usuario haya enviado su información KYC, el anchor puede notificar a la Plataforma que está listo para recibir fondos. El anchor debe usar el RPC request_offchain_funds para proporcionar las cantidades finales al usuario. Para hacerlo, realiza la siguiente solicitud JSON-RPC.

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"
      },
      "amount_fee": {
        "amount": 1,
        "asset": "iso4217:USD"
      },
      "amount_expected": {
        "amount": 10
      },
      "instructions": {
        "organization.bank_number": {
          "value": "123456789",
          "description": "US Bank routing number"
        },
        "organization.bank_account_number": {
          "value": "123456789",
          "description": "US Bank account number"
        }
      }
    }
  }
]

amount_in es la cantidad que el usuario debe enviar al negocio.
amount_out es la cantidad que el usuario recibirá.
amount_fee es la cantidad total de comisiones recolectadas por el negocio.
asset es parte del campo amount_x y está en formato SEP-38. En este ejemplo, está configurado en USD, asumiendo que el usuario realizó una transferencia bancaria al sistema usando USD.
instructions es el conjunto de campos estándar SEP-9 que el usuario debe usar para enviar fondos al negocio. En este ejemplo, el usuario debe enviar fondos a la cuenta bancaria con número de ruta 123456789 y número de cuenta 123456789.

La información sobre las cantidades (entrada/salida/tarifa) es requerida si quieres mover la transacción al estado pending_user_transfer_start.

Para procesar esto, necesitas ejecutar:

bash

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

advertencia

Para depósitos de exchange con una cotización firme (la solicitud está asociada con un quote_id), no deben proporcionarse cantidades.

Fondos Recibidos

Si se recibieron fondos offchain, querrás proporcionar información actualizada de 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
      },
      "amount_fee": {
        "amount": 1
      },
      "amount_expected": {
        "amount": 10
      }
    }
  }
]

funds_received_at es la fecha y hora de recepción de los 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 usarán los valores previos a esta solicitud.

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 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 que los fondos aún no han sido recibidos.

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

Luego, envía una transacción en la red Stellar para cumplir con el depósito del usuario. Después de que la transacción Stellar haya sido enviada, es necesario enviar la solicitud JSON-RPC notify_onchain_funds_sent para notificar al usuario que los fondos fueron 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 se transferirá al estado completed.

Enviando Pago a través del Servicio de Custodia

La Anchor Platform ofrece la posibilidad de enviar un pago a través de servicios de custodia, como Fireblocks. Para hacer un pago vía un servicio de custodia, realiza 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 completed.

advertencia

Una cuenta de usuario puede no estar lista para recibir fondos. Puedes verificar que la cuenta haya establecido una trustline. 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 trustline.

Si la integración de custodia está habilitada, la Anchor Platform hará esta validación automáticamente por ti.

Confianza Pendiente

Este estado debe establecerse si un pago requiere una trustline de activo que no fue configurada por el usuario. Hay dos formas en las que la transacción puede pasar al estado pending_trust. La primera es el procesamiento de un pago vía servicio de custodia en caso de que se detecte que la trustline no está configurada. La segunda es cuando el negocio detecta que falta la trustline y desea notificar al usuario que debe configurarse. Para mover la transacción al estado pending_trust, realiza 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 vía servicio de custodia verifica periódicamente si la trustline fue configurada. Si fue configurada, enviará automáticamente un pago al servicio de custodia y cambiará el estado de la transacción a pending_stellar.

Trust Set

Este estado debe establecerse si el negocio ha detectado si la trustline fue o no 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 trustline fue o no configurada por el usuario

Para procesar esto, necesitas ejecutar:

bash

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

información

Dependiendo del success flag, el estado de la transacción cambiará a pending_stellar si la trustline fue establecida, o a pending_anchor si no lo fue.

Reembolso Enviado

A veces, es necesario enviar fondos de vuelta al usuario (reembolso). Puedes reembolsar la suma completa (reembolso total) o hacer un conjunto de reembolsos parciales al source_account usando el refund_memo y refund_memo_type asociados con la transacción si están presentes. También, 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

información

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

Esto es similar a Reembolso Enviado, pero maneja el caso cuando un reembolso ha sido enviado a la red externa pero aún no está confirmado. El estado de la transacción se establece en pending_external. Este es el estado que se establecerá cuando se espera que Bitcoin u otra red crypto externa complete una transacción, o cuando se espera una transferencia bancaria.

Error de Transacción

Si encuentras un error irrecuperable al procesar la transacción, es obligatorio 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 transacción, y luego puedes reintentar procesar la transacción o iniciar un reembolso.

Transacción Caducada

Tu negocio puede querer expirar las transacciones que han sido abandonadas por el usuario después de algún tiempo. Es buena práctica limpiar las transacciones inactivas en el estado incomplete. Para hacerlo, realiza la siguiente solicitud JSON-RPC para expirar una transacción.

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 usarse después de que el usuario haya hecho una transferencia.

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 continuar con el procesamiento de la transacción. Para recuperar una transacción, realiza 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

Actualización de la Transacción de Retirada (Exchange) Via JSON-RPC

El diagrama del flujo de retirada SEP-6 define la secuencia/reglas de la transición de estado de la transacción. 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 los atributos requeridos, la Anchor Platform devolverá un error y no cambiará el estado de la transacción.

El flujo de exchange de retirada es el mismo que el flujo de retirada, excepto que las cantidades no necesitarán recalcularse al solicitar fondos onchain, si el usuario ha proporcionado una cotización firme del anchor.

consejo

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

Los estados en amarillo son opcionales y pueden omitirse.

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

Una vez terminado el flujo de retirada, implementar la retirada es sencillo. Algunas partes del flujo son similares y pueden reutilizarse.

El punto de partida tanto para la retirada como para el depósito es el mismo.

Listo para Recibir Fondos

De forma similar al depósito, el paso después de recopilar KYC es notificar al usuario que el anchor está listo para recibir fondos. Sin embargo, como tu servicio recibirá transacciones a través de la red Stellar, la solicitud RPC será diferente. El anchor debe usar el RPC request_onchain_funds para proporcionar las cantidades finales al usuario. Para hacerlo, realiza la siguiente solicitud JSON-RPC.

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"
      },
      "amount_fee": {
        "amount": 1,
        "asset": "stellar:USDC:GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5"
      },
      "amount_expected": {
        "amount": 10
      },
      "destination_account": "GD...G",
      "memo": "12345",
      "memo_type": "id"
    }
  }
]

amount_in es la cantidad que el usuario debe enviar al negocio.
amount_out es la cantidad que el usuario recibirá.
amount_fee es la cantidad total de comisiones recolectadas por el negocio.
asset es parte del campo amount_x y está en formato SEP-38. En este ejemplo, está configurado en USD, asumiendo que el usuario realizó una transferencia bancaria al sistema usando USD.
memo es el memo que el usuario debe usar al enviar sus fondos onchain al anchor.
memo_type es el tipo de memo que el usuario debe usar al enviar sus fondos onchain al anchor.
destination_account es la cuenta a la que el usuario debe enviar los fondos.

Para procesar esto, necesitas ejecutar:

bash

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

advertencia

Para retiradas de exchange con una cotización firme (la solicitud está asociada con un quote_id), no deben proporcionarse cantidades.

consejo

Establecer memo, memo_type y destination_account es opcional.

Si la integración con un custodio de terceros está habilitada, la Anchor Platform puede generar el memo, memo_type y destination_address si se elige un deposit_info_generator_type correspondiente. También puedes proporcionar memo y memo_type para 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 administra los activos, la Anchor Platform puede generar memos para ti. Cuando el estado cambia a pending_user_transfer_start, la Anchor Platform asigna automáticamente el memo y memo_type (solo si no están incluidos en la solicitud).

nota

Se debe configurar la cuenta Stellar que se usará para recibir los fondos.

Fondos Recibidos

Si se recibieron fondos onchain, necesitas proporcionar cantidades 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
      },
      "amount_fee": {
        "amount": 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.

Cantidad Actualizada

Si se recibieron fondos onchain, pero por alguna razón el amount_in difiere del especificado en el flujo interactivo (amount_expected), puedes actualizar amount_out y amount_fee 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
      },
      "amount_fee": {
        "amount": 1
      }
    }
  }
]

Para procesar esto, necesitas ejecutar:

bash

./call-json-rpc.sh amounts-updated.json

nota

Solo amount_out y amount_fee pueden actualizarse usando esta solicitud JSON-RPC, y no necesitas especificar los activos de las cantidades.

Fondos Offchain Disponibles

Puedes mover el estado de la transacción a pending_user_transfer_complete si se enviaron fondos offchain y está listo para que el usuario o destinatario los 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 Offchain 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

Fondos Offchain 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

Reembolso Enviado

La lógica de 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.

Enviando Reembolso a través del Servicio de Custodia

La integración con un servicio de custodia te permite hacer un reembolso a través del servicio, 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

De forma similar al flujo de depósito, puedes hacer un reembolso total 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 en 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 en el flujo de depósito. Para más detalles, consulta Transacción Caducada del flujo de depósito.

Recuperación de Transacción

Funciona de la misma manera que en 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 Payment Observer te permite delegar este paso a la Anchor Platform. Para habilitar el Payment Observer, utiliza el --stellar-observer flag en la sección de comandos del archivo de composición.

El Payment Observer rastreará todas las transacciones enviadas a la cuenta de distribución. Cuando se detecte la transacción con el memo esperado en la red, el estado cambiará automáticamente a pending_anchor y el evento será emitido (si se usa 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

advertencia

El Payment Observer 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 pagos, asegúrate de que la lógica del sistema igualará la descripción a continuación:

Primero, espera a que la transacción se incluya 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 se haya detectado y verificado esta transacción, 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​

Información del Cliente​

Cotizaciones y Tarifas​

Seguridad de la API de la Plataforma​

Uso de Clave API​

Uso de JWT​

Realizando Solicitudes JSON-RPC​

Solicitud JSON-RPC​

Respuesta JSON-RPC​

Códigos de Error​

Actualización de la Transacción de Depósito (Exchange) Via JSON-RPC​

Verificando la Información KYC​

Listo para Recibir Fondos​

Fondos Recibidos​

Esperando Fondos del Usuario​

Enviando Fondos Onchain​

Enviando Pago a través del Servicio de Custodia​

Confianza Pendiente​

Trust Set​

Reembolso Enviado​

Reembolso Pendiente​

Error de Transacción​

Transacción Caducada​

Recuperación de Transacción​

Actualización de la Transacción de Retirada (Exchange) Via JSON-RPC​

Listo para Recibir Fondos​

Fondos Recibidos​

Cantidad Actualizada​

Fondos Offchain Disponibles​

Fondos Offchain Pendientes​

Fondos Offchain Enviados​

Reembolso Enviado​

Enviando Reembolso a través del Servicio de Custodia​

Error de Transacción​

Transacción Caducada​

Recuperación de Transacción​

Seguimiento de Transacciones Stellar​

Callbacks

Información del Cliente

Cotizaciones y Tarifas

Seguridad de la API de la Plataforma

Uso de Clave API

Uso de JWT

Realizando Solicitudes JSON-RPC

Solicitud JSON-RPC

Respuesta JSON-RPC

Códigos de Error

Actualización de la Transacción de Depósito (Exchange) Via JSON-RPC

Verificando la Información KYC

Listo para Recibir Fondos

Fondos Recibidos

Esperando Fondos del Usuario

Enviando Fondos Onchain

Enviando Pago a través del Servicio de Custodia

Confianza Pendiente

Trust Set

Reembolso Enviado

Reembolso Pendiente

Error de Transacción

Transacción Caducada

Recuperación de Transacción

Actualización de la Transacción de Retirada (Exchange) Via JSON-RPC

Listo para Recibir Fondos

Fondos Recibidos

Cantidad Actualizada

Fondos Offchain Disponibles

Fondos Offchain Pendientes

Fondos Offchain Enviados

Reembolso Enviado

Enviando Reembolso a través del Servicio de Custodia

Error de Transacción

Transacción Caducada

Recuperación de Transacción

Seguimiento de Transacciones Stellar