🏦 Escrow Account

Overview

An escrow account is a secure, intermediary holding account managed by EdfaPay that temporarily holds a merchant's transaction funds before releasing them as a payout.

Rather than instantly transferring funds to the merchant's bank account after each transaction, EdfaPay holds the collected funds in an escrow account and releases them based on the merchant's configured payout schedule or upon manual payout request.

This mechanism ensures financial security, supports dispute resolution, and gives both merchants and EdfaPay full visibility and control over fund flows.

Why EdfaPay Uses Escrow

How It Works

General Flow

Customer Payment
       │
       ▼
  EdfaPay Processes Transaction
       │
       ▼
  Funds Held in Escrow Account
       │
       ▼
  Review Period (Risk & Dispute Window)
       │
       ▼
  Funds Released → Merchant Payout

Step-by-Step Breakdown

1. Customer completes payment — The transaction is authorized and captured via EdfaPay's payment gateway.
2. Funds enter escrow — The transaction amount (minus processing fees) is held in the merchant's escrow balance within EdfaPay.
3. Review window — EdfaPay applies its risk checks. If a chargeback or dispute is raised during this period, funds may be withheld to cover the reversal.
4. Payout trigger — Based on the merchant's payout schedule (daily, weekly, etc.) or a manual payout request, EdfaPay releases the available escrow balance to the merchant's bank account.

Settlement & Payout Timelines

Payout timelines depend on the merchant's configuration and account type:

📘

Note:

Settlement timelines may vary based on the merchant's bank, country of operation, and EdfaPay's internal risk policies.

Chargeback & Dispute Handling

When a chargeback or dispute is raised against a transaction, the following occurs:

1. Funds are flagged — The disputed amount is locked within the escrow account and excluded from the available payout balance.
2. Merchant is notified — EdfaPay sends a notification to the merchant with dispute details.
3. Evidence window — The merchant may submit supporting evidence through the EdfaPay Dashboard.
4. Resolution — If the dispute is resolved in the merchant's favor, the funds are returned to the escrow balance and become available for payout. If resolved against the merchant, the funds are used to cover the chargeback.

⚠️

Important:

Maintaining a healthy escrow balance reduces the risk of negative balance situations during chargeback cycles.

Technical Integration — move_to_payout Parameter

EdfaPay exposes the escrow-to-payout behavior at the API level through the move_to_payout parameter. This parameter is available in both:

• S2S (Server-to-Server) Card Payment API
• Payment Checkout / Initiate Payment Link API

What is move_to_payout?

The move_to_payout parameter controls whether a successfully captured transaction should be immediately moved to the payout queue (i.e., marked as ready for disbursement) or held in escrow for a later payout cycle.

S2S Card Payment — Request Payload

The move_to_payout parameter is passed in the body of the S2S payment request.

Endpoint:

POST /api/v1/payment/card/s2s

Request Payload Example:

{
  "merchant_key": "your-merchant-key",
  "order_id": "ORDER-20240501-001",
  "order_amount": "150.00",
  "order_currency": "SAR",
  "order_description": "Product purchase",
  "card_number": "4111111111111111",
  "card_exp_month": "12",
  "card_exp_year": "2026",
  "card_cvv2": "123",
  "payer_first_name": "John",
  "payer_last_name": "Doe",
  "payer_email": "[email protected]",
  "payer_phone": "966500000000",
  "payer_ip": "192.168.1.1",
  "term_url_3ds": "https://yourwebsite.com/3ds-return",
  "move_to_payout": true,
  "hash": "generated-hash-value"
}

Key Parameter:

Payment Checkout / Initiate Payment Link — Request Payload

The same move_to_payout parameter is available when generating a hosted payment link.

Endpoint:

POST /api/v1/payment/initiate

Request Payload Example:

{
  "merchant_key": "your-merchant-key",
  "order_id": "ORDER-20240501-002",
  "order_amount": "250.00",
  "order_currency": "SAR",
  "order_description": "Subscription payment",
  "payer_first_name": "Jane",
  "payer_last_name": "Smith",
  "payer_email": "[email protected]",
  "payer_phone": "966511111111",
  "success_url": "https://yourwebsite.com/success",
  "failure_url": "https://yourwebsite.com/failure",
  "cancel_url": "https://yourwebsite.com/cancel",
  "move_to_payout": false,
  "hash": "generated-hash-value"
}

Key Parameter:

move_to_payout Behavior Summary

Transaction Successful
        │
        ▼
move_to_payout = true          move_to_payout = false (default)
        │                                   │
        ▼                                   ▼
Funds queued for               Funds held in Escrow Account
next payout cycle                           │
        │                                   ▼
        ▼                      Released on scheduled payout
Merchant receives funds           or manual payout request

Merchant Dashboard — Escrow Balance

Merchants can monitor their escrow balance directly from the EdfaPay Dashboard:

• Escrow Balance — Total funds currently held in escrow
• Available for Payout — Funds cleared and ready for disbursement
• On Hold — Funds locked due to open disputes or chargebacks
• Payout History — Log of all past payout transactions

Frequently Asked Questions

💳 Payout Requests & Scheduling

Can I request a manual payout at any time?

Yes. Merchants can initiate a manual payout at any time directly from the EdfaPay Dashboard or programmatically via the Payout API. Manual payout requests are subject to the following conditions:

• A minimum payout threshold must be met
• Sufficient available escrow balance must exist (excluding any on-hold funds)
• The merchant account must be in good standing with no unresolved compliance flags

Does the move_to_payout parameter override my scheduled payout settings?

No. Setting move_to_payout to true does not modify or disable your configured payout schedule. It only affects the specific transaction it is applied to — immediately flagging those funds as ready for disbursement and including them in the next available payout run. All other transactions continue to follow the merchant's standard payout schedule as configured in the EdfaPay Dashboard.

Is move_to_payout supported across all payment methods?

Currently, the move_to_payout parameter is supported for card-based payments processed through:

• S2S (Server-to-Server) Card Payment API
• Hosted Checkout / Initiate Payment Link API

Support for additional payment methods may be extended in future releases. For the latest availability, please contact EdfaPay Technical Support.

⚠️ Balance, Risk & Disputes

What happens if my escrow balance goes negative?

A negative escrow balance can occur when a chargeback or reversal exceeds the merchant's available funds — for example, if a dispute is raised on a transaction that has already been paid out. In such cases:

1. EdfaPay will immediately notify the merchant via email and Dashboard alert
2. The negative balance will be offset against future incoming transactions
3. If the balance cannot be recovered through incoming payments, EdfaPay may require the merchant to submit a top-up to restore a positive balance
4. Continued negative balance may result in a temporary hold on payouts until the balance is resolved

⚠️

Best Practice:

Maintain a healthy escrow buffer, especially during high-volume periods or promotional campaigns, to absorb potential chargebacks without disrupting your payout flow.