Wallets

In this guide, we'll explore the versatile features of the wallet module, its objectives, and how you can leverage it for seamless financial transactions. MoneyHash's wallet module provides a secure and convenient way to manage your customer's finances, making it ideal for businesses looking to streamline financial operations.

The wallet module lets your customers store their money with your business. Customers may choose to keep a specific amount in their wallet for future purchases, or you can offer them the option to receive refunds directly into their wallet instead of their original payment method. By associating a customer's unique identifier when creating an Intent, you give them the opportunity to use their stored funds for transactions. As long as the stored amount is not less than the payment total, their wallet can be used as a payment method.

Wallet operations

You can perform different operations with the wallet module. As presented on the Pay with a customer wallet page, you can either show the wallet as a payment method or directly use the stored amount to execute the payment and top up a customer's wallet with a new payment.

Furthermore, this page presents other ways to interact with wallets that don't require a payment and intent creation, such as top up a wallet without payment, debit wallet without payment, refund to wallets, and payout using a wallet.

Top up a wallet without payment

This operation allows you to add funds to a customer's wallet without requiring a payment transaction. It's useful for cases where you want to reward or credit a customer's wallet with a specific amount, such as bonuses, promotions, or loyalty points.

To perform this, you are required to send an API call to the Top-Up customer wallet endpoint:

You need first to replace the customer_id on the URL above with the respective customer identifier. Then, you need to add to the payload of the request the following properties:

• amount: A float value representing the money to be added to the wallet.
• currency: The currency of the amount represented by a string of alphabetic codes from ISO 4217 Currency codes.

{
  "amount": 50,
  "currency": "usd"
}

This will result in the desired amount being added to the wallet.

Debit wallet without payment

This operation involves deducting a specific amount from a customer's wallet without the need for a payment transaction. It can be employed for various scenarios, like charging membership fees or deducting service charges.

To perform this, you are required to send an API call to the debit customer wallet endpoint:

You need first to replace the customer_id on the URL above with the respective customer identifier. Then, you need to add to the payload of the request the following properties:

• amount: A float value representing the money to be debited from the wallet.
• currency: The currency of the amount represented by a string of alphabetic codes from ISO 4217 Currency codes.

{
  "amount": 20,
  "currency": "egp"
}

This will result in the desired amount being withdrawn from the wallet. The maximum value to debit is the total available for each currency inside the wallet.

Refund to wallets

Refunding to wallets provides an alternative to traditional card refunds. Instead of returning the money to the customer's original payment method, you can refund it to their wallet, ensuring the funds remain within your ecosystem.

To perform a refund to a wallet, you need to request the following endpoint:

You need first to replace the refund_to_wallet_transaction on the URL above with the identifier from the transaction that requires refunding. Then, you need to add to the payload of the request the following properties:

• Full refund: set the amount to the total value of the transaction.
• Partial refund: set any amount smaller than the total value of the transaction.

{
  "amount": "50",
  "refund_to_wallet": true,
  "customer": "176837a8-d48d-42f0-8c4f-7c87f2229714"
}

Payout using a wallet

Initiating a payout to wallets provides an alternative way to traditional payout methods. Instead of returning the money to the customer's payout method, you can transfer it to their wallets, ensuring the amount remains within your ecosystem.

To start a payout using a wallet, you need to call the Payout intent creation endpoint:

Here, you will need to add to the payload the following properties:

Now, you have two options to set the amount of the payout:

• amount: The amount to be charged.

{
  "amount": 50,
  "amount_currency": "egp",
  "use_wallet": true,
  "customer": "176837a8-d48d-42f0-8c4f-7c87f2229714",
  "webhook_url": "https://webhook.site/b8954509-f628-4805-a4b4-58a0fb2be958"
}

• max_payout_amount: A maximum amount the customer can choose to transfer. Giving them the choice of amount.

{
  "max_payout_amount": 20,
  "amount_currency": "egp",
  "use_wallet": true,
  "customer": "176837a8-d48d-42f0-8c4f-7c87f2229714",
  "webhook_url": "https://webhook.site/b8954509-f628-4805-a4b4-58a0fb2be958"
}