Saltar al contenido principal

Depósito y Retirada Programática

información

Esta guía está disponible en tres lenguajes de programación diferentes: Typescript, Kotlin y Flutter (Dart). Puedes cambiar la versión mostrada en cada página mediante los botones de arriba.

El estándar SEP-6 define una forma en que los anchors y billeteras pueden interactuar en nombre de los usuarios. Las billeteras utilizan este estándar para facilitar intercambios entre activos on-chain (como stablecoins) y activos off-chain (como fiat, u otros activos de red como BTC).

Por favor, nota que esto es para depósitos y retiradas programáticas. Para depósitos y retiradas alojados, donde el anchor interactúa con billeteras de manera interactiva usando un popup, por favor consulta Depósito y Retirada Alojados.

Obtener Información del Anchor​

Comencemos creando un objeto sep6, que usaremos para todas las interacciones SEP-6:

const sep6 = anchor.sep6();

Primero, obtengamos información sobre el soporte del anchor para SEP-6. Esta solicitud no requiere autenticación y devolverá información genérica, como las monedas admitidas y las características admitidas por el anchor. Puedes obtener una lista completa de los campos devueltos en la especificación SEP-6.

const info = await sep6.info();

Iniciar un depósito​

Antes de comenzar, asegúrate de haberte conectado al anchor y haber recibido un token de autenticación, como se describe en la guía de billetera [Stellar Authentication]. Usaremos authToken en los ejemplos siguientes como el token de autenticación SEP-10, obtenido anteriormente.

Para iniciar una operación, necesitamos conocer un activo. Puedes codificar esto manualmente. Asegúrate de que sea uno que esté incluido en la respuesta de información anterior.

información

Antes de comenzar con el flujo de depósitos, asegúrate de que la cuenta de usuario haya establecido una línea de confianza para el activo con el que estás trabajando.

Comencemos con un depósito básico. Usaremos account para representar la clave pública de nuestra cuenta.

const deposit = await sep6.deposit({
  authToken,
  params: {
    asset_code,
    account,
  },
});

Hay varias clases de respuestas, dependiendo de si el anchor necesita más información. Todos los depósitos y retiradas tendrán estos mismos tipos de respuesta:

1. Respuesta de éxito​

Si la respuesta es exitosa (HTTP 200), entonces el anchor está procesando el depósito. Si necesita información adicional, la comunicará al proporcionar la información de la transacción.

2. Todavía procesando o denegado​

Si se devuelve un HTTP 403 con datos: customer_info_status, significa que la acción todavía está procesándose o no fue aceptada. En este caso, el campo more_info_url debería tener un enlace que describa los siguientes pasos.

Una respuesta de ejemplo:

{
  "type": "customer_info_status",
  "status": "denied",
  "more_info_url": "https://api.example.com/kycstatus?account=GACW7NONV43MZIFHCOKCQJAKSJSISSICFVUJ2C6EZIW5773OU3HD64VI"
}

3. Necesita más información KYC​

Otra respuesta común es un HTTP 403, con la respuesta: non_interactive_customer_info_needed. En este caso, el anchor necesita más información KYC a través de SEP-12.

Una respuesta de ejemplo:

{
  "type": "non_interactive_customer_info_needed",
  "fields" : ["family_name", "given_name", "address", "tax_id"]
}

Veamos cómo una billetera puede manejar esta situación. Primero, obtenemos el objeto de respuesta de depósito. Si la respuesta incluye este error, entonces podemos ver qué campos faltantes requiere el anchor.

if (deposit.type === "non_interactive_customer_info_needed") {
  // handle displaying the missing fields to the user
  console.log(deposit.fields);
}

La billetera necesitará manejar la presentación al usuario de qué campos están faltando. Y para agregar esos campos, podemos usar la clase sep12 de la siguiente manera.

const sep12 = await anchor.sep12(authToken);

// adding the missing kyc info (sample data)
await sep12.add({
  sep9Info: {
    family_name: "smith",
    given_name: "john",
    address: "123 street",
    tax_id: "123",
  },
});

Luego, podemos volver a llamar al método de depósito como antes y debería ser exitoso.

Más información sobre el envío de información KYC utilizando SEP-12 se puede encontrar en Proporcionar información KYC.

Proporcionar información KYC​

Un anchor puede responder a una solicitud de depósito o retirada diciendo que necesita información KYC adicional. Para facilitar esto, SEP-6 admite agregar información KYC de un cliente a través de SEP-12. El usuario puede enviar la información requerida utilizando el objeto sep12 de la siguiente manera.

Agreguemos algo de información KYC para nuestra cuenta usando datos de muestra. Los datos binarios (por ejemplo, datos de imagen) deben enviarse en un campo separado. Los campos permitidos para enviar al anchor se describen en SEP-9.

const sep12 = await anchor.sep12(authToken);

await sep12.add({
  sep9Info: {
    first_name: "john",
    last_name: "smith",
    email_address: "[email protected]",
    bank_number: "12345",
    bank_account_number: "12345",
  },
  sep9BinaryInfo: {
    photo_id_front: Buffer.from("./path/to/image/front"),
    photo_id_back: Buffer.from("./path/to/image/back"),
  },
});

Iniciar una retirada​

Iniciar una retirada es similar a un depósito y tiene los mismos tipos de respuesta que se describieron anteriormente.

const resp = await sep6.withdraw({
  authToken,
  params: {
    asset_code: "SRT",
    account: accountKp.publicKey,
    type: "bank_account",
    dest: "123",
    dest_extra: "12345",
  },
});

Obtener información de intercambio​

Si el anchor admite cotizaciones SEP-38, puede soportar depósitos que hagan un puente entre activos no equivalentes. Por ejemplo, un anchor recibe BRL a través de una transferencia bancaria y a cambio envía USDC (de valor equivalente menos tarifas) al usuario en Stellar.

Las funciones de intercambio sep6 permiten a un usuario iniciar un depósito o una retirada de intercambio con el anchor, y el anchor puede comunicar los siguientes pasos al usuario.

Primero, comencemos un intercambio de depósito con datos de muestra. Los activos se describen usando el esquema SEP-38.

const resp = await sep6.depositExchange({
  authToken,
  params: {
    destination_asset:
      "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    source_asset: "iso4217:USD",
    amount: "10",
  },
});

La respuesta sigue los mismos tipos que todos los depósitos y retiradas para SEP-6.

Ahora, creemos un intercambio de retirada, que sigue el mismo formato que el intercambio de depósito. También especificamos que es una retirada a cuenta bancaria utilizando el campo type.

const resp = await sep6.withdrawExchange({
  authToken,
  params: {
    destination_asset: "iso4217:USD",
    source_asset:
      "stellar:SRT:GCDNJUBQSX7AJWLJACMJ7I4BC3Z47BQUTMHEICZLE6MU4KQBRYG5JY6B",
    amount: "10",
    type: "bank_account",
  },
});

La respuesta sigue los mismos tipos que todos los depósitos y retiradas para SEP-6.

Obteniendo Información de Transacción​

En el flujo típico, la billetera obtendría datos de transacción para notificar a los usuarios sobre actualizaciones de estado. Esto se hace a través del endpoint SEP-6 GET /transaction y GET /transactions.

Seguimiento de Transacción​

Veamos cómo usar el sdk para rastrear los cambios de estado de transacción. Usaremos la clase Watcher para este propósito. Primero, inicialicemos y comencemos a rastrear una transacción.

const watcher = anchor.sep6().watcher();

const { stop, refresh } = watcher.watchOneTransaction({
  authToken,
  assetCode,
  id: txId,
  onSuccess,
  onMessage,
  onError,
});

Alternativamente, podemos rastrear múltiples transacciones para el mismo activo.

const watcher = anchor.sep6().watcher();

const { stop, refresh } = watcher.watchAllTransactions({
  authToken,
  assetCode,
  onMessage,
  onError,
});

Recuperando Transacción​

Mientras que la clase Watcher ofrece potentes capacidades de seguimiento, a veces es necesario obtener solo una transacción (o transacciones) una vez. La clase Anchor te permite obtener una transacción por ID, ID de transacción Stellar o ID de transacción externa:

const transaction = await anchor
  .sep6()
  .getTransactionBy({ authToken, id: transactionId });

También es posible obtener transacciones por el activo.

const transactions = await anchor.sep6().getTransactionsForAsset({
  authToken,
  assetCode,
});