The wallet APIs allows users to manage funds in their wallet. Using the API, funds can be added to the wallet, converted to other currencies, and withdrawn.

Currently, following currencies are supported: USD, MXN, CAD, SAR

Prerequisites

Before calling the wallet API, a corresponding user account should exist.

Authorization

OAuth2 token is required in the Authorization header.

Sandbox Endpoints

Veem's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios.

Use the base URL to access the endpoints in sandbox environment.

POST https://sandbox-api.veem.com/veem/

Add Funds

The addFunds endpoint is used to add funds to the user's wallet.

POST /v1.2/cpayments/wallet/addFunds

{  
    "amount": {  
        "number": 100,  
        "currency": "USD"  
    },  
    "fundingMethod": {  
        "id": 3518,  
        "type": "Bank"  
    }
}

{
    "id": 12345,
    "payee": {
        "email": "[email protected]",
        "phone": "tel:+33-1-23-45-67-89",
        "countryCode": "FR"
    },
    "status": "Sent",
    "claimLink": "https://api.veem.com/api/c/ABCDEF",
    "requestId": "e5dbaf73-38c2-4a92-bf3d-87bc65d77a9i",
    "payeeAmount": {
        "number": 15224,
        "currency": "USD"
    },
    "timeCreated": "2024-08-22T16:54:54.367-07:00",
    "timeUpdated": "2024-08-22T16:54:56.024-07:00",
    "fastTransfer": false,
    "debitCreditTxn": {
        "debitTxn": null,
        "creditTxn": null
    }
}

Wallet Withdraw

The withdraw endpoint allows to withdraw money from the wallet. The withdrawal will transfer the funds to the account's default funding method, whether it’s a bank account or card.

POST /v1.2/cpayments/wallet/withdraw

{
    "amount": {
        "number": 50,
        "currency": "USD"
    }
}

{
    "id": 12345,
    "payee": {
        "email": "[email protected]",
        "phone": "tel:+33-1-23-45-67-89",
        "countryCode": "FR"
    },
    "status": "Sent",
    "claimLink": "https://api.veem.com/api/c/ABCDEF",
    "requestId": "e5dbaf73-38c2-4a92-bf3d-87bc65d77a9i",
    "payeeAmount": {
        "number": 15224,
        "currency": "USD"
    },
    "timeCreated": "2024-08-22T16:54:54.367-07:00",
    "timeUpdated": "2024-08-22T16:54:56.024-07:00",
    "fastTransfer": false,
    "debitCreditTxn": {
        "debitTxn": null,
        "creditTxn": null
    }
}

Create a wallet in a new currency

By default, all users have USD wallet created for them in advance.

POST /v1.2/cpayments/wallet/wallets

{
    "currencyCode": "MXN"
}

{
    "id": 2164,
    "accountId": null,
    "availableBalance": {
        "number": 0,
        "currency": "MXN"
    },
    "pendingBalance": {
        "number": 0,
        "currency": "MXN"
    },
    "totalBalance": {
        "number": 0,
        "currency": "MXN"
    },
    "status": "Active"
}

The currencyCode should be in ISO 4217 alpha-3 code (eg. GBP, CAD, JPY)

Move funds between Wallets

The convert endpoint allows to transfer funds between different wallets under their account.

Note: When moving funds between wallets, both the source and target wallet should exist.

POST /v1.2/cpayments/wallet/convert

Request Payloads

The API supports two types fund movement between wallet balances - sending exact amount and receiving exact amount.

Sending Exact Amount

Used when the user specifies the exact amount to send from the source wallet.

{
    "sourceWallet": {
        "currency": "USD",
        "number": 50
    },
    "destinationWallet": {
        "currency": "MXN"
    }
}

{
    "id": 462531,
    "status": "Sent",
    "exchangeRate": {
        "fromAmount": 50.00,
        "fromCurrency": "USD",
        "toAmount": 50.00,
        "toCurrency": "USD"
    },
    "payeeAmount": {
        "number": 911.59,
        "currency": "MXN"
    },
    "payerFundingMethodType": "Wallet",
    "receiverFundingMethodType": "Wallet"
  ....
}

Receiving Exact Amount

Used when the user specifies the exact amount to receive in the destination wallet.

{
    "sourceWallet": {
        "currency": "USD"
    },
    "destinationWallet": {
        "currency": "MXN",
        "number": 1030
    }
}

{
    "id": 462531,
    "status": "Sent",
    "exchangeRate": {
        "fromAmount": 50.00,
        "fromCurrency": "USD",
        "toAmount": 50.00,
        "toCurrency": "USD"
    },
    "payeeAmount": {
        "number": 911.59,
        "currency": "MXN"
    },
    "payerFundingMethodType": "Wallet",
    "receiverFundingMethodType": "Wallet"
  ....
}

Validation Rules

The number field cannot be sent in both sourceWallet and destinationWallet at the same time.
The request should be structured to either specify:
- The amount to send sourceWallet.number
- The amount to receive destinationWallet.number
At least one wallet must be USD either source or destination

Error Responses

HTTP Status	Description
400 Bad Request	Converting number must be provided either in `sourceWallet` OR `destinationWallet`, but not both or neither.
400 Bad Request	Missing Wallet Source currency code
400 Bad Request	The amount $500000 exceeds the available balance
400 Bad Request	Choose USD as one currency to proceed with conversion