Wallets

Tu compañía fondea cada pago desde una única wallet. WalletsClient cubre leer el balance actual y recorrer el historial de transacciones.

El segmento currency de la ruta no elige entre varias wallets — una compañía tiene exactamente una — así que el backend valida su forma y después la ignora. Pasa igual la moneda en la que está denominada tu wallet; un valor mal formado se sigue rechazando.

Accede a estos métodos directamente en RetornaClient o a través de client.wallets() — las dos formas ejecutan el mismo código.

getMyWallet(currency)

Lee la wallet de la compañía autenticada: su estado y balance actual.

Firma

public MyWallet getMyWallet(String currency)

Parámetros

Nombre	Tipo	Requerido	Descripción
currency	String	Sí	De 3 a 5 letras mayúsculas, por ejemplo USDR. Se valida la forma del lado del cliente antes de que salga la llamada.

Retorno

MyWallet:

Accesor	Tipo	Significado
status()	String	Estado de la wallet.
currency()	String	Moneda de la wallet.
amount()	String	Balance actual, string decimal — parséalo con BigDecimal, nunca con double.

Ejemplo

import app.retorna.sdk.RetornaClient;
import app.retorna.sdk.RetornaClientBuilder;
import app.retorna.sdk.core.environment.RetornaEnvironment;
import app.retorna.sdk.models.wallet.MyWallet;

RetornaClient client = new RetornaClientBuilder()
        .environment(RetornaEnvironment.SANDBOX)
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .buildClient();

MyWallet wallet = client.getMyWallet("USDR");
System.out.printf("Balance: %s %s (status=%s)%n",
        wallet.amount(), wallet.currency(), wallet.status());

Errores

• IllegalArgumentException — currency es null o no cumple el patrón de 3 a 5 letras mayúsculas.
• RetornaB2BException con codeEnum() uno de: B2B_WALLET_NOT_CONFIGURED — todavía no hay wallet provisionada, B2B_WALLET_NOT_FOUND, B2B_UNAUTHORIZED, B2B_COMPANY_NOT_FOUND, B2B_RATE_LIMITED — reintentable, B2B_UNKNOWN.
• RetornaAuthException — falla del intercambio de token.
• RetornaSdkException — falla de red o falla de deserialización.

Notas

• Los montos son strings decimales, no punto flotante. Parséalos con BigDecimal.
• No le busques significado a la currency puntual que pasas — el backend no rutea según ese valor.

Referencia de API

GET /me/wallets/:currency

getMyWalletTransactions(currency, type, params)

Recorre el historial de transacciones de la wallet, paginado por cursor.

Firma

public WalletTransactionsResponse getMyWalletTransactions(
    String currency,
    WalletTransactionType type,
    ListWalletTransactionsParams params
)

Parámetros

Nombre	Tipo	Requerido	Descripción
currency	String	Sí	Misma regla de forma que getMyWallet.
type	WalletTransactionType	Sí	El listado a leer. Hoy el SDK expone TOP_UP (valor en el wire "top_up"), que devuelve todo lo que acredita la wallet: depósitos on-chain y créditos registrados por tesorería.
params	ListWalletTransactionsParams	No (pasa null o firstPage())	cursor (String, opaco, null para la primera página) y limit (Integer, 1 a 100, default del backend 10). Mantén limit fijo durante todo el recorrido.

Factories de conveniencia: ListWalletTransactionsParams.firstPage() y firstPage(int limit).

Retorno

WalletTransactionsResponse:

Accesor	Tipo	Significado
pagination()	CursorPagination	nextCursor() (nullable cuando termina), hasMore(), limit(), total() (nullable).
data()	List<WalletTransaction>	Transacciones de esta página.

Cada WalletTransaction:

Accesor	Tipo	Significado
id()	String	Id de la transacción.
externalId()	String	Referencia del lado del cliente, cuando aplica; nullable.
type()	String	Forma en minúsculas en el wire: "top_up" para un depósito on-chain, "b2b_manual_credit" para un crédito registrado por tesorería. Se guarda como string para que un tipo nuevo no rompa la deserialización; compara contra WalletTransactionType.TOP_UP.wire().
amount() / currency()	String	Monto de la transacción (string decimal con dos decimales, ej. "20.00") y moneda.
createdAt()	OffsetDateTime	Timestamp de creación.
status()	String	PENDING o COMPLETED, o null cuando el proveedor de fondeo no reportó nada publicable para un depósito on-chain. Un b2b_manual_credit siempre es COMPLETED. El listado incluye recargas que todavía no están acreditadas — revisa esto antes de tratar un monto como balance disponible.

Ejemplo

import app.retorna.sdk.RetornaClient;
import app.retorna.sdk.RetornaClientBuilder;
import app.retorna.sdk.core.environment.RetornaEnvironment;
import app.retorna.sdk.models.wallet.ListWalletTransactionsParams;
import app.retorna.sdk.models.wallet.WalletTransaction;
import app.retorna.sdk.models.wallet.WalletTransactionType;
import app.retorna.sdk.models.wallet.WalletTransactionsResponse;

RetornaClient client = new RetornaClientBuilder()
        .environment(RetornaEnvironment.SANDBOX)
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .buildClient();

String cursor = null;
do {
    WalletTransactionsResponse page = client.getMyWalletTransactions(
            "USDR",
            WalletTransactionType.TOP_UP,
            new ListWalletTransactionsParams(cursor, 50));

    for (WalletTransaction tx : page.data()) {
        System.out.printf("%s %s %s %s%n",
                tx.createdAt(), tx.amount(), tx.currency(), tx.status());
    }
    cursor = page.pagination().nextCursor();
} while (cursor != null);

Errores

• IllegalArgumentException — currency mal formada, type null, un cursor vacío (pero no null), o un limit fuera de 1 a 100.
• RetornaB2BException con codeEnum() uno de: B2B_WALLET_NOT_CONFIGURED, B2B_WALLET_NOT_FOUND, B2B_INVALID_PAGINATION_CURSOR, B2B_UNAUTHORIZED, B2B_RATE_LIMITED — reintentable, B2B_UNKNOWN.
• RetornaAuthException — falla del intercambio de token.
• RetornaSdkException — falla de red o falla de deserialización.

Notas

• Este listado pasó de paginación por offset a paginación por cursor — enviar un parámetro page al estilo offset no está soportado y devuelve 400.
• Mantén limit fijo durante todo el recorrido, la misma regla que listar órdenes.

Referencia de API

GET /me/wallets/:currency/transactions/:type