Developers

API reference and integration notes.

The Embank API exposes three resources: mandates, which hold authorization; entries, which move funds; and events, which report state changes. A sandbox environment returns specified return reason codes on demand so that failure handling can be built before entries are originated in production.

Request sandbox access→ Test values

Resources

Data model

mandateAuthorization and account

A verified receiving account together with the authorization obtained from the receiver. Entries reference a mandate by identifier and do not carry account numbers. A mandate holds the SEC code, the terms of the authorization, and its verification and revocation status.

entryA single debit or credit

One instruction to move funds, carrying a direction, a value in cents, a processing option and a description. Creation is idempotent. The entry remains stateful until the return period applicable to it has elapsed.

eventA recorded state change

A signed, immutable record of a transition on a mandate or an entry. Events are delivered to a subscriber endpoint, retried on failure, and replayable.

Conventions

Requests and responses

Item	Convention
Transport	HTTPS only. Requests over plain HTTP are rejected rather than redirected.
Authentication	Bearer token in the Authorization header. Keys are issued per environment and are not interchangeable.
Content type	application/json for both request and response bodies.
Amounts	Integer cents. Fractional values are rejected at validation.
Idempotency	Every mutating request accepts an idempotency key. A repeated key returns the original response rather than creating a second record.
Timestamps	ISO 8601 in UTC. Settlement dates are expressed as calendar dates in Eastern time.
Pagination	Cursor based, using the identifier of the last record in the previous page.
Errors	Conventional HTTP status codes with a machine-readable code and a human-readable message in the body.

POST/v1/ach/mandates

{
  "customer_ref": "unit-4b",
  "account_holder": "Dana Ruiz",
  "account_type": "checking",
  "verification": "instant",
  "sec_code": "PPD",
  "authorization": {
    "method": "written",
    "accepted_at": "2026-03-01T15:04:11Z",
    "terms": "monthly, amount per lease"
  }
}

// 201 Created
{
  "id": "mnd_8Fq2LpV0",
  "status": "verified",
  "account_last4": "4417",
  "sec_code": "PPD"
}

POST/v1/ach/entries

{
  "mandate_id": "mnd_8Fq2LpV0",
  "direction": "debit",
  "amount": 185000,
  "processing": "same_day",
  "description": "MAR RENT 4B",
  "idempotency_key": "rent-4b-2026-03"
}

// 201 Created
{
  "id": "ent_5rTn19Kd",
  "status": "created",
  "window": "same_day_2",
  "settlement_date": "2026-03-02"
}

Endpoints
Method	Path	Purpose
POST	/v1/ach/mandates	Create a mandate and initiate verification.
GET	/v1/ach/mandates/{id}	Retrieve a mandate with its verification and revocation status.
POST	/v1/ach/mandates/{id}/revoke	Record revocation and block further entries.
POST	/v1/ach/entries	Create an entry against a mandate.
GET	/v1/ach/entries/{id}	Retrieve an entry with its full state history.
POST	/v1/ach/entries/{id}/cancel	Cancel an entry that has not yet been transmitted.
GET	/v1/ach/settlements	List settlement records and the entries associated with each.
GET	/v1/events	List events, with replay available per event.

The API base URL is issued with your credentials and differs between the sandbox and production environments.

Webhooks

Event delivery

Every state change produces an event. Delivery is at least once, so subscribers should record the event identifier and disregard duplicates.

Fig. 07 Delivery and retry

Event delivery

State changeAn entry or mandate changes state

Event signedTimestamp and HMAC signature attached

DeliveredPOST to the subscriber endpoint over HTTPS

Acknowledged2xx received within ten seconds

On any non-2xxRedeliveredExponential backoff for 24 hours. After that the event remains available for replay from the dashboard.

Each request carries a timestamp and an HMAC-SHA256 signature computed over the raw body. Signatures should be compared in constant time and requests older than five minutes rejected.

Event types
Type	Emitted when
mandate.verified	Verification of the receiving account completes.
mandate.revoked	Revocation is recorded against the mandate.
entry.created	An entry is accepted and assigned to a window.
entry.transmitted	The entry is included in a file at the window cutoff.
entry.settled	The entry posts on its settlement date.
entry.returned	A return is received, carrying the return reason code.
entry.rejected	The entry fails validation before transmission.
mandate.noc_applied	A notification of change is applied to the mandate.

POSTsubscriber endpoint

Embank-Signature: t=1772456400,v1=9f2c...

{
  "id": "evt_Qa71Zc0m",
  "type": "entry.returned",
  "created": "2026-03-04T11:22:09Z",
  "data": {
    "entry_id": "ent_5rTn19Kd",
    "mandate_id": "mnd_8Fq2LpV0",
    "amount": 185000,
    "return_code": "R01",
    "return_reason": "insufficient funds",
    "category": "funding",
    "representment_eligible": true
  }
}

Sandbox

Test values

Sandbox entries advance through their states on an accelerated schedule. Submitting one of the values below produces the corresponding outcome, so that handling for each category of return can be built and tested deliberately.

Sandbox test values
Amount	Outcome	Category	Handling to build
$1.01	Returned R01	Funding	Re-presentment scheduling and notification to the receiver.
$1.02	Returned R02	Administrative	Cease entries, flag the mandate, re-collect account information.
$1.03	Returned R03	Administrative	Route the mandate back through verification.
$1.07	Returned R07	Unauthorized	Block further entries and surface the authorization record.
$1.10	Returned R10	Unauthorized	Dispute handling with the retained authorization attached.
$1.99	Rejected	Validation	Pre-transmission rejection handling and operator alerting.
Any other	Settles	—	Normal settlement on the accelerated schedule.

Contact

Request credentials

Describe what you are integrating and we will issue sandbox credentials and put you in contact with the team supporting the API.

Contact Embank→ Platform overview