Public API v1 · how it works

Anatomy of an Earnnest integration

One payment, from a platform's first API call to a terminal outcome. Every request, payload, and notification below is the real v1 contract. Switch payment type and scenario to see how the flow changes.

Generated from the OpenAPI specification

Integrating platform Earnnest API Payer
Payment type Scenario
1 / 8
Connect

The public resources

Four resources, in the order the flow touches them. An integration reads three and writes exactly one. Two capabilities apply to earnest money only.

Payment occasionread
The destination an organization can collect against. It also defines the custom fields a request must supply.
directioncustom_fieldsGET /payment_occasionsGET /escrow_holders (EMD network search)
created under
Transaction templateread + write
The payment request. The one write in the API. Carries the platform's own correlation_id and returns the hosted payer URL.
statuscorrelation_idhosted_payer_urlgenerate_proof_of_intent EMDPOST /transaction_templatesGET /transaction_templates/{id}
becomes, when the payer funds
Transactionread
The money movement. Read-only. Carries the public lifecycle status and, once relevant, the refund outcome.
statusrefund_outcomeGET /transactions/{id}
derives, by type
Payment artifactread
Receipts and proofs generated beneath a transaction, each a PDF at a durable URL. Proof of intent is earnest-money only.
proof_of_intent EMDpayment_receiptdeposit_receiptGET /transactions/{id}/payment_artifacts.../{artifact_type}

Notifications run alongside. Each transaction transition, and each artifact becoming available, emits a signed event delivered to every entitled organization through the Event Delivery and Webhooks product. The envelope stays thin; the integration fetches the detail. That is what the notification and artifact steps above show.

Why this stays accurate. Requests and payloads render from the same OpenAPI contract the API is built against. Scenarios are the sandbox simulator's own; failed and canceled follow the published state machine. Artifact timing reflects the existing pipeline: proof of intent at authorization (earnest-money, opt-in per request via generate_proof_of_intent), payment receipt at initiated, deposit receipt at deposited.