{"openapi":"3.1.0","info":{"title":"POST /api/v1/credit/lines/{credit_line_id}/payment-aliases","version":"1.0.0","description":"Record a payment alias"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/credit/lines/{credit_line_id}/payment-aliases":{"post":{"tags":["credit"],"summary":"Record a payment alias","description":"Register an identifier a merchant's money arrives under — the sender name their bank stamps on a wire, a reference they quote, an account mask. Resolution then becomes a lookup rather than a guess at a name (O-11). An alias already pointing at another line is refused rather than reassigned.","operationId":"create_payment_alias","parameters":[{"name":"credit_line_id","in":"path","required":true,"schema":{"type":"string","title":"Credit Line Id"}},{"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/PaymentAliasCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_PaymentAliasResponse_"}}}},"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/invalid token 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":"create_payment_alias_api_v1_credit_lines__credit_line_id__payment_aliases_post"}}},"components":{"schemas":{"PaymentAliasCreateRequest":{"properties":{"alias":{"type":"string","maxLength":255,"title":"Alias","description":"The sender name, reference or account mask as it reaches the operating account. Matching folds case, drops punctuation and strips company suffixes, so 'REVENUE ROLL, INC.' and 'Revenue Roll Inc' are the same alias."},"alias_type":{"type":"string","enum":["sender_name","account_mask","reference","other"],"title":"Alias Type","default":"sender_name"},"source":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"title":"Source"},"note":{"anyOf":[{"type":"string","maxLength":255},{"type":"null"}],"title":"Note"}},"additionalProperties":false,"type":"object","required":["alias"],"title":"PaymentAliasCreateRequest","description":"Record an identifier a merchant's payments arrive under (O-11)."},"PaymentAliasResponse":{"properties":{"id":{"type":"string","title":"Id"},"credit_line_id":{"type":"string","title":"Credit Line Id"},"alias":{"type":"string","title":"Alias"},"normalised":{"type":"string","title":"Normalised"},"alias_type":{"type":"string","title":"Alias Type"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"note":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Note"}},"type":"object","required":["id","credit_line_id","alias","normalised","alias_type"],"title":"PaymentAliasResponse"},"SuccessEnvelope_PaymentAliasResponse_":{"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/PaymentAliasResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[PaymentAliasResponse]"},"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":[]}]}