---
title: "Build a global contractor payout product"
description: "Compose onboarding, bank accounts, quotes, payouts, and reconciliation into a complete pay-your-contractors feature across Pix, SPEI, SEPA, and ACH."
date: "2026-08-26"
category: "integrations"
products: ["payouts", "compliance", "quotes", "webhooks"]
---

Paste this prompt into your coding agent to build the classic use case end to end: paying international contractors from a stablecoin balance.

## Prompt

```text
You are building a contractor payout feature on BlindPay: my business holds stablecoins and pays contractors in Brazil (Pix/BRL), Mexico (SPEI/MXN), Europe (SEPA/EUR), Argentina (Transfers/ARS), Colombia, and the US (ACH/USD).

Before writing code, read these sources and follow them over any prior knowledge:
- https://blindpay.com/docs/llms.txt (read the payout quickstart, customers, bank accounts, quotes, payment methods, and webhooks pages)
- The OpenAPI spec: curl https://api.blindpay.com/doc

Build these product pieces:
1. Contractor onboarding: terms of service, create customer (individual, KYC standard; route high-risk countries to enhanced), collect the rail-specific bank fields per country, all driven by customer.* and bankAccount.new webhooks. A contractor is payable only when KYC is approved and a bank account exists.
2. Payout run: given a list of (contractor, amount, currency), for each one quote (POST /v1/instances/{instance_id}/quotes) and execute (POST /v1/instances/{instance_id}/payouts/evm) before expires_at. Key each payout on my payroll-run line ID so retries can never double-pay, and gate the whole run behind one human approval showing total amount and FX per corridor.
3. Status and reconciliation: drive contractor-visible status from payout.new/update/complete webhooks (Svix-verified); build a per-run report of quoted rate, fees, and settled amounts; alert on payouts stuck past the rail's expected settlement time (Pix/SPEI minutes, ACH days, SEPA one business day).
4. Limits and edge cases: respect per-tier transaction limits, handle rejected KYC and RFIs with a clear contractor-facing state, and handle failed/refunded payouts by returning the line to the next run with a reason.
5. Testing: full run on a development instance (KYC auto-approves, payouts auto-complete), including one line at $666.00 (forces failed) and one at $777.00 (forces refunded) to prove the run survives partial failure.

Constraints: amounts in integer minor units, API keys server-side, no floating point money math anywhere.

Deliverables: onboarding flow, payout-run engine with approval gate and idempotency, webhook-driven status, the reconciliation report, and the failure-path tests.
```

## How to use

1. Paste the prompt with your stack and which corridors you actually pay.
2. Review the approval-gate UX; it is the piece your finance team will live in.
3. Run the sentinel-amount test before every production cutover.

## Related docs

- [Payout quickstart](https://blindpay.com/docs/quickstart-payout)
- [Payment methods](https://blindpay.com/docs/kb/payment-methods)
- [Cut-off times and limits](https://blindpay.com/docs/kb/cut-off-times)