Pular para o conteúdo principal

​
O que são Contas?

Contas representam destinos ou origens de fundos em transações ramp. Os usuários podem ter múltiplas contas de diferentes tipos para suportar vários métodos de pagamento e casos de uso.
Cada conta está vinculada a um usuário específico e deve ser verificada antes de usar em transações.

​
Tipos de Conta

Contas Bancárias

PSE, SPEI, ACH, WireContas bancárias fiat tradicionais para receber moeda local.Use para: Off-ramps (cripto → fiat)

Carteiras Cripto

USDC/USDT em múltiplas redesEndereços de carteira blockchain para receber criptomoeda.Use para: On-ramps (fiat → cripto)

​
Início Rápido

1

Criar Usuário

Usuários devem existir antes de adicionar contas
POST /api/v2/users
2

Escolher Tipo de Conta

Conta bancária para off-ramps, carteira para on-ramps
3

Criar Conta

Enviar detalhes da conta
POST /api/v2/accounts
4

Aguardar Verificação

O status da conta muda para ACTIVE após verificação
5

Usar em Ramps

Referenciar ID da conta ao criar ramps

​
Criando Contas

​
Exemplo de Conta Bancária

{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "phone": "+5511987654321",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "BR",
    "document": {
      "type": "CPF",
      "number": "12345678900",
      "issuedCountryCode": "BR"
    }
  }
}

​
Exemplo de Conta de Carteira

{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "phone": "+5511987654321",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "BR",
    "document": {
      "type": "CPF",
      "number": "12345678900",
      "issuedCountryCode": "BR"
    }
  }
}

​
Consultando Contas

​
Obter Todas as Contas do Usuário

GET /api/v2/accounts/userId/{userId}

const getUserAccounts = async (userId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/accounts/userId/${userId}`,
    {
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  return await response.json();
};

​
Pesquisar Contas

GET /api/v2/accounts?userId=user-id&type=WALLET
Filtros:
  • ids - IDs de conta específicos (separados por vírgula)
  • userId - Filtrar por usuário
  • type - Tipo de conta
  • accountNumber - Número da conta bancária
  • address - Endereço da carteira
  • limit, page - Paginação

​
Atualizando Contas

Campos limitados podem ser atualizados após a criação: 
PATCH /api/v2/accounts/{accountId}

{
  "type": "PSE",
  "data": {
    "accountNumber": "9876543210",
    "bankCode": "0002",
    "type": "checking"
  }
}
Atualizar certos campos pode exigir re-verificação e definir o status da conta de volta para PENDING.

​
Excluindo Contas

DELETE /api/v2/accounts/{accountId}
Contas usadas em ramps pendentes ou em processamento não podem ser excluídas.

​
Melhores Práticas

// Verificar se código do banco existe
const banks = await getBanks('BR');
const validBank = banks.find(b => b.code === bankCode);

// Validar formato do endereço da carteira
const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

// Verificar duplicatas
const existing = await findAccount({ userId, address });

{
  "externalId": `${yourUserId}-wallet-polygon-usdc`,
  // Facilita buscas e previne duplicatas
}

if (account.status === 'PENDING') {
  showMessage('Verificação da conta em andamento');
  // Verifique novamente em 1 hora ou aguarde webhook
}

​
Próximos Passos

Contas Bancárias

Configure contas bancárias para diferentes países

Carteiras Cripto

Configure contas de carteira de criptomoeda

Contas Pré-Financiadas

Habilite liquidações instantâneas

Referência da API

Documentação completa da API de Contas