API REFERENCE

Save a Payment Method

On this page

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

Create a $0 card-on-file checkout session for an account. Stripe setup mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The account's Stripe customer is created (and tagged with the account id) if it does not exist yet. Returns a hosted checkout URL that the client should redirect to. id may be the authenticated account or an organization the caller belongs to.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request POST \
  --url 'https://api.recoupable.dev/api/accounts/YOUR_ID/payment-method' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "successUrl": "https://chat.recoupable.dev?card=saved"
}'

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

Request bodyapplication/json

cURL for this request

curl --request POST \
  --url 'https://recoup-api.vercel.app/api/accounts/{id}/payment-method' \
  --header 'Content-Type: application/json' \
  --data '{
  "successUrl": "https://chat.recoupable.dev?card=saved"
}'

Parameters

Path parameters

idstringrequired

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

Request body required

Card-on-file session parameters

application/json

successUrlstringrequired

The URL Stripe redirects to after the card is saved.

format: uri

Responses

200Card-on-file session created successfully

application/json

idstringrequired

The checkout session ID.

urlstringrequired

The hosted checkout URL. Redirect to this URL to complete Checkout.

format: uri

400Bad request - missing or invalid parameters

application/json

errorstringrequired

Human-readable error message.

400 example

{
  "error": "successUrl must be a valid URL"
}

401Unauthorized - invalid or missing authentication

application/json

errorstringrequired

Human-readable error message.

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.

500Internal server error

application/json

errorstringrequired

Human-readable error message.

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

{
  "description": "Create a $0 card-on-file checkout session for an account. Stripe `setup` mode saves a payment method without charging anything or starting a subscription; the saved card becomes the account's default and is what credit purchases and auto top-up charge. The account's Stripe customer is created (and tagged with the account id) if it does not exist yet. Returns a hosted checkout URL that the client should redirect to. `id` may be the authenticated account or an organization the caller belongs to.",
  "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": []
    }
  ],
  "requestBody": {
    "description": "Card-on-file session parameters",
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CreateCardOnFileSessionRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Card-on-file session created successfully",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CreateSubscriptionSessionResponse"
          }
        }
      }
    },
    "400": {
      "description": "Bad request - missing or invalid parameters",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "successUrl must be a valid URL"
          }
        }
      }
    },
    "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"
          }
        }
      }
    },
    "500": {
      "description": "Internal server error",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodErrorResponse"
          },
          "example": {
            "error": "Internal server error"
          }
        }
      }
    }
  }
}