{"openapi":"3.1.0","info":{"title":"GET /api/v1/credit/issuer/card-transactions","version":"1.0.0","description":"List the issuer's card transactions"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/issuer/card-transactions":{"get":{"tags":["credit"],"summary":"List the issuer's card transactions","description":"Card transactions on the Ramp account connected to this business, as DayZero last synced them, newest first. Each carries the card, the cardholder, Ramp's state, the account it is booked to in DayZero's books, and the credit line and loan when the card is registered to a line on this business. Reimbursements are left out unless `include_reimbursements=true`. Only what the Ramp sync has stored is listed: transactions on credit-line cards are loans, read them under the line. `CREDIT_742` when `start` is after `end`.","operationId":"list_issuer_card_transactions","parameters":[{"name":"start","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"First transaction date to include (inclusive, UTC).","title":"Start"},"description":"First transaction date to include (inclusive, UTC)."},{"name":"end","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Last transaction date to include (inclusive, UTC).","title":"End"},"description":"Last transaction date to include (inclusive, UTC)."},{"name":"card_holder","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"description":"Only this cardholder's transactions (whole name, any case).","title":"Card Holder"},"description":"Only this cardholder's transactions (whole name, any case)."},{"name":"card_last_four","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}],"description":"Only transactions on the card ending in these four digits.","title":"Card Last Four"},"description":"Only transactions on the card ending in these four digits."},{"name":"state","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":32},{"type":"null"}],"description":"Only transactions in this Ramp state, e.g. `CLEARED`.","title":"State"},"description":"Only transactions in this Ramp state, e.g. `CLEARED`."},{"name":"include_reimbursements","in":"query","required":false,"schema":{"type":"boolean","description":"Also list reimbursements (`transaction_type=reimbursement`).","default":false,"title":"Include Reimbursements"},"description":"Also list reimbursements (`transaction_type=reimbursement`)."},{"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_IssuerCardTransactionPage_"}}}},"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"}}}},"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_card_transactions_api_v1_credit_issuer_card_transactions_get"}}},"components":{"schemas":{"IssuerCardTransactionItem":{"properties":{"id":{"type":"string","title":"Id","description":"DayZero's id for the stored Ramp transaction."},"provider_transaction_id":{"type":"string","title":"Provider Transaction Id","description":"Ramp's transaction id (or reimbursement id)."},"transaction_type":{"type":"string","enum":["card_transaction","reimbursement"],"title":"Transaction Type","description":"`card_transaction` for card spend; `reimbursement` only when the list was read with `include_reimbursements=true`."},"transaction_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Transaction Date","description":"When the cardholder made the purchase (Ramp's `user_transaction_time`, as a UTC date); the settlement date when Ramp sent no purchase time."},"settled_date":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Settled Date","description":"When the funds moved (Ramp's `settlement_date`), if stored."},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Signed, in cents. Positive is spend on the card (a charge); negative is money back to the card (a refund or credit). A reimbursement is positive when paid out to the employee."},"currency":{"type":"string","title":"Currency","description":"ISO 4217 code of `amount_cents`."},"merchant_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Name","description":"Merchant as Ramp names it."},"merchant_category_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Merchant Category Code","description":"The four-digit MCC Ramp reported, if any."},"card_last_four":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Last Four","description":"Last four digits of the card. On rows stored before DayZero kept it, it is read from another stored transaction on the same card or from a card registered to a credit line; null when neither knows the card."},"card_holder_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Card Holder Name","description":"The employee whose card it is (or who was reimbursed). On older rows it is read from the stored Ramp payload; null when Ramp sent none."},"provider_card_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Provider Card Id","description":"Ramp's card id; null for a reimbursement."},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"Ramp's state for the transaction as last synced, e.g. `CLEARED`, `COMPLETION` or `PENDING`."},"memo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Memo","description":"The cardholder's memo."},"ramp_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ramp Category","description":"The accounting category coded in Ramp, if the row was coded."},"booked":{"type":"boolean","title":"Booked","description":"Whether DayZero has posted a journal entry for the row."},"accounting_category":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Accounting Category","description":"The account the spend is booked to in DayZero's books (the expense side of the journal entry, names joined by `; ` when the entry is split). Null while the row is not booked."},"journal_entry_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Journal Entry Id","description":"The journal entry that books the row, if any."},"receipt_count":{"type":"integer","title":"Receipt Count","description":"How many receipts Ramp had attached when the row was synced."},"credit_line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Line Id","description":"The credit line on this business the card is registered to (matched by Ramp card id, else by last four when exactly one registered card has it), or the line holding a settlement for this transaction."},"loan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Loan Id","description":"The loan a settlement of this transaction originated, when one exists on this business."}},"type":"object","required":["id","provider_transaction_id","transaction_type","amount_cents","currency","booked","receipt_count"],"title":"IssuerCardTransactionItem","description":"One Ramp card transaction (or reimbursement) as DayZero stored it."},"IssuerCardTransactionPage":{"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/IssuerCardTransactionItem"},"type":"array","title":"Items","description":"The transactions on this page."}},"type":"object","title":"IssuerCardTransactionPage","description":"A page of the operator's stored Ramp card transactions, newest first."},"SuccessEnvelope_IssuerCardTransactionPage_":{"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/IssuerCardTransactionPage"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[IssuerCardTransactionPage]"},"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":[]}]}