Cómo obtener un destinatario en ACH en línea

Obtén Anchors, las credenciales de pago que identifican a un usuario dentro de un riel de pago como ACH en línea (antes Transfiya).
Estas credenciales son necesarias para enviar dinero directamente a la cuenta bancaria de un usuario sin necesidad de aceptación.

Prerrequisitos

Antes de comenzar:

  • Tienes un token Bearer válido para autenticar solicitudes GET.
  • Entiendes la diferencia entre:
    • Anchor Lookup – para identificar a un usuario con base en su información personal y bancaria.
    • Anchor List – para recuperar todos los Anchors asociados a un número de celular conocido.

Todas las solicitudes de lectura al Ledger de Kamin (GET) deben estar autenticadas con un token Bearer. Todas las solicitudes de mutación (POST, PUT, PATCH, DELETE, etc.) deben estar autenticadas con una firma digital.

Para más información, consulta:

Objetivo

Recuperar las credenciales de pago (llamadas Anchors) de un usuario ya sea:

  1. Usando su información personal/bancaria (Anchor Lookup), o
  2. Usando su dirección de wallet (Anchor List).

Anchor Lookup

Utiliza esto cuando tengas la identidad e información bancaria del usuario, pero no su número de celular.
Esto devolverá solo un firmante si toda la información coincide. Un firmante en ACH en línea representa los datos bancarios de un usuario.

Solicitud de ejemplo

Hashea, firma y envía al endpoint Wallet Anchor Lookup. Consulta Hashing y firmado de solicitudes para detalles.

POST https://<ledger-url>/api/v2/wallets/transfiya/anchors/!lookup
Accept: application/json, text/plain, */*
Content-Type: application/json
x-ledger: <ledger-handle>
{
    "data": {
        "custom": {
            "proprietary": "CC",
            "identification": "000000090",
            "bankAccountNumber": "9090001010",
            "routerReference": "$bancorojo"
        },
        "wallet": "transfiya"
    },
    "hash": "<sha256-hash-of-data>",
    "meta": {
        "proofs": [
            {
                "method": "ed25519-v2",
                "public": "<public-key>",
                "digest": "<digest-del-proof>",
                "result": "<signature-of-digest>",
                "custom": { "moment": "<iso-8601-timestamp>" }
            }
        ]
    }
}

Cuerpo de respuesta:

{
    "hash": "7ffb7e1e9d67e9c386f78d0cbc217bb2eb0f103d76eb49fad09d6f053b167f50",
    "meta": {
        "proofs": [
            {
                "method": "ed25519-v2",
                "public": "FJJNnx7B/6cMPPq3UM9tjoUMBomYNPgAGpEd1LkDcVI=",
                "digest": "82ddbabf512fa453fbb4b39a91668b5fe1840c41ffeb44ec802a6a6e9ac2ba4c",
                "result": "IFe9Dzc+W5vgOGiWvPNXGNQ/bVOEywZopJQTi9bo/u/X3YEDSihVC131E7hIYO2Ftlo6F8Xgl9OjG1Rnk5BtBA==",
                "custom": {
                    "moment": "2025-05-19T21:14:39.734Z"
                }
            }
        ],
        "moment": "2025-05-19T21:14:39.734Z"
    },
    "data": [
        {
            "data": {
                "access": [],
                "handle": "wbX9V3UnXie7zz6wSpKkZHUrdjA31rowcp",
                "wallet": "transfiya",
                "target": "signer:wbX9V3UnXie7zz6wSpKkZHUrdjA31rowcp@transfiya",
                "schema": "target",
                "custom": {
                    "bankAccountNumber": "9090001010"
                }
            },
            "meta": {}
        }
    ]
}

Al crear el intent, usa la propiedad data.target para especificar el usuario en el riel que recibirá la transacción. Utiliza el valor de data.target como el destinatario en un intent de tipo SEND.

Anchor List

La API de Wallet también permite obtener Anchors usando el endpoint GET /v2/wallets/:address/anchors. Para más información sobre Anchor List, consulta la Referencia de API.

Solicitud de ejemplo

GET https://<ledger-url>/api/v2/wallets/{walletAddress}/anchors
Accept: application/json, text/plain, */*
Content-Type: application/json
x-ledger: <ledger-handle>
Authorization: Bearer eyJhbGciOiJFZER....
import axios from 'axios';
import { generateJwtToken } from './common';

const keyPair = {
    public: '<llave pública>',
    secret: '<llave privada>',
    scheme: 'ed25519-raw',
};

const ledgerHandle = '<ledger de kamin>';
const ledgerUrl = 'https://<ledger-url>/api/v2';

const listAnchorsExample = async () => {
    axios
        .get(`${ledgerUrl}/wallets/tel:573066000001@transfiya/anchors`, {
            headers: {
                'x-ledger': ledgerHandle,
                Authorization: `Bearer ${await generateJwtToken(keyPair, 'backend', ledgerHandle)}`,
            },
        })
        .then((response) => {
            console.log('Respuesta:', JSON.stringify(response.data, null, 2));
        })
        .catch((error) => {
            console.error(
                'Error:',
                error.response ? error.response.data : error.message
            );
        });
};

void listAnchorsExample();

Cuerpo de respuesta:

{
    "hash": "3372fbd4223397edf45377175198990bd18e6ad0da6c00b4d37c8bf61f294623",
    "meta": {
        "proofs": [
            {
                "method": "ed25519-v2",
                "public": "aSRs/3ni0v/zcLSQetGDAy1DunN9VcBPoeUK+UyzOJA=",
                "digest": "ff0fd44dfac433009c837ffc6bcc1384869fec098274dbc1130b536b55646dbd",
                "result": "iZna2dNDSWu1Wqnl8974JE0FZzqt6huNvJIWpJjnEomJH3mhRG6f0MlecHCOq/Qv6RCCFgo1k7HEO2WWq6UFCQ==",
                "custom": {
                    "moment": "2025-06-07T12:44:15.712Z"
                }
            }
        ],
        "moment": "2025-06-07T12:44:15.712Z"
    },
    "data": [
        {
            "data": {
                "access": [],
                "handle": "wbX9V3UnXie7zz6wSpKkZHUrdjA31rowcp",
                "wallet": "tel:573066000001@transfiya",
                "target": "signer:wbX9V3UnXie7zz6wSpKkZHUrdjA31rowcp@transfiya",
                "schema": "target",
                "custom": {
                    "bankName": "Banco Rojo",
                    "bankAccountNumber": "xxxxxx1010",
                    "bankBicfi": "7095"
                }
            },
            "meta": {}
        }
    ]
}

Se pueden devolver múltiples anchors, lo que da flexibilidad para seleccionar una cuenta bancaria específica. Puedes elegir con base en el campo bankName.

Consulta de Registros Inexistentes

Al consultar un Anchor inexistente, recibirás:

{
    "hash": "846146827c46ed8b6b48aa0c8d681266f53a9c3d6e8d96d4154bf5d722adc1c6",
    "meta": {
        "proofs": [
            {
                "method": "ed25519-v2",
                "public": "FJJNnx7B/6cMPPq3UM9tjoUMBomYNPgAGpEd1LkDcVI=",
                "digest": "c7c84270b0f1f48207eff2ce05b9518a92f911e651e916630e6a19f326353939",
                "result": "1Q6SBWv9dFXQXrK+AJR6WnV/23/5etw1d92sPH8tcJdce7bqywkJPG0axjEm2IbnPToD1TIcQJQL0ppJYiBiCQ==",
                "custom": {
                    "moment": "2025-05-19T21:12:22.754Z"
                }
            }
        ],
        "moment": "2025-05-19T21:12:22.754Z"
    },
    "data": []
}

Esto significa que no hay credenciales de riel asociadas con ese usuario o dirección. Puedes intentar de nuevo más tarde, pedirle al usuario que se registre en el riel, o verificar la información.

¿Qué sigue?

Una vez que hayas recuperado un Anchor válido, puedes:

  • Usar el valor data.target en intents tipo SEND para un abono directo sin aceptación.
  • Validar si el usuario está registrado en un riel específico (ACH en línea).
  • Construir validaciones previas en tu interfaz para confirmar si un usuario puede enviar o recibir fondos.
Historial de cambios
1.2.0
  • Cambiado• Guía renombrada y movida a ACH en línea
1.1.0
  • Cambiado• Renombrado de Transfiya a ACH en línea
1.0.2
  • Agregado• Se agregó el ejemplo de la solicitud HTTP cruda (endpoint y headers) en Anchor Lookup y Anchor List, junto a los ejemplos en TypeScript, SDK y CLI.
1.0.1
  • Corregido• Correción del comando para hacer Anchor Lookup del SDK, cambiando lookup() por anchor.lookup()
1.0.0
  • Agregado• Versión inicial