[{"data":1,"prerenderedAt":884},["ShallowReactive",2],{"content-\u002Fresources\u002Fmore\u002Fstablecoin-payroll-run-runbook":3,"resources-category-stablecoin-payroll-run-runbook":869},{"title":4,"seoTitle":5,"description":6,"date":7,"updated":7,"category":8,"faq":9,"howto":25,"body":46},"Stablecoin payroll run runbook: timing, checklist and failure handling (2026)","Stablecoin payroll run runbook: timing and failures","A runbook for a stablecoin payroll run: pre-run checklist, a 200-recipient example, quote timing, cover_fees true, and what to do when a payout fails.","2026-10-28","payments",[10,13,16,19,22],{"q":11,"a":12},"Do employees or contractors need a crypto wallet to be paid?","No. The payer funds the run from its own wallet, and each recipient receives local currency in a bank account or, in Brazil, at a Pix key. The recipient only needs the bank details your platform collected at onboarding. They never see a stablecoin, which keeps the experience the same as any bank payment.",{"q":14,"a":15},"Who pays the fees on a payroll run?","With cover_fees set to true, the sender pays: fees are added on top so each recipient receives the full quoted amount. That is the usual choice for payroll. With false, fees come out of the fiat the recipient receives. The quote shows the full fee before you execute, so finance can approve the real cost.",{"q":17,"a":18},"How fast do people get paid?","It depends on the rail. Per BlindPay docs, Pix, SPEI and Transfers in Argentina are instant, Faster Payments takes 5 to 30 minutes, wire, SEPA, TED and ACH COP take about one business day, and ACH and SWIFT about two. Plan the run so slow rails start days before payday.",{"q":20,"a":21},"What happens if a payroll payout fails?","The payout ends failed or refunded, and a webhook tells you. A refund returns the stablecoins to the refund wallet on the quote, or to the sending wallet. A failed payout is not refunded automatically, so contact support. Fix the cause, such as a wrong account, then create a new quote and a new payout for that person.",{"q":23,"a":24},"Is paying a global team with stablecoins compliant?","The payout provider handles KYC, sanctions screening and travel rule checks in the same API flow, but your own duties remain. Worker classification, tax withholding and labor law are outside any payout API. Confirm them with counsel for each country before the first run. This post covers the mechanics of the run only.",{"name":26,"steps":27},"Run a stablecoin payroll batch end to end",[28,31,34,37,40,43],{"name":29,"text":30},"Freeze the payroll file","Lock the list of recipients, amounts and approved bank accounts before the run starts. Reject any row without an approved bank account or a passed KYC check.",{"name":32,"text":33},"Fund the source wallet","Estimate the stablecoin total from one indicative quote, add a buffer for rate drift, and fund the wallet before the first payout is created.",{"name":35,"text":36},"Start slow rails first","Send ACH, SEPA, TED and ACH COP payouts one to three business days before payday, and keep Pix and SPEI for payday itself.",{"name":38,"text":39},"Quote right before execute","For each recipient, create a payout quote with cover_fees set to true, then execute that quote immediately. A quote backs one payout and expires after 5 minutes by default.",{"name":41,"text":42},"Track every payout to a terminal status","Listen for payout.new, payout.update and payout.complete webhooks and mark each line completed, failed or refunded.",{"name":44,"text":45},"Close the run","Reconcile completed lines against the payroll file, requeue failed lines after fixing the cause, and tell recipients about any delay.",{"type":47,"value":48,"toc":855},"minimark",[49,62,76,82,127,132,135,186,199,203,206,349,357,361,364,484,492,506,510,522,540,561,565,574,591,595,598,703,719,723,726,763,770,774,782,790,794,839,843],[50,51,52,53,57,58,61],"p",{},"A stablecoin payroll run has five stages: freeze the payroll file, fund the wallet, create one payout quote per recipient with ",[54,55,56],"code",{},"cover_fees"," set to ",[54,59,60],{},"true",", execute each quote right after you create it, and track every payout to a terminal status. Slow rails like ACH and SEPA start days before payday. Instant rails like Pix and SPEI fire on payday.",[50,63,64,65,70,71,75],{},"This runbook is the operating procedure, as of October 2026. For what stablecoin payroll is and why LATAM contractors prefer it, read ",[66,67,69],"a",{"href":68},"\u002Fresources\u002Fmore\u002Fstablecoin-payroll-latam-contractors","stablecoin payroll for LATAM contractors",". For the underlying concepts, start with ",[66,72,74],{"href":73},"\u002Fresources\u002Fmore\u002Fwhat-is-a-stablecoin-payouts-api","what a stablecoin payouts API is",".",[50,77,78],{},[79,80,81],"strong",{},"Key takeaways",[83,84,85,89,98,101,113],"ul",{},[86,87,88],"li",{},"A payout quote locks the rate and fees for 5 minutes by default, so create the quote right before you execute it, never at the start of the run.",[86,90,91,92,94,95,97],{},"Setting ",[54,93,56],{}," to ",[54,96,60],{}," adds fees on top, so each recipient receives the full quoted amount. It is the usual choice for payroll.",[86,99,100],{},"Per BlindPay docs, Pix, SPEI and Transfers payouts are instant, while ACH and SWIFT take about two business days. The run calendar must start slow rails first.",[86,102,103,104,107,108,112],{},"A ",[54,105,106],{},"failed"," payout is not refunded automatically. Contact ",[66,109,111],{"href":110},"mailto:support@blindpay.com","support@blindpay.com"," and do not assume it resolves by itself.",[86,114,115,116,119,120,122,123,126],{},"On a development instance, a ",[54,117,118],{},"request_amount"," of 66600 forces ",[54,121,106],{}," and 77700 forces ",[54,124,125],{},"refunded",", so you can rehearse failure handling before payday.",[128,129,131],"h2",{"id":130},"what-does-a-payroll-run-look-like-end-to-end","What does a payroll run look like end to end?",[50,133,134],{},"It looks like a pipeline, not a single call. Each recipient is one quote and one payout, and the run is a loop around those pairs with checks before it and reconciliation after it.",[136,137,138,144,150,156,162,180],"ol",{},[86,139,140,143],{},[79,141,142],{},"Freeze the file."," Lock recipients, amounts and bank accounts. Anything added later goes into the next run.",[86,145,146,149],{},[79,147,148],{},"Fund the wallet."," Move enough stablecoins to the funding wallet to cover the whole run plus a buffer.",[86,151,152,155],{},[79,153,154],{},"Start slow rails."," Create and execute payouts for rails that need business days.",[86,157,158,161],{},[79,159,160],{},"Run payday rails."," On payday, quote and execute Pix, SPEI and other instant payouts.",[86,163,164,167,168,171,172,175,176,179],{},[79,165,166],{},"Track."," Consume ",[54,169,170],{},"payout.new",", ",[54,173,174],{},"payout.update"," and ",[54,177,178],{},"payout.complete"," webhooks.",[86,181,182,185],{},[79,183,184],{},"Close."," Reconcile, requeue failures and message recipients.",[50,187,188,189,193,194,198],{},"The flow per recipient follows the three documented steps on the ",[66,190,192],{"href":191},"\u002Fdocs\u002Fpayouts","payouts page",": add the bank account once, create a payout quote, execute the payout. The ",[66,195,197],{"href":196},"\u002Fresources\u002Fmore\u002Fhow-stablecoin-payouts-work-step-by-step","step-by-step guide to how stablecoin payouts work"," walks through them in detail.",[128,200,202],{"id":201},"what-should-the-payroll-run-checklist-cover-before-you-press-go","What should the payroll-run checklist cover before you press go?",[50,204,205],{},"Check recipients, money and rails before the first quote. Most failed payroll payouts trace back to a bad account or an unfunded wallet, not to the API.",[207,208,209,225],"table",{},[210,211,212],"thead",{},[213,214,215,219,222],"tr",{},[216,217,218],"th",{},"Check",[216,220,221],{},"What to confirm",[216,223,224],{},"Why it matters",[226,227,228,245,256,281,292,303,314,333],"tbody",{},[213,229,230,234,237],{},[231,232,233],"td",{},"Recipient KYC",[231,235,236],{},"Each customer has passed verification",[231,238,239,240,244],{},"Every payment flows through a customer that completed KYC (",[66,241,243],{"href":242},"\u002Fdocs\u002Fkb\u002Fkyc","KYC docs",")",[213,246,247,250,253],{},[231,248,249],{},"Bank account approved",[231,251,252],{},"Account exists and uses the right rail type",[231,254,255],{},"A payout needs an approved bank account",[213,257,258,261,274],{},[231,259,260],{},"Relationship field",[231,262,263,266,267,270,271],{},[54,264,265],{},"recipient_relationship"," is set, such as ",[54,268,269],{},"employee"," or ",[54,272,273],{},"independent_contractor",[231,275,276,277,280],{},"The bank accounts docs list these values; set ",[54,278,279],{},"first_party"," only for the customer's own account",[213,282,283,286,289],{},[231,284,285],{},"Minimum amount",[231,287,288],{},"Each line clears the rail minimum",[231,290,291],{},"10 USD sender amount on most rails, 100 USD requested amount on SWIFT, 50 USDC or 40 EUR on SEPA, 70 USDC or 50 GBP on Faster Payments",[213,293,294,297,300],{},[231,295,296],{},"Wallet funded",[231,298,299],{},"Balance covers the run plus a buffer",[231,301,302],{},"Rates move between funding day and payday",[213,304,305,308,311],{},[231,306,307],{},"Webhook endpoint",[231,309,310],{},"Registered, signature verified, handler idempotent",[231,312,313],{},"You close the run from events, not from the loop",[213,315,316,319,326],{},[231,317,318],{},"Idempotency keys",[231,320,321,322,325],{},"One ",[54,323,324],{},"Idempotency-Key"," per execute call",[231,327,328,329,244],{},"A retry replays instead of paying twice (",[66,330,332],{"href":331},"\u002Fdocs\u002Flearn\u002Fidempotency","idempotency docs",[213,334,335,338,341],{},[231,336,337],{},"Failure rehearsal",[231,339,340],{},"Sentinel amounts tested on a development instance",[231,342,343,344,346,347],{},"66600 forces ",[54,345,106],{},", 77700 forces ",[54,348,125],{},[50,350,351,352,356],{},"If a recipient is new this cycle, allow time for verification. Per the BlindPay ",[66,353,355],{"href":354},"\u002Fdocs\u002Fkb\u002Fcut-off-times","cut-off times reference",", KYC Standard takes about 60 seconds when automated, while KYC Enhanced and KYB Standard take 3 hours to 1 business day with manual review. Do not add a first-time recipient on payday morning.",[128,358,360],{"id":359},"how-should-a-200-recipient-run-be-structured","How should a 200-recipient run be structured?",[50,362,363],{},"Group recipients by rail, then schedule each group by how long the rail needs. The example below is illustrative, with no fees and no real rates.",[207,365,366,385],{},[210,367,368],{},[213,369,370,373,376,379,382],{},[216,371,372],{},"Group (illustrative)",[216,374,375],{},"Recipients",[216,377,378],{},"Rail",[216,380,381],{},"Start",[216,383,384],{},"Expected arrival, per docs",[226,386,387,404,419,434,451,468],{},[213,388,389,392,395,398,401],{},[231,390,391],{},"Brazil contractors",[231,393,394],{},"90",[231,396,397],{},"Pix",[231,399,400],{},"Payday",[231,402,403],{},"Instant",[213,405,406,409,412,415,417],{},[231,407,408],{},"Mexico contractors",[231,410,411],{},"50",[231,413,414],{},"SPEI",[231,416,400],{},[231,418,403],{},[213,420,421,424,427,430,432],{},[231,422,423],{},"Argentina contractors",[231,425,426],{},"10",[231,428,429],{},"Transfers",[231,431,400],{},[231,433,403],{},[213,435,436,439,442,445,448],{},[231,437,438],{},"Euro area staff",[231,440,441],{},"25",[231,443,444],{},"SEPA",[231,446,447],{},"2 business days before payday",[231,449,450],{},"About 1 business day",[213,452,453,456,459,462,465],{},[231,454,455],{},"US staff and vendors",[231,457,458],{},"20",[231,460,461],{},"ACH",[231,463,464],{},"3 business days before payday",[231,466,467],{},"About 2 business days",[213,469,470,473,476,479,481],{},[231,471,472],{},"UK contractors",[231,474,475],{},"5",[231,477,478],{},"Faster Payments",[231,480,400],{},[231,482,483],{},"5 to 30 minutes",[50,485,486,487,491],{},"That is 200 recipients and 200 quotes. Nothing in the docs describes a bulk endpoint, so a payroll run is a loop of quote-then-execute pairs, with your own queue controlling concurrency. Run slow-rail groups first, then payday groups in a queue sized to your API client. The development instance caps requests at 40 per minute per instance, so test your queue speed there with that limit in mind. The ",[66,488,490],{"href":489},"\u002Fdocs\u002Flearn\u002Fsandbox-vs-production","sandbox docs"," state that production instances have no per-instance request cap.",[50,493,494,495,501,502,75],{},"The Federal Reserve closes on holidays, and ACH does not move on them. Check the ",[66,496,500],{"href":497,"rel":498},"https:\u002F\u002Fwww.federalreserve.gov\u002Faboutthefed\u002Fk8.htm",[499],"nofollow","Federal Reserve holiday schedule"," when you count business days for ACH and wire. For the cadence side of recurring runs, see ",[66,503,505],{"href":504},"\u002Fresources\u002Fmore\u002Fschedule-recurring-payouts-live-quotes","scheduling recurring payouts with live quotes",[128,507,509],{"id":508},"why-set-cover_fees-to-true-for-payroll","Why set cover_fees to true for payroll?",[50,511,512,513,57,515,517,518,521],{},"Because a salary is a promise of a number. With ",[54,514,56],{},[54,516,60],{},", fees are added on top of the stablecoin amount you send, so the recipient receives the full quoted amount. With ",[54,519,520],{},"false",", fees come out of the fiat the recipient receives, which is the common case for other products.",[50,523,524,525,94,528,531,532,94,534,536,537,75],{},"On payroll, a recipient who is owed R$ 8,000 should see R$ 8,000. Set ",[54,526,527],{},"currency_type",[54,529,530],{},"receiver"," so the local amount is fixed, and ",[54,533,56],{},[54,535,60],{}," so the fee does not shrink it. The cost moves to your side and shows up in the quote's ",[54,538,539],{},"sender_amount",[50,541,542,543,547,548,552,553,556,557,75],{},"On pricing, BlindPay states it this way: \"BlindPay combines a monthly plan (platform access) with per-transaction fees that vary by rail and network and are disclosed only in the live quote before execute. BlindPay does not publish a static flat rate card; always cite the quote's fee breakdown rather than a fixed bps number.\" There is no setup fee or monthly minimum, and development instances are always free, per the ",[66,544,546],{"href":545},"\u002Fdocs\u002Flearn\u002Fbilling","billing docs",". Finance should approve the run against quote totals, not a rate card. If you earn a markup as a platform, the ",[66,549,551],{"href":550},"\u002Fdocs\u002Flearn\u002Fpartner-fees","partner fee"," shows up as ",[54,554,555],{},"partner_fee_amount"," on each quote. See also ",[66,558,560],{"href":559},"\u002Fresources\u002Fmore\u002Fpartner-fees-markup-on-live-quotes","partner fees as markup on live quotes",[128,562,564],{"id":563},"when-do-you-create-the-quote","When do you create the quote?",[50,566,567,568,571,572,75],{},"Immediately before you execute it. The quote locks the rate and fees for 5 minutes by default, and ",[54,569,570],{},"expires_at"," is returned in epoch milliseconds. SEPA and Faster Payments quotes can be shorter, so always read ",[54,573,570],{},[50,575,576,577,580,581,585,586,590],{},"A quote backs exactly one payout. If it expires, request a new one, do not retry the old ",[54,578,579],{},"quote_id",". Do not request 200 quotes at the start and execute them as the queue drains: the last ones would expire. Create, execute, move on. ",[66,582,584],{"href":583},"\u002Fresources\u002Fmore\u002Fbatch-stablecoin-payouts-live-quotes","Why one quote cannot cover a batch"," explains the pattern, and ",[66,587,589],{"href":588},"\u002Fresources\u002Fmore\u002Fhow-much-stablecoin-float-for-payouts","how much USDC to hold for payouts"," covers sizing the wallet.",[128,592,594],{"id":593},"how-do-you-handle-failures-during-the-run","How do you handle failures during the run?",[50,596,597],{},"Map each failure to one action and one owner. The table lists the cases a payroll operator meets.",[207,599,600,613],{},[210,601,602],{},[213,603,604,607,610],{},[216,605,606],{},"Failure",[216,608,609],{},"Typical cause",[216,611,612],{},"Action",[226,614,615,626,640,651,667,679,692],{},[213,616,617,620,623],{},[231,618,619],{},"Quote expired before execute",[231,621,622],{},"Queue delay, slow client",[231,624,625],{},"Create a new quote and execute it",[213,627,628,634,637],{},[231,629,630,631],{},"Amount below minimum, ",[54,632,633],{},"LIMITS_AMOUNT_OUT_OF_RANGE",[231,635,636],{},"Line under 10 USD on most rails",[231,638,639],{},"Fix the amount or combine with another line",[213,641,642,645,648],{},[231,643,644],{},"SWIFT line below 100 USD",[231,646,647],{},"SWIFT minimum on requested amount before fees",[231,649,650],{},"Move the line to a local rail or raise the amount",[213,652,653,658,661],{},[231,654,655,656],{},"Payout ",[54,657,106],{},[231,659,660],{},"Review timeout or rejected compliance check",[231,662,663,664,666],{},"Contact ",[66,665,111],{"href":110},", fix the cause, quote again",[213,668,669,673,676],{},[231,670,655,671],{},[54,672,125],{},[231,674,675],{},"Delivery not possible",[231,677,678],{},"Stablecoins returned to the refund wallet or the sender; correct the account and requeue",[213,680,681,686,689],{},[231,682,655,683],{},[54,684,685],{},"on_hold",[231,687,688],{},"Compliance review, always for SWIFT",[231,690,691],{},"Wait; holds can take up to 30 days and a timeout fails the payout",[213,693,694,697,700],{},[231,695,696],{},"Webhook missed",[231,698,699],{},"Endpoint down",[231,701,702],{},"Replay from the webhook portal or fetch the payout by id",[50,704,705,706,708,709,713,714,718],{},"Two rules keep payroll safe. First, a ",[54,707,106],{}," payout is not refunded automatically, so open a support ticket instead of waiting. Second, never pay twice: before you requeue a line, confirm the original payout's terminal status. ",[66,710,712],{"href":711},"\u002Fresources\u002Fmore\u002Fexplain-stablecoin-payouts-to-recipients","How to explain a delay to recipients"," has message templates for held and failed payments, and ",[66,715,717],{"href":716},"\u002Fresources\u002Fmore\u002Fstablecoin-payout-statuses-explained","payout statuses explained"," defines each state.",[128,720,722],{"id":721},"how-do-you-reconcile-and-close-the-run","How do you reconcile and close the run?",[50,724,725],{},"A run is closed when every payout id has a terminal status. Do the sum at the end.",[136,727,728,738,744,751,757,760],{},[86,729,730,731,171,734,171,736,75],{},"Count payouts by status: ",[54,732,733],{},"completed",[54,735,106],{},[54,737,125],{},[86,739,740,741,75],{},"Match each completed payout to its payroll line by ",[54,742,743],{},"id",[86,745,746,747,750],{},"Compare the sum of quoted ",[54,748,749],{},"receiver_amount"," values to the payroll file.",[86,752,753,754,756],{},"Compare total stablecoin sent to the sum of ",[54,755,539],{}," values.",[86,758,759],{},"Requeue failed lines with a new quote and a new idempotency key.",[86,761,762],{},"Archive quotes, payout ids and webhook events with the payroll record.",[50,764,765,769],{},[66,766,768],{"href":767},"\u002Fresources\u002Fmore\u002Fstablecoin-api-webhooks-reconciliation","Webhook reconciliation for stablecoin APIs"," shows the ledger pattern, including duplicate events.",[128,771,773],{"id":772},"what-does-this-post-not-cover","What does this post not cover?",[50,775,776,777,75],{},"It does not cover employment classification, taxes or labor law. Whether someone is an employee or contractor, what withholding applies, and which local rules govern pay in each country depend on facts about the worker and the jurisdiction, and a payout API does not decide them. Get advice for each country before your first run. For tax reporting on the US side of contractor payments, see the ",[66,778,781],{"href":779,"rel":780},"https:\u002F\u002Fwww.irs.gov\u002Ffiling\u002Fdigital-assets",[499],"IRS digital assets page",[50,783,784,785,789],{},"On compliance, the provider side covers KYC, sanctions screening and the travel rule in the same flow. See the ",[66,786,788],{"href":787},"\u002Fresources\u002Fmore\u002Ftravel-rule-stablecoin-off-ramps","travel rule for stablecoin off-ramps"," for what that includes.",[128,791,793],{"id":792},"methodology-and-sources","Methodology and sources",[50,795,796,797,800,801,806,807,810,811,171,814,171,818,171,822,171,825,171,828,171,831,175,835,838],{},"External sources: the ",[66,798,500],{"href":497,"rel":799},[499],", the ",[66,802,805],{"href":803,"rel":804},"https:\u002F\u002Fwww.bcb.gov.br\u002Fen\u002Ffinancialstability\u002Fpix_en",[499],"Central Bank of Brazil page on Pix",", and the ",[66,808,781],{"href":779,"rel":809},[499],". BlindPay docs used: ",[66,812,813],{"href":191},"payouts",[66,815,817],{"href":816},"\u002Fdocs\u002Fpayout-quotes","payout quotes",[66,819,821],{"href":820},"\u002Fdocs\u002Fbank-accounts","bank accounts",[66,823,824],{"href":354},"cut-off times",[66,826,827],{"href":545},"billing",[66,829,830],{"href":550},"partner fees",[66,832,834],{"href":833},"\u002Fdocs\u002Flearn\u002Fwebhooks","webhooks",[66,836,837],{"href":331},"idempotency",". The 200-recipient table is illustrative and contains no fees. Rail estimates are BlindPay's documented estimates as of October 2026 and can change with volume.",[128,840,842],{"id":841},"what-to-do-next","What to do next",[50,844,845,846,850,851,854],{},"Rehearse the run on a free development instance with the failure sentinels, then ",[66,847,849],{"href":848},"\u002Fcontact","request a live quote"," for your first corridor and compare it with what your finance team expects. The ",[66,852,853],{"href":816},"payout quotes docs"," have the full request fields.",{"title":856,"searchDepth":857,"depth":857,"links":858},"",2,[859,860,861,862,863,864,865,866,867,868],{"id":130,"depth":857,"text":131},{"id":201,"depth":857,"text":202},{"id":359,"depth":857,"text":360},{"id":508,"depth":857,"text":509},{"id":563,"depth":857,"text":564},{"id":593,"depth":857,"text":594},{"id":721,"depth":857,"text":722},{"id":772,"depth":857,"text":773},{"id":792,"depth":857,"text":793},{"id":841,"depth":857,"text":842},[870,875,880],{"path":871,"title":872,"description":873,"date":874},"\u002Fresources\u002Fmore\u002Fstablecoin-payin-api-pricing","Stablecoin payin API pricing: fees to expect and how to compare them","Stablecoin API pricing for payins: the fee types to expect, a worked USD 10,000 example, a quote checklist, and what BlindPay charges.","2026-10-31",{"path":876,"title":877,"description":878,"date":879},"\u002Fresources\u002Fmore\u002Fmass-payouts-api-architecture","Mass payouts API architecture: how to pay thousands of recipients across borders (2026)","A reference architecture for mass payouts: queue, quote, execute, webhooks and reconciliation, with a failure table, monitoring checklist and partner fees.","2026-10-29",{"path":881,"title":882,"description":883,"date":7},"\u002Fresources\u002Fmore\u002Ffailed-late-or-mismatched-stablecoin-payins","What happens when a stablecoin payin fails, arrives late, or does not match?","Failed stablecoin deposit refund: why payins fail, late or mismatched deposits, and the support runbook, using BlindPay's real payin statuses.",1794399384614]