{"openapi":"3.1.0","info":{"title":"POST /api/v1/credit/sandbox/card-transactions","version":"1.0.0","description":"Clear, void or dispute a card transaction"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/sandbox/card-transactions":{"post":{"tags":["credit"],"summary":"Clear, void or dispute a card transaction","description":"Sandbox only. Reports a transaction on a mock-issued card the way Ramp's webhook would, and sends it through the same ingest: a `cleared` purchase becomes a loan with no call from you, a negative amount is a refund, a `voided` one reverses the loan (or holds it when money was paid on it), a `disputed` one opens a hold. Returns what happened. A card on a live issuer program is `CREDIT_710`; a void or dispute of a transaction the book does not hold is `CREDIT_711`.","operationId":"record_sandbox_card_transaction","parameters":[{"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"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCardTransactionRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_SandboxCardTransactionResponse_"}}}},"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"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","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":"record_sandbox_card_transaction_api_v1_credit_sandbox_card_transactions_post"}}},"components":{"schemas":{"SandboxCardTransactionRequest":{"properties":{"card_id":{"type":"string","title":"Card Id","description":"The card's `id` from `POST /credit/cards`. The card must be on a program whose issuer is the mock issuer (`CREDIT_710` otherwise)."},"kind":{"type":"string","enum":["cleared","voided","disputed"],"title":"Kind","description":"`cleared`: the issuer reports a purchase (or, with a negative amount, a refund) as settled. `voided`: it now reports a cleared transaction voided. `disputed`: it lists a dispute on one.","default":"cleared"},"amount_cents":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Amount Cents","description":"`cleared` only, required. Signed cents: positive is a purchase, negative a refund. Ignored for the other kinds, which read the amount from the transaction already recorded."},"merchant_name":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Merchant Name","description":"`cleared` only. The merchant."},"merchant_category_code":{"anyOf":[{"type":"string","maxLength":8},{"type":"null"}],"title":"Merchant Category Code","description":"`cleared` only. Four-digit merchant category code."},"settled_on":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"title":"Settled On","description":"`cleared` only. The settlement date. Defaults to today, and may be later on a sandbox."},"issuer_transaction_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Issuer Transaction Id","description":"The issuer's transaction id. Optional for `cleared` (one is generated and returned; sending the same id again is a duplicate, not a second loan). Required for `voided` and `disputed`, which name a transaction recorded earlier (`CREDIT_711` if there is none)."},"refund_of_issuer_transaction_id":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Refund Of Issuer Transaction Id","description":"`cleared` with a negative amount: the transaction it refunds."}},"additionalProperties":false,"type":"object","required":["card_id"],"title":"SandboxCardTransactionRequest"},"SandboxCardTransactionResponse":{"properties":{"issuer_transaction_id":{"type":"string","title":"Issuer Transaction Id","description":"The transaction's issuer id."},"kind":{"type":"string","enum":["cleared","voided","disputed"],"title":"Kind","description":"What was reported."},"credit_line_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Credit Line Id","description":"The line the card is on."},"result":{"type":"string","enum":["loan_created","refund_recorded","duplicate","reversed","hold_opened","unchanged","ignored"],"title":"Result","description":"What the ledger did: `loan_created` (a purchase became a loan), `refund_recorded`, `duplicate` (that id was already recorded), `reversed` (a void with nothing paid on the loan took it back at once), `hold_opened` (a void with money paid, or a dispute, put the loan on hold for an operator), `unchanged` (already recorded or not eligible; see `detail`) or `ignored` (the ingest did not take it; see `detail`)."},"loan_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Loan Id","description":"The loan the transaction created or acted on."},"dispute_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispute Id","description":"The hold opened, when one was."},"detail":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Detail","description":"Why, for `unchanged` and `ignored`."}},"type":"object","required":["issuer_transaction_id","kind","result"],"title":"SandboxCardTransactionResponse"},"SuccessEnvelope_SandboxCardTransactionResponse_":{"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/SandboxCardTransactionResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[SandboxCardTransactionResponse]"},"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":[]}]}