API REFERENCE

Get Default Payment Method

On this page

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

Retrieve the default payment method on file for an account. Returns card: null when no payment method has been saved yet — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (card: null). Cards are returned even when expired; callers should compare exp_month / exp_year against the current date and warn the customer, since an off-session charge against an expired card will decline.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request GET \
  --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.

Parameters

Path parameters

idstringrequired

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

Responses

200Default payment method retrieved successfully (may be null if none on file).

application/json

account_idstringrequired

The unique identifier of the account this payment method belongs to.

format: uuid

cardone ofrequired

Default card on file. null when the account has never saved a payment method — the top-up flow will route through a checkout session in that case.

Properties

oneOf · SavedCard 1

brandstringrequired

Card brand. Common values: visa, mastercard, amex, discover, diners, jcb, unionpay, unknown.

last4stringrequired

Last four digits of the card number. Safe to display in UI for identification.

pattern: ^\d{4}$

exp_monthintegerrequired

Card expiration month (1-12). Compare against the current month to detect expired cards.

minimum: 1 · maximum: 12

exp_yearintegerrequired

Card expiration year (full 4-digit year). Compare against the current year to detect expired cards.

fundingstringrequired

Funding type. Common values: credit, debit, prepaid, unknown.

oneOf · null 2

null

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.

Full specification

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

Download accounts.json

View operation source

json

{
  "description": "Retrieve the default payment method on file for an account. Returns `card: null` when no payment method has been saved yet — the top-up dialog uses this to decide whether to show a pre-charge confirmation (card present) or route to a checkout session to collect one (`card: null`). Cards are returned even when expired; callers should compare `exp_month` / `exp_year` against the current date and warn the customer, since an off-session charge against an expired card will decline.",
  "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": {
    "200": {
      "description": "Default payment method retrieved successfully (may be `null` if none on file).",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountPaymentMethodResponse"
          }
        }
      }
    },
    "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"
          }
        }
      }
    }
  }
}