Skip to content
Ledgerline Help

Counterparties, bank verification and screening

Updated 17 September 20263 min read

On this page

A counterparty is someone you pay: a supplier, a contractor, a customer receiving a refund. Before Ledgerline sends them money, it screens them against sanctions lists and checks that their bank account is real. This page explains both steps and the review hold on large first payments.

Create a counterparty

curl https://api.ledgerline.dev/v1/counterparties \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: e4b2c7d9-3a61-4f08-b5d2-71a9c0e8f163" \
  -d name="Northwind Freight GmbH" \
  -d type=business \
  -d country=DE

The response includes the counterparty id, which starts with cpt_, and a screening object.

Sanctions screening

Every counterparty is screened the moment it is created, and again whenever its name or country changes. Screening checks against these lists:

  • OFAC (United States)
  • European Union consolidated list
  • United Nations Security Council list
  • UK HM Treasury list

Screening normally takes under 5 seconds, and the result is in the creation response. The possible outcomes are:

Result Effect
clear No match. The counterparty can be paid once its bank account is verified.
review A possible match. A compliance analyst reviews it and payouts wait.
blocked A confirmed match. Payouts are refused with sanctions_hit and HTTP 403.

Ledgerline rescreens existing counterparties against list updates daily. A counterparty that becomes a match is blocked, and any scheduled payout to them moves to pending_review.

Add and verify a bank account

A counterparty can have several bank accounts. Add one:

curl https://api.ledgerline.dev/v1/counterparties/cpt_01JA6B3M7V/bank_accounts \
  -H "Authorization: Bearer $LEDGERLINE_API_KEY" \
  -H "Idempotency-Key: 0a5d9f2c-6e18-4b73-8c4a-d37f1e6b9052" \
  -d account_number=000123456789 \
  -d routing_number=021000021 \
  -d currency=USD

Payouts to an unverified account fail with counterparty_unverified. Verify it with one of two methods:

Method How it works Time
Micro-deposits Ledgerline sends two deposits of between $0.01 and $0.99. The counterparty reports the amounts and you confirm them with POST .../verify. 1 to 2 business days
Prenote A zero-dollar test entry is sent through the rail. If the bank accepts it, the account exists. 1 to 3 business days

Micro-deposits are the default for USD accounts. Verification succeeds when the amounts match. After three wrong attempts the account is locked and you must add it again. When verification passes, a counterparty.verified event is sent.

Note

In the sandbox, verification completes instantly for the test account numbers listed in Sandbox.

Review hold for large first payments

To limit fraud, a payout of more than $25,000 to a counterparty created less than 7 days ago is held in pending_review before it is submitted. A reviewer normally clears it within 4 business hours. You get a payout.created event immediately and the status changes when the review ends. Payouts at or below $25,000 are not held, and neither are payouts to counterparties older than 7 days.

You can avoid the hold by creating counterparties ahead of time and splitting very first payments, though structuring payments to avoid review can itself trigger one.

Updating and removing

  • Change a counterparty's name or country with POST /v1/counterparties/{id}. This triggers a new screening.
  • A bank account cannot be edited. Create a new one and delete the old one with DELETE .../bank_accounts/{id}.
  • Deleting a counterparty keeps its history. Payouts already made stay in your ledger.

Quotas

Plans include 1,000 counterparties on Starter, 50,000 on Growth and 1,000,000 on Scale. See Limits and quotas.