> ## Documentation Index
> Fetch the complete documentation index at: https://developers.ebioro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Escrow Payments (Coming Soon)
> Hold funds in a smart contract until conditions are met before releasing to the merchant or payee
Escrow payments are currently in development and not yet available in production. Contact us at [support@ebioro.com](mailto:support@ebioro.com) if you'd like early access.
## Overview
Escrow payments allow funds to be **locked in a Soroban smart contract** on the Stellar network until predefined conditions are met. Instead of settling directly to the merchant's account, funds are held in escrow and released based on a configurable **release policy**.
This is useful for scenarios where trust between parties needs to be enforced programmatically — marketplaces, service delivery, remittances, and point-of-sale integrations.
Escrow is configured at the **merchant level**. When a merchant's `settlement_mode` is set to `escrow`, all payments for that merchant flow through the escrow contract automatically.
## How It Works
## Roles
Every escrow payment involves up to four roles. Understanding who is who is essential to choosing the right configuration.
### Payer (Customer / Sender)
The person or entity that **sends the money**. This is the customer buying a product, the rider paying for a trip, or the sender in a remittance. The payer's funds are locked in the escrow contract until the release conditions are met.
**Examples:** a customer on an e-commerce site, a rider in a ride-hailing app, a sender transferring money abroad.
### Payee (Recipient / Service Provider)
The person or entity that **receives the money** once funds are released. This is the party that delivers the product, provides the service, or pays out the remittance locally.
**Examples:** a driver (Uber), a host (Airbnb), a freelancer (Upwork), a licensed remittance operator, a merchant at a physical store.
### Platform Owner
The entity that **owns the escrow instance** and may have the authority to release or refund payments depending on the release policy. The platform owner is set when the escrow contract is deployed.
* In a **marketplace**, the platform owner is the marketplace company (e.g., the ride-hailing company or the freelance platform).
* In a **remittance flow**, the platform owner is typically Ebioro itself.
* In a **POS integration**, the platform owner could be the IT provider or Ebioro.
### Ebioro Operator
Ebioro's system address, which acts as the **payment infrastructure layer**. In certain release policies (`operator_or_payee`, `operator_after_timeout`), the Ebioro operator has the authority to release funds from the escrow contract.
### Quick Reference
| Role | Who is it? | Real-world examples |
| ------------------- | ------------------------------ | ------------------------------------------------------- |
| **Payer** | The one paying | Customer, rider, sender |
| **Payee** | The one receiving payment | Driver, host, freelancer, merchant, remittance operator |
| **Platform Owner** | The one controlling the escrow | Marketplace company, Ebioro, IT provider |
| **Ebioro Operator** | Payment infrastructure | Ebioro (always) |
The **payee** and the **platform owner** can be the same entity. For example, in a remittance flow the licensed operator is both the payee (receives the funds) and the merchant. In a marketplace, the driver is the payee but the marketplace company is the platform owner.
***
## Escrow vs Direct Settlement
| Feature | Direct Settlement | Escrow Settlement |
| ----------------- | --------------------------- | ----------------------------------- |
| Funds destination | Merchant wallet immediately | Locked in smart contract |
| Release control | Automatic on payment | Based on release policy |
| Refunds | Direct Stellar payment | Contract-based refund |
| Ebioro fee | At settlement | Before escrow |
| Platform fee | At settlement | At release |
| Best for | Simple payments | Marketplaces, services, remittances |
## Release Policies
Each escrow merchant is configured with a release policy that determines **who can release funds** and **when**. See [Roles](#roles) above for who each actor is.
| Policy | Who Can Release | When | Best For |
| ------------------------ | ------------------------------------ | --------------------- | --------------------------------- |
| `platform_only` | Only the **platform owner** | Anytime before expiry | Marketplaces, remittances |
| `payee_only` | Only the **payee** | Anytime before expiry | Trusted sellers |
| `operator_or_payee` | **Ebioro operator** or the **payee** | Anytime before expiry | POS / merchant payments |
| `payer_confirmation` | Only the **payer** | Anytime before expiry | Buyer-protected transactions |
| `operator_after_timeout` | Only **Ebioro operator** | After timeout period | Cash off-ramp with timeout window |
## Creating an Escrow Payment
Escrow payments are created through the same `POST /payments` endpoint. No extra steps are needed — you can optionally include `escrowPayee` and/or `escrowPlatformFee`:
```json theme={null}
{
"amount": {
"value": 5000,
"currency": "USD"
},
"description": "Ride #4521",
"redirectUrl": "https://yoursite.com/success",
"webhookUrl": "https://yoursite.com/webhook",
"escrowPayee": "GBXYZ...PAYEE_STELLAR_ADDRESS",
"escrowPlatformFee": 500
}
```
| Field | Required | Description |
| ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `escrowPayee` | Optional | Stellar address of the fund recipient. If omitted, **defaults to the merchant's Stellar account**. |
| `escrowPlatformFee` | Optional | Platform fee in basis points (1% = 100 bps) deducted at release time. If omitted, **defaults to the merchant's configured platform fee**. |
When to use `escrowPayee`:
* **Ride-hailing / delivery (Uber)**: Set it to the driver's or courier's address — it changes per order.
* **Rental platforms (Airbnb)**: Set it to the host's or property owner's address.
* **Freelance / services marketplaces (Upwork)**: Set it to the freelancer's or service provider's address.
* **Remittances / POS**: Don't set it — the merchant is the payee, so the default is correct.
When to use `escrowPlatformFee`:
* When the platform fee varies per order (e.g., different commission rates per service type or customer).
* If not set, the merchant's default platform fee is used.
Both `escrowPayee` and `escrowPlatformFee` are only applicable for merchants with `settlement_mode = escrow`. For direct settlement merchants, these fields are ignored.
## Payment Lifecycle (Escrow)
### Escrow-Specific Statuses
| Status | Description |
| -------------------- | ---------------------------------------------------------- |
| `escrow_funded` | Funds are locked in the escrow contract |
| `partially_refunded` | Part of the escrowed amount has been refunded to the payer |
| `released` | Remaining funds released to the payee (fees deducted) |
| `refunded` | Full amount refunded to the payer |
## Fee Structure
There are two types of fees, deducted at different stages:
1. **Ebioro processing fee** — deducted **before** funds enter the escrow contract. The amount locked in escrow is already net of this fee. Note that escrow processing fees differ from direct settlement fees.
2. **Platform fee** — deducted **at release time** from the escrowed amount. This is the marketplace or partner commission, configured per merchant.
**Example:**
* Customer pays: \$100 USDC
* Ebioro processing fee: deducted before escrow
* Amount locked in escrow: net of Ebioro fee
* Platform fee: deducted at release
* **Payee receives: net amount after both fees**
Contact [support@ebioro.com](mailto:support@ebioro.com) for specific fee rates.
## Use Cases
### Marketplace / Gig Economy
A ride-hailing or delivery platform where customers pay upfront and drivers receive payment after service completion.
* **Release policy:** `platform_only`
* **Flow:** Customer pays → funds locked → service delivered → platform confirms → driver paid
### POS / E-commerce
An IT provider integrates Ebioro as a payment method for physical stores or online shops.
* **Release policy:** `platform_only` or `operator_or_payee`
* **Flow:** Customer pays at checkout → funds locked → merchant confirms fulfillment → funds released
### Remittance Delivery via Licensed Operator
A sender initiates a cross-border payment. A licensed local operator delivers funds (bank deposit, cash payout) to the recipient. Ebioro validates delivery before releasing funds.
* **Release policy:** `platform_only`
* **Flow:** Sender pays → funds locked → operator delivers locally → Ebioro validates delivery → operator paid
### Cash Off-Ramp
A licensed cash operator allows users to convert crypto to physical cash at a physical location.
* **Release policy:** `operator_after_timeout`
* **Flow:** User pays → funds locked → cash handed over → timeout window → operator releases after timeout
## Webhooks
Escrow payments send the same webhook events as regular payments, with additional escrow fields:
```json theme={null}
{
"event": "payment.updated",
"data": {
"checkout_id": "chk_abc123",
"status": "paid",
"escrow_status": "funded",
"escrow_order_id": "42",
"escrow_contract_address": "CXYZ...CONTRACT"
}
}
```
## Coming Soon
The following features are planned but not yet available in the API.
### Escrow Release Endpoint
```
POST /payments/:id/release
```
Triggers the release of escrowed funds to the payee. Only available for merchants or platforms authorized by the release policy.
### Escrow-Aware Refunds
```
POST /payments/:id/refunds
```
Currently, refunds for escrow payments are not supported. A future update will integrate contract-based refunds (`refund_expired` and `partial_refund`) for escrowed payments.
## Setup
Escrow settlement is enabled per merchant. Contact [support@ebioro.com](mailto:support@ebioro.com) to configure:
* `settlement_mode: escrow`
* Release policy for your use case
* Platform fee structure
* Escrow contract deployment