{"openapi":"3.0.0","paths":{"/api/public/payments":{"post":{"operationId":"PublicApiPaymentsController_createPayment","summary":"Send pending payment","description":"Trigger a pending payment notification to be sent to the given email address. This pending payment will behave in the same way a payment sent manually through the SnapRefund web app behaves. ie) The recipient will receive a notification email for the payment containing a deep link to the Pending Payment. Once inside, the recipient will select their payout method of choice from a list of all of the available payment options for the given sender.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recipientEmail","amount","memo"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}},"application/json":{"schema":{"type":"object","required":["recipientEmail","amount","memo"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}}}},"responses":{"201":{"description":""},"400":{"description":"Invalid request data or validation failed","schema":{"example":{"statusCode":400,"code":"VALIDATION_ERROR","message":"Request validation failed","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","errors":[{"field":"recipientEmail","message":"recipientEmail must be a valid email","value":"invalid-email"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid authentication","schema":{"example":{"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Insufficient permissions or feature not enabled","schema":{"example":{"statusCode":403,"code":"PAYMENT_4221","message":"RTP functionality is not enabled for your account","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-rtp"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Resource not found (payment, profile, bank account)","schema":{"example":{"statusCode":404,"code":"PAYMENT_4041","message":"Recipient profile not found","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Resource conflict","schema":{"example":{"statusCode":409,"code":"PAYMENT_5021","message":"Check provider error: Resource already exists","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-check"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"Business logic validation failed (e.g., insufficient funds)","schema":{"example":{"statusCode":422,"code":"PAYMENT_5020","message":"Insufficient funds in the funding source","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InsufficientFunds","providerMessage":"The funding source has insufficient funds","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded","schema":{"example":{"statusCode":429,"code":"PAYMENT_4290","message":"Too many payment requests","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Internal server error","schema":{"example":{"statusCode":500,"code":"PAYMENT_5000","message":"Failed to create payment","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"502":{"description":"External payment provider error","schema":{"example":{"statusCode":502,"code":"PAYMENT_5020","message":"Payment provider (Dwolla) error","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InternalServerError","providerMessage":"An internal error occurred","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]},"get":{"operationId":"PublicApiPaymentsController_getPayments","summary":"Get list of self payments","description":"Returns a list of payments created by the current insurer","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/mass-payment":{"post":{"operationId":"PublicApiPaymentsController_massPayment","summary":"Send mass pending payments","description":"Trigger a mass pending payments notification to be sent to the given emails address. This pending payments will behave in the same way a payments sent manually through the SnapRefund web app behaves. ie) The recipient will receive a notification email for the payment containing a deep link to the Pending Payment. Once inside, the recipient will select their payout method of choice from a list of all of the available payment options for the given sender.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":""}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/{paymentId}":{"get":{"operationId":"PublicApiPaymentsController_getPayment","summary":"Get self payment by Id","description":"Getting information about a payment by its Id. The id can be obtained from a request that returns a list of all payments. Address for receiving a list of all payments: public/payments","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/send-ach":{"post":{"operationId":"PublicApiPaymentsController_sendAchTransfer","summary":"Send ACH payment","description":"Sends an ACH payment (also called direct deposit or EFT) over the Automated Clearing House federal network. ACH payments settle in 3-4 business days on average and are the cornerstore of digital payments in the US. These payments are always bank to bank transfers. During the 3-4 business days we SnapRefund will be listening to the status of the ACH payment as the banking network holds funds and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}},"application/json":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"files":{"type":"array","items":{"type":"string","format":"binary"},"nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}},"400":{"description":"Invalid request data or validation failed","schema":{"example":{"statusCode":400,"code":"VALIDATION_ERROR","message":"Request validation failed","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","errors":[{"field":"recipientEmail","message":"recipientEmail must be a valid email","value":"invalid-email"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid authentication","schema":{"example":{"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Insufficient permissions or feature not enabled","schema":{"example":{"statusCode":403,"code":"PAYMENT_4221","message":"RTP functionality is not enabled for your account","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-rtp"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Resource not found (payment, profile, bank account)","schema":{"example":{"statusCode":404,"code":"PAYMENT_4041","message":"Recipient profile not found","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Resource conflict","schema":{"example":{"statusCode":409,"code":"PAYMENT_5021","message":"Check provider error: Resource already exists","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-check"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"Business logic validation failed (e.g., insufficient funds)","schema":{"example":{"statusCode":422,"code":"PAYMENT_5020","message":"Insufficient funds in the funding source","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InsufficientFunds","providerMessage":"The funding source has insufficient funds","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded","schema":{"example":{"statusCode":429,"code":"PAYMENT_4290","message":"Too many payment requests","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Internal server error","schema":{"example":{"statusCode":500,"code":"PAYMENT_5000","message":"Failed to create payment","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"502":{"description":"External payment provider error","schema":{"example":{"statusCode":502,"code":"PAYMENT_5020","message":"Payment provider (Dwolla) error","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InternalServerError","providerMessage":"An internal error occurred","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/send-check":{"post":{"operationId":"PublicApiPaymentsController_sendCheckTransfer","summary":"Send Paper Check","description":"Sends an RTP payment via The RTP Network launched by The Clearing House. RTP payments settle in within seconds. These payments are always balance-to-bank transfers. SnapRefund will be listening to the status of the RTP payment and wait for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize. This functionality could be additionally enabled by request.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSendCheckDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}},"400":{"description":"Invalid request data or validation failed","schema":{"example":{"statusCode":400,"code":"VALIDATION_ERROR","message":"Request validation failed","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","errors":[{"field":"recipientEmail","message":"recipientEmail must be a valid email","value":"invalid-email"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid authentication","schema":{"example":{"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Insufficient permissions or feature not enabled","schema":{"example":{"statusCode":403,"code":"PAYMENT_4221","message":"RTP functionality is not enabled for your account","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-rtp"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Resource not found (payment, profile, bank account)","schema":{"example":{"statusCode":404,"code":"PAYMENT_4041","message":"Recipient profile not found","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Resource conflict","schema":{"example":{"statusCode":409,"code":"PAYMENT_5021","message":"Check provider error: Resource already exists","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-check"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"Business logic validation failed (e.g., insufficient funds)","schema":{"example":{"statusCode":422,"code":"PAYMENT_5020","message":"Insufficient funds in the funding source","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InsufficientFunds","providerMessage":"The funding source has insufficient funds","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded","schema":{"example":{"statusCode":429,"code":"PAYMENT_4290","message":"Too many payment requests","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Internal server error","schema":{"example":{"statusCode":500,"code":"PAYMENT_5000","message":"Failed to create payment","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"502":{"description":"External payment provider error","schema":{"example":{"statusCode":502,"code":"PAYMENT_5020","message":"Payment provider (Dwolla) error","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InternalServerError","providerMessage":"An internal error occurred","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/send-rtp":{"post":{"operationId":"PublicApiPaymentsController_sendRtpTransfer","summary":"Send RTP payment","description":"Sends an RTP payment via The RTP Network launched by The Clearing House. RTP payments settle in within seconds. These payments are always balance to bank transfers. SnapRefund will be listening to the status of the RTP payment and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize. This functionality should be additionally enabled for your account.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"file":{"type":"string","format":"binary","nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}},"application/json":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"file":{"type":"string","format":"binary","nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}},"400":{"description":"Invalid request data or validation failed","schema":{"example":{"statusCode":400,"code":"VALIDATION_ERROR","message":"Request validation failed","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","errors":[{"field":"recipientEmail","message":"recipientEmail must be a valid email","value":"invalid-email"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid authentication","schema":{"example":{"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Insufficient permissions or feature not enabled","schema":{"example":{"statusCode":403,"code":"PAYMENT_4221","message":"RTP functionality is not enabled for your account","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-rtp"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Resource not found (payment, profile, bank account)","schema":{"example":{"statusCode":404,"code":"PAYMENT_4041","message":"Recipient profile not found","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Resource conflict","schema":{"example":{"statusCode":409,"code":"PAYMENT_5021","message":"Check provider error: Resource already exists","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-check"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"Business logic validation failed (e.g., insufficient funds)","schema":{"example":{"statusCode":422,"code":"PAYMENT_5020","message":"Insufficient funds in the funding source","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InsufficientFunds","providerMessage":"The funding source has insufficient funds","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded","schema":{"example":{"statusCode":429,"code":"PAYMENT_4290","message":"Too many payment requests","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Internal server error","schema":{"example":{"statusCode":500,"code":"PAYMENT_5000","message":"Failed to create payment","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"502":{"description":"External payment provider error","schema":{"example":{"statusCode":502,"code":"PAYMENT_5020","message":"Payment provider (Dwolla) error","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InternalServerError","providerMessage":"An internal error occurred","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/send-same-day-ach":{"post":{"operationId":"PublicApiPaymentsController_sendSameDayAchTransfer","summary":"Send Same Day ACH payment","description":"Sends an Same Day ACH payment within the same business day (excluding weekends and holidays). This is a significant improvement compared to standard ACH transfers that can take several days. These payments are always balance to bank transfers. During the 1-2 business days we SnapRefund will be listening to the status of the Same Day ACH payment as the banking network holds funds and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize.","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"file":{"type":"string","format":"binary","nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}},"application/json":{"schema":{"type":"object","required":["recipientEmail","amount","memo","bankId"],"properties":{"file":{"type":"string","format":"binary","nullable":true},"recipientEmail":{"type":"string"},"amount":{"type":"string","format":"number"},"memo":{"type":"string","minLength":1},"bankId":{"type":"string"},"senderBankId":{"type":"string","nullable":true},"approversEmails":{"type":"array","items":{"type":"string"},"nullable":true}}}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}},"400":{"description":"Invalid request data or validation failed","schema":{"example":{"statusCode":400,"code":"VALIDATION_ERROR","message":"Request validation failed","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","errors":[{"field":"recipientEmail","message":"recipientEmail must be a valid email","value":"invalid-email"}]}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationErrorResponseDto"}}}},"401":{"description":"Missing or invalid authentication","schema":{"example":{"statusCode":401,"code":"UNAUTHORIZED","message":"Unauthorized","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"403":{"description":"Insufficient permissions or feature not enabled","schema":{"example":{"statusCode":403,"code":"PAYMENT_4221","message":"RTP functionality is not enabled for your account","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-rtp"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"404":{"description":"Resource not found (payment, profile, bank account)","schema":{"example":{"statusCode":404,"code":"PAYMENT_4041","message":"Recipient profile not found","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"409":{"description":"Resource conflict","schema":{"example":{"statusCode":409,"code":"PAYMENT_5021","message":"Check provider error: Resource already exists","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-check"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"422":{"description":"Business logic validation failed (e.g., insufficient funds)","schema":{"example":{"statusCode":422,"code":"PAYMENT_5020","message":"Insufficient funds in the funding source","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InsufficientFunds","providerMessage":"The funding source has insufficient funds","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}},"429":{"description":"Rate limit exceeded","schema":{"example":{"statusCode":429,"code":"PAYMENT_4290","message":"Too many payment requests","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"500":{"description":"Internal server error","schema":{"example":{"statusCode":500,"code":"PAYMENT_5000","message":"Failed to create payment","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponseDto"}}}},"502":{"description":"External payment provider error","schema":{"example":{"statusCode":502,"code":"PAYMENT_5020","message":"Payment provider (Dwolla) error","timestamp":"2026-02-15T10:30:00.123Z","path":"/api/public/payments/send-ach","provider":{"provider":"dwolla","providerCode":"InternalServerError","providerMessage":"An internal error occurred","details":null}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProviderErrorResponseDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/accept-ach/{paymentId}":{"post":{"operationId":"PublicApiPaymentsController_acceptAchTransfer","summary":"Accept pending payment as ACH payment","description":"Sends an ACH payment (also called direct deposit or EFT) over the Automated Clearing House federal network. ACH payments settle in 3-4 business days on average and are the cornerstore of digital payments in the US. These payments are always bank to bank transfers. During the 3-4 business days we SnapRefund will be listening to the status of the ACH payment as the banking network holds funds and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAcceptAchDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/accept-check/{paymentId}":{"post":{"operationId":"PublicApiPaymentsController_acceptCheckTransfer","summary":"Accept pending payment as Paper Check","description":"Send a paper check via physical mail couriers. Paper checks aren't the newest or the fastest way to send money to someone, but when all else fails they present a time-honored method of sending a payment. Multiple mail speeds are supported and every option except standard mail (the Mail enum value) supports tracking info once the check is printed and shipped. Note; a phone number for the recipient must be provided if the chosen mailType is FedEx. This is used in case FedEx couriers need to contact the recipient to coordinate delivery.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAcceptCheckDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/accept-rtp/{paymentId}":{"post":{"operationId":"PublicApiPaymentsController_acceptRtpTransfer","summary":"Accept pending payment as RTP payment","description":"Sends an RTP payment via The RTP Network launched by The Clearing House. RTP payments settle in within seconds. These payments are always balance to bank transfers. SnapRefund will be listening to the status of the RTP payment and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize. This functionality could be additionally enabled by request.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAcceptRtpDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/accept-same-day-ach/{paymentId}":{"post":{"operationId":"PublicApiPaymentsController_acceptSameDayAchTransfer","summary":"Accept pending payment as Same Day ACH payment","description":"Sends an Same Day ACH payment within the same business day (excluding weekends and holidays). This is a significant improvement compared to standard ACH transfers that can take several days. These payments are always balance to bank transfers. During the 1-2 business days we SnapRefund will be listening to the status of the Same Day ACH payment as the banking network holds funds and waits for return codes. After the alloted time, if no return codes are generated the payment will settle and the funds transfer will finalize.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAcceptAchDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/accept-venmo/{paymentId}":{"post":{"operationId":"PublicApiPaymentsController_acceptVenmoTransfer","summary":"Accept pending payment as Venmo payment","description":"Sends a Venmo payment from the sender PayPal Wallet.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAcceptVenmoDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/send-venmo":{"post":{"operationId":"PublicApiPaymentsController_sendVenmoPayment","summary":"Send Venmo Direct Payment","description":"Send a Venmo Direct Payment from your PayPal Wallet.","parameters":[{"name":"idempotency-key","required":true,"in":"header","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSendVenmoDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/balance":{"get":{"operationId":"PublicApiPaymentsController_getWalletBalance","summary":"Get Wallet Balance","description":"Receive Wallet Balance response. This functionality should be additionally enabled for your account.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/paypal/balance":{"get":{"operationId":"PublicApiPaymentsController_getPaypalWalletBalance","summary":"Get PayPal Wallet Balance","description":"Receive PayPal Wallet Balance response. This functionality should be additionally enabled for your account.","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletBalanceDto"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/deposit":{"post":{"operationId":"PublicApiPaymentsController_makeDeposit","summary":"Deposit funds into your Wallet","description":"Sends the provided amount of funds from your bank account to your Wallet. This functionality should be additionally enabled for your account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiWalletTransferDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/paypal/deposit":{"post":{"operationId":"PublicApiPaymentsController_makePaypalDeposit","summary":"Deposit funds into your PayPal Wallet","description":"Moves funds from your bank account to your PayPal Wallet inside SnapRefund. This functionality should be additionally enabled for your account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiWalletTransferDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/paypal/withdraw":{"post":{"operationId":"PublicApiPaymentsController_makePaypalWithdraw","summary":"Withdraw funds from your PayPal Wallet","description":"Moves funds from your PayPal Wallet inside SnapRefund to your bank account. This functionality should be additionally enabled for your account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiWalletTransferDto"}}}},"responses":{"201":{"description":""}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/wallet/withdraw":{"post":{"operationId":"PublicApiPaymentsController_makeWithdraw","summary":"Withdraw funds from your Wallet","description":"Sends the provided amount of funds from your Wallet to your bank account. This functionality should be additionally enabled for your account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiWalletTransferDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"object"}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/user/{userId}/pending":{"get":{"operationId":"PublicApiPaymentsController_getCustomerPendingPayments","summary":"Get list of insured’s pending payments","description":"Receive pending customer payments. Please note that you can only access the customer you created and only the pending payments where you are the merchant.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/{paymentId}/cancel":{"patch":{"operationId":"PublicApiPaymentsController_cancelPayment","summary":"Cancel pending payment","description":"Retry your payment. Change payment status to Awaiting-cash-out. It works only for payments in status Cancelled.","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/{paymentId}/retry":{"patch":{"operationId":"PublicApiPaymentsController_retryPayment","summary":"Retry pending payment","description":"Cancel your payment. Change payment status to Cancelled. It works only for payments in status Awaiting-cash-out","parameters":[{"name":"paymentId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/payments/user/{userId}":{"get":{"operationId":"PublicApiPaymentsController_getUserPayments","summary":"Get list of insured’s payments","description":"Get list of payments sent to the insured","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicPaymentDto"}}}}}},"tags":["payments"],"security":[{"Authorization":[]}]}},"/api/public/users":{"get":{"operationId":"PublicApiUsersController_getUsersList","summary":"Get list of all insureds","description":"Returns list of all created insureds with known info. Can be filtered by email","parameters":[{"name":"value","required":false,"in":"query","schema":{"type":"string"}},{"name":"take","required":true,"in":"query","schema":{"minimum":0,"maximum":250,"default":10,"type":"number"}},{"name":"skip","required":true,"in":"query","schema":{"minimum":0,"default":0,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserListDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}":{"get":{"operationId":"PublicApiUsersController_getUser","summary":"Get insured information","description":"Returns all known info for the customer with the given userId.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInfoDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]},"patch":{"operationId":"PublicApiUsersController_updateUser","summary":"Update insured information","description":"Updates the customer's details in the database. All body fields are optional. Any fields that are supplied will overwrite the current values stored there. Note that bank details are not modifiable through this endpoint, instead you should use /api/public/user/{userId}/bank","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserInfoDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserInfoDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiUsersController_deleteUser","summary":"Delete insured","description":"Delete insured with all information","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/payment-email-preference":{"patch":{"operationId":"PublicApiUsersController_updatePaymentEmailPreference","summary":"Update insured’s payment email notifications","description":"Update customer's communication preferences. If enabled, customer will receive email notifications.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentEmailPreferenceDto"}}}},"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/marketing-email-preference":{"patch":{"operationId":"PublicApiUsersController_updateMarketingEmailPreference","summary":"Update insured’s marketing email notifications","description":"Update customer's communication preferences. If enabled, customer will receive email notifications about our new features.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateMarketingEmailPreferenceDto"}}}},"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/payment-sms-preference":{"patch":{"operationId":"PublicApiUsersController_updatePaymentSmsPreference","summary":"Update insured’s SMS text notifications","description":"Update customer's communication preferences. If enabled, customer will receive sms text notifications.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePaymentSmsPreferenceDto"}}}},"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/create-unverified":{"post":{"operationId":"PublicApiCreateUserController_createUserReceiveOnlyUser","summary":"Create insured","description":"Create an unverified personal or business user.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserReceiveOnlyDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserReceiveOnlyResponseDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/banks":{"get":{"operationId":"PublicApiUserBanksController_getBanks","summary":"Get list of insured’s banks","description":"Retrieve list of customer's funding sources","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BankFundingSourceDto"}}}}}},"tags":["user"],"security":[{"Authorization":[]}]},"post":{"operationId":"PublicApiUserBanksController_addBank","summary":"Add bank for insured","description":"Adds an unverified bank account to the user's account. Note that only two banks can exist per user at any given time.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankInfoDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BankFundingSourceDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/banks/{id}":{"delete":{"operationId":"PublicApiUserBanksController_removeBank","summary":"Delete insured’s bank by id","description":"Remove an unverified bank account from customer account","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"number"}},{"name":"id","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/addresses":{"get":{"operationId":"PublicApiUserAddressesController_getAddressesList","summary":"Get list of insured’s addresses","description":"Returns a list of customers addresses. An alias from the address can be used for check send.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/AddressInfoDto"}}}}}},"tags":["user"],"security":[{"Authorization":[]}]},"post":{"operationId":"PublicApiUserAddressesController_addAddress","summary":"Add address for insured","description":"Adds a new address for the client. All address1 addresses and aliases must be unique for each customer.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressCreateDto"}}}},"responses":{"201":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/users/{userId}/addresses/{alias}":{"get":{"operationId":"PublicApiUserAddressesController_getAddress","summary":"Get insured’s address by alias","description":"Returns the address of the customer. An alias from an address can be used for check send.","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"alias","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressInfoDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiUserAddressesController_deleteAddress","summary":"Delete insured address by alias","description":"Removes an existing customer address by its alias. The alias can be obtained from the endpoint: /api/public/users/{userId}/addresses","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"alias","required":true,"in":"path","schema":{"type":"string"}}],"responses":{"200":{"description":""}},"tags":["user"],"security":[{"Authorization":[]}]},"patch":{"operationId":"PublicApiUserAddressesController_updateAddress","summary":"Update insured’s address information","description":"Updates an existing customer address by its alias. The alias can be obtained from the endpoint: /api/public/users/{userId}/addresses","parameters":[{"name":"userId","required":true,"in":"path","schema":{"type":"string"}},{"name":"alias","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressUpdateDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressInfoDto"}}}}},"tags":["user"],"security":[{"Authorization":[]}]}},"/api/public/my-info/banks":{"get":{"operationId":"PublicApiMyInfoController_getBanks","summary":"Get banks list","description":"Retrieve list of funding sources","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/SenderBankFundingSourceDto"}}}}}},"tags":["my-info"],"security":[{"Authorization":[]}]}},"/api/public/invoices":{"post":{"operationId":"PublicApiInvoicesController_createInvoice","summary":"Create invoice","description":"Creates a new invoice with optional EOB file attachment","parameters":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/InvoiceCreateDto"}},"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreateDto"}}}},"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"Authorization":[]}]},"get":{"operationId":"PublicApiInvoicesController_getInvoicesList","summary":"Get list of self invoices","description":"Returns a list of invoices created by the current insurer","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicInvoiceDto"}}}}}},"tags":["invoices"],"security":[{"Authorization":[]}]}},"/api/public/invoices/{invoiceId}":{"get":{"operationId":"PublicApiInvoicesController_getInvoice","summary":"Get invoice by id","description":"Returns an invoice by its ID","parameters":[{"name":"invoiceId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"Invoice details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicInvoiceDto"}}}}},"tags":["invoices"],"security":[{"Authorization":[]}]},"put":{"operationId":"PublicApiInvoicesController_updateInvoice","summary":"Update invoice","description":"Updates an invoice by its ID","parameters":[{"name":"invoiceId","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUpdateDto"}}}},"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiInvoicesController_deleteInvoice","summary":"Delete invoice","description":"Deletes an invoice by its ID","parameters":[{"name":"invoiceId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["invoices"],"security":[{"Authorization":[]}]}},"/api/public/invoices/{invoiceId}/remit-commission":{"post":{"operationId":"PublicApiInvoicesController_remitCommission","summary":"Remit commission for an invoice","description":"Remits commission from the trust account to the operational account","parameters":[{"name":"invoiceId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"Authorization":[]}]}},"/api/public/invoices/{invoiceId}/remit-premium":{"post":{"operationId":"PublicApiInvoicesController_remitPremium","summary":"Remit premium for an invoice","description":"Remits premium from the trust account to the operational account","parameters":[{"name":"invoiceId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"201":{"description":""}},"tags":["invoices"],"security":[{"Authorization":[]}]}},"/api/public/carriers":{"get":{"operationId":"PublicApiCarriersController_getCarriers","summary":"Get list of carriers","description":"Returns a list of carriers","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CarrierDto"}}}}}},"tags":["carriers"],"security":[{"Authorization":[]}]},"post":{"operationId":"PublicApiCarriersController_createCarrier","summary":"Create carrier","description":"Creates a new carrier","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCarrierDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"number"}}}}},"tags":["carriers"],"security":[{"Authorization":[]}]}},"/api/public/carriers/{id}":{"get":{"operationId":"PublicApiCarriersController_getCarrier","summary":"Get carrier by id","description":"Returns a carrier by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CarrierDto"}}}}},"tags":["carriers"],"security":[{"Authorization":[]}]},"put":{"operationId":"PublicApiCarriersController_updateCarrier","summary":"Update carrier","description":"Updates a carrier by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCarrierDto"}}}},"responses":{"200":{"description":""}},"tags":["carriers"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiCarriersController_deleteCarrier","summary":"Delete carrier","description":"Deletes a carrier by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["carriers"],"security":[{"Authorization":[]}]}},"/api/public/policyholders":{"get":{"operationId":"PublicApiPolicyholdersController_getPolicyholders","summary":"Get list of policyholders","description":"Returns a list of policyholders","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PolicyholderDto"}}}}}},"tags":["policyholders"],"security":[{"Authorization":[]}]},"post":{"operationId":"PublicApiPolicyholdersController_createPolicyholder","summary":"Create policyholder","description":"Creates a new policyholder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyholderCreateDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"type":"number"}}}}},"tags":["policyholders"],"security":[{"Authorization":[]}]}},"/api/public/policyholders/{id}":{"get":{"operationId":"PublicApiPolicyholdersController_getPolicyholder","summary":"Get policyholder by id","description":"Returns a policyholder by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyholderDto"}}}}},"tags":["policyholders"],"security":[{"Authorization":[]}]},"put":{"operationId":"PublicApiPolicyholdersController_updatePolicyholder","summary":"Update policyholder","description":"Updates a policyholder by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyholderUpdateDto"}}}},"responses":{"200":{"description":""}},"tags":["policyholders"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiPolicyholdersController_deletePolicyholder","summary":"Delete policyholder","description":"Deletes a policyholder by its ID","parameters":[{"name":"id","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":""}},"tags":["policyholders"],"security":[{"Authorization":[]}]}},"/api/public/refunds":{"post":{"operationId":"PublicApiRefundsController_createRefund","summary":"Create refund to policyholder","description":"Creates a refund payment to an existing policyholder. The refund will be visible in the AgentSnap dashboard under invoices. Requires an existing policyholder ID that belongs to your account.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePublicRefundDto"}}}},"responses":{"201":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicRefundResponseDto"}}}}},"tags":["refunds"],"security":[{"Authorization":[]}]},"get":{"operationId":"PublicApiRefundsController_getRefunds","summary":"Get list of refunds","description":"Returns a list of refunds created by the current account","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PublicRefundResponseDto"}}}}}},"tags":["refunds"],"security":[{"Authorization":[]}]}},"/api/public/refunds/{refundId}":{"get":{"operationId":"PublicApiRefundsController_getRefund","summary":"Get refund by ID","description":"Returns a specific refund by its ID","parameters":[{"name":"refundId","required":true,"in":"path","schema":{"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicRefundResponseDto"}}}}},"tags":["refunds"],"security":[{"Authorization":[]}]}},"/api/public/subscriptions":{"get":{"operationId":"PublicApiSubscriptionsController_getSubscriptions","summary":"List subscriptions","description":"Retrieves a paginated list of subscriptions for the merchant with optional filtering","parameters":[{"name":"limit","required":false,"in":"query","description":"Maximum number of subscriptions to return (default: 20, max: 100)","schema":{"type":"number"}},{"name":"starting_after","required":false,"in":"query","description":"Cursor for pagination - ID of the last subscription from previous page","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by subscription status","schema":{"enum":["incomplete","incomplete_expired","trialing","active","past_due","canceled","unpaid","paused","unpaid_paused"],"type":"string"}},{"name":"customer_id","required":false,"in":"query","description":"Filter by Stripe customer ID (must start with \"cus_\")","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved subscriptions list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponseDto"}}}},"400":{"description":"Invalid pagination parameters or filter values"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]},"post":{"operationId":"PublicApiSubscriptionsController_createSubscription","summary":"Create subscription","description":"Creates a new subscription for a customer","parameters":[],"requestBody":{"required":true,"description":"Subscription configuration including customer and plan details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionDto"}}}},"responses":{"201":{"description":"Successfully created subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionResponseDto"}}}},"400":{"description":"Invalid subscription configuration"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]}},"/api/public/subscriptions/billing-portal":{"post":{"operationId":"PublicApiSubscriptionsController_createCustomerPortal","summary":"Create customer billing portal","description":"Creates a Stripe billing portal session for an existing customer to manage their subscription, payment methods, and billing details","parameters":[],"requestBody":{"required":true,"description":"Customer portal configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerPortalDto"}}}},"responses":{"200":{"description":"Successfully created customer portal session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerPortalResponseDto"}}}},"400":{"description":"Invalid customer or return URL"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Customer not found"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]}},"/api/public/subscriptions/products":{"post":{"operationId":"PublicApiSubscriptionsController_createProduct","summary":"Create subscription product","description":"Creates a new subscription product with associated pricing plans","parameters":[],"requestBody":{"required":true,"description":"Product and pricing plan configuration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductWithPlansDto"}}}},"responses":{"201":{"description":"Successfully created subscription product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductResponseDto"}}}},"400":{"description":"Invalid product or plan configuration"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]},"get":{"operationId":"PublicApiSubscriptionsController_getProducts","summary":"Get subscription products","description":"Retrieves all subscription products for the merchant","parameters":[{"name":"include_plans","required":false,"in":"query","description":"Whether to include pricing plans in the response","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved products","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ProductListItemDto"}}}}},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]}},"/api/public/subscriptions/{id}":{"get":{"operationId":"PublicApiSubscriptionsController_getSubscription","summary":"Get subscription by ID","description":"Retrieves detailed information about a specific subscription","parameters":[{"name":"id","required":true,"in":"path","description":"Subscription ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully retrieved subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionDetailResponseDto"}}}},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Subscription not found"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]},"delete":{"operationId":"PublicApiSubscriptionsController_cancelSubscription","summary":"Cancel subscription","description":"Cancels a subscription immediately or at the end of the current billing period","parameters":[{"name":"id","required":true,"in":"path","description":"Subscription ID to cancel","schema":{"type":"string"}}],"requestBody":{"required":false,"description":"Cancellation options","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionDto"}}}},"responses":{"200":{"description":"Successfully canceled subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelSubscriptionResponseDto"}}}},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Subscription not found"}},"tags":["subscriptions"],"security":[{"Authorization":[]}]}},"/api/public/customers/check":{"get":{"operationId":"PublicApiCustomersController_checkCustomerExists","summary":"Check if customer exists","description":"Verifies if a customer exists by email and returns their information including active subscriptions","parameters":[{"name":"email","required":true,"in":"query","description":"Customer email address to check","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully checked customer existence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerCheckResponseDto"}}}},"400":{"description":"Invalid email format or missing email parameter"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["customers"],"security":[{"Authorization":[]}]}},"/api/public/customers/onboard":{"post":{"operationId":"PublicApiCustomersController_onboardCustomer","summary":"Onboard new customer","description":"Creates a new customer with Stripe account and payment method setup","parameters":[],"requestBody":{"required":true,"description":"Customer onboarding information including personal details and payment method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardCustomerDto"}}}},"responses":{"201":{"description":"Successfully onboarded customer with Stripe account details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardCustomerResponseDto"}}}},"400":{"description":"Invalid customer data or payment method setup failed"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["customers"],"security":[{"Authorization":[]}]}},"/api/public/customers":{"get":{"operationId":"PublicApiCustomersController_getCustomers","summary":"Get customers list","description":"Retrieves a paginated list of customers for the merchant","parameters":[{"name":"limit","required":false,"in":"query","description":"Maximum number of customers to return (default: 50, max: 100)","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Number of customers to skip for pagination (default: 0)","schema":{"type":"number"}},{"name":"include_subscriptions","required":false,"in":"query","description":"Whether to include subscription data for each customer (default: false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved customers list with optional subscription data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerListResponseDto"}}}},"400":{"description":"Invalid limit or offset parameters"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"}},"tags":["customers"],"security":[{"Authorization":[]}]}},"/api/public/customers/{id}":{"get":{"operationId":"PublicApiCustomersController_getCustomer","summary":"Get customer by ID","description":"Retrieves detailed information about a specific customer including payment methods and optionally subscription history","parameters":[{"name":"id","required":true,"in":"path","description":"Stripe customer ID (starting with \"cus_\")","schema":{"type":"string"}},{"name":"include_subscriptions","required":false,"in":"query","description":"Whether to include subscription data for the customer (default: false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successfully retrieved customer details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomerDetailResponseDto"}}}},"400":{"description":"Invalid customer ID format"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Customer not found"}},"tags":["customers"],"security":[{"Authorization":[]}]},"put":{"operationId":"PublicApiCustomersController_updateCustomer","summary":"Update customer information","description":"Updates customer details such as contact information and address","parameters":[{"name":"id","required":true,"in":"path","description":"Stripe customer ID (starting with \"cus_\")","schema":{"type":"string"}}],"requestBody":{"required":true,"description":"Customer update data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerDto"}}}},"responses":{"200":{"description":"Successfully updated customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerResponseDto"}}}},"400":{"description":"Invalid update data or email format"},"401":{"description":"Invalid or missing authorization token"},"403":{"description":"Insufficient permissions"},"404":{"description":"Customer not found"}},"tags":["customers"],"security":[{"Authorization":[]}]}}},"info":{"title":"STAGING","description":"","version":"2.0","contact":{}},"tags":[],"servers":[{"url":"https://claims-staging.snaprefund.io"}],"components":{"securitySchemes":{"Authorization":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"ValidationErrorDto":{"type":"object","properties":{"field":{"type":"string","example":"recipientEmail","description":"Field name that failed validation"},"message":{"type":"string","example":"recipientEmail must be a valid email","description":"Validation error message"}},"required":["field","message"]},"ValidationErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","example":400,"description":"HTTP status code"},"code":{"type":"string","example":"PAYMENT_4002","description":"Machine-readable error code"},"message":{"type":"string","example":"Invalid payment amount","description":"Human-readable error message"},"timestamp":{"type":"string","example":"2026-02-15T10:30:00Z","description":"ISO 8601 timestamp"},"path":{"type":"string","example":"/api/public/payments/send-ach","description":"Request path"},"errors":{"description":"Array of field validation errors","type":"array","items":{"$ref":"#/components/schemas/ValidationErrorDto"}}},"required":["statusCode","code","message","timestamp","path","errors"]},"ErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","example":400,"description":"HTTP status code"},"code":{"type":"string","example":"PAYMENT_4002","description":"Machine-readable error code"},"message":{"type":"string","example":"Invalid payment amount","description":"Human-readable error message"},"timestamp":{"type":"string","example":"2026-02-15T10:30:00Z","description":"ISO 8601 timestamp"},"path":{"type":"string","example":"/api/public/payments/send-ach","description":"Request path"}},"required":["statusCode","code","message","timestamp","path"]},"ProviderErrorContextDto":{"type":"object","properties":{"provider":{"type":"string","example":"dwolla","enum":["dwolla","checkflo","plaid","stripe"],"description":"External provider name"},"providerCode":{"type":"string","example":"InsufficientFunds","description":"Provider-specific error code (for support/debugging)"},"providerMessage":{"type":"string","example":"Insufficient funds in the funding source","description":"Provider-specific error message (sanitized to exclude account details)"},"details":{"type":"object","description":"Additional provider error context (omitted to prevent data leakage)"}},"required":["provider"]},"ProviderErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","example":400,"description":"HTTP status code"},"code":{"type":"string","example":"PAYMENT_4002","description":"Machine-readable error code"},"message":{"type":"string","example":"Invalid payment amount","description":"Human-readable error message"},"timestamp":{"type":"string","example":"2026-02-15T10:30:00Z","description":"ISO 8601 timestamp"},"path":{"type":"string","example":"/api/public/payments/send-ach","description":"Request path"},"provider":{"description":"Information about the external provider error","allOf":[{"$ref":"#/components/schemas/ProviderErrorContextDto"}]}},"required":["statusCode","code","message","timestamp","path","provider"]},"PublicPaymentDto":{"type":"object","properties":{"id":{"type":"number","description":"Id of payment. Can be used for any payment operations."},"transactionId":{"type":"string","description":"Payment transaction Id. It can be seen in the application in the transaction history."},"amount":{"type":"number","description":"Payment amount without any fees."},"customerId":{"type":"number","nullable":true,"description":"The Id of customerwho will receive the payment or has already received it."},"customerName":{"type":"string","description":"Name of the customer who will receive the payment or has already received it."},"merchantName":{"type":"string","description":"Name of the merchant who will send the payment or has already sent it."},"fee":{"type":"number","description":"Fee for the payment amount. It will only be different from zero when this payment is sent."},"feeDeductFrom":{"type":"string","nullable":true,"description":"Which side of the transfer will pay the fee."},"status":{"type":"string","nullable":true,"description":"Status of payment. Main statuses: Awaiting-cash-out, Cancelled, Preparing to mail, In-transit, Settled"},"type":{"type":"string","nullable":true,"description":"Type of payment. Can be only of two types: ACH or paper check with delivery type."},"memo":{"type":"string","maxLength":280,"description":"A string with a maximum length of 280 characters."},"failureReason":{"type":"string","nullable":true,"description":"If the current payment is ACH and has the failed status, here you can get a description of the reason for the failure"},"failureAchCode":{"type":"string","nullable":true,"description":"If the current payment is ACH and has the failed status, here you can get an ACH error code"},"settledAt":{"format":"date-time","type":"string","nullable":true,"description":"Time when payment is settled or mailed"},"achReturnFee":{"type":"number","nullable":true,"description":"ACH return fee amount charged when a payment is returned"},"achReturnFeeDate":{"format":"date-time","type":"string","nullable":true,"description":"Date when the ACH return fee was charged"},"achReturnCode":{"type":"string","nullable":true,"description":"ACH return code (e.g., R01 for Insufficient Funds)"},"achReturnReason":{"type":"string","nullable":true,"description":"Human-readable reason for ACH return"},"availablePaymentMethods":{"nullable":true,"type":"array","description":"Allowed payout methods for this payment. If null, all methods are available.","items":{"type":"string","enum":["--","P2D","ACH","Paper Check","Fee Payment","Monthly Fee Payment","RTP","Expedited ACH","Same Day ACH","Wallet Deposit","Wallet Withdraw","PayPal Wallet Deposit","PayPal Wallet Withdraw","Venmo","Auto Remit Commission"]}},"createdAt":{"format":"date-time","type":"string"}},"required":["id","transactionId","amount","customerId","customerName","merchantName","fee","feeDeductFrom","status","type","memo","createdAt"]},"PaymentSendCheckDto":{"type":"object","properties":{"recipientEmail":{"type":"string","description":"The user's email address. This value will be used for all future notifications and web-app logins for this user, so choose carefully."},"amount":{"type":"number","minimum":0.01,"description":"The amount of money being transferred. Amounts should have either 0 or 2 decimal places. Max limit is based on most current agreement with SnapRefund. Minimum limit is $0.01."},"memo":{"type":"string","minLength":1,"maxLength":280,"description":"A string with a maximum length of 280 characters."},"alias":{"type":"string","description":"An alias for the client's address information. The alias value can be retrieved by the endpoint: /api/public/users/{userId}/addresses"},"mailType":{"enum":["FedEx","Mail","USPSFirst","USPSTrack"],"type":"string","description":"Check shipping type. Available in four options only: FedEx, Mail, USPSFirst, USPSTrack."},"approversEmails":{"description":"Array of email addresses for payment approvers","type":"array","items":{"type":"string"}}},"required":["recipientEmail","amount","memo","alias","mailType"]},"PaymentAcceptAchDto":{"type":"object","properties":{"bankId":{"type":"string","description":"The customer's bank to be used for the ACH dwolla transfer. The id value can be retrieved by the endpoint: /api/public/users/{userId}/banks"}},"required":["bankId"]},"PaymentAcceptCheckDto":{"type":"object","properties":{"alias":{"type":"string","description":"An alias for the client's address information. The alias value can be retrieved by the endpoint: /api/public/users/{userId}/addresses"},"mailType":{"enum":["FedEx","Mail","USPSFirst","USPSTrack"],"type":"string","description":"Check shipping type. Available in four options only: FedEx, Mail, USPSFirst, USPSTrack."}},"required":["alias","mailType"]},"PaymentAcceptRtpDto":{"type":"object","properties":{"bankId":{"type":"string","description":"The customer's bank to be used for the RTP dwolla transfer. The id value can be retrieved by the endpoint: /api/public/users/{userId}/banks"}},"required":["bankId"]},"PaymentAcceptVenmoDto":{"type":"object","properties":{"venmoRecipientType":{"enum":["PHONE","EMAIL","USER_HANDLE"],"type":"string","description":"Venmo recipient type. Available values: USER_HANDLE, PHONE, EMAIL."},"venmoReceiver":{"type":"string","description":"Venmo identifier that matches the selected recipient type."}},"required":["venmoRecipientType","venmoReceiver"]},"PaymentSendVenmoDto":{"type":"object","properties":{"recipientEmail":{"type":"string","description":"The user's email address. This value will be used for all future notifications and web-app logins for this user, so choose carefully."},"amount":{"type":"number","minimum":0.01,"description":"The amount of money being transferred. Amounts should have either 0 or 2 decimal places. Max limit is based on most current agreement with SnapRefund. Minimum limit is $0.01."},"memo":{"type":"string","minLength":1,"maxLength":280,"description":"A string with a maximum length of 280 characters."},"venmoRecipientType":{"enum":["PHONE","EMAIL","USER_HANDLE"],"type":"string","description":"Venmo recipient type. Available values: USER_HANDLE, PHONE, EMAIL."},"venmoReceiver":{"type":"string","description":"Venmo identifier that matches the selected recipient type."}},"required":["recipientEmail","amount","memo","venmoRecipientType","venmoReceiver"]},"WalletBalanceDto":{"type":"object","properties":{"value":{"type":"string"},"currency":{"type":"string"}},"required":["value","currency"]},"PublicApiWalletTransferDto":{"type":"object","properties":{"fundingSource":{"type":"string","description":"Dwolla funding source id to use as the counterparty for the transfer"},"amount":{"type":"string","description":"Amount of funds to deposit or withdraw"}},"required":["fundingSource","amount"]},"UserDto":{"type":"object","properties":{"id":{"type":"number","description":"Id of insured"},"email":{"type":"string","description":"The user's email address. This value will be used for all future notifications and web-app logins for this user, so choose carefully."},"firstName":{"type":"string","description":"The user's legal first name."},"lastName":{"type":"string","description":"The user's legal last name."},"businessName":{"type":"string","nullable":true,"description":"The user's business name, if applicable. Providing a value here will cause this user to be created as an Unverified Business type, otherwise they will be an Unverified Personal type."}},"required":["id","email","firstName","lastName"]},"UserListDto":{"type":"object","properties":{"total":{"type":"number"},"users":{"type":"array","items":{"$ref":"#/components/schemas/UserDto"}}},"required":["total","users"]},"AddressInfoDto":{"type":"object","properties":{"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"postalCode":{"type":"string","minLength":5,"maxLength":5},"state":{"enum":["AL","AK","AS","AZ","AR","CA","CO","CT","DC","DE","FL","GA","GU","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MP","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","PR","RI","SC","SD","TN","TX","UM","UT","VT","VI","VA","WA","WV","WI","WY"],"type":"string"},"phone":{"type":"string","nullable":true},"alias":{"type":"string","description":"The name of the address information. Will be used to deliver checks."}},"required":["address1","city","postalCode","state","alias"]},"UserPreferencesDto":{"type":"object","properties":{"paymentSMSAllowed":{"type":"boolean","description":"The customer's communication preferences. If enabled, customer will receive sms text notifications."},"marketingEmailsAllowed":{"type":"boolean","description":"The customer's communication preferences. If enabled, customer will receive email notifications about our new features."},"paymentEmailsAllowed":{"type":"boolean","description":"The customer's communication preferences. If enabled, customer will receive email notifications."}},"required":["paymentSMSAllowed","marketingEmailsAllowed","paymentEmailsAllowed"]},"UserInfoDto":{"type":"object","properties":{"addresses":{"type":"array","items":{"$ref":"#/components/schemas/AddressInfoDto"}},"preferences":{"$ref":"#/components/schemas/UserPreferencesDto"}},"required":["addresses","preferences"]},"UpdateUserInfoDto":{"type":"object","properties":{"email":{"type":"string","description":"The user's email address. This value will be used for all future notifications and web-app logins for this user, so choose carefully."},"firstName":{"type":"string","description":"The user's legal first name."},"lastName":{"type":"string","description":"The user's legal last name."}}},"UpdatePaymentEmailPreferenceDto":{"type":"object","properties":{"isAllowed":{"type":"boolean","description":"Update the customer's communication preferences status to enabled (true) or disabled (false)."}},"required":["isAllowed"]},"UpdateMarketingEmailPreferenceDto":{"type":"object","properties":{"isAllowed":{"type":"boolean","description":"Update the customer's communication preferences status to enabled (true) or disabled (false)."}},"required":["isAllowed"]},"UpdatePaymentSmsPreferenceDto":{"type":"object","properties":{"isAllowed":{"type":"boolean","description":"Update the customer's communication preferences status to enabled (true) or disabled (false)."}},"required":["isAllowed"]},"BankInfoDto":{"type":"object","properties":{"routingNumber":{"type":"string","minLength":9,"maxLength":9,"description":"A numeric string for the bank routing number corresponding to a US bank or credit union. The first two digits must be in a range from \"01\" through \"12\", or \"21\" through \"32\", and the string value must consist of nine digits."},"accountNumber":{"type":"string","minLength":4,"maxLength":17,"description":"A numeric string of 4-17 digits."},"accountType":{"enum":["checking","savings"],"type":"string","description":"The type of bank account this is must be one of these values: checking or savings."}},"required":["routingNumber","accountNumber","accountType"]},"CreateUserReceiveOnlyDto":{"type":"object","properties":{"bankInfo":{"description":"Bank details of the insured. It can be added at creation or with a different endpoint.","allOf":[{"$ref":"#/components/schemas/BankInfoDto"}]},"address":{"description":"The user's physical mailing address. Providing a value here is only necessary if you want the user to be able to receive paper checks in the mail.","allOf":[{"$ref":"#/components/schemas/AddressInfoDto"}]},"email":{"type":"string","description":"The user's email address. This value will be used for all future notifications and web-app logins for this user, so choose carefully."},"firstName":{"type":"string","description":"The user's legal first name."},"lastName":{"type":"string","description":"The user's legal last name."},"businessName":{"type":"string","nullable":true,"description":"The user's business name, if applicable. Providing a value here will cause this user to be created as an Unverified Business type, otherwise they will be an Unverified Personal type."}},"required":["email","firstName","lastName"]},"CreateUserReceiveOnlyResponseDto":{"type":"object","properties":{"id":{"type":"number"}},"required":["id"]},"BankFundingSourceDto":{"type":"object","properties":{"id":{"type":"string","description":"This is dwolla bank id. Used for all ACH payments."},"name":{"type":"string","description":"Name of the bank."},"accountType":{"enum":["checking","savings"],"type":"string","description":"Type of bank account. Can be only checking or savings"},"type":{"enum":["bank","balance","virtual","card"],"type":"string","description":"Type of current funding source. It will always be a bank, since we can only have bank-type funding sources."},"status":{"enum":["unverified","verified"],"type":"string","description":"Bank status. This status is derived from information about the source of funding for the dwolla. For clients created with the API it will always be undefined as we don't use PLAID to validate as we do in the application."}},"required":["id","name","accountType","type","status"]},"AddressCreateDto":{"type":"object","properties":{"address1":{"type":"string"},"address2":{"type":"string"},"city":{"type":"string"},"postalCode":{"type":"string","minLength":5,"maxLength":5},"state":{"enum":["AL","AK","AS","AZ","AR","CA","CO","CT","DC","DE","FL","GA","GU","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MP","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","PR","RI","SC","SD","TN","TX","UM","UT","VT","VI","VA","WA","WV","WI","WY"],"type":"string"},"phone":{"type":"string"},"alias":{"type":"string","description":"The name of the address information. Will be used to deliver checks."}},"required":["address1","city","postalCode","state","phone","alias"]},"AddressUpdateDto":{"type":"object","properties":{"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"city":{"type":"string"},"postalCode":{"type":"string","minLength":5,"maxLength":5},"state":{"enum":["AL","AK","AS","AZ","AR","CA","CO","CT","DC","DE","FL","GA","GU","HI","ID","IL","IN","IA","KS","KY","LA","ME","MD","MA","MI","MN","MP","MS","MO","MT","NE","NV","NH","NJ","NM","NY","NC","ND","OH","OK","OR","PA","PR","RI","SC","SD","TN","TX","UM","UT","VT","VI","VA","WA","WV","WI","WY"],"type":"string"},"phone":{"type":"string","nullable":true},"alias":{"type":"string","description":"The name of the address information. Will be used to deliver checks."}},"required":["address1","city","postalCode","state","alias"]},"SenderBankFundingSourceDto":{"type":"object","properties":{"id":{"type":"string","description":"This is dwolla bank id. Used for all ACH payments."},"name":{"type":"string","description":"Name of the bank."},"accountType":{"enum":["checking","savings"],"type":"string","description":"Type of bank account. Can be only checking or savings"},"type":{"enum":["bank","balance","virtual","card"],"type":"string","description":"Type of current funding source. It will always be a bank, since we can only have bank-type funding sources."},"status":{"enum":["unverified","verified"],"type":"string","description":"Bank status. This status is derived from information about the source of funding for the dwolla. For clients created with the API it will always be undefined as we don't use PLAID to validate as we do in the application."},"defaultForPayments":{"type":"boolean","description":"Shows if this bank used for payments by default or not"}},"required":["id","name","accountType","type","status","defaultForPayments"]},"InvoiceCreateDto":{"type":"object","properties":{"policyholderId":{"type":"number","description":"ID of the policyholder for whom this invoice is created."},"carrierId":{"type":"number","description":"ID of the insurance carrier."},"mgaId":{"type":"number","description":"ID of the MGA."},"grossPremium":{"type":"number","description":"Gross premium amount with up to 2 decimal places."},"commission":{"type":"number","nullable":true,"description":"Commission amount with up to 2 decimal places."},"taxes":{"type":"number","nullable":true,"description":"Tax amount with up to 2 decimal places."},"serviceFee":{"type":"number","nullable":true,"description":"Service fee amount."},"effectiveDate":{"format":"date-time","type":"string","description":"Effective date of the invoice."},"expirationDate":{"format":"date-time","type":"string","description":"Expiration date of the invoice."},"policyId":{"type":"string","nullable":true,"maxLength":50,"description":"External policy ID."},"brokerCode":{"type":"string","nullable":true,"maxLength":50,"description":"Broker code associated with this invoice."},"memo":{"type":"string","nullable":true,"maxLength":256,"description":"Memo or notes related to the invoice."},"downPayment":{"type":"number","nullable":true,"description":"Down payment amount."},"financeAmount":{"type":"number","nullable":true,"description":"Finance amount."},"shouldBeSigned":{"type":"boolean","description":"Whether the invoice should be signed."},"paymentMethod":{"enum":["card","us_bank_account","affirm"],"type":"string","description":"Desired payment method for the policyholder."},"stripeSubscriptionId":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription ID if this invoice is generated from a subscription payment.","example":"sub_1234567890abcdef"}},"required":["policyholderId","carrierId","grossPremium","effectiveDate","expirationDate"]},"InvoicePolicyholderDto":{"type":"object","properties":{"id":{"type":"number","description":"Unique policyholder identifier"},"firstName":{"type":"string","description":"First name of the policyholder"},"lastName":{"type":"string","description":"Last name of the policyholder"},"businessName":{"type":"string","nullable":true,"description":"Business name (if business policy)"},"email":{"type":"string","description":"Primary contact email","format":"email"}},"required":["id","firstName","lastName","businessName","email"]},"InvoiceCarrierDto":{"type":"object","properties":{"id":{"type":"number","description":"Unique carrier identifier"},"firstName":{"type":"string","description":"First name of the carrier contact"},"lastName":{"type":"string","description":"Last name of the carrier contact"},"businessName":{"type":"string","description":"Carrier business name"},"email":{"type":"string","description":"Primary contact email","format":"email"},"commission":{"type":"number","nullable":true,"description":"Commission percentage for this carrier"}},"required":["id","firstName","lastName","businessName","email","commission"]},"PublicInvoiceStatusDto":{"type":"object","properties":{"code":{"enum":[1,2,3,4,21,19,20,22,5,6,7,8,9,10,11,12,17,13,14,15,16,18,23],"type":"number","description":"The numeric code of the invoice status.","example":1},"value":{"type":"string","description":"The string representation of the invoice status.","example":"payment_link_pending"}},"required":["code","value"]},"PublicInvoiceDto":{"type":"object","properties":{"id":{"type":"number","description":"Id of the invoice. Used for invoice operations."},"policyholder":{"nullable":true,"description":"Detailed policyholder information","allOf":[{"$ref":"#/components/schemas/InvoicePolicyholderDto"}]},"carrier":{"nullable":true,"description":"Detailed carrier information","allOf":[{"$ref":"#/components/schemas/InvoiceCarrierDto"}]},"type":{"type":"string","description":"The type of the invoice (e.g., \"Invoice\", \"Refund\")."},"status":{"description":"The current status of the invoice.","allOf":[{"$ref":"#/components/schemas/PublicInvoiceStatusDto"}]},"grossPremium":{"type":"number","nullable":true,"description":"Total gross premium amount."},"commission":{"type":"number","nullable":true,"description":"Commission amount for the invoice."},"taxes":{"type":"number","nullable":true,"description":"Applicable taxes."},"serviceFee":{"type":"number","nullable":true,"description":"Service fee associated with the invoice."},"downPayment":{"type":"number","nullable":true,"description":"Down payment amount."},"financeAmount":{"type":"number","nullable":true,"description":"Amount financed for the premium."},"memo":{"type":"string","nullable":true,"maxLength":280,"description":"Optional memo related to the invoice (max 280 chars)."},"policyId":{"type":"string","nullable":true,"description":"Policy ID if linked to this invoice."},"brokerCode":{"type":"string","nullable":true,"description":"Broker code associated with the invoice."},"paymentMethod":{"type":"string","nullable":true,"description":"The payment method selected for this invoice."},"createdAt":{"format":"date-time","type":"string","description":"Date when the invoice was created."},"premiumSettledAt":{"format":"date-time","type":"string","nullable":true,"description":"Date when the premium was settled."},"effectiveDate":{"format":"date-time","type":"string","nullable":true,"description":"Effective date of the invoice."},"expirationDate":{"format":"date-time","type":"string","nullable":true,"description":"Expiration date of the invoice."},"shouldBeSigned":{"type":"boolean","description":"Indicates if the invoice requires a signature."},"stripeSubscriptionId":{"type":"string","nullable":true,"description":"Stripe subscription ID if this invoice was generated from a subscription."}},"required":["id","policyholder","carrier","type","status","grossPremium","commission","taxes","serviceFee","downPayment","financeAmount","memo","policyId","brokerCode","paymentMethod","createdAt","premiumSettledAt","effectiveDate","expirationDate","shouldBeSigned"]},"InvoiceUpdateDto":{"type":"object","properties":{"policyholderId":{"type":"number","description":"ID of the policyholder for whom this invoice is created."},"carrierId":{"type":"number","description":"ID of the insurance carrier."},"grossPremium":{"type":"number","description":"Gross premium amount with up to 2 decimal places."},"commission":{"type":"number","nullable":true,"description":"Commission amount with up to 2 decimal places."},"memo":{"type":"string","nullable":true,"maxLength":256,"description":"Memo or notes related to the invoice."},"policyId":{"type":"string","nullable":true,"maxLength":50,"description":"External policy ID."},"brokerCode":{"type":"string","nullable":true,"maxLength":50,"description":"Broker code associated with this invoice."},"taxes":{"type":"number","nullable":true,"description":"Tax amount with up to 2 decimal places."},"effectiveDate":{"format":"date-time","type":"string","description":"Effective date of the invoice."},"expirationDate":{"format":"date-time","type":"string","nullable":true,"description":"Expiration date of the invoice."},"serviceFee":{"type":"number","nullable":true,"description":"Service fee amount."},"downPayment":{"type":"number","nullable":true,"description":"Down payment amount."},"financeAmount":{"type":"number","nullable":true,"description":"Finance amount."},"stripeSubscriptionId":{"type":"string","nullable":true,"maxLength":255,"description":"Stripe subscription ID if this invoice is generated from a subscription payment.","example":"sub_1234567890abcdef"}}},"CarrierDto":{"type":"object","properties":{"id":{"type":"number","description":"Unique carrier identifier"},"name":{"type":"string","description":"Carrier name"},"email":{"type":"string","description":"Primary contact email","format":"email"},"commission":{"type":"number","description":"Commission percentage for this carrier","nullable":true}},"required":["id","name","email"]},"AddressDto":{"type":"object","properties":{"id":{"type":"number"},"profileId":{"type":"number","nullable":true},"alias":{"type":"string"},"address1":{"type":"string"},"address2":{"type":"string","nullable":true},"address3":{"type":"string","nullable":true},"country":{"nullable":true,"type":"object"},"city":{"type":"string"},"state":{"nullable":true,"type":"object"},"provinceOrRegion":{"type":"string","nullable":true},"postalCode":{"type":"string"},"type":{"nullable":true,"type":"object"},"phone":{"type":"string","nullable":true},"firstName":{"type":"string","nullable":true},"lastName":{"type":"string","nullable":true},"toReceiveChecks":{"type":"boolean"}},"required":["id","profileId","alias","address1","address2","address3","country","city","state","provinceOrRegion","postalCode","type","phone","firstName","lastName","toReceiveChecks"]},"CreateCarrierDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"First name of the carrier contact"},"lastName":{"type":"string","maxLength":255,"description":"Last name of the carrier contact"},"businessName":{"type":"string","maxLength":255,"description":"Business name of the carrier"},"email":{"type":"string","maxLength":255,"description":"Primary contact email","format":"email"},"commission":{"type":"number","description":"Commission rate for this carrier"},"address":{"description":"Carrier address information","allOf":[{"$ref":"#/components/schemas/AddressDto"}]}},"required":["firstName","lastName","businessName","email"]},"UpdateCarrierDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"First name of the carrier contact"},"lastName":{"type":"string","maxLength":255,"description":"Last name of the carrier contact"},"businessName":{"type":"string","maxLength":255,"description":"Business name of the carrier"},"email":{"type":"string","maxLength":255,"description":"Primary contact email","format":"email"},"commission":{"type":"number","description":"Commission rate for this carrier"},"address":{"description":"Carrier address information","allOf":[{"$ref":"#/components/schemas/AddressDto"}]}}},"PolicyholderDto":{"type":"object","properties":{"id":{"type":"number","description":"Unique policyholder identifier"},"firstName":{"type":"string","description":"First name of the policyholder"},"lastName":{"type":"string","description":"Last name of the policyholder"},"businessName":{"type":"string","description":"Business name (if business policy)","nullable":true},"email":{"type":"string","description":"Primary contact email","format":"email"}},"required":["id","firstName","lastName","email"]},"PolicyholderCreateDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"The first name of the policyholder","example":"John"},"lastName":{"type":"string","maxLength":255,"description":"The last name of the policyholder","example":"Doe"},"businessName":{"type":"string","nullable":true,"maxLength":255,"description":"The business name of the policyholder (optional)","example":"Acme Insurance"},"email":{"type":"string","maxLength":255,"description":"The email of the policyholder","example":"john.doe@example.com"}},"required":["firstName","lastName","email"]},"PolicyholderUpdateDto":{"type":"object","properties":{"firstName":{"type":"string","maxLength":255,"description":"First name of the policyholder"},"lastName":{"type":"string","maxLength":255,"description":"Last name of the policyholder"},"businessName":{"type":"string","nullable":true,"maxLength":255,"description":"Business name (if business policy)"},"email":{"type":"string","maxLength":255,"description":"Primary contact email","format":"email"}}},"CreatePublicRefundDto":{"type":"object","properties":{"policyholderId":{"type":"number","minimum":1,"description":"ID of the policyholder receiving the refund. Must be an existing policyholder that belongs to your account."},"amount":{"type":"number","minimum":0.01,"description":"Refund amount in dollars. Amounts should have either 0 or 2 decimal places. Minimum is $0.01."},"memo":{"type":"string","maxLength":280,"description":"Optional memo/description for the refund. Maximum 280 characters."}},"required":["policyholderId","amount"]},"PolicyholderInfoDto":{"type":"object","properties":{"id":{"type":"number","description":"Policyholder ID"},"firstName":{"type":"string","description":"Policyholder first name"},"lastName":{"type":"string","description":"Policyholder last name"},"businessName":{"type":"string","nullable":true,"description":"Business name if applicable"},"email":{"type":"string","description":"Policyholder email address"}},"required":["id","firstName","lastName","email"]},"PublicRefundResponseDto":{"type":"object","properties":{"id":{"type":"number","description":"Unique identifier for the refund"},"policyholderId":{"type":"number","description":"ID of the policyholder receiving the refund"},"amount":{"type":"number","description":"Refund amount in dollars"},"memo":{"type":"string","nullable":true,"description":"Memo/description for the refund"},"status":{"description":"Current status of the refund","allOf":[{"$ref":"#/components/schemas/PublicInvoiceStatusDto"}]},"createdAt":{"format":"date-time","type":"string","description":"Date when the refund was created"},"policyholder":{"description":"Policyholder information","allOf":[{"$ref":"#/components/schemas/PolicyholderInfoDto"}]}},"required":["id","policyholderId","amount","status","createdAt","policyholder"]},"SubscriptionCustomerDto":{"type":"object","properties":{"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"email":{"type":"string","description":"Customer email"},"name":{"type":"string","description":"Customer name"}},"required":["stripeCustomerId","email","name"]},"SubscriptionPlanDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID"},"name":{"type":"string","description":"Plan name"},"amount":{"type":"number","description":"Plan amount in cents"},"currency":{"type":"string","description":"Currency code"},"interval":{"type":"string","description":"Billing interval"},"intervalCount":{"type":"number","description":"Billing interval count","example":1}},"required":["stripePriceId","name","amount","currency","interval","intervalCount"]},"SubscriptionListItemDto":{"type":"object","properties":{"status":{"type":"string","description":"Subscription status","enum":["incomplete","incomplete_expired","trialing","active","past_due","canceled","unpaid","paused","unpaid_paused"]},"customer":{"description":"Customer information","allOf":[{"$ref":"#/components/schemas/SubscriptionCustomerDto"}]},"plan":{"description":"Plan information","allOf":[{"$ref":"#/components/schemas/SubscriptionPlanDto"}]},"currentPeriodStart":{"format":"date-time","type":"string","description":"Current period start"},"currentPeriodEnd":{"format":"date-time","type":"string","description":"Current period end"},"createdAt":{"format":"date-time","type":"string","description":"Subscription creation date"}},"required":["status","customer","plan","currentPeriodStart","currentPeriodEnd","createdAt"]},"SubscriptionPaginationDto":{"type":"object","properties":{"limit":{"type":"number","description":"Applied limit per page"},"hasMore":{"type":"boolean","description":"Whether more results are available"},"nextCursor":{"type":"string","description":"Cursor for next page (if hasMore is true)"}},"required":["limit","hasMore"]},"SubscriptionListResponseDto":{"type":"object","properties":{"data":{"description":"List of subscriptions","type":"array","items":{"$ref":"#/components/schemas/SubscriptionListItemDto"}},"pagination":{"description":"Pagination information","allOf":[{"$ref":"#/components/schemas/SubscriptionPaginationDto"}]}},"required":["data","pagination"]},"CreateCustomerPortalDto":{"type":"object","properties":{"stripeCustomerId":{"type":"string","description":"Stripe customer ID (must start with \"cus_\")"},"returnUrl":{"type":"string","description":"URL to redirect after portal session"}},"required":["stripeCustomerId","returnUrl"]},"CreateCustomerPortalResponseDto":{"type":"object","properties":{"url":{"type":"string","description":"Portal session URL"}},"required":["url"]},"CreatePlanDto":{"type":"object","properties":{"name":{"type":"string","description":"Plan name for display purposes","example":"Premium Auto Insurance"},"description":{"type":"string","description":"Detailed plan description","example":"Comprehensive auto insurance with full coverage"},"amount":{"type":"number","description":"Price amount in cents (e.g., 2999 = $29.99)","example":2999,"minimum":0},"currency":{"type":"string","description":"Currency code (ISO 4217 format)","example":"usd","pattern":"^[a-z]{3}$"},"interval":{"enum":["day","week","month","year"],"type":"string","description":"🔄 **BILLING INTERVAL: Defines the billing frequency unit**\n    \n**Purpose:** Specifies the base time unit for billing cycles. This works together with `intervalCount` to determine exactly how often customers are charged.\n\n**Available Options:**\n- `day`: Daily billing (use with caution - typically for very short-term subscriptions)\n- `week`: Weekly billing (common for services, memberships)\n- `month`: Monthly billing (most common for SaaS, insurance, subscriptions)\n- `year`: Annual billing (often with discounts, insurance policies)\n\n**💡 Common Patterns:**\n- **Monthly**: `interval: \"month\", intervalCount: 1` → Bill every month\n- **Quarterly**: `interval: \"month\", intervalCount: 3` → Bill every 3 months  \n- **Semi-Annual**: `interval: \"month\", intervalCount: 6` → Bill every 6 months\n- **Annual**: `interval: \"year\", intervalCount: 1` → Bill every year\n- **Bi-Annual**: `interval: \"year\", intervalCount: 2` → Bill every 2 years\n\n**🏢 Insurance Industry Examples:**\n- Auto Insurance: Often `month` (monthly premiums) or `year` (annual policies)\n- Health Insurance: Typically `month` (monthly premiums)\n- Life Insurance: Usually `month` or `year` depending on policy type\n\n**⚠️ Important Notes:**\n- Must be combined with `intervalCount` for complete billing schedule\n- Cannot be changed after plan creation (create new plan instead)\n- Affects customer payment experience and cash flow","example":"month"},"intervalCount":{"type":"number","description":"🔢 **INTERVAL COUNT: Multiplier for billing frequency**\n    \n**Purpose:** Specifies how many `interval` units to wait between each billing cycle. This creates the complete billing schedule when combined with `interval`.\n\n**How It Works:**\nThe billing frequency = `intervalCount` × `interval`\n\n**📊 Practical Examples:**\n\n**Monthly Plans:**\n- `intervalCount: 1` + `interval: \"month\"` = Every 1 month (monthly)\n- `intervalCount: 3` + `interval: \"month\"` = Every 3 months (quarterly)  \n- `intervalCount: 6` + `interval: \"month\"` = Every 6 months (semi-annually)\n\n**Annual Plans:**\n- `intervalCount: 1` + `interval: \"year\"` = Every 1 year (annually)\n- `intervalCount: 2` + `interval: \"year\"` = Every 2 years (biennial)\n\n**Weekly Plans:**\n- `intervalCount: 1` + `interval: \"week\"` = Every week\n- `intervalCount: 2` + `interval: \"week\"` = Every 2 weeks (bi-weekly)\n- `intervalCount: 4` + `interval: \"week\"` = Every 4 weeks (~monthly)\n\n**🏢 Insurance Business Use Cases:**\n- **Auto Insurance**: `intervalCount: 1, interval: \"month\"` for monthly premiums\n- **Annual Policies**: `intervalCount: 1, interval: \"year\"` with discount pricing\n- **Quarterly Business**: `intervalCount: 3, interval: \"month\"` for commercial policies\n\n**💰 Pricing Strategy Tips:**\n- Higher `intervalCount` often comes with discounts (annual vs monthly)\n- Lower `intervalCount` provides steadier cash flow\n- Consider customer preference vs cash flow needs\n\n**⚠️ Constraints:**\n- Must be a positive integer (minimum: 1)\n- Default: 1 if not specified\n- Maximum varies by `interval` type (Stripe enforces limits)\n- Cannot be modified after plan creation","example":1,"minimum":1,"default":1}},"required":["name","amount","currency","interval"]},"CreateProductWithPlansDto":{"type":"object","properties":{"productName":{"type":"string","description":"Product name for display purposes","example":"Auto Insurance Plans"},"productDescription":{"type":"string","description":"Detailed product description","example":"Comprehensive auto insurance coverage with multiple plan options"},"plans":{"description":"Array of pricing plans for this product","example":[{"name":"Basic Auto Coverage","description":"Essential auto insurance coverage","amount":4999,"currency":"usd","interval":"month","intervalCount":1},{"name":"Premium Auto Coverage (Annual)","description":"Full coverage with annual discount","amount":49999,"currency":"usd","interval":"year","intervalCount":1}],"type":"array","items":{"$ref":"#/components/schemas/CreatePlanDto"}}},"required":["productName","plans"]},"CreateProductPlanDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID"},"amount":{"type":"number","description":"Price amount in cents"},"currency":{"type":"string","description":"Currency code"},"interval":{"type":"string","description":"Billing interval","enum":["month","year"]}},"required":["stripePriceId","amount","currency","interval"]},"CreateProductResponseDto":{"type":"object","properties":{"stripeProductId":{"type":"string","description":"Stripe product identifier"},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"plans":{"description":"Available pricing plans","type":"array","items":{"$ref":"#/components/schemas/CreateProductPlanDto"}}},"required":["stripeProductId","name","description","plans"]},"ProductPlanDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID"},"amount":{"type":"number","description":"Price amount in cents"},"currency":{"type":"string","description":"Currency code"},"interval":{"type":"string","description":"Billing interval (month, year, etc.)"},"intervalCount":{"type":"number","description":"Number of intervals between billings","default":1}},"required":["stripePriceId","amount","currency","interval"]},"ProductListItemDto":{"type":"object","properties":{"stripeProductId":{"type":"string","description":"Stripe product identifier"},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"plans":{"description":"Available pricing plans (if include_plans=true)","type":"array","items":{"$ref":"#/components/schemas/ProductPlanDto"}}},"required":["stripeProductId","name","description"]},"CreateSubscriptionDto":{"type":"object","properties":{"effectiveDate":{"format":"date-time","type":"string","description":"Effective date of the policy/subscription","example":"2024-01-01T00:00:00.000Z"},"expirationDate":{"format":"date-time","type":"string","description":"Expiration date of the policy/subscription","example":"2025-01-01T00:00:00.000Z"},"stripeCustomerId":{"type":"string","pattern":"/^cus_/","description":"The Stripe customer ID (must start with \"cus_\")"},"stripePriceId":{"type":"string","pattern":"/^price_/","description":"The Stripe price ID for the subscription plan (must start with \"price_\")"},"policyholderId":{"type":"number","description":"The policyholder ID from contact catalog"},"carrierId":{"type":"number","description":"The carrier ID from contact catalog"},"isAutoRemitPremiums":{"type":"boolean","description":"Whether to automatically remit premiums for invoices created from this subscription"},"serviceFee":{"type":"number","description":"Service fee amount to be applied to invoices created from this subscription"},"taxes":{"type":"number","description":"Tax amount to be applied to invoices created from this subscription"},"commission":{"type":"number","description":"Commission amount to override default calculation for invoices created from this subscription"},"numDaysForAutoRemind":{"type":"number","description":"Number of days for auto-reminder notifications"},"memo":{"type":"string","maxLength":200,"description":"Custom memo prefix for invoices created from this subscription"},"brokerCode":{"type":"string","maxLength":50,"description":"Broker code associated with this subscription"},"shouldBeSigned":{"type":"boolean","description":"Whether invoices created from this subscription should be signed"},"isCommissionVisibleForPolicyholder":{"type":"boolean","description":"Whether commission should be visible to policyholder in invoices created from this subscription"},"mgaId":{"type":"number","description":"ID of the MGA."},"policyId":{"type":"string","nullable":true,"maxLength":50,"description":"External policy ID."},"downPayment":{"type":"number","nullable":true,"description":"Down payment amount."},"financeAmount":{"type":"number","nullable":true,"description":"Finance amount."},"paymentMethod":{"enum":["card","us_bank_account"],"type":"string","description":"Required payment method for the subscription. This determines fee structures and payment processing. Only card and us_bank_account are supported."},"billingPortalReturnUrl":{"type":"string","description":"URL used as the return URL for the Stripe billing portal. When customers access the billing portal to manage their subscription, they will be redirected to this URL when they exit the portal. This is NOT used for initial payment redirect."},"checkoutSuccessUrl":{"type":"string","description":"URL to redirect to after successful payment completion in the Stripe Checkout Session. This URL will be used when the customer successfully completes payment for the subscription."},"checkoutCancelUrl":{"type":"string","description":"URL to redirect to when the customer cancels the payment in the Stripe Checkout Session. This URL will be used when the customer cancels the checkout process."}},"required":["effectiveDate","expirationDate","stripeCustomerId","stripePriceId","policyholderId","carrierId","paymentMethod","checkoutSuccessUrl"]},"CreateSubscriptionPlanDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID (e.g., price_1234...)"},"amount":{"type":"number","description":"Pre-fee price amount in cents (base price before any fees are added)"},"interval":{"type":"string","description":"Billing interval"},"intervalCount":{"type":"number","description":"Interval count (e.g., 3 for every 3 months)"}},"required":["stripePriceId","amount","interval"]},"SubscriptionPricingDto":{"type":"object","properties":{"baseAmount":{"type":"number","description":"Base amount before fees (gross premium) in cents"},"totalFees":{"type":"number","description":"Total fees applied (service fee + payment method fee) in cents"},"totalAmount":{"type":"number","description":"Final amount charged to customer (base + fees) in cents"},"interval":{"type":"string","description":"Billing interval"},"intervalCount":{"type":"number","description":"Interval count (e.g., 3 for every 3 months)"},"paymentMethod":{"type":"string","description":"Payment method used which determines fee structure","enum":["card","us_bank_account"]}},"required":["baseAmount","totalFees","totalAmount","interval","intervalCount","paymentMethod"]},"CreateSubscriptionResponseDto":{"type":"object","properties":{"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"status":{"type":"string","description":"Subscription status","enum":["incomplete","incomplete_expired","trialing","active","past_due","canceled","unpaid","paused","unpaid_paused"]},"invoiceId":{"type":"number","nullable":true,"description":"Internal invoice ID for reference"},"plan":{"description":"Original plan details (pre-fee pricing)","allOf":[{"$ref":"#/components/schemas/CreateSubscriptionPlanDto"}]},"subscriptionPricing":{"description":"Actual subscription pricing (including fees)","allOf":[{"$ref":"#/components/schemas/SubscriptionPricingDto"}]},"checkoutSessionUrl":{"type":"string","nullable":true,"description":"Stripe Checkout Session URL for completing subscription payment with redirect support"},"billingPortalUrl":{"type":"string","nullable":true,"description":"Billing portal URL for customer to manage their subscription"}},"required":["stripeCustomerId","status","plan","subscriptionPricing"]},"DetailedSubscriptionPlanDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID (e.g., price_1234...)"},"name":{"type":"string","description":"Plan display name"},"amount":{"type":"number","description":"Price amount in cents (e.g., 2999 = $29.99)"},"currency":{"type":"string","description":"Currency code (e.g., \"usd\")"},"interval":{"type":"string","description":"Billing frequency unit","enum":["day","week","month","year"]},"intervalCount":{"type":"number","description":"Frequency multiplier (e.g., 3 = every 3 months)"}},"required":["stripePriceId","name","amount","currency","interval","intervalCount"]},"InvoiceSummaryDto":{"type":"object","properties":{"id":{"type":"number","description":"Invoice ID"},"status":{"type":"string","description":"Invoice status"},"grossPremium":{"type":"number","description":"Gross premium amount"},"commission":{"type":"number","description":"Commission amount"},"netPremium":{"type":"number","description":"Net premium amount"},"serviceFee":{"type":"number","description":"Service fee"},"policyId":{"type":"string","nullable":true,"description":"Policy ID"},"effectiveDate":{"format":"date-time","type":"string","description":"Effective date"},"expirationDate":{"format":"date-time","type":"string","description":"Expiration date"},"createdAt":{"format":"date-time","type":"string","description":"Invoice creation date"}},"required":["id","status","grossPremium","commission","netPremium","serviceFee","effectiveDate","expirationDate","createdAt"]},"SubscriptionDetailResponseDto":{"type":"object","properties":{"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"customerEmail":{"type":"string","description":"Customer email"},"status":{"type":"string","description":"Subscription status"},"currentPeriodStart":{"format":"date-time","type":"string","description":"Current period start"},"currentPeriodEnd":{"format":"date-time","type":"string","description":"Current period end"},"plan":{"description":"Subscription Plan Details","allOf":[{"$ref":"#/components/schemas/DetailedSubscriptionPlanDto"}]},"invoices":{"description":"Associated Invoices","type":"array","items":{"$ref":"#/components/schemas/InvoiceSummaryDto"}}},"required":["stripeCustomerId","customerEmail","status","currentPeriodStart","currentPeriodEnd","plan"]},"CancelSubscriptionDto":{"type":"object","properties":{"cancellationReason":{"type":"string","description":"Reason for cancellation - logged for auditing purposes (optional)","example":"Customer requested cancellation due to pricing"}}},"CancelSubscriptionResponseDto":{"type":"object","properties":{"status":{"type":"string","description":"Updated subscription status"},"canceledAt":{"format":"date-time","type":"string","description":"Cancellation timestamp"}},"required":["status","canceledAt"]},"CustomerCheckResponseDto":{"type":"object","properties":{"exists":{"type":"boolean","description":"Whether the customer exists"},"stripeCustomerId":{"type":"string","description":"Stripe customer ID (if exists)"}},"required":["exists"]},"CustomerAddressDto":{"type":"object","properties":{"street":{"type":"string","description":"Street address","example":"123 Main St"},"city":{"type":"string","description":"City","example":"New York"},"state":{"type":"string","description":"State or province","example":"NY"},"postalCode":{"type":"string","description":"Postal or ZIP code","example":"10001"}}},"OnboardCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Customer email address"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number"},"address":{"description":"Customer address","allOf":[{"$ref":"#/components/schemas/CustomerAddressDto"}]}},"required":["email"]},"OnboardedCustomerDto":{"type":"object","properties":{"id":{"type":"string","description":"Customer ID"},"email":{"type":"string","description":"Customer email address"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number"},"address":{"description":"Customer address","allOf":[{"$ref":"#/components/schemas/CustomerAddressDto"}]},"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"createdAt":{"format":"date-time","type":"string","description":"Customer creation date"},"updatedAt":{"format":"date-time","type":"string","description":"Last update date"}},"required":["id","email","stripeCustomerId","createdAt","updatedAt"]},"OnboardCustomerResponseDto":{"type":"object","properties":{"customer":{"description":"The created/found customer object","allOf":[{"$ref":"#/components/schemas/OnboardedCustomerDto"}]},"stripeCustomerId":{"type":"string","description":"The Stripe customer ID for the external customer"},"message":{"type":"string","description":"Success message"}},"required":["customer","stripeCustomerId","message"]},"CustomerListSubscriptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Subscription ID"},"status":{"type":"string","description":"Subscription status","enum":["active","past_due","canceled","incomplete","trialing"]},"currentPeriodStart":{"format":"date-time","type":"string","description":"Current billing period start"},"currentPeriodEnd":{"format":"date-time","type":"string","description":"Current billing period end"},"plan":{"type":"object","nullable":true,"description":"Plan details","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID (e.g., price_1234...)"},"name":{"type":"string","description":"Plan name"},"amount":{"type":"number","description":"Plan amount in cents"},"currency":{"type":"string","description":"Plan currency"},"interval":{"type":"string","description":"Billing interval (month, year, etc.)"}}}},"required":["id","status","currentPeriodStart","currentPeriodEnd","plan"]},"CustomerListItemDto":{"type":"object","properties":{"id":{"type":"string","description":"Customer ID"},"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number"},"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"hasActiveSubscription":{"type":"boolean","description":"Whether customer has active subscription (properly calculated when include_subscriptions=true)"},"subscriptions":{"description":"Customer subscriptions (only included when include_subscriptions=true)","type":"array","items":{"$ref":"#/components/schemas/CustomerListSubscriptionDto"}},"createdAt":{"format":"date-time","type":"string","description":"Customer creation date"},"updatedAt":{"format":"date-time","type":"string","description":"Last update date"}},"required":["id","email","stripeCustomerId","hasActiveSubscription","createdAt","updatedAt"]},"PaginationDto":{"type":"object","properties":{"total":{"type":"number","description":"Total number of customers"},"limit":{"type":"number","description":"Applied limit per page"},"offset":{"type":"number","description":"Applied offset for pagination"},"hasMore":{"type":"boolean","description":"Whether more results are available"}},"required":["total","limit","offset","hasMore"]},"CustomerListResponseDto":{"type":"object","properties":{"data":{"description":"List of customers","type":"array","items":{"$ref":"#/components/schemas/CustomerListItemDto"}},"pagination":{"description":"Pagination information","allOf":[{"$ref":"#/components/schemas/PaginationDto"}]}},"required":["data","pagination"]},"SubscriptionPlanDetailDto":{"type":"object","properties":{"stripePriceId":{"type":"string","description":"Stripe price ID (e.g., price_1234...)"},"name":{"type":"string","description":"Plan name"},"amount":{"type":"number","description":"Plan amount in cents"},"currency":{"type":"string","description":"Currency code"},"interval":{"type":"string","description":"Billing interval"},"productId":{"type":"number","description":"Product ID"},"productName":{"type":"string","description":"Product name"},"productDescription":{"type":"string","nullable":true,"description":"Product description"}},"required":["stripePriceId","name","amount","currency","interval","productId","productName"]},"CustomerSubscriptionDto":{"type":"object","properties":{"id":{"type":"string","description":"Subscription ID"},"status":{"type":"string","description":"Subscription status","enum":["active","past_due","canceled","incomplete","trialing","paused","unpaid","incomplete_expired"]},"plan":{"description":"Plan details","allOf":[{"$ref":"#/components/schemas/SubscriptionPlanDetailDto"}]},"currentPeriodStart":{"format":"date-time","type":"string","description":"Current period start"},"currentPeriodEnd":{"format":"date-time","type":"string","description":"Current period end"},"createdAt":{"format":"date-time","type":"string","description":"Subscription creation date"},"failureReason":{"type":"string","nullable":true,"description":"Reason for subscription failure"},"failureCode":{"type":"string","nullable":true,"description":"Code for subscription failure"},"lastFailureAt":{"format":"date-time","type":"string","nullable":true,"description":"Timestamp of last failure"}},"required":["id","status","plan","currentPeriodStart","currentPeriodEnd","createdAt"]},"CustomerDetailResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Customer ID"},"email":{"type":"string","description":"Customer email"},"firstName":{"type":"string","description":"Customer first name"},"lastName":{"type":"string","description":"Customer last name"},"phone":{"type":"string","description":"Customer phone number"},"stripeCustomerId":{"type":"string","description":"Stripe customer ID"},"address":{"description":"Customer address","allOf":[{"$ref":"#/components/schemas/CustomerAddressDto"}]},"createdAt":{"format":"date-time","type":"string","description":"Customer creation date"},"updatedAt":{"format":"date-time","type":"string","description":"Last update date"},"subscriptions":{"description":"Customer subscriptions (only included when include_subscriptions=true)","type":"array","items":{"$ref":"#/components/schemas/CustomerSubscriptionDto"}}},"required":["id","email","stripeCustomerId","createdAt","updatedAt"]},"UpdateCustomerDto":{"type":"object","properties":{"email":{"type":"string","description":"Updated email address","format":"email"},"firstName":{"type":"string","description":"Updated first name"},"lastName":{"type":"string","description":"Updated last name"},"phone":{"type":"string","description":"Updated phone number"},"address":{"description":"Updated address","allOf":[{"$ref":"#/components/schemas/CustomerAddressDto"}]}}},"UpdateCustomerResponseDto":{"type":"object","properties":{"id":{"type":"string","description":"Customer ID"},"email":{"type":"string","description":"Updated email"},"stripeCustomerId":{"type":"string","description":"Stripe customer ID (read-only)"},"firstName":{"type":"string","description":"Updated first name"},"lastName":{"type":"string","description":"Updated last name"},"phone":{"type":"string","description":"Updated phone"},"address":{"description":"Updated address","allOf":[{"$ref":"#/components/schemas/CustomerAddressDto"}]},"createdAt":{"format":"date-time","type":"string","description":"Customer creation date"},"updatedAt":{"format":"date-time","type":"string","description":"Update timestamp"}},"required":["id","email","stripeCustomerId","createdAt","updatedAt"]}}}}