FAQ - Lead | API Docs

Can we reuse existing Lead entities for blockchain payments, or do we need to create new ones?

You can reuse existing entities. If you already have Lead customers set up (for example, from previous integrations), you don’t need to create new entity objects. Simply reference them when you initiate blockchain payments.

Do we need an entity for every user, or just at the account level?

Entities represent the end-customer (the person or business sending or receiving funds). You need one entity per customer account.

Why does the payment request require both the creditor's address and creditor_agent information?

The creditor is the person or business receiving funds outside of Lead. We need their address to verify who they are for compliance. The creditor_agent tells us how and where to send funds - for example, which bank in which country. Together, these identify both “who” receives the funds and “how” to deliver them.

What's the difference between the debtor and creditor?

Debtor: The Lead customer sending the funds (the source)
Creditor: The receiver outside of Lead (the destination)

Where do I find the account identifier information?

The account identifier is the source of your funds. You have two options:Option 1: Lead account number (for USD transfers)

Register an account number via the API if you don’t have one already
Retrieve your account number using the account retrieval endpoint
Use the account_number_id as your debtor account identifier

Option 2: External blockchain wallet (for stablecoin transfers)

Provide a wallet address you control
Use the wallet_address as your debtor account identifier

How do I use idempotency with blockchain payments?

Include the Idempotency-Key header in your POST request. This ensures that if your request times out or fails, you can safely retry without accidentally creating duplicate payments.

When will I get a 409 Conflict error, and what does it mean?

A 409 response means your request was received and processing has started. Because payments process asynchronously, this can happen even if your original request hasn’t completed yet.Here’s what each scenario means:

Same key + same request body + still processing → 409 (processing continues; check webhooks or poll by ID for status)
Same key + different request body + still processing → 409 (key is locked to the original body)
Same key + same request body + completed (within 48 hours) → Replays the original response (no reprocessing)
Same key + different request body + completed (within 48 hours) → 403 (key is locked; use a new key)
Same key + any request body + expired (over 48 hours) → Treated as a new request and processed normally

To track payment status, subscribe to webhooks or fetch the payment object by its ID.

If a transfer is rejected after funds leave my account, where do the funds go?

In the rare case of a rejection, the movement of funds requires manual intervention. Please reach out to Lead if you have an issue.

Can transfers be clawed back after they've settled?

Yes, but only in rare cases (fraud, sanctions violations, or operational errors). Here’s how we handle it:

Sanctions issues: Detected before funds move. You’ll receive a webhook notification and a message via Slack with details.
Fraud or operational errors: If detected after settlement, we’ll notify you via Slack with next steps for reclaiming funds.

Can transfers be cancelled after they have been created?

Not at this time. Please reach out to Lead if you have an issue.

Documentation Index