Payouts and settlement

A card payment’s money waits a few days to clear, then it’s paid out: automatically every day once it reaches 1.00 or more in the account’s currency, or on request (POST /v1/payouts). The wait is set by the account’s settlement tier when the payment was taken. A payout shows as TUPPENCE on your bank statement, unless you set another payout line.

Scroll sideways to see all of it →

In Europe, payouts go to the business’s IBAN by SEPA, in euros. A payout leaves only on a TARGET2 banking day: never at a weekend, nor on 1 January, Good Friday, Easter Monday, 1 May, 25 or 26 December (a country’s own holidays don’t stop a SEPA payout). Instant payouts cost 1.5% there, in every European country we serve except Slovakia, and next-day payouts aren’t offered (Pricing).

Settlement tiers

settlement_tier	settlement_days	When it applies
new_account	7	Until the account has seasoned: £1,000$1,000€1,000 of its card payments at least seven days old, at most £250$250€250 from any one card. After 90 days without a payment it seasons again. See Payouts and limits for new accounts.
standard	3	Once seasoned.
next_day	1	UK only: next-day payouts are switched on, by the business (below) or by agreement with Tuppence.

Rule
Calendar days (UTC), weekends included	A next_day payment taken on Friday can be paid out on Saturday; banks pay on working days, so it arrives Monday
Each payment keeps its own days	settlement_days on GET /v1/payments/:id is fixed when it’s taken; a later tier change never re-dates it
The money is held on the same schedule	For a UK account, Tuppence sets the card processor’s settlement delay to the tier at creation and every change, and checks it nightly. The money can be released later than the tier says, never earlier
Nothing leaves in the first 168 hours	Whatever the tier: see new_account_floor

GET /v1/payout_settings has settlement_tier, settlement_days, settlement_tier_since, and settlement_tier_changes_at / settlement_tier_changes_to when a change is due. account.settlement_seasoned is sent when an account seasons.

Instant payouts

Get pending money within 30 minutes for 0.99% of the amount. Available to UK, US, Australian, Canadian and Singaporean businesses, to a bank account that can receive instant payments, once a new account’s first 168 hours are up and it has seasoned. Use Get it now on the dashboard’s Balance, or POST /v1/payouts with method: "instant".

The fee comes out of the payout:

You ask for amount	Taken from balance (total_amount)	fee_amount	Reaches the bank (amount)
10000	10000 (£100.00$100.00€100.00)	99	9901 (£99.01$99.01€99.01)

At least £1.00$1.00€1.00 must reach the bank, so the least you can ask for is £1.01$1.01€1.01. The whole amount counts against your payout limits.

Ask	Answers
GET /v1/payouts/instant/quote?amount=10000	The fee, what arrives, and when (arrives). Or why not, and where to fix it
instant_payouts on GET /v1/payout_settings	Whether you can, why not, and largest_amount (the most you could ask for now, within your limits)
instant_payouts.destinations.bank	Usable or not, reason, message, fix_url (Ask for higher limits, the held-payout help article, or the bank account form) and, for a new account, available_from
instant_payouts.destinations.card_balance	UK only: the card balance as a destination, described before it can be used

curl

curl "https://api.tuppence.ai/v1/payouts/instant/quote?amount=5872" \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

Node

const quote = await tuppence.payouts.instantQuote({ amount: 5872 });
if (quote.available) {
  // £58.13 arrives within 30 minutes; the £0.59 fee comes out of the £58.72.
  await tuppence.payouts.create({ method: "instant", amount: quote.total_amount });
} else {
  console.log(quote.reason, quote.message, quote.fix_url, quote.available_from);
}

const quote = await tuppence.payouts.instantQuote({ amount: 5872 });
if (quote.available) {
  // $58.13 arrives within 30 minutes; the $0.59 fee comes out of the $58.72.
  await tuppence.payouts.create({ method: "instant", amount: quote.total_amount });
} else {
  console.log(quote.reason, quote.message, quote.fix_url, quote.available_from);
}

const quote = await tuppence.payouts.instantQuote({ amount: 5872 });
if (quote.available) {
  // €58.13 arrives within 30 minutes; the €0.59 fee comes out of the €58.72.
  await tuppence.payouts.create({ method: "instant", amount: quote.total_amount });
} else {
  console.log(quote.reason, quote.message, quote.fix_url, quote.available_from);
}

Python

quote = tuppence.payouts.instant_quote(amount=5872)
if quote.available:
    # £58.13 arrives within 30 minutes; the £0.59 fee comes out of the £58.72.
    tuppence.payouts.create(method="instant", amount=quote.total_amount)
else:
    print(quote.reason, quote.message, quote.fix_url, quote.available_from)

quote = tuppence.payouts.instant_quote(amount=5872)
if quote.available:
    # $58.13 arrives within 30 minutes; the $0.59 fee comes out of the $58.72.
    tuppence.payouts.create(method="instant", amount=quote.total_amount)
else:
    print(quote.reason, quote.message, quote.fix_url, quote.available_from)

quote = tuppence.payouts.instant_quote(amount=5872)
if quote.available:
    # €58.13 arrives within 30 minutes; the €0.59 fee comes out of the €58.72.
    tuppence.payouts.create(method="instant", amount=quote.total_amount)
else:
    print(quote.reason, quote.message, quote.fix_url, quote.available_from)

Next-day payouts (UK)

Next-day payouts are UK only. On a US account, next_day.available is always false, with reason: region and no message, and POST /v1/payout_settings/next_day is refused with region_unavailable.

Next-day payouts are UK only. On a European account, next_day.available is always false, with reason: region and no message, and POST /v1/payout_settings/next_day is refused with region_unavailable.

A UK business on standard can switch itself to next-day: each payment taken from then on can be paid out the following day, for +0.20% per payment (Pricing).

Case	Next-day fee	settlement_days
UK card	+0.20%, added to the card rate before the one round-up: £100.00 on a UK consumer card is 0.79% + 0.20% = 99p, in the same application_fee_amount, with a payout.next_day part in its fee breakdown	1
Card issued outside the UK	None (they can’t be paid out faster)	3
Bacs Direct Debit	None (fee_breakdown.next_day_unavailable: method)	The account’s usual
Covered by fee-free processing	None (the allowance covers the next-day part too)	As above, by card
Taken before it was switched on or off	Keeps the speed and fee it was taken with	unchanged

When it opens

It opens once the account is in the UK, has seasoned (standard), two weeks have passed since the UTC day of its first payment, payouts are approved, nothing is on hold, the balance isn’t negative and the account isn’t in Probation. In live mode it’s also behind Tuppence’s own switch during rollout. Each mode has its own clock.

Until it first opens, it’s hidden: available: false with reason not_yet, region or flag_off, and no message. Owners and admins are emailed the day it opens. After that it’s never hidden: if a hold makes the account ineligible, message says why and fix_url links to the fix.

next_day on GET /v1/payout_settings:

Field
available	true when every rule above holds
reason	Why not, when available is false
message	One line for the business, or null (always null while hidden)
fix_url	Where the business fixes it, or null where it only has to wait
available_from	When the reason clears by itself (Unix seconds), where it does
enabled	Next-day is on now
source	upgrade (switched on by the business) or staff (agreed with Tuppence)
fee_bps	While on, the rate locked when it was switched on: 20 at today’s price, or what was agreed. While off, the rate switching on now would lock (null while hidden)
since, ends_at	When it came into force, and when an agreed one ends (null: no end)
agreed_message	What Tuppence said when it switched next-day on for the business, or null
ended	While off, the last time it stopped: at, cause (switched_off, suspended, revoked, ended) and note
typical_amount, typical_fee	The worked example: the median of the last 30 days’ payments (50.00 with fewer than five) and its next-day fee, rounded up

Switch it on or off

curl

curl https://api.tuppence.ai/v1/payout_settings/next_day \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY" \
  -H "Idempotency-Key: next-day-on-1" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Node

const { next_day } = await tuppence.payouts.settings();
if (next_day.available) await tuppence.payouts.setNextDay({ enabled: true });

Python

settings = tuppence.payouts.settings()
if settings.next_day.available:
    tuppence.payouts.set_next_day(enabled=True)

POST /v1/payout_settings/next_day takes {"enabled": true} or {"enabled": false} and answers with next_day as above.

Who	A key with payouts:write; in the dashboard, an owner or admin (Balance → Payout speed)
Idempotent	Send an Idempotency-Key. On when on, or off when off, changes nothing and succeeds
On	Tuppence sets the processor’s delay to one day first, then puts next-day in force, so you’re never charged for speed you aren’t getting
Off	In force at once for new payments (three days, no fee); the processor’s delay follows
403 next_day_unavailable	Can’t be switched on now: same reason, message, available_from, fix_url as next_day; nothing changes
409 next_day_unavailable, reason: stripe_refused	The card processor didn’t accept the new delay; nothing changed. Try again
400 region_unavailable	A US or European account
410 use_payout_settings	The old POST /v1/settlement_requests is gone

Tuppence switches a self-serve upgrade off, and tells the business why, if payouts go on hold, the account goes back to Probation, or it goes 90 days without a payment. The business can switch it on again once it reopens.

When your balance goes below zero

A dispute or refunds can take more than your balance holds. Payouts wait while it’s below zero, and the shortfall is collected from the bank account you’re paid out to: within three working days in the UK, the next working day in the US. Your balance is back at zero as soon as the debit is made.

Each debit is a bank_debit (GET /v1/bank_debits, with the payouts:read scope) and a negative_balance_debit balance transaction. If your bank refuses it, the debit is failed with a failure_code, a negative_balance_debit_failed balance transaction takes the amount back out, and we try again later. You receive bank_debit.created, bank_debit.paid and bank_debit.failed. Connected accounting software books each debit as a transfer from your bank account to your Tuppence account.

Your fees

GET /v1/account/pricing lists every price the account pays now: the card rate and surcharges, next-day and instant payouts, and the dispute fee. Each is from the public list or agreed with Tuppence, with the end date of any agreed price. The dashboard shows the same under Settings → Your fees. For a price of your own, talk to us.

curl

curl https://api.tuppence.ai/v1/account/pricing \
  -H "Authorization: Bearer $TUPPENCE_SECRET_KEY"

Node

const { prices } = await tuppence.account.retrievePricing();
for (const p of prices) console.log(p.type, p.bps, p.fixed, p.source, p.ends_at);

Python

for p in tuppence.account.retrieve_pricing().prices:
    print(p.type, p.bps, p.fixed, p.source, p.ends_at)

Next

• Payouts and limits for new accounts
• Pricing