Payouts

Update Saved Payout Method

Changed on

Changes the label used to identify a saved payout method or makes it the account's default payout method.

patch/payouts/methods/{id}

Request

  • Base URL: https://api.whop.com/api/v1
  • URL: https://api.whop.com/api/v1/payouts/methods/{id}
  • Auth: HTTP bearer

Request body

is_defaulttrue

Set to true to make this the account's default payout method. false is not accepted.

nicknamestring

New label for the payout method, with at least one non-whitespace character and a maximum of 100 characters.

Example request

{
  "is_default": true,
  "nickname": "Primary checking"
}

Response

payout method updated

account_referencestring nullable required

Masked identifier for the destination.

bank_verification_state'checking' | 'verified' | 'no_data' | 'warning' | 'broken' | 'null' nullable required

Lifecycle trust state: checking (verification still running), verified (bank confirmed ownership or a payout already completed to it), no_data (verification unavailable or bank returned no ownership data), warning (bank could not confirm the destination's owner), broken (payouts failed with a permanent account error), null (never checked).

created_atstring date-time required
destination_currencystring required
estimated_arrivalobject nullable required

null after an update. List payout methods to retrieve arrival estimates.

fee_structureobject nullable required

null after an update. List payout methods to retrieve the configured fee terms.

idstring required

Payout method ID, prefixed potk_.

institution_namestring nullable required
is_cloneboolean required

Whether this method is a copy of one saved on another of the payer's accounts.

is_defaultboolean required
last_paid_out_atstring date-time nullable required

When the most recent completed payout was delivered to this method, as an ISO 8601 timestamp. null when nothing has been paid out to it yet.

linked_via_plaidboolean required

Whether the payer added this method by signing in to their bank rather than typing account details.

needs_plaid_reconnectboolean required

Whether the bank sign-in behind this method has expired and must be redone before it counts as linked.

nicknamestring nullable required

User-defined label for the payout method.

object'payout_method' required
payer_namestring nullable required
quoteobject nullable required

Always null after an update.

status'created' | 'active' | 'broken' required

created — saved, no payout has completed through it yet. active — a payout through it completed. broken — a payout through it failed with an error attributable to the method, and it no longer accepts payouts; a later successful payout returns it to active.

status_reasonstring nullable required

Machine-readable code for why the method is broken — the newest failure recorded through it, whether a payout error or a pre-payout rejection. null unless the method is broken, or when it was disabled without a recorded failure.

unavailable_reason'destination_retired' | 'null' nullable required

Why this method is unavailable: destination_retired means the payout provider stopped offering the destination. Whop may automatically remap an eligible method that was not linked through Plaid to a compatible replacement; otherwise, the account owner must re-add it. null means no unavailability reason is known.

Example response

{
  "account_reference": "••••0472",
  "bank_verification_state": "checking",
  "created_at": "2026-01-01T12:00:00.000Z",
  "destination_currency": "usd",
  "id": "potk_xxxxxxxxxxxxxx",
  "institution_name": "Frost Bank",
  "is_default": true,
  "nickname": "Primary checking",
  "object": "payout_method",
  "payer_name": "ACH Bank Deposit",
  "recipient": {
    "email": "jane.doe@example.com"
  },
  "status": "created",
  "supported_payout_method": {
    "country_code": "USA",
    "delivery_type": "bank_deposit",
    "icon_url": "https://whop-assets-example.s3.amazonaws.com/uploads/image/2026-01-01/ach-bank-deposit-icon",
    "name": "ACH Bank Deposit",
    "supports_plaid": true,
    "supports_standard_delivery": true
  },
  "unavailable_reason": "destination_retired"
}

Changes

  • a66448c54b9dRevision changes
    • breaking

      removed the required property / from the response with the status

    • info

      added the required property / to the response with the status

  • 29f35a260bbfRevision changes
    • info

      added the optional property to the response with the status