Product
Escrow, verification and conditional release API
Add 2-step payments to the software your customers already use.
The PayKeeper Escrow API is a JSON REST API that lets ERP, SaaS and marketplace platforms create an escrow account for each transaction, attach the conditions that must be verified, and trigger conditional release to one or many parties. PayKeeper runs the licensed escrow in the background; your product stays front and center.
Licensed escrow company, NMLS 2401821, South Jordan, Utah. Full reference and sandbox at docs.paykeeper.com.
Try the PayKeeper Escrow API
Pick an endpoint, edit the request, copy it as cURL, Node.js or Python, and send it to the sandbox. Every endpoint, field and error code here comes from the live reference.
The PayKeeper Escrow API holds money in escrow wallets and pays it out to one or many parties when your platform says the condition is met. It is a JSON REST API over HTTPS with HTTP Basic authentication, idempotency keys on every write that moves money, your own ids accepted anywhere a PayKeeper id is, and webhooks for deposits, payouts and disbursements. PayKeeper, Inc. (NMLS 2401821) is the licensed escrow holder, so your platform does not need an escrow license.
POSTCreate a wallet
/wallets
Opens an escrow wallet from a preset, ready to fund. One wallet per order, project, claim or deal keeps every dollar traceable to the transaction it belongs to.
Credentials HTTP Basic
Sandbox credentials only. They stay in this page's memory and go straight to the sandbox host; nothing is saved. No credentials yet? Book a 30-minute call and sandbox access follows.
https://app-dev.paykeeper.com/api/public/escrow/walletscurl --request POST \ --url 'https://app-dev.paykeeper.com/api/public/escrow/wallets' \ --user "$PAYKEEPER_ORG_ID:$PAYKEEPER_ACCESS_KEY_SECRET" \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Idempotency-Key: 3f2c9a1e-6b7d-4e21-9c8a-5d0f1b2e7a44' \ --data '{ "preset": "FUNDING", "label": "Order 1042 escrow", "description": "Funds held for order 1042 until delivery is confirmed", "externalId": "order-1042", "metadata": { "orderId": "1042", "region": "UT" }, "currency": "USD" }'Response
Click Try It! to send this request to the sandbox and see the response here. Or choose a documented response:
application/json
- 201
- Wallet created, open and ready to fund.
- 400
- Malformed request: missing_field, unsupported_currency, invalid_field, invalid_body, invalid_idempotency_key, invalid_actor_headers.
- 401
- missing_credentials or invalid_credentials.
- 403
- policy_composition_not_permitted (wallets come from presets only) or public_api_not_enabled.
- 409
- external_id_already_exists (nothing created) or idempotency_key_in_use (retry after Retry-After).
- 422
- preset_not_available or idempotency_key_reused.
- 503
- virtual_account_unavailable (nothing created) or upstream_busy (retry with the same key). No money moved.
The lifecycle of a 2-step payment
Four stages. Your platform sees each one through an API call or a webhook, so it reacts to every state change instead of guessing.
- 1Escrow
Create the transaction
Provisions a dedicated escrow account, names the parties and attaches the release conditions, locked and auditable from this moment.
POST /wallets - 2Escrow
Fund it
The payer funds by ACH, wire, card or stablecoin. PayKeeper confirms receipt and notifies every party.
deposit posted - 3Verification
Verify the condition
Your platform, a third party, an AI agent or a PayKeeper workflow submits the evidence. Every check is logged.
your platform's check - 4Conditional release
Release
PayKeeper validates the trigger, applies splits and fees, disburses to each party and returns reconciliation data.
disbursement completed
A dispute raised on your platform is one call: the escrow goes on hold, undisputed items keep moving, and release resumes once the agreed process resolves it.
From sandbox to first payout in four calls
The whole money path of a 2-step payment: hold it, then release it to everyone owed. The condition check stays in your platform, where the data already lives.
- 1Set up
Pick a preset
GET /wallet-presetsFUNDINGis the usual preset: payers you instruct fund the wallet, and money leaves only on your instruction. PayKeeper sets presets up for your organization. - 2Escrow
Open a wallet per deal
Create one wallet for each order, project, claim or grant. Pass your own id as
POST /walletsexternalIdand useext:order-1042anywhere after that. - 3Collect
Hand payers the funding instructions
Wire and ACH details plus a payment reference, or the wallet's own account number. Each credit posts to the wallet and fires a webhook.
GET /wallets/{id}/funding-instructions - 4Release
Pay every party in one call
When your platform's condition is met, one disbursement pays up to 100 payees, people, companies or wallets, each leg tracked to a final status.
POST /disbursements
Test the full loop without a bank: POST /sandbox/deposits simulates a wire or ACH credit against a wallet's payment reference or account number, so balances, statements and disbursements can be exercised end to end.
Built so money calls are safe to retry
Payment APIs fail in the network, not just in your code. These guarantees come straight from the reference.
Idempotent by design
Send an
Idempotency-Key(required on disbursements) and a retry of the same body can never pay twice. Reusing a key for a different body returnsidempotency_key_reused.503 means no money moved
When the API can't finish safely it says so:
503withupstream_busyortimed_out, nothing created, retry with the same key afterRetry-After.Your ids, everywhere
Give wallets, payees, disbursements and each leg an
externalId, then address them asext:{externalId}. No id mapping table to maintain.Payees resolved, never duplicated
POST /payeesreturns the existing person or company (200) or creates one (201). Conflicting names, emails, SSNs or EINs are refused with a named 409 instead of paying the wrong party.Rules set by presets
A preset fixes the wallet's fee, funding route and policy: who can see, fund, disburse and administer. A request that tries to write its own policy is refused, so integrations can't loosen controls.
Every leg accounted for
Disbursements end
COMPLETED,PARTIALLY_COMPLETED,FAILEDorCANCELED, with each leg's status. Wallet statements list every credit in and every leg out, newest first.
Every endpoint and webhook
Base URL (sandbox): https://app-dev.paykeeper.com/api/public/escrow. Production credentials and host come with onboarding.
| Endpoint | What it does |
|---|---|
| Wallets | |
GET/wallet-presets | Wallet types your organization can open (fee, funding route, policy). |
POST/wallets | Open an escrow wallet from a preset. |
GET/wallets | Your wallets, newest first; filter by preset or externalId. |
GET/wallets/{walletId} | One wallet, balance refreshed from the ledger. |
GET/wallets/{walletId}/funding-instructions | Wire and ACH details, payment reference or the wallet's own account number. |
GET/wallets/{walletId}/transactions | The wallet's statement: credits in, disbursement legs out. |
| Payees | |
POST/payees | Find or create a person or company to pay. |
GET/payees | Everyone you have set up to pay. |
GET/payees/{payeeId} | One payee, by id, wallet id or ext: reference. |
| Disbursements | |
POST/disbursements | Pay 1 to 100 destinations from one wallet in a single call. |
GET/disbursements | Your disbursements, newest first; filter by source wallet. |
GET/disbursements/{disbursementId} | One disbursement with every leg's current status. |
| Sandbox | |
POST/sandbox/deposits | Simulate an incoming wire or ACH deposit. |
Webhooks: your platform reacts to money movement instead of polling.
- Deposit posted
- Deposit returned
- Transfer received
- Payout posted
- Payout failed
- Disbursement completed
- Disbursement partially completed
- Disbursement failed
Pagination is offset based (limit 1–100, default 25; offset). Lists return newest first. metadata takes up to 20 string tags and comes back as sent. Errors carry a machine-readable code, and param names the field on a 400.
Built for lean engineering teams
REST API and webhooks
A predictable, versioned REST API with webhook events for every escrow, verification and release state change.
Sandbox from day one
Build and test against a sandbox before any real money moves.
Configurable release logic
Time-based, event-driven or approval-gated conditions, passed when the transaction is created.
Compliance built in
Trigger PayKeeper’s KYB, KYC and OFAC screening at onboarding instead of building a compliance stack.
Multi-party disbursement
One release can pay a seller, subcontractors, referral partners, tax authorities and your platform fee.
Reconciliation data
Every inflow, hold, release and fee is available by API or report, ready for QuickBooks, NetSuite or Xero.
Platforms that embed PayKeeper
Most platforms already track the milestones, approvals and documents a release depends on. PayKeeper turns that data into release rules.
ERP and SaaS providers
Offer escrow, verification and conditional release as a native feature for industries with step payments and milestones.
Marketplaces
Escrow per order, delivery-gated release and automatic fee carve-out.
Insurance companies
Match claim payments to adjuster approvals, completed repairs and vendor invoices.
Disaster recovery programs
Connect program management software to strict, auditable release rules.
Construction software
Sync draws, inspections and lien waivers with escrow-backed disbursement.
Law firms
Manage third-party funds at scale, released on documented case milestones.
Grant administrators
Hundreds of payees with their own timelines and verification criteria.
Non-profits
Individually tailored conditions on both the giving and receiving side.
Questions
Do we need our own escrow license?
No. PayKeeper, Inc. is the licensed escrow company (Utah, NMLS 2401821). Your platform integrates the API and stays the customer-facing product; PayKeeper holds the funds and runs compliance.
How does the PayKeeper API authenticate?
With HTTP Basic: your organization id and access key secret, base64-encoded, on every request. PayKeeper issues the credentials and enables the API for your organization; until then requests return 403 public_api_not_enabled.
Is it safe to retry a request that timed out?
Yes. Send an Idempotency-Key (a UUID) with each write; it is required on disbursements and sandbox deposits. Retrying the same body with the same key never creates a second wallet, payee or payment, and a 503 always means nothing moved.
Can we use our own order or customer ids?
Yes. Wallets, payees, disbursements and individual legs take an externalId, unique within your organization, and every lookup accepts ext:{externalId} in place of the PayKeeper id.
Who verifies the conditions?
Whoever the agreement names: your platform’s own logic, a third party such as an inspector or registry, an AI agent or verification model, or a PayKeeper review workflow.
How many parties can one release pay?
Up to 100 destinations per disbursement: existing payees, people by email or mobile number, companies by name and contact email (EIN optional), organizations already on PayKeeper, or wallets.
Which webhooks does the API send?
Deposit posted, deposit returned, transfer received, payout posted, payout failed, disbursement completed, disbursement partially completed and disbursement failed.
How long does integration take?
Most marketplace integrations reach a testable state within a few weeks. Enterprise clients are typically operational within two to four weeks of completing onboarding.
Which rails can we fund and release on?
ACH, wire, card and approved stablecoins such as USDC, in any combination.
Is there a sandbox?
Yes. The sandbox runs at app-dev.paykeeper.com with the same endpoints, and POST /sandbox/deposits simulates incoming wire and ACH credits so you can test balances, statements and disbursements before any real money moves. The full reference at docs.paykeeper.com has a Try It panel on every endpoint.