Wallet Operations

The four operations below require no payment or intent - each is a direct API call for managing balance outside the checkout flow.

Top up a wallet without payment

This operation allows to add funds to a customer's wallet directly - for bonuses, promotions, or loyalty credits etc.

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

Replace customer_id with the customer's identifier, then send:

• 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

Deduct funds from a customer's wallet independent of any payment transaction — for example, membership fees, service charges, or manual balance corrections.

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

Replace customer_id with the customer's identifier, then send:

• 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"
}

The maximum debitable value is the available balance for that currency in the wallet.

Refund to wallets

Route a refund into the customer's wallet rather than back through the original payment method. Funds settle instantly and remain within your ecosystem, available for the customer's next transaction.

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

Replace refund_to_wallet_transaction with the transaction to refund, then send:

• amount: A string representing the amount to be refunded.
• refund_to_wallet: A boolean flag indicating to MoneyHash to refund the amount to a wallet.
• customer: A string representing the unique identifier of the customer who owns the wallet to receive the amount.

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

Set amount to the transaction's total value for a Full refund, or to any smaller value for a Partial refund.

Payout using a wallet

Payouts to wallets offer an alternative to traditional payout methods. Instead of returning funds to the customer's external payout method, you can transfer them into the customer's wallet, keeping the balance 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:

• amount_currency: The currency of the amount represented by a string of alphabetic codes from ISO 4217 Currency codes.
• use_wallet: A flag indicating MoneyHash to use the wallet to execute the payout.
• customer: The customer's unique identifier.
• webhook_url: A URL that the MoneyHash server will send a POST request to you when needed.

Set the payout amount using either:

• 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"
}

• OR 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"
}