API REFERENCE

Remove the payment method

On this page

DELETE/api/accounts/{id}/payment-method

Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. id may be the authenticated account or an organization the caller belongs to.

Other cards remain attached. A later GET /api/accounts/{id}/payment-method can return another remaining card; removal does not guarantee card: null or checkout-only purchases. A later explicitly requested credit purchase can use a remaining card, while an account with no card uses checkout. Removal does not turn automatic top-ups back on; enabling them again requires an explicit settings update.

The API saves auto_topup_enabled: false before detaching the selected card. If saving that setting fails, no card is detached. If settings are saved but detachment fails, automatic top-ups remain off and the request returns 500. Both failures return the same generic error, so read the payment method and auto-top-up settings to determine the current state. A missing customer or selected card returns 404 without changing settings or cards.

After an error or uncertain response, reread both states before deciding whether to retry. A successful removal may expose another selected card, so blindly repeating DELETE can remove a different card. Removal preserves balances, configured top-up amounts and thresholds, and other saved cards. It does not cancel subscriptions, invoices, a charge already in progress, or a concurrent explicit settings update.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request DELETE \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/payment-method' \
  --header 'x-api-key: YOUR_API_KEY'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

idpath · stringrequired

cURL for this request

curl --request DELETE \
  --url 'https://api.recoupable.dev/api/accounts/{id}/payment-method'

Parameters

Path parameters

idstringrequired

The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.

Responses

204Automatic top-ups are off and the selected card is detached; no response body.

No response body schema is specified.

400Invalid account id; no billing changes are performed.

application/json

errorstringrequired

Human-readable error message.

Example: "Unauthorized"

400 example

{
  "error": "id must be a valid UUID"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

Example: "Unauthorized"

401 example

{
  "error": "Unauthorized"
}

403Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)

application/json

errorstringrequired

Human-readable error message.

Example: "Unauthorized"

404No tagged Stripe customer or selected card exists. Settings and cards are unchanged.

application/json

errorstringrequired

Human-readable error message.

Example: "Unauthorized"

404 example

{
  "error": "No payment method on file"
}

500Unable to complete card removal. Automatic top-ups may already be off; read the card and settings before retrying.

application/json

errorstringrequired

Human-readable error message.

Example: "Unauthorized"

500 example

{
  "error": "Internal server error"
}

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download accounts.json

View operation source

json

{
  "operationId": "deleteAccountsByIdPaymentMethod",
  "description": "Turn off automatic credit top-ups for the authorized account, then detach its selected default card. This removes one card selected from the account's tagged Stripe customers; it does not delete every saved card. A successful request returns 204 with no response body. `id` may be the authenticated account or an organization the caller belongs to.\n\nOther cards remain attached. A later `GET /api/accounts/{id}/payment-method` can return another remaining card; removal does not guarantee `card: null` or checkout-only purchases. A later explicitly requested credit purchase can use a remaining card, while an account with no card uses checkout. Removal does not turn automatic top-ups back on; enabling them again requires an explicit settings update.\n\nThe API saves `auto_topup_enabled: false` before detaching the selected card. If saving that setting fails, no card is detached. If settings are saved but detachment fails, automatic top-ups remain off and the request returns 500. Both failures return the same generic error, so read the payment method and auto-top-up settings to determine the current state. A missing customer or selected card returns 404 without changing settings or cards.\n\nAfter an error or uncertain response, reread both states before deciding whether to retry. A successful removal may expose another selected card, so blindly repeating DELETE can remove a different card. Removal preserves balances, configured top-up amounts and thresholds, and other saved cards. It does not cancel subscriptions, invoices, a charge already in progress, or a concurrent explicit settings update.",
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "description": "The unique identifier (UUID) of the account. Must be the authenticated account or another accessible via organization membership.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "204": {
      "description": "Automatic top-ups are off and the selected card is detached; no response body."
    },
    "400": {
      "description": "Invalid account id; no billing changes are performed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "id must be a valid UUID"
          }
        }
      }
    },
    "401": {
      "description": "Unauthorized - invalid or missing authentication",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "Unauthorized"
          }
        }
      }
    },
    "403": {
      "description": "Forbidden - the account is not the caller's and not an organization they belong to (an unknown id also returns 403, never 404)",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          }
        }
      }
    },
    "404": {
      "description": "No tagged Stripe customer or selected card exists. Settings and cards are unchanged.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "No payment method on file"
          }
        }
      }
    },
    "500": {
      "description": "Unable to complete card removal. Automatic top-ups may already be off; read the card and settings before retrying.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "Internal server error"
          }
        }
      }
    }
  }
}

Get started with Recoup.

Try Our Platform

Build Your Platform

Remove the payment method

Authentication

Request

Try it

Parameters

Path parameters

Responses

Full specification