Payments

Refund Payment

Changed on

Refunds all or part of a payment through the processor that charged it, and updates its membership to match. The buyer is emailed, the affiliate commission on the payment is clawed back, and any open Resolution Center case on the payment is closed.

post/payments/{id}/refund

Request

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

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

partial_amountnumber nullable

The amount to refund, stated in this payment's currency like every other amount on it. When the buyer was billed in a different currency, it is converted at the payment's own exchange rate before the refund is issued. An amount that covers everything still refundable refunds the rest of the payment — omit it to refund the rest without having to work out what that is.

Example request

{
  "partial_amount": 49
}

Response

payment refunded

account_idstring nullable required

The account that received the payment, prefixed biz_.

auto_refundedboolean required

True when Whop refunded the payment automatically, for example on a dispute alert.

billing_reason'subscription_create' | 'subscription_cycle' | 'subscription_update' | 'one_time' | 'manual' | 'subscription' required

The reason why a specific payment was billed

checkout_configuration_idstring nullable required

The checkout configuration the buyer paid through, prefixed ch_, or null.

client_secretstring nullable required

The credential a buyer's surface presents to poll this payment, set its return URL and resume it when the bank asked the customer to authenticate. Only on payments created from a confirmation token or waiting on that authentication, and always null in list responses — retrieve the payment for it.

created_atstring required

When the payment was created, as an ISO 8601 timestamp.

currency'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau' required

The available currencies on the platform

customer_emailstring nullable required

The buyer's email address. Null without member:email:read on the account or when the buyer has no assigned email.

customer_phonestring nullable required

The phone number the buyer gave at checkout, when one was collected.

decline_code'insufficient_funds' | 'lost_card' | 'stolen_card' | 'expired_card' | 'suspected_fraud' | 'invalid_card_number' | 'invalid_cvc' | 'invalid_cvc_or_expiration' | 'incorrect_pin' | 'authentication_required' | 'card_not_supported' | 'currency_not_supported' | 'duplicate_transaction' | 'generic_decline' | 'invalid_account' | 'invalid_amount' | 'processing_error' | 'restricted_card' | 'card_velocity_exceeded' | 'contact_issuer' | 'card_declined_by_issuer' | 'bank_declined' | 'regulatory_blocked' | 'transaction_not_permitted' | 'transaction_stopped' | 'card_type_not_supported' | 'issuer_not_found' | 'closed_account' | 'issuer_unavailable' | 'invalid_zip' | 'invalid_expiry_month' | 'invalid_expiry_year' | 'invalid_expiry' | 'invalid_transaction' | 'cannot_authorize' | 'pin_required' | 'pin_try_exceeded' | 'provider_declined' | 'high_risk' | 'test_mode_decline' | 'merchant_blacklist' | 'reenter_transaction' | 'invalid_pin' | 'pin_required_as' | 'withdrawal_count_limit_exceeded' | 'invalid_country' | 'issuer_error' | 'invalid_card_holder_name' | 'no_accounts' | 'transaction_cancelled' | 'three_d_secure_success' | 'three_d_secure_canceled' | 'three_d_secure_invalid_card_number' | 'three_d_secure_generic_error' | 'three_d_secure_timeout' | 'three_d_secure_failed' | 'three_d_secure_card_not_enrolled' | 'three_d_secure_fraud' | 'three_d_secure_too_many_attempts' | 'three_d_secure_rejected_by_bank' | 'three_d_secure_reported_lost_or_stolen' | 'blocked_by_cardholder' | 'test_mode_test_card' | 'try_again_later' | 'transaction_not_allowed' | 'bank_insufficient_funds' | 'bank_account_not_found' | 'bank_account_closed' | 'bank_account_frozen' | 'bank_invalid_routing_number' | 'bank_non_transaction_account' | 'bank_authorization_revoked' | 'bank_payment_stopped' | 'bank_not_authorized' | 'bank_account_holder_deceased' | 'bank_duplicate' | 'bank_amount_error' | 'bank_regulatory_blocked' | 'bank_details_invalid' | 'bank_processing_error' | 'bank_generic_decline' | 'sepa_invalid_iban' | 'sepa_no_mandate' | 'sepa_mandate_data_invalid' | 'sepa_disputed' | 'sepa_refused_by_customer' | 'sepa_generic_decline' required

The reason a payment was declined.

dispute_alerted_atstring nullable required

When an issuer warned that this payment will be disputed, or null.

failure_messagestring nullable required

Why the most recent attempt failed, in plain words, or null.

financing_installments_countnumber nullable required

For installment methods, how many payments the charge splits into.

idstring required

Payment ID, prefixed pay_.

ip_addressstring nullable required

The buyer's IP address at checkout, as identified by Whop's fraud screening. Null when the payment was not screened at checkout, such as a subscription renewal or a charge made without the buyer present.

last_payment_attempt_atstring nullable required

When the most recent charge attempt ran, or null.

member_idstring nullable required

The buyer's member record on the account, prefixed mber_. Null without the member:basic:read permission.

membership_idstring nullable required

The membership this payment is billed against, prefixed mem_. Null for one-off purchases or without the member:basic:read permission.

metadataobject nullable required

Your own key-value data attached when the payment was created.

needs_trackingboolean nullable required

True when funds are held until the order ships and no tracking number has been added yet. Null without the shipment:basic:read permission.

next_payment_attempt_atstring nullable required

When the next automatic retry is scheduled, or null.

paid_atstring nullable required

When the money was collected, or null while it has not been.

payment_method_idstring nullable required

The stored payment method that was charged, prefixed payt_. Null when the method was not saved.

payment_method_type'acss_debit' | 'addi' | 'affirm' | 'afterpay_clearpay' | 'alipay' | 'alipayhk' | 'alma' | 'amazon_pay' | 'apple' | 'apple_pay' | 'au_bank_transfer' | 'au_becs_debit' | 'bacs_debit' | 'bancolombia' | 'bancontact' | 'bank_wire' | 'billie' | 'blik' | 'boleto' | 'bre_b' | 'ca_bank_transfer' | 'capchase_pay' | 'card' | 'card_present' | 'card_installments_three' | 'card_installments_six' | 'card_installments_twelve' | 'cashapp' | 'claritypay' | 'coinbase' | 'crypto' | 'custom' | 'customer_balance' | 'demo_pay' | 'duitnow_qr' | 'efecty' | 'eps' | 'eu_bank_transfer' | 'fpx' | 'flex_pay' | 'gb_bank_transfer' | 'gcash' | 'giropay' | 'google_pay' | 'gopay' | 'grabpay' | 'id_bank_transfer' | 'ideal' | 'interac' | 'kakao_pay' | 'klarna' | 'klarna_pay_now' | 'konbini' | 'kr_card' | 'kr_market' | 'kriya' | 'kueski' | 'link' | 'mb_way' | 'm_pesa' | 'mercado_pago' | 'mercado_pago_ar' | 'mercado_pago_mx' | 'mobilepay' | 'modo' | 'mondu' | 'multibanco' | 'naver_pay' | 'nequi' | 'netbanking' | 'ng_bank' | 'ng_bank_transfer' | 'ng_card' | 'ng_market' | 'ng_ussd' | 'ng_wallet' | 'nupay' | 'nz_bank_account' | 'oney' | 'oney_3x' | 'oney_4x' | 'opay' | 'oxxo' | 'p24' | 'pago_efectivo' | 'pse' | 'pay_by_bank' | 'payco' | 'paynow' | 'paypal' | 'paypal_express' | 'paypay' | 'payto' | 'payto_email' | 'payto_phone' | 'payto_bank_account' | 'pix' | 'platform_balance' | 'promptpay' | 'qris' | 'rapipago' | 'rechnung' | 'revolut_pay' | 'samsung_pay' | 'satispay' | 'scalapay' | 'sencillito' | 'sepa_debit' | 'sequra' | 'servipag' | 'sezzle' | 'shop_pay' | 'shopeepay' | 'sofort' | 'south_korea_market' | 'spei' | 'splitit' | 'sunbit' | 'swish' | 'tabby' | 'tamara' | 'touch_n_go' | 'twint' | 'upi' | 'us_bank_account' | 'us_bank_transfer' | 'venmo' | 'verve' | 'vipps' | 'webpay' | 'wechat_pay' | 'whop_pay' | 'yape' | 'zip' | 'coinflow' | 'unknown' required

The different types of payment methods that can be used.

payments_failednumber required

How many charge attempts have failed on this payment.

plan_idstring nullable required

The variant that was charged, prefixed plan_.

product_idstring nullable required

The product the variant belongs to, prefixed prod_. Null for a variant with no product.

promo_code_idstring nullable required

The promo code applied at checkout, prefixed promo_, or null.

quote_idstring nullable required

The payment quote this payment charged, prefixed pq_: its purchase, promo code and tax_amount are the quote's. Null when the payment named no quote and tax was calculated at charge time.

recovery_urlstring nullable required

Whop-hosted URL where the buyer can sign in and complete 3D Secure for an off-session charge the bank challenged — a subscription renewal or a saved-card payment. Null when recovery is unavailable, you lack member:basic:read, or in list responses. Retrieve the payment for it.

refundableboolean required

True when the payment is paid, not yet fully refunded, and its processor supports refunds.

refunded_atstring nullable required

When the payment was refunded, or null.

retryableboolean required

True when the payment is open and Whop can attempt the charge again — see POST /payments/{id}/retry.

risk_scorenumber nullable required

Whop's published risk index from 0 (lowest) to 100 (highest), including enforced decision floors. This is not a fraud probability. Null when no score is available.

risk_signalsobject nullable required

Deprecated. Risk score explanations are no longer provided; always null. DEPRECATED: Risk score explanations are no longer provided. Always null.

settlement_time_atstring nullable required

When the portion not listed in holds posts to the account's available balance, at midnight UTC. The financial_activity.funds_available webhook's posted_at carries the same value when the settlement that clears it posts. Null until the payment is paid, and always null in list responses — retrieve the payment for it.

shipment_idstring nullable required

The shipment fulfilling this payment, prefixed ship_. Null when nothing ships or without the shipment:basic:read permission.

status'draft' | 'open' | 'authorized' | 'paid' | 'pending' | 'uncollectible' | 'unresolved' | 'void' required

The status of a receipt

substatus'succeeded' | 'requires_capture' | 'pending' | 'failed' | 'blocked' | 'past_due' | 'canceled' | 'price_too_low' | 'uncollectible' | 'refunded' | 'auto_refunded' | 'partially_refunded' | 'dispute_warning' | 'dispute_needs_response' | 'dispute_warning_needs_response' | 'resolution_needs_response' | 'dispute_under_review' | 'dispute_warning_under_review' | 'resolution_under_review' | 'dispute_won' | 'dispute_warning_closed' | 'resolution_won' | 'dispute_lost' | 'dispute_closed' | 'resolution_lost' | 'drafted' | 'incomplete' | 'unresolved' | 'open_dispute' | 'open_resolution' required

The friendly status of a payment. This is a derived status that provides a human-readable summary of the payment state, combining the underlying status and substatus fields.

tax_behavior'exclusive' | 'inclusive' | 'unspecified' | 'unable_to_collect' required

The type of tax inclusivity applied to the receipt, for determining whether the tax is included in the final price, or paid on top.

three_ds_verifiedboolean required

True when the buyer completed 3D Secure for this payment.

updated_atstring required

When the payment last changed, as an ISO 8601 timestamp.

voidableboolean required

True when the payment can be voided or canceled. The request is rejected if the payment is no longer eligible — see POST /payments/{id}/void.

Example response

{
  "account_id": "biz_xxxxxxxxxxxxxx",
  "amount_after_fees": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "billing_address": {
    "city": "Austin",
    "country": "US",
    "line1": "1114 Bouldin Ave",
    "line2": "Unit B",
    "name": "Dana Whitfield",
    "postal_code": "78704",
    "state": "TX"
  },
  "billing_reason": "subscription_create",
  "client_secret": "pay_xxxxxxxxxxxxxx_secret_vdefault_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "created_at": "2026-01-01T12:00:00.000Z",
  "currency": "usd",
  "customer_email": "marcus@shinetime.example",
  "customer_phone": "+xxxxxxxxxxx",
  "decline_code": "insufficient_funds",
  "holds": [
    {
      "amount": {
        "amount": "-1234.56",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      },
      "type": "reserve"
    }
  ],
  "id": "pay_xxxxxxxxxxxxxx",
  "line_items": [
    {
      "id": "li_xxxxxxxxxxxxxx",
      "label": "Ceramic Coating Package",
      "plan_id": "plan_xxxxxxxxxxxxxx",
      "plan_title": "Ceramic Coating — Full Vehicle",
      "product_id": "prod_xxxxxxxxxxxxxx",
      "product_title": "Ceramic Coating Package",
      "quantity": 1,
      "subtotal": {
        "amount": "-1234.56",
        "currency": "usd",
        "decimals": 2,
        "display_decimals": 2
      }
    }
  ],
  "member_id": "mber_xxxxxxxxxxxxxx",
  "membership_id": "mem_xxxxxxxxxxxxxx",
  "metadata": {
    "order_ref": "SHINE-4417"
  },
  "paid_at": "2026-01-01T12:00:00.000Z",
  "payment_instrument": {
    "card": {
      "brand": "visa",
      "exp_month": 10,
      "exp_year": 2031,
      "issuer_identification_number": "41111111",
      "last4": "4242"
    },
    "display_name": "Visa •••• 4242",
    "icons": {
      "card": {
        "dark": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        },
        "light": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        }
      },
      "square": {
        "dark": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        },
        "light": {
          "png_1x": "https://content.whop.com/payment_methods/visa/icons/card_dark_30.png",
          "png_2x": "https://content.whop.com/payment_methods/visa/icons/card_dark_60.png",
          "png_4x": "https://content.whop.com/payment_methods/visa/icons/card_dark_120.png",
          "svg": "https://content.whop.com/payment_methods/visa/icons/card_dark.svg"
        }
      }
    },
    "payment_method_type": "card"
  },
  "payment_method_id": "payt_xxxxxxxxxxxxxx",
  "payment_method_type": "acss_debit",
  "payment_rule_matches": [
    {
      "action": "allow"
    }
  ],
  "plan_id": "plan_xxxxxxxxxxxxxx",
  "presentment_total": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "product_id": "prod_xxxxxxxxxxxxxx",
  "refunded_amount": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "retryable": true,
  "shipping_address": {
    "city": "Austin",
    "country": "US",
    "line1": "1114 Bouldin Ave",
    "line2": "Unit B",
    "name": "Dana Whitfield",
    "postal_code": "78704",
    "state": "TX"
  },
  "status": "draft",
  "substatus": "succeeded",
  "subtotal": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "tax_amount": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "tax_behavior": "exclusive",
  "tax_refunded_amount": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "total": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "updated_at": "2026-01-01T12:00:00.000Z",
  "usd_total": {
    "amount": "-1234.56",
    "currency": "usd",
    "decimals": 2,
    "display_decimals": 2
  },
  "user": {
    "id": "user_xxxxxxxxxxxxxx",
    "name": "Dana Whitfield",
    "profile_picture": {
      "url": "https://ui-avatars.com/api/"
    },
    "username": "danawhitfield"
  },
  "verification_checks": {
    "address_line1": "PASS",
    "arn": "74123456789",
    "authorization_code": "A1B2C3",
    "card_holder_name": "PASS",
    "card_security_code": "PASS",
    "zip_code": "PASS"
  }
}

Changes

  • 507636677fe9Revision changes
    • warning

      added the new payto_bank_account enum value to the //// response property for the response status

    • warning

      added the new payto_email enum value to the //// response property for the response status

    • warning

      added the new payto_phone enum value to the //// response property for the response status

    • info

      added the required property to the response with the status

  • 7d2eaa643369Revision changes
    • breaking

      removed the required property from the response with the status