Skip to main content

​
What are Accounts?

Accounts represent destinations or sources for funds in ramp transactions. Users can have multiple accounts of different types to support various payment methods and use cases.
Each account is linked to a specific user and must be verified before use in transactions.

​
Account Types

Bank Accounts

PSE, SPEI, ACH, WireTraditional fiat bank accounts for receiving local currency.Use for: Off-ramps (crypto → fiat)

Crypto Wallets

USDC/USDT on multiple networksBlockchain wallet addresses for receiving cryptocurrency.Use for: On-ramps (fiat → crypto)

​
Quick Start

1

Create User

Users must exist before adding accounts
POST /api/v2/users
2

Choose Account Type

Bank account for off-ramps, wallet for on-ramps
3

Create Account

Submit account details
POST /api/v2/accounts
4

Wait for Verification

Account status changes to ACTIVE after verification
5

Use in Ramps

Reference account ID when creating ramps

​
Creating Accounts

​
Bank Account Example

{
  "type": "PSE",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "bank-account-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "accountNumber": "1234567890",
    "bankCode": "0001",
    "type": "savings",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
Wallet Account Example

{
  "type": "WALLET",
  "userId": "4d23aa52-1b40-4584-a8ea-58aba6099c5c",
  "externalId": "wallet-1",
  "data": {
    "firstName": "Juan",
    "lastName": "García",
    "email": "[email protected]",
    "phone": "+573001234567",
    "currency": "USDC",
    "network": "POLYGON",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "countryCode": "CO",
    "document": {
      "type": "NUIP",
      "number": "1234567890",
      "issuedCountryCode": "CO"
    }
  }
}

​
Querying Accounts

​
Get All User Accounts

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();
};

​
Search Accounts

GET /api/v2/accounts?userId=user-id&type=WALLET
Filters:
  • ids - Specific account IDs (comma-separated)
  • userId - Filter by user
  • type - Account type
  • accountNumber - Bank account number
  • address - Wallet address
  • limit, page - Pagination

​
Get Account by ID

GET /api/v2/accounts/{accountId}

​
Updating Accounts

Limited fields can be updated after creation: 
PATCH /api/v2/accounts/{accountId}

{
  "type": "PSE",
  "data": {
    "accountNumber": "9876543210",
    "bankCode": "0002",
    "type": "checking"
  }
}
Updating certain fields may require re-verification and set account status back to PENDING.

​
Deleting Accounts

DELETE /api/v2/accounts/{accountId}

const deleteAccount = async (accountId) => {
  const response = await fetch(
    `https://teste-94u93qnn.uc.gateway.dev/api/v2/accounts/${accountId}`,
    {
      method: 'DELETE',
      headers: { 'Authorization': `Bearer ${token}` }
    }
  );
  
  if (response.ok) {
    console.log('Account deleted');
  }
};
Accounts used in pending or processing ramps cannot be deleted.

​
Account Verification

Accounts go through verification: Status:
  • ACTIVE - Ready for transactions
  • PENDING - Under verification
  • REJECTED - Verification failed
  • INACTIVE - Disabled

​
Multiple Accounts

Users can have multiple accounts: 
const userAccounts = await getUserAccounts(userId);

// Group by type
const groupedAccounts = {
  banks: userAccounts.filter(a => ['PSE', 'SPEI', 'ACH'].includes(a.type)),
  wallets: userAccounts.filter(a => a.type === 'WALLET')
};

// Find default account
const defaultWallet = userAccounts.find(a => 
  a.type === 'WALLET' && 
  a.data.network === 'POLYGON' &&
  a.data.currency === 'USDC'
);

​
Best Practices

// Verify bank code exists
const banks = await getBanks('CO');
const validBank = banks.find(b => b.code === bankCode);

// Validate wallet address format
const isValidAddress = /^0x[a-fA-F0-9]{40}$/.test(address);

// Check for duplicates
const existing = await findAccount({ userId, address });

{
  "externalId": `${yourUserId}-wallet-polygon-usdc`,
  // Makes lookups easy and prevents duplicates
}

if (account.status === 'PENDING') {
  showMessage('Account verification in progress');
  // Check back in 1 hour or wait for webhook
}

// Help users identify accounts
const accountLabel = account.type === 'WALLET'
  ? `${account.data.currency} on ${account.data.network}`
  : `${account.data.bankCode} - ${account.data.accountNumber.slice(-4)}`;

​
Next Steps

Bank Accounts

Set up bank accounts for different countries

Crypto Wallets

Configure cryptocurrency wallet accounts

Pre-Fund Accounts

Enable instant settlements

API Reference

Complete Accounts API documentation