Wallets Management - Getting Started with Deposits Wallets

A wallet is a financial transaction application that usually runs on mobile device, is used to store payment information, passwords and funds securely. Much similar to how a physical wallet works, a mobile wallet stores personal payment information securely. You can fund a wallet with your card or bank details securely stored and from there make payments to people or vendors with ease. By allowing you to save payment information for later use by adding a debit card or bank details into the app, mobile wallets save you the stress of inputting your bank or card details each time you want to make a payment. A mobile wallet is software, or an online service that enables individuals or businesses to make transactions electronically. It stores users' payment information for different payment modes on various websites. It is an online software or service which enables users to securely store payment information, such as credit card details, bank details, and, in some cases, store value.

Paying into your wallet in the Deposits ecosystem can be done by card or ACH.

  • By Card
  • By Bank (ACH)

By Card

As the name implies, this method charges your card to make a payment or top up to your wallet. This method requires some important card details to be collected in order for the card to be charged.

On the Deposits ecosystem, to top up your wallet using this method, there are two steps/endpoints to go through. This is because the card must first be tokenized to be charged.

The two endpoints are:

  • Tokenize A Card
  • Charge Tokenized Card, Fund Wallet

Tokenize A Card

https://api.deposits.dev/api/v1/user/tokenize-card

This endpoint takes in 7 parameters, 5 which are important as they are the details that allow the card to be charged:

Parameter Description
Card Name Name of card holder
Card Number Sixteen-digit number on the card
Expiry Month A two-digit number representing the card's expiration month
Expiry Year A two-digit number representing the card's expiration year
cvv The three- or four-digit card security code

This endpoint is expected to return a response similar to the one below:

{
    "status": "success",
    "message": "Card tokenized successfully",
    "data": {
        "user_id": 926,
        "auth_code": "S4S0zdEvu60D5439",
        "meta_data": "{\\"status\\":\\"PASS\\",\\"responseCode\\":\\"A0000\\",\\"responseMessage\\":\\"Success\\",\\"token\\":\\"S4S0zdEvu60D5439\\",\\"expirationDate\\":\\"122020\\",\\"cardType\\":\\"V\\",\\"maskedCardNumber\\":\\"5439\\",\\"cardTransactionIdentifier\\":\\"000000000342969\\",\\"taskID\\":\\"18420249\\",\\"transactionID\\":\\"16682145\\",\\"transactionTimestamp\\":\\"2022-06-20T07:53:07\\",\\"expiration\\":\\"1220\\",\\"cvv\\":\\"999\\",\\"full_name\\":\\"Oyin kansola\\",\\"issuer\\":[{\\"Card_Number\\":\\"401200\\",\\"Brand\\":\\"VISA\\",\\"Card_Type\\":\\"CREDIT\\",\\"Bank_Name\\":\\"EXTRAS TEST - VISA\\",\\"Country\\":\\"United States\\"}]}",
        "primary_card": "false",
        "status": "active",
        "updated_at": "2022-06-20T14:53:08.000000Z",
        "created_at": "2022-06-20T14:53:08.000000Z",
        "id": 727,
        "meta_data_json": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "token": "S4S0zdEvu60D5439",
            "expirationDate": "122020",
            "cardType": "V",
            "maskedCardNumber": "5439",
            "cardTransactionIdentifier": "000000000342969",
            "taskID": "18420249",
            "transactionID": "16682145",
            "transactionTimestamp": "2022-06-20T07:53:07",
            "expiration": "1220",
            "cvv": "999",
            "full_name": "Oyin kansola",
            "issuer": [
                {
                    "Card_Number": "401200",
                    "Brand": "VISA",
                    "Card_Type": "CREDIT",
                    "Bank_Name": "EXTRAS TEST - VISA",
                    "Country": "United States"
                }
            ]
        }
    }
}

After successfully tokenizing a card, an id is returned which is what the card will now be known as or referred to within the Deposits ecosystem. In this instance, the id for this card is now 727.

Charge Tokenized Card, Fund Wallet

https://api.deposits.dev/api/v1/user/charge-tokenized-card-fund-wallet.

This endpoint is the second and final step in funding your Deposits wallet, as it charges an already tokenized card, which saves you the stress of inputting your card details each time you want to fund the wallet.

When a card is charged successfully, a response similar to this can be expected.

{
    "status": "success",
    "message": "Card Charged Successfully",
    "data": {
        "client_id": 4,
        "user_id": "0",
        "email": "titan.offline@gmail.com",
        "recieved_by": "oyinawosan@gmail.com",
        "transaction_id": "16686839",
        "reference": "70",
        "description": "topup",
        "amount": "1",
        "balance": 0,
        "ledger_period": "5",
        "extra_info": "{\\"customer\\":\\"[\\\\\\"customer_name\\\\\\":\\\\\\"Jane\\\\\\"]\\"}",
        "currency": "usd",
        "category": "topup",
        "payment_method": "ach",
        "payment_direction": "credit",
        "status": "completed",
        "created_at": "2022-06-20T17:32:42.000000Z",
        "settlement_date": "2022-06-20T17:32:42.347264Z",
        "updated_at": "2022-06-20T17:32:42.000000Z",
        "id": 3541
    }
}

By Bank (ACH)

ACH transfers move funds between multiple accounts accessible by the Automated Clearing House (ACH). Banks mostly use ACH in the United States of America, and Payments made via ACH usually have a settlement period that differs based on the bank involved.

There are two types of ACH transfers:

  • ACH Pull
  • ACH Push

In this scenario, we are dealing with ACH Pull.

ACH Pull

ACH Pull occurs when the receiving account initiates a payment. This means that the receiving account charges the sending account, and funds are pulled from the source account to the receiving account.

Any ACH transfer initiated by the receiving account is regarded as an ACH Pull.

To learn more about ACH transfers and how they work, please read ACH Fundamentals

To fund your wallet via bank(ACH Pull), there are three endpoints/steps you have to go through:

  • Add Bank
  • Verify Bank
  • Fund Wallet Via Bank

Add Bank

This is the first endpoint to go through as it takes in your bank account details, and returns an ID which the account will be known as or referred to within the Deposits ecosystem. Of the 7 parameters this endpoint takes in, 5 are strictly the bank account details.

Parameter Description
routing_number The user's bank account routing (transit) number
account_number Bank account number as provided by user
account_name Name of account holder as provided by user
bank_name The bank name as provided by the user
account_type The type of bank account. This will either be a checking or savings account.

When the needed information is put in, the endpoint returns a successful response similar to this:

{
    "status": "success",
    "message": "Bank Account saved",
    "data": {
        "user_id": 926,
        "email": "oyinawosan@gmail.com",
        "type": "fiat",
        "bank": "GNS Bank",
        "account_name": "Jina niko",
        "account_type": "CHECKING",
        "account_number": "353014201995580",
        "routing_number": "101112842",
        "status": "pending",
        "updated_at": "2022-06-21T06:25:18.000000Z",
        "created_at": "2022-06-21T06:25:18.000000Z",
        "id": 1010
    }
}

After this is successfully done, you can move on to the next step.

Verify Bank

This endpoint verifies the newly added external account using 2 micro-deposits and the information provided by the user. This aims to ensure the account indeed belongs to you and that the information provided is accurate.

When a bank account verification is successful, a response similar to this will be returned. Now the account can be charged or credited without needing to enter the account details afresh.

{
    "status": "success",
    "message": "Bank account verified successfully",
    "data": {
        "id": 845,
        "user_id": "963",
        "email": "jeremiah@deposits.com",
        "type": "fiat",
        "account_name": "Jina nikon",
        "account_number": "353014201995580",
        "currency": null,
        "iban": null,
        "swift": null,
        "zip": null,
        "address": null,
        "city": null,
        "state": null,
        "country": null,
        "tax_id": "",
        "routing_number": "101112842",
        "coin_address": "",
        "bank": "GNS Bank",
        "sec": null,
        "account_type": "CHECKING",
        "privacy_token": "",
        "status": "completed",
        "created_at": "2022-01-18T08:46:05.000000Z",
        "updated_at": "2022-01-18T09:31:18.000000Z"
    }
}

Fund Wallet Via Bank

This endpoint is the final one through which your wallet is topped up. It is this endpoint that pulls the specified funds from the bank account into the wallet.

When this is done, a response similar to this is returned, which contains Status to let you know if the payment is pending or has already been processed.

{
    "status": "success",
    "message": "Transaction Successful",
    "data": {
        "id": null,
        "email": "jeremiah@deposits.com",
        "type": "credit",
        "transaction_id": "14002551",
        "value": "1.00",
        "balance": "8.00",
        "description": "topup",
        "status": "pending",
        "currency": null,
        "reference": "922",
        "created_at": "2022-01-27T13:26:19.000000Z"
    }
}

Withdrawals

Withdrawing from your Deposits wallet is stress-free and powered by the /withdraw endpoint. This endpoint allows you to withdraw desired value from your wallet to a bank account you have previously added.

This endpoint takes in 4 parameters, 2 of which are important or integral to the withdrawal being successful.

Parameter Description
amount Value in specified currency's smallest unit. e.g. $10 would be represented as 1000.
account_id This is the ID generated for a bank account added to the Deposits ecosystem.

When a withdrawal is successful, a response similar to this is returned.

{
    "status": "success",
    "message": "Withdrawal ",
    "data": {
        "user_id": 3,
        "email": "calmpress@gmail.com",
        "type": "withdrawal",
        "currency": "usd",
        "amount": "1",
        "description": "wallet withdrawal",
        "transaction_id": "0efc2",
        "account_name": "Plaid Checking",
        "account_number": "eyJpdiI6Imt4dloraTFqUmRjcWhoTVVXTW43VHc9PSIsInZhbHVlIjoiOUNuODdyTDk2ck5SUlVPZnRSSEYvdGZEeC9SeU8xWjBiclFQRy95eFBKST0iLCJtYWMiOiIxZjM0MGI0NTczNzhmOGE3YzMzMzMwZWVkNDdiZTk4MDRiYjlhMzE1ZTIzNDQwYzVmMTlmYjM3NGU3OWM1ZGNlIn0=",
        "bank": "CITIZENS BANK NA",
        "account_id": 6,
        "status": "pending",
        "updated_at": "2021-05-04T21:20:41.000000Z",
        "created_at": "2021-05-04T21:20:41.000000Z",
        "id": 523
    }
}

Wallet funding and management with Deposits is straightforward and designed to get you up and running in little to no time. You can fund your wallet, withdraw from your wallet and even send funds to others with ease.

Deposits Team

Deposits Team