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 APIPOST /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, auser.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 atop_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, awallet_updated
event is also triggered.
Updated over 1 year ago
See how developers can start a charging session for a user with a wallet.