{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/issuer/cards","version":"1.0.0","description":"List the issuer's cards"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/issuer/cards":{"get":{"tags":["credit"],"summary":"List the issuer's cards","description":"The cards on the Ramp account connected to this business, by cardholder: last four, name, cardholder, status and spend limit, with the credit line a card is registered to. `source=live` reads Ramp now (`409 CREDIT_740` without a Ramp connection, `503 CREDIT_741` when Ramp does not answer within 20 seconds); `source=stored` builds the list from stored transactions and registered cards without calling Ramp; `source=auto` (the default) reads Ramp and falls back to the stored list, saying why in `issuer_note`.","operationId":"list_issuer_cards","parameters":[{"name":"source","in":"query","required":false,"schema":{"enum":["auto","live","stored"],"type":"string","description":"`auto` (Ramp, else stored), `live` (Ramp only) or `stored`.","default":"auto","title":"Source"},"description":"`auto` (Ramp, else stored), `live` (Ramp only) or `stored`."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"description":"Page size (1 to 500).","default":100,"title":"Limit"},"description":"Page size (1 to 500)."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`next_cursor` from the previous page, passed back unchanged.","title":"Cursor"},"description":"`next_cursor` from the previous page, passed back unchanged."},{"name":"include_total_count","in":"query","required":false,"schema":{"type":"boolean","description":"Also return `total`, the number of matching rows (one more query).","default":false,"title":"Include Total Count"},"description":"Also return `total`, the number of matching rows (one more query)."},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_IssuerCardPage_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict - Resource already exists or is in an incompatible state","content":{"application/json":{"example":{"error":"conflict","message":"Resource already exists","code":"CONFLICT_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"example":{"error":"service_unavailable","message":"The service is temporarily unavailable. Please try again later.","code":"GEN_004","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"list_issuer_cards_api_v1_credit_issuer_cards_get"}}},"components":{"schemas":{"IssuerCardItem":{"properties":{"provider_card_id":{"type":"string","title":"Provider Card Id","description":"Ramp's card id."},"provider_fund_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Fund Id","description":"The Ramp fund (spend limit) the card draws on."},"last_four":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Four","description":"Last four digits. Ramp redacts it until a card is activated; it is then read from stored transactions when one knows it."},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display Name","description":"The card's name in Ramp."},"cardholder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cardholder Name","description":"The employee who holds the card: from Ramp's card or user record, else from the card's stored transactions."},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status","description":"Ramp's state: `ACTIVE`, `SUSPENDED`, `TERMINATED`, `UNACTIVATED` or `CHIP_LOCKED` (for a card registered to a credit line, its DayZero status in capitals). Null when the card is known only from stored transactions."},"is_physical":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Physical","description":"Physical (true) or virtual (false), when known."},"spend_limit_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Spend Limit Cents","description":"The fund's spend limit per `spend_interval`, in cents, if known."},"spend_interval":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Spend Interval","description":"What the limit resets on: `TOTAL` (lifetime), `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `YEARLY` or `ANNUAL`."},"transaction_count":{"type":"integer","title":"Transaction Count","description":"Card transactions DayZero has stored for the card."},"last_transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Last Transaction Date","description":"Date of the newest stored transaction on it."},"credit_line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Line Id","description":"The credit line the card is registered to, if any."},"card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Id","description":"DayZero's card id when the card is registered to a credit line."},"source":{"type":"string","enum":["issuer","transactions","credit_line"],"title":"Source","description":"Where the card was found: `issuer` (listed by Ramp just now), `transactions` (only seen on stored transactions) or `credit_line` (only a card registered to a credit line)."}},"type":"object","required":["provider_card_id","transaction_count","source"],"title":"IssuerCardItem","description":"One card on the business's Ramp connection."},"IssuerCardPage":{"properties":{"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass back as `cursor` for the next page. Null on the last."},"has_next":{"type":"boolean","title":"Has Next","description":"Another page follows. Looked up one row past the page, so a full last page is not reported as more.","default":false},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit","description":"The page size the list was read with."},"total":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total","description":"Row count; present only with `include_total_count=true`."},"items":{"items":{"$ref":"#/components/schemas/IssuerCardItem"},"type":"array","title":"Items","description":"The cards on this page."},"source":{"type":"string","enum":["live","stored"],"title":"Source","description":"`live` when Ramp was read for this answer; `stored` when it was built from stored transactions and registered cards only."},"issuer_note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Issuer Note","description":"Why a `source=auto` answer is `stored`: no Ramp connection, or Ramp did not answer in time. Null on a live answer."}},"type":"object","required":["source"],"title":"IssuerCardPage","description":"The cards on the business's Ramp connection, by cardholder."},"SuccessEnvelope_IssuerCardPage_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/IssuerCardPage"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[IssuerCardPage]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}