Quickstart

This guide walks through authenticating to the Birch Hill API, creating a recipient, initiating a cross-border payment, and receiving the settlement confirmation webhook. Total time: under 15 minutes.

Authentication

All requests to the Birch Hill API require a bearer token in the Authorization header. You manage API keys in the portal under Settings > API Keys.

There are two key types:

• Live keys (bhl_live_...): initiate real payments and access live compliance records.
• Test keys (bhl_test_...): sandbox environment, no real funds move, settlement webhooks fire automatically.

curl https://api.birchhiil.com/v1/account \
  -H "Authorization: Bearer bhl_test_..."

# Response
{
  "account_id": "acc_...",
  "name": "Acme Corp Treasury",
  "plan": "treasury",
  "corridors_enabled": ["USD-EUR", "USD-MXN", "USD-BRL"]
}

Corridors

A corridor is a source currency and destination currency pair. Each corridor is settled on a specific rail. You can list enabled corridors on your account:

import birchhill

client = birchhill.Client(api_key="bhl_test_...")
corridors = client.corridors.list()

for c in corridors:
    print(c.id, c.avg_settlement_seconds, c.status)

Creating a payment

Before you can create a payment, you need a recipient object. Recipients store the destination bank details and are reused across payments.

recipient = client.recipients.create(
    name="Lieferant GmbH",
    country="DE",
    currency="EUR",
    iban="DE89 3704 0044 0532 0130 00",
    bic="COBADEFFXXX"
)

payment = client.payments.create(
    amount=750000,
    currency="USD",
    destination_currency="EUR",
    recipient_id=recipient.id,
    reference="INV-2026-0440",
    corridor="USD-EUR"
)

print(payment.settlement_id)
print(payment.status)

Settlement webhooks

Configure a webhook endpoint in the portal under Settings > Webhooks. Birch Hill sends a POST request signed with HMAC-SHA256 on each status change.

from flask import request
import birchhill

@app.route("/webhooks/bhl", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    sig = request.headers.get("Bhl-Signature")

    event = birchhill.Webhook.verify(
        payload=payload,
        signature=sig,
        secret="whsec_..."
    )

    if event.type == "payment.settled":
        stl_id = event.data.settlement_id
        trail_url = event.data.compliance_trail_url

    return "", 200

Retrieving the compliance trail

The compliance trail is available immediately after settlement. You can retrieve it via the API or download it as a PDF from the portal.

trail = client.compliance.get_trail(
    settlement_id="bhl_stl_f3a9d2e7"
)

print(trail.sanction_check_result)
print(trail.corridor_path)
print(trail.settled_at)
print(trail.fx_rate_applied)
print(trail.download_url)

ERP integration

Birch Hill is designed to integrate with treasury management systems and ERPs. The most common pattern is:

1. Your TMS triggers a payment instruction via the Birch Hill API when an AP record is approved.
2. Birch Hill initiates settlement and returns a settlement_id immediately.
3. The settlement confirmation webhook fires when funds are received.
4. Your TMS marks the payable as settled and stores the compliance trail URL against the ledger entry.

For SAP S/4HANA, the outbound IDoc mapping and the settlement confirmation inbound handler are documented in the SAP integration guide. For Oracle Cloud Financials, use the Payment Process Request API with the Birch Hill response mapped to the Bank Account Confirmation object.

Reconciliation webhooks

Birch Hill fires a payment.reconciliation_ready event after each settlement with a structured reconciliation payload containing the ledger-ready fields your ERP expects: payment reference, settled amount in destination currency, applied FX rate, settlement timestamp, and compliance trail identifier.

{
  "event": "payment.reconciliation_ready",
  "settlement_id": "bhl_stl_f3a9d2e7",
  "reference": "INV-2026-0440",
  "amount_sent_usd": 750000.00,
  "amount_received_eur": 693608.25,
  "fx_rate": 0.924811,
  "settled_at": "2026-05-14T09:26:19Z",
  "compliance_trail_id": "ctr_8e2b..."
}

Python SDK

Install the Python SDK via pip:

pip install birchhill

Node.js SDK

npm install birchhill