Payout Details

Introduction

After creating your payout account, you are now ready to send payouts.

You can send payouts to either:

• Bank
• Wallet

info

The payout account type should match the beneficiary account type. In other words, to send a payout to a bank account, the type of the source payout account should be a bank as well.

Create a Payout

The following example is for sending a payout from ANB bank account to ANB beneficiary.

Verb, Path, and Headers

POST /v1/payouts
Authorization: Basic {BASE64 encoded secret key}

{
  "source_id": "ceb461ea-3f35-4027-b20a-beb89f5ee574",
  "amount": 100,
  "purpose": "personal",
  "destination": {
    "type": "bank",
    "iban": "SA5330400108057386290014",
    "name": "Faisal Alghurayri",
    "mobile": "0555555555",
    "country": "SA",
    "city": "Riyadh"
  }
}

Response

{
  "id": "ac2cc6d8-1ffa-48e9-a6eb-d4e98dbdb8ec",
  "source_id": "ceb461ea-3f35-4027-b20a-beb89f5ee574",
  "sequence_number": "6244377266243449",
  "channel": "internal",
  "status": "initiated",
  "amount": 100,
  "currency": "SAR",
  "purpose": "personal",
  "comment": null,
  "destination": {
    "type": "bank",
    "mobile": "0555555555",
    "iban": "SA5330400108057386290014",
    "name": "Faisal Alghurayri",
    "country": "SA",
    "city": "Riyadh"
  },
  "message": "Payment was received, please check back after 5 minutes",
  "failure_reason": null,
  "created_at": "2025-04-08T06:52:10.868Z",
  "updated_at": "2025-04-08T06:52:10.895Z",
  "metadata": null
}

Payout Channel

The payout channel is automatically determined by Moyasar.

Channel	Description	Criteria	Payout Delivery Timeline
internal	The payout is sent internally	Source and destination are in the same bank or wallet	Instant
ips	Instant local transfer between different banks	Amount is less than or equal 20,000 SAR given both source and destination support IPS	Semi-Instant
sarie	Local transfer through SARIE between banks	Amount is more than 20,000 SAR	Semi-Instant during workdays between 9:00 AM and 3:00 PM

Payout Status

Status	Description
queued	The initial status of the payout
initiated	Moyasar has sent the payout request to the bank or wallet
paid	The payout is successfully done
failed	The payout is failed
canceled	You have canceled the payout. Only queued payouts can get canceled
returned	The payout is reversed

Payout Flows

Below diagrams show normal scenarios. Eventually, all payouts will be processed to either paid or failed.

If there is a transient error like a timeout between Moyasar and the bank or wallet, the flow will become asynchronous. More on that below.

Wallet or Bank (Internal Channel)

This flow is synchronous unless a transient error occurs. Almost all banks and wallets instantly process the payout if it is internal.

Bank (IPS Channel)

This flow is asynchronous.

Bank (SARIE Channel)

This flow is asynchronous.

If the payout is done within the SARIE working hours, the flow will be as same as IPS flow above.

However, if it is outside the working hours, it will be queued for later processing.

Transient Error

If there is a transient error like a timeout between Moyasar and the bank or wallet, the flow will become asynchronous.

Moyasar is going to retry sending the request after a few minutes for multiple times. When the retries are exhausted, the payout will be marked as failed accordingly. Therefore, you need to check the status every 5-10 minutes.

An alternative would be to set up webhooks to receive a notification once the payout status changes.

Thanks to relying on a sequence_number when trying to create the payout, duplicate payouts should never happen.

Payout Purposes

Purpose
bills_or_rent
expenses_services
purchase_assets
saving_investment
government_dues
money_exchange
credit_card_loan
personal
investment_transaction
family_assistance
donation
payroll_benefits
online_purchase
hajj_and_umra
dividend_payment
government_payment
investment_house
payment_to_merchant
own_account_transfer