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.

11 endpoints

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.

Headers

Idempotency-Key (optional, 1–255 printable ASCII): reuse the same key only to retry the same body. A UUID is best.

Body · application/json
{
  "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"
}

preset (required, from GET /wallet-presets) · label (required, 1–200) · description (≤ 2000) · externalId (≤ 200, unique in your organization) · metadata (≤ 20 keys) · currency (USD)

Full reference for create a wallet →

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.

Base URL sandboxhttps://app-dev.paykeeper.com/api/public/escrow/wallets
curl --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

201400401403409422503
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.

4 stages
  1. 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
  2. 2Escrow

    Fund it

    The payer funds by ACH, wire, card or stablecoin. PayKeeper confirms receipt and notifies every party.

    deposit posted
  3. 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
  4. 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.

4 calls
  1. 1Set up

    Pick a preset

    FUNDING is the usual preset: payers you instruct fund the wallet, and money leaves only on your instruction. PayKeeper sets presets up for your organization.

    GET /wallet-presets
  2. 2Escrow

    Open a wallet per deal

    Create one wallet for each order, project, claim or grant. Pass your own id as externalId and use ext:order-1042 anywhere after that.

    POST /wallets
  3. 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
  4. 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.

6 guarantees
  • 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 returns idempotency_key_reused.

  • 503 means no money moved

    When the API can't finish safely it says so: 503 with upstream_busy or timed_out, nothing created, retry with the same key after Retry-After.

  • Your ids, everywhere

    Give wallets, payees, disbursements and each leg an externalId, then address them as ext:{externalId}. No id mapping table to maintain.

  • Payees resolved, never duplicated

    POST /payees returns 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, FAILED or CANCELED, 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.

13 endpoints
PayKeeper Escrow API endpoints
EndpointWhat it does
Wallets
GET/wallet-presetsWallet types your organization can open (fee, funding route, policy).
POST/walletsOpen an escrow wallet from a preset.
GET/walletsYour wallets, newest first; filter by preset or externalId.
GET/wallets/{walletId}One wallet, balance refreshed from the ledger.
GET/wallets/{walletId}/funding-instructionsWire and ACH details, payment reference or the wallet's own account number.
GET/wallets/{walletId}/transactionsThe wallet's statement: credits in, disbursement legs out.
Payees
POST/payeesFind or create a person or company to pay.
GET/payeesEveryone you have set up to pay.
GET/payees/{payeeId}One payee, by id, wallet id or ext: reference.
Disbursements
POST/disbursementsPay 1 to 100 destinations from one wallet in a single call.
GET/disbursementsYour disbursements, newest first; filter by source wallet.
GET/disbursements/{disbursementId}One disbursement with every leg's current status.
Sandbox
POST/sandbox/depositsSimulate 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

6 features
  • 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.

8 platform types
  • 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.