Logo|
Escrowly
菜单
开始托管运作原理费用计算器服务API 文档
+1 (888) 868-9811
Escrowly
Social MediaSocial MediaSocial MediaSocial MediaSocial Media

版权所有 © 及商标注册 2023-2025 Escrowly LLC。保留所有权利。持有加密牌照的科技公司

REST APIVersion 1

Escrowly Connect API

Create protected stablecoin transactions from your server, send buyers to Escrowly's hosted checkout, and keep your order system synchronized with signed webhooks.

Base URLhttps://api.escrowly.com/api/v1

Getting started

Overview

Escrowly Connect is a server-to-server REST API for merchants. Your application creates a transaction, redirects the buyer to the returned checkout_url, and tracks the transaction through API reads and signed webhook events.

1

Create

Create a transaction from your backend.

2

Checkout

Redirect the buyer to hosted checkout.

3

Synchronize

Process signed status webhooks.

Getting started

Authentication

Send your API key in the X-Api-Key header on every merchant API request. Generate and manage keys in Merchant Resources.

Request headers
1X-Api-Key: ek_test_your_key
2Content-Type: application/json

Keep keys server-side

Never include an API key in browser JavaScript, a mobile app, a public repository, screenshots, or support messages. Revoke and replace a key immediately if it is exposed.

Getting started

Test and live modes

Key prefixModeBehavior
ek_test_TestSafe integration data. Checkout funding is simulated and no real funds, ledger entries, or blockchain escrow are created.
ek_live_LiveProduction transactions using real funding, escrow, and ledger processing.

The key selects the mode automatically. Test and live transactions and webhook configurations are isolated from one another.

Getting started

Quick start

Create your first test transaction from a trusted backend. Save the returned transaction ID with your internal order before redirecting the buyer.

CURL
1curl -X POST "https://api.escrowly.com/api/v1/connect/transactions" \
2  -H "X-Api-Key: ek_test_your_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "amount": "125.00",
6    "currency": "USDT",
7    "description": "Order #ATH-1001",
8    "buyer_email": "[email protected]",
9    "inspection_period_days": 3,
10    "fee_payer": "buyer",
11    "redirect_url": "https://merchant.example.com/orders/ATH-1001/success",
12    "cancel_url": "https://merchant.example.com/orders/ATH-1001",
13    "metadata": { "order_id": "ATH-1001" }
14  }'

201 Created

Response
1{
2  "id": "9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
3  "status": "awaiting_payment",
4  "checkout_url": "https://my.escrowly.com/checkout/9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
5  "amount": "125.00",
6  "currency": "USDT",
7  "fee_payer": "buyer",
8  "inspection_period_days": 3,
9  "created_at": "2026-07-14T08:30:00.000Z",
10  "expires_at": "2026-07-15T08:30:00.000Z"
11}

Transactions

Create a transaction

POST/connect/transactionsAPI key required

Creates a checkout session with a 24-hour payment window. The response contains the URL where the buyer completes payment.

cURL
1curl -X POST "https://api.escrowly.com/api/v1/connect/transactions" \
2  -H "X-Api-Key: ek_test_your_key" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "amount": "125.00",
6    "currency": "USDT",
7    "description": "Order #ATH-1001",
8    "buyer_email": "[email protected]",
9    "inspection_period_days": 3,
10    "fee_payer": "buyer",
11    "redirect_url": "https://merchant.example.com/orders/ATH-1001/success",
12    "cancel_url": "https://merchant.example.com/orders/ATH-1001",
13    "metadata": { "order_id": "ATH-1001" }
14  }'
201 response
1{
2  "id": "9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
3  "status": "awaiting_payment",
4  "checkout_url": "https://my.escrowly.com/checkout/9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
5  "amount": "125.00",
6  "currency": "USDT",
7  "fee_payer": "buyer",
8  "inspection_period_days": 3,
9  "created_at": "2026-07-14T08:30:00.000Z",
10  "expires_at": "2026-07-15T08:30:00.000Z"
11}

Avoid duplicate orders

This endpoint does not currently accept an idempotency key. Store the returned transaction ID and do not blindly retry a request whose result is uncertain.

Transactions

Retrieve a transaction

GET/connect/transactions/{transaction_id}API key required

Returns the latest transaction state. A key can only retrieve transactions belonging to the same merchant.

cURL
1curl "https://api.escrowly.com/api/v1/connect/transactions/9f431ea5-4f57-4cdf-8b73-1be61f4cbe21" \
2  -H "X-Api-Key: ek_live_your_key"
200 response
1{
2  "id": "9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
3  "status": "funded",
4  "mode": "live",
5  "amount": "125",
6  "currency": "USDT",
7  "description": "Order #ATH-1001",
8  "buyer_email": "[email protected]",
9  "inspection_period_days": 3,
10  "fee_payer": "buyer",
11  "network": "TRC",
12  "blockchain_tx_hash": "0x...",
13  "metadata": { "order_id": "ATH-1001" },
14  "funded_at": "2026-07-14T08:42:11.000Z",
15  "expires_at": "2026-07-15T08:30:00.000Z",
16  "created_at": "2026-07-14T08:30:00.000Z",
17  "updated_at": "2026-07-14T08:42:11.000Z"
18}

Transactions

List transactions

GET/connect/transactions?status=funded&page=1&limit=20API key required

Lists transactions for the merchant and mode associated with the supplied key. Filter by status and paginate large result sets.

cURL
1curl "https://api.escrowly.com/api/v1/connect/transactions?status=funded&page=1&limit=20" \
2  -H "X-Api-Key: ek_live_your_key"
200 response
1{
2  "data": [
3    {
4      "id": "9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
5      "status": "funded",
6      "amount": "125",
7      "currency": "USDT",
8      "mode": "live",
9      "metadata": { "order_id": "ATH-1001" }
10    }
11  ],
12  "total": 1,
13  "page": 1,
14  "limit": 20,
15  "totalPages": 1
16}

Transactions

Mark as delivered

POST/connect/transactions/{transaction_id}/mark-deliveredAPI key required

Marks a live, funded order as delivered or fulfilled and starts the buyer's configured inspection period.

cURL
1curl -X POST "https://api.escrowly.com/api/v1/connect/transactions/9f431ea5-4f57-4cdf-8b73-1be61f4cbe21/mark-delivered" \
2  -H "X-Api-Key: ek_live_your_key"

Escrow lifecycle protection

Merchant-initiated early release and refund are not integration actions. Completion and refunds are processed through the buyer inspection, dispute, and resolution lifecycle.

Transactions

Transaction statuses

StatusMeaning
awaiting_paymentCheckout created; payment has not yet been confirmed.
payment_detectedA payment was detected and is being confirmed.
fundedFunds are secured in escrow.
inspection_expiringThe buyer inspection window is close to ending.
completedThe transaction completed and funds were released through the escrow lifecycle.
disputedA dispute is open.
resolvedThe dispute was resolved.
refundedFunds were returned through the dispute or resolution lifecycle.
cancelledThe transaction was cancelled before completion.
expiredThe 24-hour checkout payment window expired.

Checkout flow

Redirect the buyer

After a successful create request, redirect the buyer to the exact checkout_url returned by Escrowly. Do not construct this URL yourself and do not collect wallet credentials or payment secrets on your own site.

Browser redirect
1window.location.assign(transaction.checkout_url);

Checkout session

The hosted page handles buyer sign-in and payment. Your server should trust signed webhooks and authenticated transaction reads—not browser query parameters—as the source of payment status.

Checkout flow

Payment lifecycle

1
awaiting_payment

Buyer opens hosted checkout.

2
payment_detected

Payment confirmation is in progress.

3
funded

Funds are secured in escrow. Fulfil the order.

4
completed / disputed

Inspection completes or a dispute is handled.

Webhooks

Configure webhooks

Create separate test and live webhook endpoints from Merchant Resources. The URL must use HTTPS, resolve publicly, and must not redirect to a private or internal address.

Save the signing secret

The plaintext webhook secret is shown once. Store it in your server's secret manager; it is required to verify deliveries.

Webhooks

Events

transaction.createdtransaction.payment_detectedtransaction.fundedtransaction.escrow_createdtransaction.inspection_expiringtransaction.completedtransaction.refundedtransaction.disputedtransaction.resolvedtransaction.cancelledtransaction.expired

Subscribe only to the events your application handles, or select all events in the dashboard.

Webhooks

Payload and headers

HeaderPurpose
X-Escrowly-SignatureHex-encoded HMAC-SHA256 signature.
X-Escrowly-EventEvent type, for example transaction.funded.
X-Escrowly-Event-IdUnique delivery event ID for replay protection and deduplication.
Content-Typeapplication/json
Example payload
1{
2  "id": "wh_evt_537af9da-c491-4d07-8e9c-ff3512db68ab",
3  "event": "transaction.funded",
4  "mode": "live",
5  "created_at": "2026-07-14T08:42:11.000Z",
6  "data": {
7    "transaction_id": "9f431ea5-4f57-4cdf-8b73-1be61f4cbe21",
8    "status": "funded",
9    "amount": "125.00",
10    "currency": "USDT",
11    "metadata": { "order_id": "ATH-1001" }
12  }
13}

Webhooks

Verify signatures

Verify the signature before parsing or acting on the event. The calculation must use the exact raw request body bytes received from Escrowly.

Node.js
1const crypto = require('crypto');
2
3function verifyEscrowlyWebhook(rawBody, signature, secret) {
4  const signingKey = crypto
5    .createHash('sha256')
6    .update(secret)
7    .digest('hex');
8
9  const expected = crypto
10    .createHmac('sha256', signingKey)
11    .update(rawBody)
12    .digest('hex');
13
14  const receivedBuffer = Buffer.from(signature, 'hex');
15  const expectedBuffer = Buffer.from(expected, 'hex');
16
17  return receivedBuffer.length === expectedBuffer.length &&
18    crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
19}

Process safely

Reject an invalid signature, deduplicate using X-Escrowly-Event-Id, return a 2xx response quickly, and move slow business work to your own queue.

Webhooks

Retries

Escrowly retries transient delivery failures, including network errors, timeouts, HTTP 408, HTTP 429, and server-side 5xx responses. Retries use increasing delays and stop after the delivery attempt limit.

Other 4xx responses are treated as permanent failures. Webhook requests have a 10-second delivery timeout and redirects are rejected.

API reference

Create request fields

FieldTypeRequirementNotes
amountstringRequiredDecimal greater than 0; maximum 1,000,000,000 and up to 8 decimal places.
currencystringOptionalUSDT, USDC, or DAI. Uses your merchant default when omitted.
descriptionstringOptionalA customer-readable order or transaction description.
buyer_emailstringOptionalPre-fills and associates the expected buyer email.
inspection_period_daysintegerOptionalBuyer inspection window from 1 to 30 days.
fee_payerstringOptionalbuyer, seller, or split. Uses your merchant default when omitted.
redirect_urlURLOptionalBuyer destination after successful checkout. HTTPS recommended.
cancel_urlURLOptionalBuyer destination when checkout is cancelled. HTTPS recommended.
webhook_urlHTTPS URLOptionalPer-transaction webhook URL. Must be public and must use HTTPS.
metadataobjectOptionalYour own structured reference data, such as an order ID.
itemsarrayOptionalUp to 100 items with name, quantity, and unit_price.

Item fields

FieldTypeValidation
namestringRequired; 1 to 200 characters.
quantityintegerRequired; 1 to 100,000.
unit_pricestringRequired; non-negative decimal value.

API reference

Pagination

ParameterDefaultRules
page1Integer greater than or equal to 1.
limit20Integer from 1 to 100.
status—Optional transaction status filter.

API reference

Rate limits

Every transaction API response reports the applicable allowance. Read these headers and slow requests before the limit is exhausted:

HeaderMeaning
X-RateLimit-LimitMaximum requests in the current window.
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp when the current window resets.
Retry-AfterSeconds to wait after a 429 response.

API reference

Errors

Failed requests return JSON with an HTTP status and a human-readable message. Validate the status code before reading the response body.

Example error
1{
2  "message": "Amount must be greater than 0",
3  "error": "Bad Request",
4  "statusCode": 400
5}
HTTP statusMeaning
400Invalid input or an action is not valid for the current transaction state.
401Missing, invalid, revoked, or expired API key.
403The transaction belongs to a different merchant.
404The requested transaction was not found.
429Rate limit exceeded; respect Retry-After.
500Unexpected server error. Retry reads safely; investigate before retrying creates.

API reference

Security checklist

Keep API keys and webhook secrets in a server-side secret manager.

Use test keys during development and isolate test data from production.

Use HTTPS for return URLs and all webhook endpoints.

Verify every webhook against the exact raw request body.

Deduplicate webhook deliveries by event ID.

Fetch the transaction from the API before fulfilling high-value orders.

Log transaction IDs, but never log full API keys or secrets.

Revoke unused keys and rotate credentials after any suspected exposure.

Ready to integrate?

Create a test API key in Merchant Resources and complete the quick-start flow before enabling live mode.

Open Merchant ResourcesContact support

携手创新，共创未来

加入我们，保障加密资产安全与合规

加入我们，共同引领安全加密交易的未来——在这里，无论是数字资产还是传统资产交易，每笔交易都建立在诚信、创新与安心保障之上。

立即开始
Innovate together
Escrowly

全球信任，安全保障

+1 (888) 868-9811
关于我们费用计算器运作原理API 文档博客

Escrowly 服务

加密托管服务域名托管机动车辆托管里程碑交易在线商品与数字物品股票与投资托管奢侈品托管房地产托管

支持

支付选项认证承运商欺诈预防联系我们

合作伙伴

开始合作我们的伙伴合作咨询API 指南

政策

隐私政策反洗钱与了解你的客户政策监管合规法律安全政策风险披露条款与条件

卓越

Rating Stars

4.9

Trustpilot Logo

Based on100's of reviews

Norton Security

关注我们

Social MediaSocial MediaSocial MediaSocial MediaSocial Media
Google PlayApp Store

Escrowly.com 在遵守适用法规的前提下运营，以提供安全的加密托管服务。Escrowly LLC 是在 FinCEN 注册的货币服务企业，并遵守所有反洗钱/了解你的客户法规。Escrowly 版权所有。
我们不是银行，也非法律咨询机构。
更多信息请访问 FinCEN.gov

© Escrowly® 安托密。Escrowly LLC（美国）（美国注册号 8,141,506）
受监管。安全可靠。引领安全加密托管的未来。