CAcardda
Vendor card

Change card PIN

Sets a new 4-digit PIN on a physical card. Authorized for admins, holders of the vendor_cards_manage permission, or the cardholder.

The pin parameter is required (missing → 412, from params.require(:pin)). It must match ^\d\d\d\d$ and the card's vendor must support PIN updates; otherwise the endpoint returns 422 with { "error_code": "vendor_cards/pin_not_supported" }. Vendor-side failures return 500 with the vendor's message.

patch/v1/vendor_cards/{vendor_card_id}/pin

Request

  • Base URL
    https://api.cardda.com
  • URL
    https://api.cardda.com/v1/vendor_cards/{vendor_card_id}/pin
  • Auth
    HTTP bearer

Path parameters

vendor_card_idstring required

The id of the vendor card

Parameters

#/paths/~1v1~1merchants/get/parameters/0 (unresolved $ref)

Request body

pinstring required

The new 4-digit PIN. Must match ^\d\d\d\d$. Only cards whose vendor supports PIN updates accept this; others return 422.

Example request

{
  "pin": "1234"
}

Response

The vendor card, after the PIN was updated.

idstring

Card id. Cardda card ids are vendor-prefixed base64-encoded strings (e.g. Q2FyZDoxMDIwNjQ5Mw==), not UUIDs.

user_idstring

Firebase user id of the cardholder (not a UUID).

company_idstring uuid
type'AptoCard' | 'BrexCard' | 'Cards::Increase::Card' | 'Cards::Plh::Card' | 'DivvyCard' | 'Issuing::Relay::Card' | 'Issuing::Slash::Card' | 'MercuryCard' | 'MeshCard' | 'PomeloCard' | 'StripeCard'

Single Table Inheritance discriminator (issuing vendor / STI sub-class). A persisted column, so it always serializes into the row for every caller.

namestring
last4string
status'active' | 'inactive' | 'pending' | 'canceled'
status_preferencestring
migratedboolean
usageinteger nullable
limit_interval'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization'

Current spending limit interval.

limit_interval_preference'daily' | 'weekly' | 'monthly' | 'yearly' | 'all_time' | 'per_authorization' nullable

Requested spending limit interval.

allocation_interval_preference'daily' | 'weekly' | 'monthly' | 'yearly' nullable

Interval at which recurring allocations are applied.

allocation_priority_preference'low' | 'mid' | 'high' | 'max' nullable

Priority level for fund allocation across multiple cards.

recurring_allocation_amount_centsinteger nullable

Recurring allocation amount in cents.

remaining_balancestring nullable

Actual amount the card can spend right now, as a decimal string in the card's currency (not cents). This is the minimum between the user's spending limit and the company's available balance.

spentinteger
company_expendable_balance_in_limit_currencystring nullable

Company funds this card can still draw, expressed in the card's limit_currency, as a decimal string (a BigDecimal serialized to JSON, not a number). Show-only — returned by GET /v1/vendor_cards/{id} only, and only when the caller can read the company balance (policy(company).balance?). Absent from the list endpoint.

spent_in_interval_with_limit_currencynumber float

Amount spent in the current limit interval, converted to the card's limit_currency. Always a number (defaults to 0.0); never null. Show-only — returned by GET /v1/vendor_cards/{id} only.

vendor_max_spending_limitsunknown
non_sensitive_informationobject nullable

Non-sensitive cardholder/configuration attributes (user_name, user_identifier, country, address, postal_code, restricted_merchants, phone). Empty object when unavailable. Show-only — returned by GET /v1/vendor_cards/{id} only.

last_allocation_transaction_statusstring nullable

Status of the most recent allocation transaction on this card. Show-only — returned by GET /v1/vendor_cards/{id} only.

last_allocation_transaction_created_atstring date-time nullable

Creation timestamp of the most recent allocation transaction. Show-only — returned by GET /v1/vendor_cards/{id} only.

allocation_priority_statsobject nullable

Total recurring allocation (cents) per priority group across the company's active cards (e.g. { "low": 5000000, "mid": 3000000 }), or null for card types that don't compute it. Show-only — returned by GET /v1/vendor_cards/{id} only.

preference_restricted_spendablestring nullable

Amount the card can still spend before hitting its configured spending limit, as a decimal string in the card's currency (not cents). Calculated as the spending limit minus amount already spent in the current interval. Unlike remaining_balance, this does not consider the company's available funds.

spent_in_intervalnumber float
spent_in_vendor_intervalnumber float
fees_in_vendor_intervalnumber float
created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "Q2FyZDoxMDIwNjQ5Mw==",
  "user_id": "U2MGkNZT6zNPKtB85OpJi9SjFvG2",
  "type": "PomeloCard",
  "name": "AWS",
  "last4": "4163",
  "status_preference": "inactive",
  "migrated": true,
  "limit_amount": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "limit_interval": "daily",
  "limit_amount_preference": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "allocated_amount": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "allocated_amount_preference": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "recurring_allocation_amount_cents": 50000,
  "remaining_balance": "2000.0",
  "spent": 472025,
  "company_expendable_balance_in_limit_currency": "3200000.0",
  "spent_in_interval_with_limit_currency": 472025,
  "vendor_max_allocation": {
    "amount": "3000.0",
    "formatted": "$3.000 CLP",
    "cents": "3000.0",
    "currency_iso": "CLP"
  },
  "preference_restricted_spendable": "2000.0",
  "spent_in_interval": 472025,
  "spent_in_vendor_interval": 472025
}

Changes

No recorded changes to this operation across all 1 revision of this API.