Escrow Payments (Coming Soon)

Escrow payments are currently in development and not yet available in production. Contact us at [email protected] 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 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:

{
  "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:

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.
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 [email protected] 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:

{
  "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 [email protected] to configure:

settlement_mode: escrow
Release policy for your use case
Platform fee structure
Escrow contract deployment

Getting Started

Core Concepts

Overview

How It Works

Roles

Payer (Customer / Sender)

Payee (Recipient / Service Provider)

Platform Owner

Ebioro Operator

Quick Reference

Escrow vs Direct Settlement

Release Policies

Creating an Escrow Payment

Payment Lifecycle (Escrow)

Escrow-Specific Statuses

Fee Structure

Use Cases

Marketplace / Gig Economy

POS / E-commerce

Remittance Delivery via Licensed Operator

Cash Off-Ramp

Webhooks

Coming Soon

Escrow Release Endpoint

Escrow-Aware Refunds

Setup

Getting Started

Core Concepts

​Overview

​How It Works

​Roles

​Payer (Customer / Sender)

​Payee (Recipient / Service Provider)

​Platform Owner

​Ebioro Operator

​Quick Reference

​Escrow vs Direct Settlement

​Release Policies

​Creating an Escrow Payment

​Payment Lifecycle (Escrow)

​Escrow-Specific Statuses

​Fee Structure

​Use Cases

​Marketplace / Gig Economy

​POS / E-commerce

​Remittance Delivery via Licensed Operator

​Cash Off-Ramp

​Webhooks

​Coming Soon

​Escrow Release Endpoint

​Escrow-Aware Refunds

​Setup

Overview

How It Works

Roles

Payer (Customer / Sender)

Payee (Recipient / Service Provider)

Platform Owner

Ebioro Operator

Quick Reference

Escrow vs Direct Settlement

Release Policies

Creating an Escrow Payment

Payment Lifecycle (Escrow)

Escrow-Specific Statuses

Fee Structure

Use Cases

Marketplace / Gig Economy

POS / E-commerce

Remittance Delivery via Licensed Operator

Cash Off-Ramp

Webhooks

Coming Soon

Escrow Release Endpoint

Escrow-Aware Refunds

Setup