Pay with a Customer Wallet
Overview
On this page, you'll find a guide on how to allow your customers to use their wallet amount to execute payments, how to top up their wallet, and how to directly use their balance as the payment method - and for every option presented, you need to start with intent creation using the Create Intent endpoint:
Showing the Customer's Wallet
Your customer may use the amount they have in their wallet only when it is larger than the total payment amount. To be able to present your customers with their wallet, you need to add the respective customer's unique identifier to the payload.
Payload Properties
| Property | Type | Description |
|---|---|---|
amount | Number | The amount to charge in the payment process. |
amount_currency | String | The currency of the amount, represented by a string of alphabetic codes from ISO 4217 Currency codes. |
operation | String | The type of the current intent. Can be one of purchase, authorize, or capture. |
webhook_url | String | A URL that the MoneyHash server will send a POST request to when needed. |
customer | String | The unique identifier of the customer. |
Example: Intent Payload with Customer
{
"amount": 50,
"amount_currency": "usd",
"customer": "c6c42108-293f-44c9-92fc-5d6ef2003b33",
"operation": "purchase",
"webhook_url": "https://webhook.site/b8954509-f628-4805-a4b4-58a0fb2be958"
}For the example above, if the customer has a wallet amount larger than 50 USD, the wallet option will be presented as a payment method option.
Include Wallet Balance While Paying with Any Method
If the customer has a wallet amount that is less than the total intent amount, they can use the balance to pay partially with other methods.
This is supported with our SDKs and as part of our embed experience.
Using a Wallet Directly
To directly choose the customer's wallet to execute the payment during the creation of the intent, you need to add the following fields to the payload.
Payload Properties
| Property | Type | Description |
|---|---|---|
amount | Number | The amount to charge in the payment process. |
amount_currency | String | The currency of the amount, represented by a string of alphabetic codes from ISO 4217 Currency codes. |
operation | String | The type of the current intent. Can be one of purchase, authorize, or capture. |
webhook_url | String | A URL that the MoneyHash server will send a POST request to when needed. |
customer | String | The unique identifier of the customer. |
use_wallet | Boolean | Adding this flag as true will execute the payment with the customer's wallet amount without presenting the payment method selection to the customer. |
Example: Intent Payload with use_wallet Flag
use_wallet Flag{
"amount": 50,
"amount_currency": "usd",
"use_wallet": true,
"customer": "11dedf5a-92ea-4cca-8a48-a711a49f26dd",
"webhook_url": "https://webhook.site/b8954509-f628-4805-a4b4-58a0fb2be958"
}Top Up a Customer's Wallet
MoneyHash allows your customer to top up the amount available in their wallet. To do this, you need to create an intent and add the following fields.
Payload Properties
| Property | Type | Description |
|---|---|---|
amount | Number | The amount to charge in the payment process. |
amount_currency | String | The currency of the amount, represented by a string of alphabetic codes from ISO 4217 Currency codes. |
operation | String | The type of the current intent. Can be one of purchase, authorize, or capture. |
webhook_url | String | A URL that the MoneyHash server will send a POST request to when needed. |
customer | String | The unique identifier of the customer. |
top_up_wallet | Boolean | A flag that indicates the intention to top up the wallet amount with the respective intent. |
Example: Intent Payload with top_up_wallet Flag
top_up_wallet Flag{
"amount": 50,
"amount_currency": "usd",
"top_up_wallet": true,
"customer": "11dedf5a-92ea-4cca-8a48-a711a49f26dd",
"webhook_url": "https://webhook.site/b8954509-f628-4805-a4b4-58a0fb2be958"
}The intent created here allows your customer to execute a payment as any other - not to buy something, but to store the amount paid in their wallet in MoneyHash's system.
Summary
| Use Case | Key Flag/Field | Behavior |
|---|---|---|
| Show wallet as an option | customer | Wallet appears only if balance > intent amount. |
| Partial payment with wallet | (SDK/embed only) | Wallet balance used partially, remainder paid via another method. |
| Pay directly with wallet | use_wallet: true | Skips payment method selection; charges the wallet directly. |
| Top up wallet | top_up_wallet: true | Payment amount is stored in the customer's wallet instead of purchasing something. |
Updated about 2 months ago