Saltar al contenido principal
Versión: 3.0.0

Integración

Integrar con la Anchor Platform para facilitar pagos transnacionales implica implementar lo siguiente, como mínimo:

  • GET /customer & PUT /customer puntos finales de la API KYC para solicitar y recopilar datos KYC de los clientes
  • GET /rate punto final de la API RFQ para proporcionar tasas de FX entre los activos on & off-chain admitidos
  • GET /transactions solicitudes para obtener actualizaciones sobre el estado de las transacciones de la Anchor Platform (documentación disponible pronto)
  • JSON-RPC solicitudes para actualizar el estado de las transacciones de la Anchor Platform

Lo siguiente también puede ser requerido dependiendo de tu caso de uso:

  • DELETE /customer si tu negocio quiere o está obligado a permitir que los enviados soliciten la eliminación de los datos de los clientes

Crear un servidor de negocios​

Primero, vamos a crear un servidor de negocios y a añadirlo a nuestro archivo docker compose.

version: "3.8"

services:
  sep-server:
    image: stellar/anchor-platform:latest
    command: --sep-server
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home
    ports:
      - "8080:8080"
    depends_on:
      - db
  platform-server:
    image: stellar/anchor-platform:latest
    command: --platform-server
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home
    ports:
      - "8085:8085"
    depends_on:
      - db

  server:
    build: .
    ports:
      - "8081:8081"
    env_file:
      - ./dev.env
  db:
    image: postgres:14
    ports:
      - "5432:5432"
    env_file:
      - ./dev.env

A continuación, crea un servidor web simple utilizando tu lenguaje de programación preferido y un Dockerfile que inicie el servidor. docker compose up debería iniciar exitosamente los tres servicios.

Esta guía no proporciona un ejemplo de implementación de los puntos finales, pero puedes encontrar más información sobre los esquemas de solicitud y respuesta en el Anchor Platform API Reference, y las secciones a continuación ampliarán los conceptos importantes para entender al implementar los puntos finales.

Puntos finales de devolución de llamada del cliente​

La Anchor Platform nunca almacena la PII de tus clientes, y en su lugar actúa como un servidor proxy entre las aplicaciones del cliente y tu negocio, reenviando solicitudes y respuestas a la otra parte. Actualmente, las solicitudes y respuestas son casi idénticas a las definidas en la SEP-12 KYC API specification.

Identificación de clientes​

Los clientes pueden ser identificados utilizando dos enfoques.

El primer enfoque utiliza una cuenta Stellar y un memo. Al utilizar la Anchor Platform para facilitar pagos transnacionales, la organización emisora usa su propia cuenta Stellar, la que se utilizó para autenticarse mediante SEP-10 Stellar Authentication, al registrar clientes en tu negocio. Los memos se utilizan para distinguir clientes únicos que provienen de la misma organización emisora.

El segundo enfoque utiliza identificadores de clientes generados por tu servicio. Por ejemplo, si una organización emisora está registrando a un cliente, tu negocio recibirá una solicitud PUT /customer como la siguiente:

{
  "account": "GDJUOFZGW5WYBK4GIETCSSM6MTTIJ4SUMCQITPTLUWMQ6B4UIX2IEX47",
  "memo": "780284017",
  "type": "sep31-sender",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]"
}

En este ejemplo, la clave pública GDJ...X47 identifica a la organización emisora, y el memo 780284017 identifica al cliente. Los memos suelen ser enteros de 64 bits, pero también pueden ser otros tipos de datos, así que deben guardarse como cadenas. En respuesta, tu negocio debería devolver un identificador de cliente.

{
  "id": "fb5ddc93-1d5d-490d-ba5f-2c361cea41f7"
}

Tu servidor de negocios puede usar cualquier identificador para los clientes siempre que sea una cadena.

Después del registro de un cliente, la organización emisora puede usar cualquiera de los dos enfoques al verificar el estado del cliente. Por ejemplo, podrías recibir una solicitud GET /customer como la siguiente:

/customer?account=GDJUOFZGW5WYBK4GIETCSSM6MTTIJ4SUMCQITPTLUWMQ6B4UIX2IEX47&memo=780284017&type=sep31-sender

O bien, la organización emisora podría usar el identificador que devolviste cuando originalmente registraron al cliente.

/customer?id=fb5ddc93-1d5d-490d-ba5f-2c361cea41f7&type=sep31-sender

Tu negocio necesitará mantener un mapeo entre la cuenta y el memo utilizados para registrar originalmente al cliente y el ID que devuelves en la respuesta, así como los datos KYC proporcionados. En futuras iteraciones de la Anchor Platform, podríamos mantener este mapeo para tu negocio, así solo tendrías que trabajar con los IDs que generas.

Tipos de clientes​

Tu negocio probablemente requiera diferentes conjuntos de información KYC según el tipo de cliente. Puedes definir las etiquetas para cada uno de estos tipos de clientes en tu archivo dev.assets.yaml, y tus organizaciones emisoras necesitarán entender qué etiqueta usar al registrar o consultar el estado de los clientes.

En las solicitudes PUT /customer, debes usar el tipo que se pasó para evaluar si el remitente ha proporcionado todos los campos requeridos. En las solicitudes GET /customer, debes usar el tipo para determinar el estado del cliente.

Probar con la billetera demo​

Puedes probar tu implementación con la Stellar Demo Wallet siguiendo los pasos a continuación.

  1. Seleccionar "Generar keypair para nueva cuenta"
  2. Seleccionar "Crear cuenta"
  3. Seleccionar "Añadir activo" e introducir el código del activo y el dominio de origen de la Anchor Platform, localhost:8080
  4. Seleccionar "Añadir trustline"
  5. Financiar tu cuenta con un saldo del activo
  6. Seleccionar "SEP-31 Enviar" en el menú desplegable

Deberías ver que la billetera demo encuentra las URL de tu servicio, se autentica y verifica qué campos KYC necesita recopilar. Luego debería presentar un formulario para que introduzcas los detalles KYC para el remitente y el receptor.

billetera demo después de iniciar una transacción

Una vez que hayas introducido la información solicitada, se enviará esa información a la Anchor Platform, que la enviará a tu servidor de negocios. Una vez que la billetera demo tenga los IDs de los clientes que has generado, iniciará una transacción que debería fallar.

Punto final de devolución de llamada de tasas​

Una vez que la organización emisora haya registrado a los clientes involucrados en la transacción, necesitará solicitar una cotización, o tasa de FX, a tu negocio. La Anchor Platform solicita esta información a tu servidor de negocios utilizando el GET /rate endpoint.

Cotizaciones firmes vs. indicativas​

Las solicitudes de cotizaciones tendrán un parámetro type que es [indicative][indicative] o [firm][firm]. Si type=firm, tu respuesta debe incluir el campo id y la fecha-hora expires_at y reservar la liquidez necesaria para cumplir con esta cotización hasta que la cotización expire. Si type=indicative, no devuelvas los campos id o expires_at porque la tasa proporcionada no se utilizará en una transacción.

Ten en cuenta que el cliente puede solicitar que la cotización expire después de una fecha-hora específica utilizando el parámetro expires_after. Tu negocio debe honrar esta solicitud devolviendo un valor expires_at que esté en o después de la fecha-hora solicitada o rechazar la solicitud con una respuesta 400 Bad Request, que será reenviada al cliente.

Usar el ID del cliente​

Las solicitudes pueden incluir un parámetro client_id que identifica a la organización emisora que solicita la tasa. Puedes usar este parámetro para adherirte a los términos comerciales acordados con esa organización emisora, como ofrecer tasas con descuento. client_id puede no estar presente para solicitudes indicativas, en cuyo caso debería devolverse tu precio de mercado. Actualmente client_id siempre será la clave pública Stellar que la organización emisora usó para autenticarse con la Anchor Platform.

Métodos de entrega​

Es común que las tasas y tarifas de los negocios difieran dependiendo de los métodos de pago utilizados para enviar fondos al destinatario. Si tus métodos de entrega están configurados en tu archivo asset.yaml, los clientes siempre proporcionarán el método de pago que quieren que tu negocio use para las solicitudes de cotización firmes.

Debido a que este punto final actualmente solo se utiliza para pagar remesas en activos off-chain, se utilizará el buy_delivery_method. Si este punto final se usa en otros flujos de transacción como depósitos SEP-24, entonces sell_delivery_method también podría ser pasado para los negocios que apoyan estos tipos de transacciones.

Recuperar actualizaciones del estado de la transacción​

Para facilitar pagos transnacionales, necesitarás poder detectar cuando una organización emisora ha enviado a tu negocio un pago on-chain y determinar qué transacción estaba destinada a cumplir.

La forma más fácil de hacerlo es ejecutar el Stellar Observer, que detectará estos pagos y actualizará el registro correspondiente de la transacción con información sobre el pago. Tu negocio puede detectar estas actualizaciones sondeando el punto final de la API Platform GET /transactions.

Ejecutar el Stellar Observer​

El Stellar Observer monitorea el ledger Stellar para pagos realizados a tu(s) cuenta(s) y actualiza los registros de transacciones correspondientes con información sobre pagos on-chain. Para ejecutar el observer, añade lo siguiente a tu archivo docker compose.

services:
  ...
  observer:
    image: stellar/anchor-platform:latest
    command: --stellar-observer
    env_file:
      - ./dev.env
    volumes:
      - ./config:/home

Sondeando pagos recibidos​

El Stellar Observer realiza solicitudes JSON-RPC a la API Platform cada vez que detecta pagos recibidos para transacciones iniciadas por organizaciones emisoras, actualizando así la fecha-hora transfer_received_at de la transacción.

Tu negocio debería sondear periódicamente el punto final de la API Platform GET /transactions para detectar estas actualizaciones. Puedes referirte al siguiente ejemplo:

curl http://localhost:8080/transactions?sep=31&order_by=transfer_received_at&order=desc

La respuesta incluirá una lista de transacciones de pagos transnacionales iniciadas por organizaciones emisoras. Esta lista estará ordenada de acuerdo al momento en que se recibió un pago para esa transacción. Para cada transacción devuelta, tu negocio debería verificar si ya ha detectado el pago para esa transacción. Si lo ha hecho, has detectado todos los pagos realizados a tu(s) cuenta(s).

Actualizar transacción a través de JSON-RPC​

El diagrama de flujo SEP-31 define la secuencia/reglas de la transición del 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 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.

sep31 flow

consejo

Los estados en verde son obligatorios y definen el flujo 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 ha caducado.

Puedes crear una plantilla para realizar solicitudes JSON-RPC a la Anchor Platform.

Este capítulo también contiene información sobre el formato de solicitud/respuesta y códigos de error que podrían ser devueltos por la Anchor Platform.

Listo para recibir fondos​

Las transacciones SEP-31 deberían estar inicialmente en el estado pending_receiver. Para solicitar fondos del Sending Anchor, el Receiving Anchor debería cambiar el estado de la transacción a pending_sender haciendo la siguiente solicitud RPC:

// request-onchain-funds.json
[
  {
    "id": 1,
    "jsonrpc": "2.0",
    "method": "request_onchain_funds",
    "params": {
      "transaction_id": "<transaction_id>",
      "message": "Request onchain funds",
      "destination_account": "GD...G",
      "memo": "12345",
      "memo_type": "id"
    }
  }
]

Para procesar esto, necesitas ejecutar:

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

El estado de la transacción se cambiará a pending_sender.

Fondos recibidos​

Si el Sending Anchor ha enviado los fondos, el Receiving Anchor debería cambiar el estado de la transacción a pending_receiver haciendo la siguiente solicitud JSON-RPC:

// 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:

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

El estado de la transacción se cambiará a pending_receiver.

Fondos offchain enviados​

Para completar la transacción y cambiar su estado a completed, necesitas hacer una solicitud JSON-RPC notify_offchain_funds_sent.

// 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:

./call-json-rpc.sh offchain-funds-sent.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.

// 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:

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

Verificando la información del cliente​

En algunos casos, el Receiving Anchor podría necesitar solicitar información actualizada del Sending Anchor. Por ejemplo, el banco le dice al Receiving Anchor que el nombre del Cliente Receptor proporcionado es incorrecto o le falta un segundo nombre. Dado que esta información fue enviada a través de SEP-12, la transacción debería pasar al estado pending_customer_info_update hasta que el Sending Anchor realice otra solicitud PUT /customer de SEP-12 para actualizar. El Sending Anchor puede verificar qué campos necesitan ser actualizados haciendo una solicitud SEP-12 GET /customer que incluya los parámetros id o account & memo. El Receiving Anchor debería responder con un estado NEEDS_INFO y last_name incluido en los campos descritos.

Después de que el Sending Anchor realice una solicitud SEP-12 PUT /customer, llama al método JSON-RPC notify_customer_info_updated nuevamente para actualizar el estado de la transacción. Además, llama a este método cada vez que cambie el estado SEP-12 para 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 devolución de llamada sea notificado del último estado del cliente, permitiendo que el cliente solicite al usuario que actualice su información.

// 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": "sep31-receiver" // or sep31-sender
    }
  }
]

Para procesar esto, necesitas ejecutar:

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

Hacer un reembolso Stellar​

La integración con el servicio de custodia te permite realizar reembolsos a través del servicio de custodia, como Fireblocks.

// 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:

./call-json-rpc.sh do-stellar-refund.json
nota

No puedes hacer múltiples reembolsos en el flujo SEP-31. Por esta razón, el total del monto reembolsado más la tarifa de monto debería ser igual a amount_in. De lo contrario, obtendrás un error.

Reembolso enviado​

Hay una posibilidad de enviar todos los fondos de vuelta al Sending Anchor (reembolso). Necesitas reembolsar la suma total (reembolso completo).

// 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:

./call-json-rpc.sh refund-sent.json
nota

No puedes hacer múltiples reembolsos en el flujo SEP-31. Por esta razón, el monto a reembolsar más la tarifa de monto debería ser igual a amount_in. De lo contrario, obtendrás un error.

Error de transacción​

Si encuentras un error irrecuperable al procesar la transacción, es necesario establecer el estado de la transacción a error. Puedes usar el campo de mensaje para describir los detalles del error.

// 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:

./call-json-rpc.sh transaction-error.json
consejo

Si un usuario ha realizado una transferencia, deberías hacer una recuperación de transacción, y luego puedes volver a intentar procesar la transacción o iniciar un reembolso.

Transacción Caducada​

Tu negocio puede querer caducar aquellas transacciones que han sido abandonadas por el usuario después de un tiempo. Es una buena práctica limpiar las transacciones inactivas en estado incompleto. Para hacerlo, simplemente cambia el estado de la transacción a caducado.

// 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:

./call-json-rpc.sh transaction-expired.json
consejo

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

Recuperación de Transacción​

El estado de la transacción puede cambiarse 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 la transacción, es necesario hacer la siguiente solicitud JSON-RPC:

// 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:

./call-json-rpc.sh transaction-recovery.json

Configuración​

Puedes habilitar estos tipos de transacciones actualizando la configuración de tu archivo assets.yaml:

assets:
  - ...
    sep31:
      quotes_required: false