Accounts

The Accounts API allows you to manage user accounts, including retrieving account information, checking balances, performing currency conversions, and managing Tropicard integrations.

The Account Object

{
    "id": 21221,
    "accountNumber": "TP00-0000-0000-0000-0000",
    "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "alias": "My Account",
    "balance": 418090,
    "pendingIn": 1422276,
    "pendingOut": 0,
    "state": 1,
    "paymentEntityId": 34,
    "currency": "USDC",
    "type": 1,
    "createdAt": "2025-07-14T19:10:04.936Z",
    "updatedAt": "2025-07-22T13:16:59.737Z",
    "isDefault": false,
    "groupId": null,
    "TropiCards": [],
    "services": [
        {
            "slug": "CRYPTO_TOPUP",
            "enabled": true
        }
    ],
    "paymentMethods": [
        {
            "slug": "TPP",
            "name": "Tropipay",
            "enabled": true
        }
    ]
}

Attributes

Attribute	Type	Description
`id`	integer	Unique identifier for the account.
`accountNumber`	string	The unique account number.
`userId`	string	The ID of the user who owns the account.
`alias`	string	A user-defined name for the account.
`balance`	integer	The current balance of the account in cents.
`pendingIn`	integer	The amount of incoming funds that are pending confirmation, in cents.
`pendingOut`	integer	The amount of outgoing funds that are pending confirmation, in cents.
`state`	integer	The state of the account (e.g., `1` for active).
`currency`	string	The currency code for the account (e.g., `USDC`, `EUR`).
`type`	integer	The type of account (e.g., `1` for a standard account).
`createdAt`	string	The date and time when the account was created, in ISO 8601 format.
`updatedAt`	string	The date and time when the account was last updated, in ISO 8601 format.
`isDefault`	boolean	Indicates if this is the user's default account.
`services`	array	A list of financial services enabled for this account.
`paymentMethods`	array	A list of payment methods available for this account.

List All Accounts

Returns a list of all accounts associated with the authenticated user.

GET/accounts/

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/ \
  -H "Authorization: Bearer sk_test_..."

Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by account type

Response

[
  {
    "id": 21221,
    "accountNumber": "TP00-0000-0000-0000-0000",
    "userId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
    "alias": "My Account",
    "balance": 418090,
    "pendingIn": 1422276,
    "pendingOut": 0,
    "state": 1,
    "paymentEntityId": 34,
    "currency": "USDC",
    "type": 1,
    "createdAt": "2025-07-14T19:10:04.936Z",
    "updatedAt": "2025-07-22T13:16:59.737Z",
    "isDefault": false,
    "groupId": null,
    "TropiCards": [],
    "services": [
        {
            "slug": "CRYPTO_TOPUP",
            "enabled": true
        }
    ],
    "paymentMethods": [
        {
            "slug": "TPP",
            "name": "Tropipay",
            "enabled": true
        }
    ]
  }
]

Retrieve Account Balance

Retrieves the balance for a specific account.

GET/accounts/balance/{accountNumber}

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/balance/TP1234567890123456789012 \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "accountNumber": "TP00-0000-0000-0000-0000",
  "balance": 418090,
  "pendingIn": 1422276,
  "pendingOut": 0,
  "currency": "USDC"
}

Response Parameters

Parameter	Type	Description
`accountNumber`	string	The unique account number.
`balance`	integer	The current balance of the account in cents.
`pendingIn`	integer	The amount of incoming funds that are pending confirmation, in cents.
`pendingOut`	integer	The amount of outgoing funds that are pending confirmation, in cents.
`currency`	string	The currency code for the account (e.g., `USDC`).

Retrieve All Account Balances

Retrieves the balance information for all user accounts.

GET/accounts/allBalance

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/allBalance \
  -H "Authorization: Bearer sk_test_..."

Response

[
  {
    "balance": 418090,
    "currency": "USDC"
  },
  {
    "balance": 163202,
    "currency": "EUR"
  }
]

Response Parameters

The response is an array of account objects, each with the following attributes:

Parameter	Type	Description
`balance`	integer	The total balance of the account in cents.
`currency`	string	The currency code for the account (e.g., `USDC`, `EUR`).

Set Default Account

Sets a specific account as the default account for the user.

PUT/accounts/default

curl -X PUT https://sandbox.tropipay.me/api/v3/accounts/default \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": 21221
  }'

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	ID of the account to set as default

Response

{
  "success": true
}

Add Tropicard Account

Links a Tropicard to the user's account.

POST/accounts/

curl -X POST https://sandbox.tropipay.me/api/v3/accounts/ \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tropicardNumber": "1234567890123456",
    "pin": "1234"
  }'

Parameters

Parameter	Type	Required	Description
`tropicardNumber`	string	Yes	16-digit Tropicard number
`pin`	string	Yes	4-digit PIN code

Simulate Currency Conversion

Simulates a currency conversion between two accounts to preview rates and fees.

POST/accounts/{sourceAccountId}/convert/{targetAccountId}/simulate

curl -X POST https://sandbox.tropipay.me/api/v3/accounts/acc_123/convert/acc_124/simulate \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountToPay": 10000
  }'

Parameters

Parameter	Type	Required	Description
`amountToPay`	integer	Yes	Amount to convert in cents

Response

{
  "amountToPay": 10000,
  "amountToGet": 8500,
  "rate": 0.85,
  "fee": 250,
  "sourceCurrency": "USD",
  "targetCurrency": "EUR"
}

Response Parameters

Parameter	Type	Description
`amountToPay`	integer	Amount to be debited in cents
`amountToGet`	integer	Amount to be credited in cents
`rate`	number	Exchange rate applied
`fee`	integer	Conversion fee in cents
`sourceCurrency`	string	Source account currency
`targetCurrency`	string	Target account currency

Execute Currency Conversion

Executes a currency conversion between two accounts.

POST/accounts/{sourceAccountId}/convert/{targetAccountId}

curl -X POST https://sandbox.tropipay.me/api/v3/accounts/acc_123/convert/acc_124 \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amountToPay": 10000
  }'

Parameters

Parameter	Type	Required	Description
`amountToPay`	integer	Yes	Amount to convert in cents

Get Crypto Address for Self-Charge

Retrieves a cryptocurrency address for depositing funds into an account.

GET/accounts/{accountId}/selfcharge/crypto

curl -X GET https://sandbox.tropipay.me/api/v3/accounts/21221/selfcharge/crypto \
  -H "Authorization: Bearer sk_test_..."

Response

{
  "feePercent": 300,
  "feeFixed": 0,
  "accounts": [
    {
      "address": "Bvmv25du1Um2gvMFAd3EQjUCano9a7tPXDp9KnxWRqjc",
      "network": "SOLANA",
      "currency": "USDC"
    }
  ]
}

Response Parameters

Parameter	Type	Description
`feePercent`	integer	The deposit fee as a percentage (e.g., 300 for 3.00%).
`feeFixed`	integer	A fixed deposit fee in cents.
`accounts`	array	An array of available deposit addresses.

Account Object in `accounts` array

Parameter	Type	Description
`address`	string	The cryptocurrency wallet address for the deposit.
`network`	string	The blockchain network (e.g., `SOLANA`).
`currency`	string	The cryptocurrency code (e.g., `USDC`).

Error Handling

The Accounts API uses conventional HTTP response codes to indicate the success or failure of an API request.

Common Error Codes

Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid authentication
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Account doesn't exist
`409`	Conflict - Account already exists or invalid state
`422`	Unprocessable Entity - Invalid account data
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Example Error Response

{
  "error": {
    "type": "invalid_request_error",
    "code": "account_not_found",
    "message": "No such account: acc_invalid",
    "param": "accountId"
  }
}

The Account Object​

Attributes​

List All Accounts​

Parameters​

Response​

Retrieve Account Balance​

Response​

Response Parameters​

Retrieve All Account Balances​

Response​

Response Parameters​

Set Default Account​

Parameters​

Response​

Add Tropicard Account​

Parameters​

Simulate Currency Conversion​

Parameters​

Response​

Response Parameters​

Execute Currency Conversion​

Parameters​

Get Crypto Address for Self-Charge​

Response​

Response Parameters​

Account Object in accounts array​

Error Handling​

Common Error Codes​

Example Error Response​

The Account Object

Attributes

List All Accounts

Parameters

Response

Retrieve Account Balance

Response

Response Parameters

Retrieve All Account Balances

Response

Response Parameters

Set Default Account

Parameters

Response

Add Tropicard Account

Parameters

Simulate Currency Conversion

Parameters

Response

Response Parameters

Execute Currency Conversion

Parameters

Get Crypto Address for Self-Charge

Response

Response Parameters

Account Object in `accounts` array

Error Handling

Common Error Codes

Example Error Response