API Reference

The Birch Hill API is RESTful and returns JSON. Base URL: https://api.birchhiil.com/v1. All requests require a bearer token in the Authorization header.

Payments

POST /v1/payments

Create a new cross-border payment. Returns a payment object with a settlement_id. Settlement confirmation fires a payment.settled webhook event.

request body

{
  "amount": 2450000,
  "currency": "USD",
  "destination_currency": "EUR",
  "recipient_id": "rec_8c3f...",
  "reference": "INV-2026-0831",
  "corridor": "USD-EUR",
  "metadata": { "department": "AP" }
}

GET /v1/payments/{settlement_id}

Retrieve a payment by its settlement ID. Returns full payment object including current status, rail used, applied FX rate, and compliance trail reference.

GET /v1/payments

List payments. Supports filtering by status, corridor, date range, and reference. Returns paginated results. Default limit: 25. Maximum: 100.

Recipients

POST /v1/recipients

Create a recipient. Recipients store destination bank details and are reused across payments. Required fields vary by destination country.

EU recipient

{
  "name": "Lieferant GmbH",
  "country": "DE",
  "currency": "EUR",
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX"
}

GET /v1/recipients/{recipient_id}

Retrieve a recipient by ID. Returns stored bank details and the list of payments made to this recipient.

Corridors

GET /v1/corridors

List all corridors available on your account. Each corridor object includes average settlement time, current rail status, and FX availability.

GET /v1/corridors/{corridor_id}/quote

Get a real-time FX quote for a corridor and amount. Quotes are valid for 30 seconds. Use the quote_id in the payment creation body to lock the rate.

Compliance Trail

GET /v1/compliance/trail/{settlement_id}

Retrieve the full compliance trail for a settled payment. Available immediately after settlement. Returns structured JSON with all audit fields.

response

{
  "settlement_id": "bhl_stl_f3a9d2e7",
  "status": "CONFIRMED",
  "initiated_at": "2026-05-14T09:22:08Z",
  "settled_at": "2026-05-14T09:26:19Z",
  "corridor": "USD-EUR",
  "amount_sent": 2450000.00,
  "amount_received": 2265787.95,
  "fx_rate_applied": 0.924811,
  "sanction_check": "PASS",
  "sanction_lists_checked": ["OFAC_SDN", "EU_CONSOLIDATED", "UN_SC"],
  "initiated_by": "usr_treasury_ops",
  "reference": "INV-2026-0831",
  "download_pdf_url": "https://api.birchhiil.com/..."
}

Webhook Events

Birch Hill sends webhook events to your configured endpoint URL via HTTP POST. All payloads are signed with HMAC-SHA256 in the Bhl-Signature header.

Event	When it fires
`payment.initiated`	Immediately after a payment is created and pre-screening passes
`payment.settling`	When funds enter the settlement rail
`payment.settled`	When destination funds are confirmed received
`payment.reconciliation_ready`	After settlement, includes ERP-ready reconciliation fields
`payment.failed`	If settlement fails (rare); includes failure reason
`payment.sanction_held`	If pre-screening flags a sanction match requiring review

Account

GET /v1/account

Retrieve your account details: account ID, plan tier, enabled corridors, monthly volume consumed, and API key metadata.

GET /v1/account/usage

Current month usage: payment count, total volume settled by corridor, and wire fee total. Useful for reconciling against your invoice.