Wallet Credit via Top Up

Introduction

Each eDRV user has a wallet associated with them. In the beginning, the balance of this wallet will be set to 0.
There are multiple ways to top-up a user's wallet:

Manual Top Up via payment URL (with a Credit Card, Google/Apple Pay)
Manual Top Up via a Stored Credit Card
Automatic Top Up (Coming Soon)

To top-up a wallet, the developer needs to define the amount of money they would like to capture from the user's credit card and the amount they would like to top up (wallet_amount) to the wallet once the payment is successful. This allows developers to offer discounted wallet top-ups.

// Flat balance update
{
  "type" : "manual",
  "wallet": "63d211c12abcb85f9c634b6e",
  "amount" : 2000,
  "wallet_amount": 2000,
}

// 10% discount: top up $22.00 via a $20.00 payment capture
{
  "type" : "manual",
  "wallet": "63d211c12abcb85f9c634b6e",
  "amount" : 2000,
  "wallet_amount": 2200,
}

// 1000 FLAT discount
{
  "type" : "manual",
  "wallet": "63d211c12abcb85f9c634b6e",
  "amount" : 2000,
  "wallet_amount": 3000,
}

📘
By default, newly created users will have a wallet associated with them but for the existing users, please look at the section on [how to create a wallet for existing users] (https://docs.edrv.io/docs/introduction-to-user-wallets#creating-a-wallet-for-existing-users).

1. Manual Top Up via URL (New/Unknown Credit Card)

Developers can top-up a wallet by accepting payments from a driver as follows:

Create a top-up object with type = manual and specify the wallet id by calling API POST /top_up
Redirect the driver to open the link defined in topUp.url in a browser where the specified user can enter their credit card and complete the payment.

{
  "type": "manual",
  "wallet": "63d211c12abcb85f9c634b6e",
  "amount": 2000,
  "wallet_amount": 2500
}

When the driver successfully enters their card details and money is captured, eDRV triggers a top_up.completed webhook event and the user's wallet balance is updated.
Note: The user will also have the option to save their credit card details for future transactions. In this case, a user.updated webhook event is also triggered.

{
  "_id": "60e7116e15f9305d44e9d4d5",
  "user": "60e7116e15f9305d44e9d4d5",
 	"wallet": "63d211c12abcb85f9c634b6e",
  "url": "https://wallet.edrv.io/60e7116e15f9305d44e9d4d5",
  "status": "created",
  "type": "manual",
  "amount": 2000,
  "wallet_amount": 2500,
  "currency": "usd",
  "test_mode": true,
  "createdAt": "2021-07-21T12:50:36.660Z",
  "updatedAt": "2021-07-21T12:50:36.660Z",
  "expiredAt": "2021-07-21T12:55:36.660Z"
}

📘
If the payment does not succeed by topUp.expiredAt, the top_up object will expire, and a top_up.expired webhook event will be triggered.

2. Manual Top Up via Stored Credit Card

When the driver explicitly saves a credit card for future payment purposes (via the topUp.url UI) developers have the option of using this payment method for a top-up.
This can be done as follows:
a. Create a top-up object with type = manual_with_payment_method and specify the wallet id and payment_method by calling the POST /top_up API.
b. If the correct payment_method id is provided, then the eDRV will attempt to capture payment from the driver's saved credit card of amount and the user's wallet will be updated by wallet_amount.

//A $20.00 card payment capture attempt to top-up user's wallet by $25.00
{
  "type": "manual",
  "wallet": "63d211c12abcb85f9c634b6e",
  "payment_method": "pm_1MUQQWRJPNC5bQnzczAzUJps",
  "amount": 2000,
  "wallet_amount": 2500
}

The API will return the following response if the user has a valid payment_method

{
  "_id": "60e7116e15f9305d44e9d4d5",
  "user": "60e7116e15f9305d44e9d4d5",
 	"wallet": "63d211c12abcb85f9c634b6e",
  "url": "https://wallet.edrv.io/60e7116e15f9305d44e9d4d5",
  "status": "created",
  "type": "manual_with_payment_method",
  "amount": 2000,
  "wallet_amount": 2500,
  "currency": "usd",
  "test_mode": true,
  "createdAt": "2021-07-21T12:50:36.660Z",
  "updatedAt": "2021-07-21T12:50:36.660Z",
  "expiredAt": "2021-07-21T12:55:36.660Z"
}

Webhook Events

When creating a top-up, top_up.created event will be triggered.
If the top-up is not successful within 5 minutes, top_up.expired event will be triggered.
If the top-up is successful within 5 minutes, top_up.completed event will be triggered. Additionally, a wallet_updated event is also triggered.