THthredfi
Payouts

Create or update a payout

Create a new payout or update an existing one via external_id. Partners send completed processor settlements (Stripe, Adyen, etc.) with associated invoice payments and refund payments. Returns 201 for new payouts, 200 for updates. Updates are blocked if payout is already reconciled to a bank transaction.

post/v1/platform/businesses/{business_id}/payouts/

Request

  • Base URL
    https://docs.thredfi.com (the document declares no server; this is the origin it was published from)
  • Auth
    • HTTP bearer
    • or HTTP bearer
    • or HTTP basic
    • or HTTP bearer
    • or HTTP bearer

Path parameters

business_idstring uuid required

Business UUID (unique identifier for the business)

Request body

external_idstring required

Partner's unique payout ID (idempotency key)

processor'stripe' | 'paypal' | 'square' | 'adyen' | 'worldpay' | 'sage_pay' | 'klarna' | 'other' required

Payment processor (stripe, adyen, paypal, etc.)

  • stripe - Stripe
  • paypal - PayPal
  • square - Square
  • adyen - Adyen
  • worldpay - Worldpay
  • sage_pay - Sage Pay
  • klarna - Klarna
  • other - Other
processor_payout_idstring

Processor's payout ID reference

paid_out_amount_centsinteger required

Net payout amount in cents (can be negative if refunds exceed payments)

fee_centsinteger required

Processor fee charged in cents (must be >= 0)

additional_refunds_amount_centsinteger

Additional refunds not tied to specific RefundPayment records in cents

currency'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD' required

Payout currency (ISO 4217)

  • EUR - EUR
  • GBP - GBP
  • USD - USD
  • SEK - SEK
  • NOK - NOK
  • DKK - DKK
  • ISK - ISK
  • MYR - MYR
  • SGD - SGD
status'pending' | 'processing' | 'paid' | 'failed' | 'cancelled' required

Payout status (must be 'paid')

  • pending - Pending
  • processing - Processing
  • paid - Paid
  • failed - Failed
  • cancelled - Cancelled
completed_atstring date-time required

When payout was completed (ISO 8601)

payment_idsstring[]

List of Payment UUIDs included in this payout

refund_payment_idsstring[]

List of RefundPayment UUIDs included in this payout

reference_numberstring

User-visible payout reference number

memostring

Internal memo or notes

metadataunknown

Response

idstring uuid required
business_idstring uuid required
external_idstring
processor'stripe' | 'paypal' | 'square' | 'adyen' | 'worldpay' | 'sage_pay' | 'klarna' | 'other' | '' required
  • stripe - Stripe
  • paypal - PayPal
  • square - Square
  • adyen - Adyen
  • worldpay - Worldpay
  • sage_pay - Sage Pay
  • klarna - Klarna
  • other - Other
processor_payout_idstring required
paid_out_amount_centsinteger required

Net payout amount in cents (can be negative)

fee_centsinteger
additional_refunds_amount_centsinteger

Additional refunds not tied to specific RefundPayment records

net_amount_centsinteger required

Net amount: paid_out_amount - fee

currency'EUR' | 'GBP' | 'USD' | 'SEK' | 'NOK' | 'DKK' | 'ISK' | 'MYR' | 'SGD'
  • EUR - Euro
  • GBP - British Pound
  • USD - US Dollar
  • SEK - Swedish Krona
  • NOK - Norwegian Krone
  • DKK - Danish Krone
  • ISK - Icelandic Króna
  • MYR - Malaysian Ringgit
  • SGD - Singapore Dollar
status'pending' | 'processing' | 'paid' | 'failed' | 'cancelled'
  • pending - Pending
  • processing - Processing
  • paid - Paid
  • failed - Failed
  • cancelled - Cancelled
completed_atstring date-time nullable
imported_atstring date-time required
reference_numberstring
memostring
metadataunknown
payment_countinteger required

Number of payments in this payout

refund_payment_countinteger required

Number of refund payments in this payout

gross_payments_amount_centsinteger required

Total amount of invoice payments before refunds

total_refunds_amount_centsinteger required

Total amount of refund payments in cents

expected_net_amount_centsinteger required

Expected net: payments - refunds - additional_refunds - fees

amount_variance_centsinteger required

Difference between reported and expected net (for debugging)

reconciliation_status'unreconciled' | 'partially_reconciled' | 'fully_reconciled' required

Reconciliation state

  • unreconciled - Unreconciled
  • partially_reconciled - Partially Reconciled
  • fully_reconciled - Fully Reconciled
settlement_file_idstring uuid nullable required

Settlement file UUID if attached

created_atstring date-time required
updated_atstring date-time required

Changes

No recorded changes to this operation across all 1 revision of this API.