Home

Developers

API Documentation

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.

Create

Create a transaction from your backend.

Checkout

Redirect the buyer to hosted checkout.

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 prefix	Mode	Behavior
ek_test_	Test	Safe integration data. Checkout funding is simulated and no real funds, ledger entries, or blockchain escrow are created.
ek_live_	Live	Production 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

Status	Meaning
awaiting_payment	Checkout created; payment has not yet been confirmed.
payment_detected	A payment was detected and is being confirmed.
funded	Funds are secured in escrow.
inspection_expiring	The buyer inspection window is close to ending.
completed	The transaction completed and funds were released through the escrow lifecycle.
disputed	A dispute is open.
resolved	The dispute was resolved.
refunded	Funds were returned through the dispute or resolution lifecycle.
cancelled	The transaction was cancelled before completion.
expired	The 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

awaiting_payment

Buyer opens hosted checkout.

payment_detected

Payment confirmation is in progress.

funded

Funds are secured in escrow. Fulfil the order.

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

Header	Purpose
X-Escrowly-Signature	Hex-encoded HMAC-SHA256 signature.
X-Escrowly-Event	Event type, for example transaction.funded.
X-Escrowly-Event-Id	Unique delivery event ID for replay protection and deduplication.
Content-Type	application/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

Field	Type	Requirement	Notes
amount	string	Required	Decimal greater than 0; maximum 1,000,000,000 and up to 8 decimal places.
currency	string	Optional	USDT, USDC, or DAI. Uses your merchant default when omitted.
description	string	Optional	A customer-readable order or transaction description.
buyer_email	string	Optional	Pre-fills and associates the expected buyer email.
inspection_period_days	integer	Optional	Buyer inspection window from 1 to 30 days.
fee_payer	string	Optional	buyer, seller, or split. Uses your merchant default when omitted.
redirect_url	URL	Optional	Buyer destination after successful checkout. HTTPS recommended.
cancel_url	URL	Optional	Buyer destination when checkout is cancelled. HTTPS recommended.
webhook_url	HTTPS URL	Optional	Per-transaction webhook URL. Must be public and must use HTTPS.
metadata	object	Optional	Your own structured reference data, such as an order ID.
items	array	Optional	Up to 100 items with name, quantity, and unit_price.

Item fields

Field	Type	Validation
name	string	Required; 1 to 200 characters.
quantity	integer	Required; 1 to 100,000.
unit_price	string	Required; non-negative decimal value.

API reference

Pagination

Parameter	Default	Rules
page	1	Integer greater than or equal to 1.
limit	20	Integer 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:

Header	Meaning
X-RateLimit-Limit	Maximum requests in the current window.
X-RateLimit-Remaining	Requests remaining in the current window.
X-RateLimit-Reset	Unix timestamp when the current window resets.
Retry-After	Seconds 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 status	Meaning
400	Invalid input or an action is not valid for the current transaction state.
401	Missing, invalid, revoked, or expired API key.
403	The transaction belongs to a different merchant.
404	The requested transaction was not found.
429	Rate limit exceeded; respect Retry-After.
500	Unexpected 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 Resources Contact support

Innover ensemble

Rejoignez-nous pour sécuriser votre crypto et assurer la conformité

Rejoignez-nous dans notre parcours pour devenir le leader des transactions crypto sécurisées – où chaque transaction, qu’elle concerne des actifs numériques ou traditionnels, repose sur l’intégrité, l’innovation et la tranquillité d’esprit.

Commencer maintenant

Menu

Escrowly Connect API

Overview

Authentication

Test and live modes

Quick start

Create a transaction

Retrieve a transaction

List transactions

Mark as delivered

Transaction statuses

Redirect the buyer

Payment lifecycle

Configure webhooks

Events

Payload and headers

Verify signatures

Retries

Create request fields

Item fields

Rate limits

Errors

Security checklist

Ready to integrate?

Rejoignez-nous pour sécuriser votre crypto et assurer la conformité

Services Escrowly

Support

Partenaire

Politiques