Skip to main content
POST
/
v1
/
platform
/
businesses
/
{business_id}
/
payouts
Create or update a payout
curl --request POST \
  --url https://sandbox.thredfi.com/v1/platform/businesses/{business_id}/payouts/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "external_id": "<string>",
  "processor": "stripe",
  "paid_out_amount_cents": 123,
  "fee_cents": 1,
  "currency": "EUR",
  "status": "pending",
  "completed_at": "2023-11-07T05:31:56Z",
  "processor_payout_id": "<string>",
  "additional_refunds_amount_cents": 0,
  "payment_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "refund_payment_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "reference_number": "<string>",
  "memo": "<string>",
  "metadata": "<unknown>"
}
'
{
  "id": "be90c3cc-7d18-4e2d-8e6e-9f5d7e4a5c3b",
  "business_id": "3c90c3cc-8c03-4c1a-9c7a-8e5c9a3b4f2d",
  "external_id": "stripe_po_2024_12_20",
  "processor": "stripe",
  "processor_payout_id": "po_1OeYZb2eZvKYlo2C6KqhQWxE",
  "paid_out_amount_cents": 920000,
  "fee_cents": 30000,
  "additional_refunds_amount_cents": 0,
  "net_amount_cents": 890000,
  "currency": "GBP",
  "status": "paid",
  "completed_at": "2024-12-20T14:30:45Z",
  "imported_at": "2024-12-20T15:00:12Z",
  "reference_number": "PAYOUT-2024-W51",
  "memo": "Weekly Stripe settlement",
  "metadata": {
    "batch_id": "w51"
  },
  "payment_count": 2,
  "refund_payment_count": 1,
  "gross_payments_amount_cents": 1000000,
  "total_refunds_amount_cents": 50000,
  "expected_net_amount_cents": 920000,
  "amount_variance_cents": 0,
  "payments": [
    {
      "id": "3c90c3cc-8c03-4c1a-9c7a-8e5c9a3b4f2d",
      "external_id": "stripe_pi_xyz123",
      "payment_reference": "PAY-2024-0042",
      "customer_name": "The Red Lion Pub Ltd",
      "payment_date": "2024-12-15",
      "total_amount_cents": 450000,
      "currency": "GBP"
    }
  ],
  "refund_payments": [
    {
      "id": "5e92e5ee-ae25-6e3c-be9c-ag7ebe5d6h4f",
      "external_id": "stripe_re_abc456",
      "refund_id": "6f03f6ff-bf36-7f4d-cf0d-bh8fcf6e7i5g",
      "customer_name": "The Red Lion Pub Ltd",
      "refunded_amount_cents": 50000,
      "completed_at": "2024-12-16T10:00:00Z"
    }
  ],
  "reconciliation_status": "unreconciled",
  "settlement_file_id": null,
  "created_at": "2024-12-20T15:00:12Z",
  "updated_at": "2024-12-20T15:00:12Z"
}

Authorizations

​
Authorization
string
header
required

Partner-level JWT token (unscoped). Token payload includes partner_id. Business access is validated via partner ownership. Format: Bearer <your-jwt-token>

Use this for: Multi-business operations where the business_id is specified in the URL and partner has access to multiple businesses.

Path Parameters

​
business_id
string<uuid>
required

Business UUID (unique identifier for the business)

Body

Serializer for creating or updating payouts All amounts in cents (integers)

​
external_id
string
required

Partner's unique payout ID (idempotency key)

Required string length: 1 - 255
​
processor
enum<string>
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
Available options:
stripe,
paypal,
square,
adyen,
worldpay,
sage_pay,
klarna,
other
​
paid_out_amount_cents
integer
required

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

​
fee_cents
integer
required

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

Required range: x >= 0
​
currency
enum<string>
required

Payout currency (ISO 4217)

  • EUR - EUR
  • GBP - GBP
  • USD - USD
  • SEK - SEK
  • NOK - NOK
  • DKK - DKK
  • ISK - ISK
  • MYR - MYR
  • SGD - SGD
Available options:
EUR,
GBP,
USD,
SEK,
NOK,
DKK,
ISK,
MYR,
SGD
​
status
enum<string>
required

Payout status (must be 'paid')

  • pending - Pending
  • processing - Processing
  • paid - Paid
  • failed - Failed
  • cancelled - Cancelled
Available options:
pending,
processing,
paid,
failed,
cancelled
​
completed_at
string<date-time>
required

When payout was completed (ISO 8601)

​
processor_payout_id
string

Processor's payout ID reference

Maximum string length: 255
​
additional_refunds_amount_cents
integer
default:0

Additional refunds not tied to specific RefundPayment records in cents

Required range: x >= 0
​
payment_ids
string<uuid>[]

List of Payment UUIDs included in this payout

​
refund_payment_ids
string<uuid>[]

List of RefundPayment UUIDs included in this payout

​
reference_number
string

User-visible payout reference number

Maximum string length: 100
​
memo
string

Internal memo or notes

​
metadata
any

Custom metadata (max 1KB JSON object)

Response

Full payout serializer for detail views and create responses Includes all computed fields and expanded payment/refund arrays

​
id
string<uuid>
required
​
business_id
string<uuid>
required
​
processor
enum<string>
required
  • stripe - Stripe
  • paypal - PayPal
  • square - Square
  • adyen - Adyen
  • worldpay - Worldpay
  • sage_pay - Sage Pay
  • klarna - Klarna
  • other - Other
Available options:
stripe,
paypal,
square,
adyen,
worldpay,
sage_pay,
klarna,
other,
​
processor_payout_id
string
required
Maximum string length: 255
​
paid_out_amount_cents
integer<int64>
required

Net payout amount in cents (can be negative)

Required range: -9223372036854776000 <= x <= 9223372036854776000
​
net_amount_cents
integer
required

Net amount: paid_out_amount - fee

​
imported_at
string<date-time>
required
​
payment_count
integer
required

Number of payments in this payout

​
refund_payment_count
integer
required

Number of refund payments in this payout

​
gross_payments_amount_cents
integer
required

Total amount of invoice payments before refunds

​
total_refunds_amount_cents
integer
required

Total amount of refund payments in cents

​
expected_net_amount_cents
integer
required

Expected net: payments - refunds - additional_refunds - fees

​
amount_variance_cents
integer
required

Difference between reported and expected net (for debugging)

​
payments
any[]
required

Expanded payment details

​
refund_payments
any[]
required

Expanded refund payment details

​
reconciliation_status
enum<string>
required

Reconciliation state

  • unreconciled - Unreconciled
  • partially_reconciled - Partially Reconciled
  • fully_reconciled - Fully Reconciled
Available options:
unreconciled,
partially_reconciled,
fully_reconciled
​
settlement_file_id
string<uuid> | null
required

Settlement file UUID if attached

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
external_id
string
Maximum string length: 255
​
fee_cents
integer<int64>
Required range: 0 <= x <= 9223372036854776000
​
additional_refunds_amount_cents
integer<int64>

Additional refunds not tied to specific RefundPayment records

Required range: 0 <= x <= 9223372036854776000
​
currency
enum<string>
  • 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
Available options:
EUR,
GBP,
USD,
SEK,
NOK,
DKK,
ISK,
MYR,
SGD
​
status
enum<string>
  • pending - Pending
  • processing - Processing
  • paid - Paid
  • failed - Failed
  • cancelled - Cancelled
Available options:
pending,
processing,
paid,
failed,
cancelled
​
completed_at
string<date-time> | null
​
reference_number
string
Maximum string length: 100
​
memo
string
​
metadata
any