{ "openapi": "3.1.0", "info": { "title": "TalusPay API", "description": "The Talus Pay API is organized into two main areas: Merchant Onboarding and Payments. The Merchant Onboarding endpoints are designed to facilitate the registration, verification, and configuration of new merchants within the platform. This includes creating merchant accounts, submitting necessary documentation, and managing compliance checks.\n\nOn the other hand, the Payments endpoints focus on transaction processing, allowing merchants to accept payments, initiate refunds, and handle transaction statuses. This section is structured to manage payment methods, securely process card transactions, and retrieve transaction histories, ensuring a smooth flow of payment operations for merchants. Together, these two areas provide comprehensive support for managing both the setup and ongoing financial activities of merchants.\n\nThe TalusPay status page provides real-time updates on the operational status of API services, including onboarding and payments, as well as historical uptime data. You can check the current service status at [Status page](https://status.taluspay.com)", "version": "v1", "contact": { "name": "TalusPay", "url": "https://docs.taluspay.com", "email": "engineering@taluspay.com" }, "x-logo": { "url": "https://apply.taluspay.com/assets/company-logo.svg", "href": "https://taluspay.com" } }, "servers": [ { "url": "https://api.taluspay.com", "description": "Production environment onboarding" }, { "url": "https://api.taluspay-sandbox.com", "description": "Sandbox environment onboarding" } ], "tags": [], "paths": { "/v1/merchants": { "post": { "operationId": "Create merchant", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequestDto" } } } }, "responses": { "201": { "description": "Create merchant. If a merchant with the given device IMEI already exists for this account, it will return the existing merchant. Note: Phone numbers are not used for deduplication.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMerchantResponseDto" } } } } }, "security": [ { "api-key-secret": [] } ], "summary": "", "tags": [ "Merchants" ] }, "get": { "operationId": "List merchants", "parameters": [ { "name": "filter.lead.onboardingStatus", "required": false, "in": "query", "description": "Filter by lead onboarding status", "schema": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "APPROVED", "FAILED" ] } }, { "name": "filter.createdAt", "required": false, "in": "query", "description": "Filter by creation date (ISO format date string)", "schema": { "format": "date" } }, { "name": "filter.deactivated", "required": false, "in": "query", "description": "Filter by deactivated status", "schema": { "example": false, "type": "boolean" } }, { "name": "filter.phoneNumber", "required": false, "in": "query", "description": "Filter by phone number (exact match)", "schema": { "example": "+1234567890", "type": "string" } }, { "name": "filter.sid", "required": false, "in": "query", "description": "Filter by merchant SID (exact match)", "schema": { "example": "merchant_01234567890abcdef", "type": "string" } }, { "name": "sortBy", "required": false, "in": "query", "description": "Sort by field. Available fields: sid, createdAt, phoneNumber, deactivated, lead.onboardingStatus", "schema": { "pattern": "^(sid,createdAt|phoneNumber|deactivated|lead\\.onboardingStatus):(ASC|DESC)$", "default": "createdAt:DESC" } }, { "name": "limit", "required": false, "in": "query", "description": "Number of items per page", "schema": { "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "page", "required": false, "in": "query", "description": "Page number (1-based)", "schema": { "minimum": 1, "default": 1 } } ], "responses": { "200": { "description": "List all merchants for the account with pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantListResponseDto" } } } } }, "security": [ { "account-password-sign-in": [] }, { "api-key-secret": [] } ], "summary": "", "tags": [ "Merchants" ] } }, "/v1/merchants/{merchant_id}": { "get": { "operationId": "Get merchant", "parameters": [ { "name": "merchant_id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Get merchant object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMerchantResponseDto" } } } } }, "security": [ { "account-password-sign-in": [] }, { "api-key-secret": [] } ], "summary": "", "tags": [ "Merchants" ] }, "patch": { "operationId": "Update merchant", "parameters": [ { "name": "merchant_id", "required": true, "in": "path", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicLeadDto" } } } }, "responses": { "200": { "description": "Update merchant data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMerchantResponseDto" } } } } }, "security": [ { "api-key-secret": [] } ], "summary": "", "tags": [ "Merchants" ] } }, "/v1/onboarding_links": { "post": { "description": "Creates a new onboarding link for a merchant. Important: Creating a new link will automatically expire all previous onboarding links for the same merchant.", "operationId": "Create onboarding link", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnboardingLinkRequestDto" } } } }, "responses": { "201": { "description": "Create an onboarding link for a merchant. Note: Creating a new link will expire all previous onboarding links for the same merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOnboardingLinkResponseDto" } } } } }, "security": [ { "api-key-secret": [] } ], "summary": "Create an onboarding link for a merchant", "tags": [ "Onboarding Links" ] } }, "/v1/webhooks": { "post": { "operationId": "Create webhook", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWebhookRequestDto" } } } }, "responses": { "200": { "description": "Create webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterWebhookResponseDto" } } } } }, "security": [ { "account-password-sign-in": [] }, { "api-key-secret": [] } ], "summary": "", "tags": [ "Webhooks" ] }, "get": { "operationId": "Get webhook", "parameters": [], "responses": { "200": { "description": "Get webhooks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookResponseDto" } } } } } }, "security": [ { "account-password-sign-in": [] }, { "api-key-secret": [] } ], "summary": "", "tags": [ "Webhooks" ] } }, "/v1/webhooks/{webhook_id}": { "delete": { "operationId": "Delete webhook", "parameters": [ { "name": "webhook_id", "required": true, "in": "path", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Delete webhook" } }, "security": [ { "account-password-sign-in": [] }, { "api-key-secret": [] } ], "summary": "", "tags": [ "Webhooks" ] } }, "/v1/statements/{merchantId}": { "get": { "description": "Retrieve a list of available monthly statements for the authenticated merchant", "operationId": "StatementsController_getStatements", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "The unique identifier of the merchant", "schema": { "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k", "type": "string" } } ], "responses": { "200": { "description": "List of statements for the merchant", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementsListResponseDto" } } } }, "400": { "description": "Merchant not approved - no MID available" }, "404": { "description": "Merchant not found or no statements available" }, "500": { "description": "Internal server error while fetching statements" } }, "security": [ { "bearer": [] }, { "api-key-secret": [] } ], "summary": "Get merchant statements", "tags": [ "Statements" ] } }, "/v1/statements/{merchantId}/download/{statementId}": { "get": { "description": "Download a specific monthly statement PDF with ISV branding applied", "operationId": "StatementsController_downloadStatement", "parameters": [ { "name": "merchantId", "required": true, "in": "path", "description": "The unique identifier of the merchant", "schema": { "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k", "type": "string" } }, { "name": "statementId", "required": true, "in": "path", "description": "The unique identifier of the statement to download", "schema": { "example": "859963", "type": "string" } } ], "responses": { "200": { "description": "PDF statement file successfully downloaded" }, "400": { "description": "Merchant not approved - no MID available" }, "404": { "description": "Statement not found or merchant not found" }, "500": { "description": "Internal server error while downloading the statement" } }, "security": [ { "bearer": [] }, { "api-key-secret": [] } ], "summary": "Download a statement PDF", "tags": [ "Statements" ] } }, "/v1/terminal": { "post": { "tags": [ "Payments" ], "description": "Create a terminal payment", "operationId": "Create Terminal Payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TerminalPaymentBody" } } }, "required": true }, "responses": { "200": { "description": "Invoice payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" }, "examples": { "Terminal Payment": { "description": "Terminal Payment", "value": { "payment_type": "TERMINAL", "id": "preq_01h455vb4pex5vsknk084sn02q", "email_address": "test@test.ai", "phone_number": "1234567890", "amount": 100, "tip": 20, "tax": 14340, "status": "CREATED" } } } } } }, "400": { "description": "Bad request response - validation error", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 400, "error": "VALIDATION_EXCEPTION", "message": [ "merchant_id must not be blank" ], "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } }, "500": { "description": "An issue occurred with creating payments in upstream servers", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 500, "error": "INTERNAL_SERVER_ERROR", "message": "An upstream server encountered an error. Please reach out to us with the given request ID, and we'll help you out", "request_id": "0ce46ced-b6bb-4be2-8db8-4ee16b306f97" } } } } } } } }, "/v1/scan_to_pay": { "post": { "tags": [ "Payments" ], "description": "Create a scan-to-pay payment", "operationId": "Create Scan To Pay Payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanToPayPaymentBody" }, "examples": { "With Items": { "description": "With Items", "value": { "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t", "tip": 20, "items": [ { "name": "Item 1", "quantity": 1, "unit_price": 100 } ], "tax": 14340 } }, "Without Items": { "description": "Without Items", "value": { "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t", "tip": 20, "tax": 14340, "amount": 100 } } } } }, "required": true }, "responses": { "200": { "description": "Scan to pay payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" }, "examples": { "Scan To Pay Payment": { "description": "Scan To Pay Payment", "value": { "payment_type": "SCAN_TO_PAY", "id": "preq_01h455vb4pex5vsknk084sn02q", "payment_asset_url": "https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3", "email_address": "test@test.ai", "phone_number": "1234567890", "amount": 100, "tip": 20, "tax": 14340, "status": "CREATED" } } } } } }, "400": { "description": "Bad request response - validation error", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 400, "error": "VALIDATION_EXCEPTION", "message": [ "merchant_id must not be blank" ], "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } }, "500": { "description": "An issue occurred with creating payments in upstream servers", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 500, "error": "INTERNAL_SERVER_ERROR", "message": "An upstream server encountered an error. Please reach out to us with the given request ID, and we'll help you out", "request_id": "0ce46ced-b6bb-4be2-8db8-4ee16b306f97" } } } } } } } }, "/v1/manual": { "post": { "tags": [ "Payments" ], "description": "Create a manual payment", "operationId": "Create Manual Payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ManualPaymentBody" } } }, "required": true }, "responses": { "200": { "description": "Manual payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" } } } }, "400": { "description": "Bad request response - validation error", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 400, "error": "VALIDATION_EXCEPTION", "message": [ "merchant_id must not be blank" ], "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } }, "500": { "description": "An issue occurred with creating payments in upstream servers", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 500, "error": "INTERNAL_SERVER_ERROR", "message": "An upstream server encountered an error. Please reach out to us with the given request ID, and we'll help you out", "request_id": "0ce46ced-b6bb-4be2-8db8-4ee16b306f97" } } } } } } } }, "/v1/invoice": { "post": { "tags": [ "Payments" ], "description": "Create an invoice payment", "operationId": "Create Invoice Payment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePaymentBody" }, "examples": { "With Items": { "description": "With Items", "value": { "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t", "tip": 20, "items": [ { "name": "Item 1", "quantity": 1, "unit_price": 100 } ], "tax": 14340 } }, "Without Items": { "description": "Without Items", "value": { "merchant_id": "merchant_02c7h71rf3eg396idngupsr66t", "tip": 20, "tax": 14340, "amount": 100 } } } } }, "required": true }, "responses": { "200": { "description": "Invoice payment created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRequest" }, "examples": { "Invoice Payment": { "description": "Invoice Payment", "value": { "payment_type": "INVOICE", "id": "preq_01h455vb4pex5vsknk084sn02q", "payment_asset_url": "https://url.com/invoice/71f34949-eef4-4dcc-a899-6038634760c3", "email_address": "test@test.ai", "phone_number": "1234567890", "amount": 100, "tip": 20, "tax": 14340, "status": "CREATED" } } } } } }, "400": { "description": "Bad request response - validation error", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 400, "error": "VALIDATION_EXCEPTION", "message": [ "merchant_id must not be blank" ], "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } }, "500": { "description": "An issue occurred with creating payments in upstream servers", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 500, "error": "INTERNAL_SERVER_ERROR", "message": "An upstream server encountered an error. Please reach out to us with the given request ID, and we'll help you out", "request_id": "0ce46ced-b6bb-4be2-8db8-4ee16b306f97" } } } } } } } }, "/v1/refunds": { "post": { "tags": [ "Refunds" ], "description": "Create a Refund", "operationId": "Create Refund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundPaymentBody" } } }, "required": true }, "responses": { "200": { "description": "Refund created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "description": "Bad request response - validation error", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 400, "error": "VALIDATION_EXCEPTION", "message": [ "charge_id must not be blank" ], "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } } } } }, "/v1/refunds/{refund_id}": { "get": { "tags": [ "Refunds" ], "description": "Retrieve a Refund by its ID", "operationId": "Get Refund", "parameters": [ { "name": "refund_id", "in": "path", "description": "Unique identifier for the refund", "required": true, "schema": { "type": "string", "example": "re_09jb6y6791fg2bt0drtfvajtnl" } } ], "responses": { "200": { "description": "Refund retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "404": { "description": "Refund not found", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 404, "error": "NOT_FOUND", "message": "Refund not found", "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } } } } }, "/v1/charges": { "get": { "tags": [ "Charges" ], "description": "Retrieve all charges with pagination", "operationId": "Get All Charges", "parameters": [ { "name": "page", "in": "query", "description": "Page number (0-based)", "required": false, "schema": { "type": "integer", "default": 0, "example": 0, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Number of charges per page", "required": false, "schema": { "type": "integer", "default": 20, "example": 20, "minimum": 1 } }, { "name": "merchant_id", "in": "query", "description": "Optional merchant ID to filter charges", "required": false, "schema": { "type": "string", "example": "merchant_01j3sc1n1keghbg5q97gr1s08m" } }, { "name": "payment_type", "in": "query", "description": "Optional payment type to filter charges", "required": false, "schema": { "type": "string", "enum": [ "MANUAL", "INVOICE", "TERMINAL", "SCAN_TO_PAY" ], "example": "MANUAL" } }, { "name": "status", "in": "query", "description": "Optional status to filter charges", "required": false, "schema": { "type": "string", "enum": [ "AUTHORIZED", "SETTLED" ], "example": "SETTLED" } }, { "name": "charge_id", "in": "query", "description": "Optional charge ID to filter charges", "required": false, "schema": { "type": "string", "example": "ch_01j8emz8chfxbb2bqmtref8ch7" } } ], "responses": { "200": { "description": "Charges retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChargeListResponseDTO" } } } } } } }, "/v1/charges/{charge_id}": { "get": { "tags": [ "Charges" ], "description": "Retrieve a charge by its ID", "operationId": "Get Charge", "parameters": [ { "name": "charge_id", "in": "path", "description": "Unique identifier for the charge", "required": true, "schema": { "type": "string", "example": "charge_09jb6y6791fg2bt0drtfvajtnl" } } ], "responses": { "200": { "description": "Charge retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Charge" } } } }, "404": { "description": "Charge not found", "content": { "*/*": { "schema": { "type": "string", "example": { "status": 404, "error": "NOT_FOUND", "message": "Charge not found", "request_id": "d6da6dc6-cc76-4534-95fc-dccc842375d3" } } } } } } } } }, "components": { "securitySchemes": { "merchant-onboarding-session-token": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Current accounts merchant onboarding auth session token - using JWT. Used in onboarding web form." }, "account-password-sign-in": { "scheme": "bearer", "bearerFormat": "JWT", "type": "http", "description": "Account sign in." }, "api-key-secret": { "type": "http", "scheme": "basic", "description": "Account api key secret. Combination of base64 encode of account_sid:account_secret_key" } }, "schemas": { "DeviceDto": { "type": "object", "properties": { "imei": { "type": "string", "description": "Device IMEI number", "example": "357111112222333", "minLength": 15, "maxLength": 17 } }, "required": [ "imei" ] }, "BusinessType": { "type": "string", "enum": [ "Sole Proprietor", "Limited Liability (LLC)", "Partnership", "Association/State & Trust", "Tax Exempt Org", "Corporation" ] }, "BankAccount": { "type": "object", "properties": { "bank_name": { "type": "string" }, "routing_number": { "type": "string" }, "account_holder_name": { "type": "string" }, "account_number": { "type": "string" }, "account_number_confirm": { "type": "string" } }, "required": [ "bank_name", "routing_number", "account_holder_name", "account_number", "account_number_confirm" ] }, "TinType": { "type": "string", "enum": [ "EIN", "SSN", "ITIN" ] }, "Address": { "type": "object", "properties": { "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "zip": { "type": "string" } }, "required": [ "address", "city", "state", "zip" ] }, "JobTitle": { "type": "string", "enum": [ "President", "Vice President", "Treasurer", "Owner", "Partner", "CEO", "Secretary", "Director", "Controller", "Accountant", "Chairman", "Contact Only" ] }, "Owner": { "type": "object", "properties": { "first_name": { "type": "string" }, "contact_phone": { "type": "string" }, "last_name": { "type": "string" }, "middle_name": { "type": "string" }, "job_title": { "allOf": [ { "$ref": "#/components/schemas/JobTitle" } ] }, "ownership_percentage": { "type": "string", "example": "25", "description": "Ownership percentage as a numeric value between 0 and 100 (without % symbol)" }, "email": { "type": "string" }, "date_of_birth": { "type": "string" }, "home_address": { "$ref": "#/components/schemas/Address" }, "ssn": { "type": "string" } }, "required": [ "first_name", "last_name", "job_title", "ownership_percentage", "email", "date_of_birth", "home_address", "ssn" ] }, "ProductCategory": { "type": "string", "enum": [ "Apparel", "B2B", "Construction", "Education", "Entertainment", "Financial Services", "Grocery and Food", "Lodging", "Medical", "Restaurants", "Retail", "Services", "Supplies", "Telemarketing and Direct Marketing", "Transportation", "Vehicle Sales, Parts and Service", "Wholesale" ] }, "ProductSubcategory": { "type": "string", "enum": [ "Veterinary Services", "Agricultural Cooperatives", "Landscaping Services", "Miscellaneous Publishing and Printing Services", "Typesetting, Plate Making and Related Services (Business to Business MCC)", "Specialty Cleaning, Polishing and Sanitation Preparations (Business to Business MCC)", "Equipment Sales", "Tailors, Seamstresses, Mending, Alterations", "Laundry, Cleaning, and Garment Services", "Laundromats", "Dry Cleaners", "Carpet and Upholstery Cleaning", "Photographic Studios", "Beauty and Barber Shops", "Shoe Repair Shops, Shoe Shine Parlors, and Hat Cleaning Shops", "Funeral Services and Crematories", "Tax Preparation Services", "Counseling Services - Debt, Marriage, and Personal", "Clothing Rental - Costumes, Uniforms and Formal Wear", "Massage Parlors", "Health and Beauty Spas", "Miscellaneous Personal Services", "Advertising Services", "Blueprinting and Photocopying Services", "Commercial Photography, Art, and Graphics", "Quick Copy, Reproduction Service", "Stenographic Service", "Exterminating and Disinfecting Services", "Cleaning, Maintenance & Janitorial Services", "Computer Programming, Data Processing, and Integrated Systems Design Services", "Information Retrieval Services (B2B)", "Computer Maintenance, Repair and Services (B2B)", "Management, Consulting, and Public Relations Services", "Equipment, Tool, Furniture, and Appliance Rental and Leasing", "Photofinishing Laboratories and Photo Developing", "Business Services", "Truck Stops", "Automobile Rental Agency", "Truck and Utility Trailer Rentals", "Motor Home and Recreational Vehicle Rentals", "Parking Lots and Garages", "Express Parking Payments", "Automotive Top & Body Shops", "Tire Retreading & Repair", "Automotive Paint Shops", "Automotive Service Shops (Non-Dealer)", "Car Washes", "Towing Services", "Electronic Repair Shops", "Air Conditioning and Refrigeration Repair Shops", "Electrical and Small Appliance Repair Shops", "Watch, Clock, and Jewelry Repair Shops", "Furniture - Reupholster, Repair, and Refinishing", "Welding Services", "Miscellaneous Repair Shops and Related Services", "Legal Services and Attorneys", "Child Care Services", "Charitable and Social Service Organizations", "Civic, Social, and Fraternal Associations", "Political Organizations", "Religious Organizations", "Architectural, Engineering, and Surveying Services", "Graphic Designers", "i-Purchasing", "Mail", "Government", "Referral", "General Contractor", "HVAC, Plumbing", "Electricians", "Masonry, Tile and Insulation Contractors", "Carpentry", "Roofing, Siding, and Sheet Metal Work Contractors", "Concrete Work", "Special Trade Contractors, not otherwise listed", "Taxicabs and Limousines", "Storage", "Boat Rentals and Leasing", "Marinas, Marine Service, and Supplies", "Misc. Transportation", "Misc. business-to-business", "Office Furniture (B2B)", "Construction Materials (B2B)", "Office Equipment (B2B)", "Computers & Software (B2B)", "Commercial Equipment (B2B)", "Medical and Laboratory Supplies (B2B)", "Metal Products (B2B)", "Electrical Supplies (B2B)", "Hardware Supplies (B2B)", "Plumbing and Heating (B2B)", "Industrial Supplies (B2B)", "Specialty Jewelry (B2B)", "Miscellaneous Supplies (B2B)", "Office Supplies (B2B)", "Sewing Supplies (B2B)", "Uniforms (B2B)", "Footwear (B2B)", "Chemicals (B2B)", "Petroleum and Fuels (B2B)", "Books (B2B)", "Florists and Nurseries (B2B)", "Paints (B2B)", "Misc. goods (B2B)", "Pharmaceuticals", "Hearing Aids--Sales, Service, and Supplies", "Orthopedic Goods and Prosthetic Devices", "Doctors", "Dentists", "Osteopathic Physicians", "Chiropractors", "Optometrists and Ophthalmologists", "Opticians, Optical Goods and Eyeglasses", "Podiatrists and Chiropodists", "Nursing and Personal Care Facilities", "Hospitals", "Medical and Dental Laboratories", "Medical Services Health Practitioners - No Elsewhere Classified", "Home Supply Warehouses", "Lumber, Concrete, Sand & Gravel", "Glass, Paint and Wallpaper", "Hardware and Electrical", "Nursery and Garden Supplies", "Mobile homes", "Duty Free Stores", "Discount Store", "Department Stores", "Variety Stores", "Miscellaneous General Merchandise", "Wig & Toupee Shops", "Furniture and Home Furnishings Stores", "Floor coverings, Rugs", "Drapery, Window Covering, and Upholstery Stores", "Fireplaces and Accessories Stores", "Miscellaneous Home Furnishing Specialty Stores", "Appliances", "Electronics", "Music Stores", "Computer Software Stores", "Record Stores", "Digital Media, Books, Movies, Music", "Digital Goods – Games", "Digital Goods – Applications (Excludes Games)", "Large Digital Goods Merchant", "Drug Stores and Pharmacies", "Package Stores--Beer, Wine, and Liquor", "Secondhand store", "Antique Shop", "Pawn Shop", "Wrecking and Salvage Yards", "Antique Reproduction Stores", "Bicycle Shop-Sales and Services", "Sporting Goods Stores", "Book Stores", "Stationery, Office and School Supply Stores", "Jewelry Stores", "Hobby, Toy and Game Stores", "Camera and Photographic Supply Stores", "Gift, Card, Novelty, and Souvenir Stores", "Luggage and Leather Goods Stores", "Sewing, Needlework, Fabric, and Piece Good Stores", "Glassware and Crystal Stores", "Artist Supply and Craft Stores", "Art Dealers and Galleries", "Stamp and Coin Stores", "Religious Goods Stores", "Cosmetic Stores", "Typewriter Stores--Sales, Service, and Rentals", "Fuel Dealers--Fuel Oil, Wood, Coal, and Liquefied Petroleum", "Florists", "News Dealers & Newsstands", "Pet Shops, Pet Food, and Supplies", "Swimming Pools--Sales, Supplies, and Services", "Electric Razor Stores Sales & Services", "Tent and Awning Stores", "Miscellaneous & Specialty Retail Stores", "Grocery stores", "Frozen meat", "Candy and snacks", "Dairy products", "Pastries", "Miscellaneous", "New and Used Car Dealers", "Used Car Dealers", "Supplies", "Tires", "Auto Part Stores", "Boat Dealers", "Camper, Recreational and Utility Trailer Dealers", "Motorcycle Dealers", "Motor Home Dealers", "Snowmobile Dealers", "Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers", "Men's & Boys' Clothing and Accessory Stores", "Women's Ready-to-Wear Stores", "Women's Accessory and Specialty Stores", "Children's and Infants' Wear Stores", "Family Clothing Stores", "Sports and Riding Apparel Stores", "Shoe Stores", "Furriers & Fur Shops", "Men's and Women's Clothing Stores", "Miscellaneous Apparel and Accessory Stores", "Catering", "Restaurants", "Bars and Lounges", "Fast Food", "Insurance via Direct Mail", "Mail Order", "Lodging - Hotels, Motels, and Resorts", "Sporting and Recreational Camps", "Trailer Parks and Campgrounds", "Motion Picture Distribution", "Motion Picture Theater", "DVD/Video Tape Rental Stores", "Dance Halls, Studios & Schools", "Bands, Orchestras & Misc Entertainment", "Billiards & Pool Establishments", "Bowling Alleys", "Professional and Semi-Pro Athletic Clubs, Arenas and Stadiums", "Tourist Attractions", "Public Golf Courses", "Arcades", "Interactive Arcades including Paintball and Laser Tag", "Amusement Parks and Carnivals", "Recreational Membership Clubs", "Zoos and Aquariums", "Outdoor Recreation including pools, ice rinks, etc.", "Elementary and Secondary Schools", "Colleges, Universities, Professional Schools, and Junior Colleges", "Correspondence Schools", "Business and Secretarial Schools", "Trade and Vocational Schools", "Schools and Educational Services - Not Elsewhere Classified", "Real Estate Agents and Managers - Rentals; Property Management", "Accounting", "Visa", "Emergency", "U.K. Supermarkets, Electronic Hot File", "U.K. Petrol Stations, Electronic Hot File", "Electronics", "Quasi Cash", "Intra-Company Purchases" ] }, "Product": { "type": "object", "properties": { "description": { "type": "string" }, "category": { "allOf": [ { "$ref": "#/components/schemas/ProductCategory" } ] }, "subcategory": { "allOf": [ { "$ref": "#/components/schemas/ProductSubcategory" } ] }, "website": { "type": "string" } }, "required": [ "description", "category", "subcategory", "website" ] }, "MainContactPerson": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" } }, "required": [ "name", "email" ] }, "SalesPercentage": { "type": "object", "properties": { "card_swipe_percentage": { "type": "string" }, "moto_percentage": { "type": "string" }, "online_percentage": { "type": "string" }, "keyed_percentage": { "type": "string" } }, "required": [ "card_swipe_percentage", "online_percentage", "keyed_percentage" ] }, "Sales": { "type": "object", "properties": { "average_monthly_in_credit_card": { "type": "string" }, "average_ticket_value": { "type": "string" }, "highest_amount_to_date": { "type": "string" }, "sales_percentage": { "$ref": "#/components/schemas/SalesPercentage" }, "average_amex_monthly_sales": { "type": "string" }, "average_amex_ticket_value": { "type": "string" } }, "required": [ "average_monthly_in_credit_card", "average_ticket_value", "highest_amount_to_date", "sales_percentage", "average_amex_monthly_sales", "average_amex_ticket_value" ] }, "TwoTieredCapabilitiesDto": { "type": "object", "properties": {} }, "PassThroughIcCapabilitiesDto": { "type": "object", "properties": {} }, "FlatRateCapabilitiesDto": { "type": "object", "properties": {} }, "TieredCapabilitiesDto": { "type": "object", "properties": {} }, "CashDiscountCapabilitiesDto": { "type": "object", "properties": {} }, "CustomAchCapabilitiesDto": { "type": "object", "properties": { "txn_fee_percent": { "type": "string", "description": "ACH transaction percentage fee", "example": "1.50" }, "txn_fee_fixed": { "type": "string", "description": "ACH transaction fixed fee", "example": "0.25" }, "return_fee_fixed": { "type": "string", "description": "ACH return fixed fee", "example": "5.00" }, "chargeback_fee_fixed": { "type": "string", "description": "ACH chargeback fixed fee", "example": "10.00" }, "monthly_fee": { "type": "string", "description": "ACH monthly fee", "example": "25.00" }, "daily_batch_fee": { "type": "string", "description": "ACH daily batch fee", "example": "1.00" }, "return_reversal_fee": { "type": "string", "description": "ACH return reversal fee", "example": "7.50" } } }, "CustomDefaultCapabilityOptionsDto": { "type": "object", "properties": { "two_tiered": { "$ref": "#/components/schemas/TwoTieredCapabilitiesDto" }, "pass_through_ic": { "$ref": "#/components/schemas/PassThroughIcCapabilitiesDto" }, "flat_rate": { "$ref": "#/components/schemas/FlatRateCapabilitiesDto" }, "tiered": { "$ref": "#/components/schemas/TieredCapabilitiesDto" }, "cash_discount": { "$ref": "#/components/schemas/CashDiscountCapabilitiesDto" }, "ach": { "$ref": "#/components/schemas/CustomAchCapabilitiesDto" } } }, "MerchantCapabilitiesParams": { "type": "object", "properties": { "types": { "type": "array", "description": "Array of capability types", "example": [ "two_tiered", "ach" ], "items": { "type": "string", "enum": [ "two_tiered", "pass_through_ic", "flat_rate", "tiered", "cash_discount", "ach" ] } }, "options": { "description": "Capability options for each type", "example": { "two_tiered": { "vmd_cp_rate_percent": "2.00", "vmd_cp_fee_fixed": "0.10", "vmd_cnp_rate_percent": "2.50", "vmd_cnp_fee_fixed": "0.15", "amex_cp_rate_percent": "3.10", "amex_cp_fee_fixed": "0.25", "amex_cnp_rate_percent": "3.50", "amex_cnp_fee_fixed": "0.30" }, "ach": { "txn_fee_percent": "1.50", "txn_fee_fixed": "0.25" } }, "allOf": [ { "$ref": "#/components/schemas/CustomDefaultCapabilityOptionsDto" } ] } } }, "CreateMerchantMonthlyFeesDto": { "type": "object", "properties": { "minimum_processing_fee": { "type": "number", "description": "Minimum processing fee (applies to flat_rate pricing model)", "example": 35 }, "merchant_advance_service_charge": { "type": "number", "description": "Merchant advance service charge (applies to cash_discount pricing model)", "example": 35 } } }, "CreateMerchantFeesDto": { "type": "object", "properties": { "monthly": { "description": "Monthly fees for the merchant", "allOf": [ { "$ref": "#/components/schemas/CreateMerchantMonthlyFeesDto" } ] } } }, "PublicLeadDto": { "type": "object", "properties": { "legal_business_name": { "type": "string" }, "legal_phone": { "type": "string" }, "business_phone": { "type": "string" }, "business_type": { "allOf": [ { "$ref": "#/components/schemas/BusinessType" } ] }, "bank_account": { "$ref": "#/components/schemas/BankAccount" }, "tin": { "type": "string" }, "tin_type": { "allOf": [ { "$ref": "#/components/schemas/TinType" } ] }, "doing_business_as": { "type": "string" }, "business_established_date": { "type": "string" }, "legal_business_address": { "$ref": "#/components/schemas/Address" }, "dba_address": { "$ref": "#/components/schemas/Address" }, "owner_one": { "$ref": "#/components/schemas/Owner" }, "owner_two": { "$ref": "#/components/schemas/Owner" }, "owner_three": { "$ref": "#/components/schemas/Owner" }, "owner_four": { "$ref": "#/components/schemas/Owner" }, "main_product": { "$ref": "#/components/schemas/Product" }, "main_contact_person": { "$ref": "#/components/schemas/MainContactPerson" }, "current_sales": { "$ref": "#/components/schemas/Sales" }, "bank_account_results": { "type": "string" }, "capabilities": { "description": "Capabilities settings. When account has ACH capabilities, only monthly_fee and transaction_fee can be overridden in ACH options.", "allOf": [ { "$ref": "#/components/schemas/MerchantCapabilitiesParams" } ] }, "fees": { "description": "Custom monthly fees for this merchant. If provided, will be merged with account fees. Only minimum_processing_fee and merchant_advance_service_charge can be overridden.", "allOf": [ { "$ref": "#/components/schemas/CreateMerchantFeesDto" } ] } }, "required": [ "legal_business_name", "legal_phone", "business_type", "bank_account", "tin", "tin_type", "business_established_date", "legal_business_address", "owner_one", "main_product", "main_contact_person", "current_sales" ] }, "CreateMerchantRequestDto": { "type": "object", "properties": { "phone": { "type": "string" }, "device": { "$ref": "#/components/schemas/DeviceDto" }, "merchant": { "$ref": "#/components/schemas/PublicLeadDto" }, "agent": { "type": "number" } } }, "OnboardingStatus": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "APPROVED", "FAILED" ], "description": "Merchant onboarding status" }, "MerchantPayment": { "type": "object", "properties": { "tokenizer_publishable_key": { "type": "string", "example": "pub_XXXXXXXXXXXXXX", "description": "Public key used for tokenizer" }, "terminal_id": { "type": "string", "example": "Cx78a65ada9", "description": "Terminal ID" } }, "required": [ "tokenizer_publishable_key", "terminal_id" ] }, "MerchantDefaults": { "type": "object", "properties": { "display_name": { "type": "string", "example": "My Store", "description": "Display name for the merchant" }, "logo": { "type": "string", "example": "https://example.com/logo.png", "description": "Logo URL for the merchant" }, "primary_color": { "type": "string", "example": "#FF5733", "description": "Primary color for merchant branding" }, "secondary_color": { "type": "string", "example": "#FF5733", "description": "Secondary color for merchant branding" }, "redirect_url": { "type": "string", "example": "https://merchant-site.com/thank-you", "description": "URL to redirect after completing a transaction" }, "custom_domain": { "type": "string", "example": "https://apply.example.com", "description": "Custom domain for merchant onboarding" }, "support": { "type": "object", "description": "ISV support contact information" } }, "required": [ "display_name", "logo", "primary_color", "secondary_color" ] }, "TwoTieredCapabilitiesResponseDto": { "type": "object", "properties": { "vmd_cp_rate_percent": { "type": "string", "example": "2.00", "description": "Visa/Mastercard card present rate percent" }, "vmd_cp_fee_fixed": { "type": "string", "example": "0.10", "description": "Visa/Mastercard card present fee fixed" }, "vmd_cnp_rate_percent": { "type": "string", "example": "2.50", "description": "Visa/Mastercard card not present rate percent" }, "vmd_cnp_fee_fixed": { "type": "string", "example": "0.15", "description": "Visa/Mastercard card not present fee fixed" }, "amex_cp_rate_percent": { "type": "string", "example": "3.10", "description": "Amex card present rate percent" }, "amex_cp_fee_fixed": { "type": "string", "example": "0.25", "description": "Amex card present fee fixed" }, "amex_cnp_rate_percent": { "type": "string", "example": "3.50", "description": "Amex card not present rate percent" }, "amex_cnp_fee_fixed": { "type": "string", "example": "0.30", "description": "Amex card not present fee fixed" } }, "required": [ "vmd_cp_rate_percent", "vmd_cp_fee_fixed", "vmd_cnp_rate_percent", "vmd_cnp_fee_fixed", "amex_cp_rate_percent", "amex_cp_fee_fixed", "amex_cnp_rate_percent", "amex_cnp_fee_fixed" ] }, "PassThroughIcCapabilitiesResponseDto": { "type": "object", "properties": { "processor_markup_percent": { "type": "string", "example": "0.10", "description": "Processor markup percent" }, "transaction_fee_fixed": { "type": "string", "example": "0.10", "description": "Transaction fee fixed" }, "vmd_credit_discount_percent": { "type": "string", "description": "Visa/Mastercard credit discount percent" }, "vmd_credit_fee_fixed": { "type": "string", "description": "Visa/Mastercard credit fee fixed" }, "vmd_debit_discount_percent": { "type": "string", "description": "Visa/Mastercard debit discount percent" }, "vmd_debit_fee_fixed": { "type": "string", "description": "Visa/Mastercard debit fee fixed" }, "amex_discount_percent": { "type": "string", "description": "Amex discount percent" }, "amex_fee_fixed": { "type": "string", "description": "Amex fee fixed" } }, "required": [ "processor_markup_percent", "transaction_fee_fixed", "vmd_credit_discount_percent", "vmd_credit_fee_fixed", "vmd_debit_discount_percent", "vmd_debit_fee_fixed", "amex_discount_percent", "amex_fee_fixed" ] }, "FlatRateCapabilitiesResponseDto": { "type": "object", "properties": { "rate_percent": { "type": "string", "example": "2.90", "description": "Flat rate percent" }, "fee_fixed": { "type": "string", "example": "0.30", "description": "Fee fixed" }, "vmd_credit_rate_percent": { "type": "string", "description": "Visa/Mastercard credit rate percent" }, "vmd_credit_fee_fixed": { "type": "string", "description": "Visa/Mastercard credit fee fixed" }, "vmd_debit_rate_percent": { "type": "string", "description": "Visa/Mastercard debit rate percent" }, "vmd_debit_fee_fixed": { "type": "string", "description": "Visa/Mastercard debit fee fixed" }, "amex_rate_percent": { "type": "string", "description": "Amex rate percent" }, "amex_fee_fixed": { "type": "string", "description": "Amex fee fixed" } }, "required": [ "rate_percent", "fee_fixed", "vmd_credit_rate_percent", "vmd_credit_fee_fixed", "vmd_debit_rate_percent", "vmd_debit_fee_fixed", "amex_rate_percent", "amex_fee_fixed" ] }, "TieredCapabilitiesResponseDto": { "type": "object", "properties": { "vmd_qual_credit_rate_percent": { "type": "string", "example": "1.79", "description": "Visa/Mastercard qualified credit rate percent" }, "vmd_midq_credit_rate_percent": { "type": "string", "example": "2.19", "description": "Visa/Mastercard mid-qualified credit rate percent" }, "vmd_midq_credit_fee_fixed": { "type": "string", "example": "0.15", "description": "Visa/Mastercard mid-qualified credit fee fixed" }, "vmd_nonq_credit_rate_percent": { "type": "string", "example": "3.25", "description": "Visa/Mastercard non-qualified credit rate percent" }, "vmd_nonq_credit_fee_fixed": { "type": "string", "example": "0.20", "description": "Visa/Mastercard non-qualified credit fee fixed" }, "vmd_qual_debit_rate_percent": { "type": "string", "example": "1.50", "description": "Visa/Mastercard qualified debit rate percent" }, "vmd_midq_debit_rate_percent": { "type": "string", "example": "1.90", "description": "Visa/Mastercard mid-qualified debit rate percent" }, "vmd_midq_debit_fee_fixed": { "type": "string", "example": "0.12", "description": "Visa/Mastercard mid-qualified debit fee fixed" }, "vmd_nonq_debit_rate_percent": { "type": "string", "example": "2.95", "description": "Visa/Mastercard non-qualified debit rate percent" }, "vmd_nonq_debit_fee_fixed": { "type": "string", "example": "0.18", "description": "Visa/Mastercard non-qualified debit fee fixed" }, "amex_qual_credit_rate_percent": { "type": "string", "example": "2.89", "description": "Amex qualified credit rate percent" }, "amex_midq_credit_rate_percent": { "type": "string", "example": "3.29", "description": "Amex mid-qualified credit rate percent" }, "amex_midq_credit_fee_fixed": { "type": "string", "example": "0.25", "description": "Amex mid-qualified credit fee fixed" }, "amex_nonq_credit_rate_percent": { "type": "string", "example": "4.35", "description": "Amex non-qualified credit rate percent" }, "amex_nonq_credit_fee_fixed": { "type": "string", "example": "0.30", "description": "Amex non-qualified credit fee fixed" }, "qualified_rate_percent": { "type": "string", "example": "1.79", "description": "Qualified rate percent (legacy)" }, "qualified_fee_fixed": { "type": "string", "example": "0.10", "description": "Qualified fee fixed (legacy)" }, "mid_qualified_rate_percent": { "type": "string", "example": "2.19", "description": "Mid-qualified rate percent (legacy)" }, "mid_qualified_fee_fixed": { "type": "string", "example": "0.15", "description": "Mid-qualified fee fixed (legacy)" }, "non_qualified_rate_percent": { "type": "string", "example": "3.25", "description": "Non-qualified rate percent (legacy)" }, "non_qualified_fee_fixed": { "type": "string", "example": "0.20", "description": "Non-qualified fee fixed (legacy)" } }, "required": [ "vmd_qual_credit_rate_percent", "vmd_midq_credit_rate_percent", "vmd_midq_credit_fee_fixed", "vmd_nonq_credit_rate_percent", "vmd_nonq_credit_fee_fixed", "vmd_qual_debit_rate_percent", "vmd_midq_debit_rate_percent", "vmd_midq_debit_fee_fixed", "vmd_nonq_debit_rate_percent", "vmd_nonq_debit_fee_fixed", "amex_qual_credit_rate_percent", "amex_midq_credit_rate_percent", "amex_midq_credit_fee_fixed", "amex_nonq_credit_rate_percent", "amex_nonq_credit_fee_fixed", "qualified_rate_percent", "qualified_fee_fixed", "mid_qualified_rate_percent", "mid_qualified_fee_fixed", "non_qualified_rate_percent", "non_qualified_fee_fixed" ] }, "CashDiscountCapabilitiesResponseDto": { "type": "object", "properties": { "advantage_rate": { "type": "string", "example": "3.00", "description": "TalusPay Advantage rate percentage", "enum": [ "4.00", "3.99", "3.75", "3.50", "3.25", "3.00" ] } }, "required": [ "advantage_rate" ] }, "AchPaymentsCapabilitiesResponseDto": { "type": "object", "properties": { "txn_fee_fixed": { "type": "string", "example": "0.25", "description": "ACH transaction fixed fee" }, "txn_fee_percent": { "type": "string", "example": "0.75", "description": "ACH transaction percentage fee" }, "return_fee_fixed": { "type": "string", "example": "5.00", "description": "ACH return fixed fee" }, "chargeback_fee_fixed": { "type": "string", "example": "10.00", "description": "ACH chargeback fixed fee" }, "txn_premium_fee_fixed": { "type": "string", "example": "0.30", "description": "ACH transaction premium fixed fee" }, "monthly_fee": { "type": "string", "example": "25.00", "description": "ACH monthly fee" }, "daily_batch_fee": { "type": "string", "example": "1.00", "description": "ACH daily batch fee" }, "return_reversal_fee": { "type": "string", "example": "7.50", "description": "ACH return reversal fee" }, "gross_volume_discount_rate": { "type": "string", "example": "2.50", "description": "ACH gross volume discount rate" }, "premium_discount_rate": { "type": "string", "example": "3.00", "description": "ACH premium discount rate" } }, "required": [ "txn_fee_fixed", "txn_fee_percent", "return_fee_fixed", "chargeback_fee_fixed", "txn_premium_fee_fixed", "monthly_fee", "daily_batch_fee", "return_reversal_fee", "gross_volume_discount_rate", "premium_discount_rate" ] }, "DefaultCapabilityOptionsResponseDto": { "type": "object", "properties": { "two_tiered": { "description": "Two-tiered payment capabilities", "allOf": [ { "$ref": "#/components/schemas/TwoTieredCapabilitiesResponseDto" } ] }, "pass_through_ic": { "description": "Pass-through IC payment capabilities", "allOf": [ { "$ref": "#/components/schemas/PassThroughIcCapabilitiesResponseDto" } ] }, "flat_rate": { "description": "Flat rate payment capabilities", "allOf": [ { "$ref": "#/components/schemas/FlatRateCapabilitiesResponseDto" } ] }, "tiered": { "description": "Tiered payment capabilities", "allOf": [ { "$ref": "#/components/schemas/TieredCapabilitiesResponseDto" } ] }, "cash_discount": { "description": "Cash discount payment capabilities", "allOf": [ { "$ref": "#/components/schemas/CashDiscountCapabilitiesResponseDto" } ] }, "ach": { "description": "ACH payment capabilities", "allOf": [ { "$ref": "#/components/schemas/AchPaymentsCapabilitiesResponseDto" } ] } }, "required": [ "two_tiered", "pass_through_ic", "flat_rate", "tiered", "cash_discount", "ach" ] }, "DefaultCapabilitiesResponseDto": { "type": "object", "properties": { "types": { "type": "array", "description": "Capability types", "example": [ "two_tiered", "ach" ], "items": { "type": "string", "enum": [ "two_tiered", "pass_through_ic", "flat_rate", "tiered", "cash_discount", "ach" ] } }, "options": { "description": "Capability options", "allOf": [ { "$ref": "#/components/schemas/DefaultCapabilityOptionsResponseDto" } ] } }, "required": [ "types", "options" ] }, "AorakiMerchant": { "type": "object", "properties": {} }, "DeviceResponseDto": { "type": "object", "properties": { "id": { "type": "string", "description": "Device ID", "example": "dev_2x4y6z8a0b1c2d3e4f5g6h7j8k" }, "imei": { "type": "string", "description": "Device IMEI number", "example": "357111112222333" }, "imei_status": { "type": "string", "description": "Device IMEI status", "enum": [ "ACTIVE", "BLOCKED", "UNKNOWN" ], "example": "ACTIVE" }, "created_at": { "format": "date-time", "type": "string", "description": "Device creation timestamp", "example": "2024-01-15T10:30:00.000Z" }, "updated_at": { "format": "date-time", "type": "string", "description": "Device last update timestamp", "example": "2024-01-15T10:30:00.000Z" } }, "required": [ "id", "imei", "imei_status", "created_at", "updated_at" ] }, "GetMerchantResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k" }, "phone": { "type": "string", "example": "12819374192" }, "automatic_payouts": { "type": "boolean", "description": "Merchant payouts status" }, "deactivated": { "type": "boolean", "description": "Merchant deactivation flag" }, "created_at": { "format": "date-time", "type": "string" }, "lead_id": { "type": "number", "description": "Onboarding application ID" }, "lead_onboarding_status": { "description": "Merchant onboarding status", "allOf": [ { "$ref": "#/components/schemas/OnboardingStatus" } ] }, "merchant": { "description": "Merchant onboarding information", "allOf": [ { "$ref": "#/components/schemas/PublicLeadDto" } ] }, "payment": { "description": "Merchant payment information", "allOf": [ { "$ref": "#/components/schemas/MerchantPayment" } ] }, "defaults": { "description": "Merchant default settings", "allOf": [ { "$ref": "#/components/schemas/MerchantDefaults" } ] }, "default_capabilities": { "description": "Merchant default capabilities", "allOf": [ { "$ref": "#/components/schemas/DefaultCapabilitiesResponseDto" } ] }, "payment_keys": { "description": "Merchant payment keys", "allOf": [ { "$ref": "#/components/schemas/AorakiMerchant" } ] }, "device": { "description": "Merchant device information", "allOf": [ { "$ref": "#/components/schemas/DeviceResponseDto" } ] } }, "required": [ "id", "phone", "automatic_payouts", "deactivated", "created_at", "lead_id", "lead_onboarding_status", "merchant", "payment", "defaults", "default_capabilities", "payment_keys" ] }, "SimplifiedMerchantResponseDto": { "type": "object", "properties": { "id": { "type": "string", "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k" }, "phone": { "type": "string", "example": "12819374192" }, "automatic_payouts": { "type": "boolean", "description": "Merchant payouts status" }, "deactivated": { "type": "boolean", "description": "Merchant deactivation flag" }, "created_at": { "format": "date-time", "type": "string" }, "lead_id": { "type": "number", "description": "Onboarding application ID" }, "lead_onboarding_status": { "description": "Merchant onboarding status", "allOf": [ { "$ref": "#/components/schemas/OnboardingStatus" } ] }, "merchant": { "description": "Merchant onboarding information", "allOf": [ { "$ref": "#/components/schemas/PublicLeadDto" } ] }, "payment": { "description": "Merchant payment information", "allOf": [ { "$ref": "#/components/schemas/MerchantPayment" } ] }, "defaults": { "description": "Merchant default settings", "allOf": [ { "$ref": "#/components/schemas/MerchantDefaults" } ] }, "default_capabilities": { "description": "Merchant default capabilities", "allOf": [ { "$ref": "#/components/schemas/DefaultCapabilitiesResponseDto" } ] }, "device": { "description": "Merchant device information", "allOf": [ { "$ref": "#/components/schemas/DeviceResponseDto" } ] } }, "required": [ "id", "phone", "automatic_payouts", "deactivated", "created_at", "lead_id", "lead_onboarding_status", "merchant", "payment", "defaults", "default_capabilities" ] }, "PaginationMetaDto": { "type": "object", "properties": { "page": { "type": "number", "description": "Current page number", "example": 1 }, "limit": { "type": "number", "description": "Number of items per page", "example": 20 }, "total": { "type": "number", "description": "Total number of items", "example": 150 }, "total_pages": { "type": "number", "description": "Total number of pages", "example": 8 }, "has_next": { "type": "boolean", "description": "Whether there is a next page", "example": true }, "has_previous": { "type": "boolean", "description": "Whether there is a previous page", "example": false } }, "required": [ "page", "limit", "total", "total_pages", "has_next", "has_previous" ] }, "MerchantListResponseDto": { "type": "object", "properties": { "merchants": { "description": "List of merchants", "type": "array", "items": { "$ref": "#/components/schemas/SimplifiedMerchantResponseDto" } }, "pagination": { "description": "Pagination metadata", "allOf": [ { "$ref": "#/components/schemas/PaginationMetaDto" } ] } }, "required": [ "merchants", "pagination" ] }, "OnboardingLinkType": { "type": "string", "enum": [ "account_onboarding" ] }, "OnboardingLinkAttributionParams": { "type": "object", "description": "IRIS attribution to assign to the merchant's lead when the link is created.", "properties": { "user_id": { "type": "number", "description": "Primary IRIS user ID (agent) to assign to the lead", "example": 12345 }, "channel_id": { "type": "number", "description": "IRIS channel / group ID", "example": 67890 }, "source_id": { "type": "number", "description": "IRIS source ID", "example": 42 }, "rsl_user_id": { "type": "number", "description": "IRIS RSL user ID", "example": 11111 }, "referral_partner_user_id": { "type": "number", "description": "IRIS referral partner user ID", "example": 22222 } }, "required": [ "user_id" ] }, "CreateOnboardingLinkRequestDto": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "return_url": { "type": "string", "description": "URL to redirect after onboarding completion", "example": "https://dashboard.example.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "type": { "default": "account_onboarding", "allOf": [ { "$ref": "#/components/schemas/OnboardingLinkType" } ] }, "allow_skip_device_selection": { "type": "boolean", "description": "Allow the merchant to continue past device selection without choosing a device, after confirming they will supply their own compatible one. Omit to inherit your account default. Only has an effect where device selection is required for your account.", "example": true }, "attribution": { "$ref": "#/components/schemas/OnboardingLinkAttributionParams" } }, "required": [ "merchant_id", "type" ] }, "CreateOnboardingLinkResponseDto": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL of the onboarding link with token", "example": "https://dashboard.example.com?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "id": { "type": "string", "description": "The ID of the onboarding link" }, "expires_at": { "type": "string", "description": "The expiration date of the onboarding link" }, "merchant_id": { "type": "string", "description": "The merchant ID associated with this onboarding link" } }, "required": [ "url", "id", "expires_at", "merchant_id" ] }, "RegisterWebhookRequestDto": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string", "enum": [ "merchant", "charge", "payouts" ] } } }, "required": [ "url", "label", "scope" ] }, "RegisterWebhookResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "events": { "type": "object" } }, "required": [ "id", "url", "label", "secret", "created_at", "events" ] }, "WebhookResponseDto": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "string" }, "created_at": { "format": "date-time", "type": "string" }, "events": { "type": "object" } }, "required": [ "id", "url", "label", "secret", "created_at", "events" ] }, "StatementMetadataDto": { "type": "object", "properties": { "statement_id": { "type": "string", "example": "stmt_2024_01_abc123", "description": "Unique identifier for the statement" }, "merchant_id": { "type": "string", "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k", "description": "Merchant identifier" }, "statement_date": { "type": "string", "example": "2024-01-31", "description": "Statement date in YYYY-MM-DD format" }, "period_start": { "type": "string", "example": "2024-01-01", "description": "Period start date in YYYY-MM-DD format" }, "period_end": { "type": "string", "example": "2024-01-31", "description": "Period end date in YYYY-MM-DD format" }, "total_amount": { "type": "number", "example": 1250.75, "description": "Total amount for the statement period" }, "currency": { "type": "string", "example": "USD", "description": "Currency code" }, "status": { "type": "string", "example": "available", "description": "Statement status", "enum": [ "available", "processing", "error" ] }, "download_url": { "type": "string", "example": "https://api.taluspay.com/v1/statements/download/stmt_2024_01_abc123", "description": "Download URL for the statement" } }, "required": [ "statement_id", "merchant_id", "statement_date", "period_start", "period_end", "total_amount", "currency", "status" ] }, "StatementsListResponseDto": { "type": "object", "properties": { "statements": { "description": "List of available statements for the merchant", "type": "array", "items": { "$ref": "#/components/schemas/StatementMetadataDto" } }, "total_count": { "type": "number", "example": 5, "description": "Total number of statements available" }, "merchant_id": { "type": "string", "example": "merchant_2x4y6z8a0b1c2d3e4f5g6h7j8k", "description": "Merchant identifier" } }, "required": [ "statements", "total_count", "merchant_id" ] }, "TransactionRequest": { "type": "object", "properties": { "payment_type": { "type": "string", "description": "Type of payment", "enum": [ "MANUAL", "INVOICE", "TERMINAL", "SCAN_TO_PAY", "REFUND" ] }, "id": { "type": "string", "description": "Unique identifier for the payment request", "example": "preq_01h455vb4pex5vsknk084sn02q" }, "payment_asset_url": { "type": "string", "description": "URL of the payment asset" }, "email_address": { "type": "string", "description": "Email address of the customer", "example": "test@test.ai" }, "phone_number": { "type": "string", "description": "Phone number of the customer" }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the payment" }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount" }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount" }, "status": { "type": "string", "description": "Status of the payment request" } }, "required": [ "amount", "id", "payment_asset_url", "payment_type", "status" ] }, "TerminalPaymentBody": { "type": "object", "properties": { "terminal_id": { "type": "string", "description": "Unique identifier for the terminal", "example": "234h2ev0i4726hij9o00", "minLength": 1 }, "signature_required": { "type": "boolean", "description": "Flag to indicate if a signature is required", "example": false }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t", "minLength": 1 }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the payment", "example": 100 }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount", "example": 1 }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount", "example": 10 }, "debit": { "type": "boolean", "description": "Flag to indicate if terminal should allow debit cards", "example": true } }, "required": [ "amount", "debit", "merchant_id", "signature_required", "tax", "terminal_id", "tip" ] }, "ItemBody": { "type": "object", "description": "List of items", "properties": { "name": { "type": "string", "description": "Name of the item", "example": "Door Lockout service", "minLength": 1 }, "quantity": { "type": "integer", "format": "int32", "description": "Quantity of the item", "example": 1 }, "unit_price": { "type": "integer", "format": "int32", "description": "Unit price of the item", "example": 47800 } }, "required": [ "name", "quantity", "unit_price" ] }, "ScanToPayPaymentBody": { "type": "object", "properties": { "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t", "minLength": 1 }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount", "example": 1 }, "items": { "type": "array", "description": "List of items", "items": { "$ref": "#/components/schemas/ItemBody" } }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount", "example": 10 }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the payment. If items are provided, amount should not be specified.", "example": 100 }, "taxPercent": { "type": "string" } }, "required": [ "amount", "items", "merchant_id", "tax", "taxPercent", "tip" ] }, "Refund": { "type": "object", "description": "List of refunds associated with this charge", "properties": { "id": { "type": "string", "description": "Unique identifier for the refund", "example": "re_01j8emz8chfxbb2bqmtref8ch7" }, "charge_id": { "type": "string", "description": "Unique identifier for the charge", "example": "ch_01j8emz8chfxbb2bqmtref8ch7" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t" }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the refund", "example": 100 }, "created_at": { "type": "integer", "format": "int32", "description": "Timestamp in milliseconds when the refund was created", "example": 1727875117482 } }, "required": [ "amount", "charge_id", "created_at", "id", "merchant_id" ] }, "RefundPaymentBody": { "type": "object", "properties": { "charge_id": { "type": "string", "description": "Unique identifier for the charge", "example": "ch_01j8emz8chfxbb2bqmtref8ch7" }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t", "minLength": 1 }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the refund", "example": 100 } }, "required": [ "amount", "charge_id", "merchant_id" ] }, "Merchant": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t" }, "gateway_merchant_id": { "type": "string", "description": "Unique identifier for the merchant in the payment gateway", "example": "cs32cvc4i4783pdn9ml1" }, "api_key": { "type": "string", "description": "Secret API key for the merchant", "example": "api_2y46nIaf2xjtD0B74aZ6oxhQRxL" }, "pub_api_key": { "type": "string", "description": "Public API key for the merchant", "example": "pub_2y46nKsfnVmYQ7Fw6FTOhvS9l0F" }, "processors": { "type": "array", "description": "Merchant processors", "items": { "$ref": "#/components/schemas/MerchantProcessor" } } }, "required": [ "id" ] }, "MerchantProcessor": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the processor", "example": "cs32cvn0i4793pdn9mog" }, "processor_type": { "type": "string", "enum": [ "ACH", "CREDIT_CARD" ] } }, "required": [ "id", "processor_type" ] }, "Charge": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier for the charge", "example": "ch_01j8emz8chfxbb2bqmtref8ch7" }, "merchant": { "$ref": "#/components/schemas/Merchant" }, "payment_type": { "type": "string", "description": "Type of payment for the charge", "example": "MANUAL" }, "status": { "type": "string", "description": "status of the charge", "enum": [ "AUTHORIZED", "SETTLED" ], "example": "SETTLED" }, "requested_amount": { "type": "integer", "format": "int32", "description": "Requested amount for the charge", "example": 100 }, "amount_authorized": { "type": "integer", "format": "int32", "description": "Amount authorized for the charge", "example": 100 }, "amount_captured": { "type": "integer", "format": "int32", "description": "Amount captured for the charge", "example": 100 }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount for the charge", "example": 1 }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount for the charge", "example": 10 }, "card_last_4": { "type": "string", "description": "Last 4 digits of the card used for the charge", "example": 1234 }, "card_brand": { "type": "string", "description": "Brand of the card used for the charge", "example": "VISA" }, "created_at": { "type": "integer", "format": "int32", "description": "Timestamp when the charge was created", "example": 1727875117482 }, "authorized_at": { "type": "integer", "format": "int32", "description": "Timestamp when the charge was authorized", "example": 1727875117482 }, "captured_at": { "type": "integer", "format": "int32", "description": "Timestamp when the charge was captured", "example": 1727875117482 }, "settled_at": { "type": "integer", "format": "int32", "description": "Timestamp when the charge was settled", "example": 1727875117482 }, "card_entry_method": { "type": "string", "description": "Method used for card entry", "enum": [ "SWIPE", "CHIP", "MANUAL" ], "example": "MANUAL" }, "billing_address": { "$ref": "#/components/schemas/PaymentBillingAddress", "description": "Billing address details" }, "card_expiration_date": { "type": "string", "description": "Expiration date of the card", "example": "01/27" }, "card_type": { "type": "string", "description": "Type of the card", "example": "debit" }, "failure_reason": { "type": "string", "description": "Reason for the charge failure", "example": "Card declined" }, "refunds": { "type": "array", "description": "List of refunds associated with this charge", "items": { "$ref": "#/components/schemas/Refund" } } }, "required": [ "amount_authorized", "amount_captured", "card_entry_method", "created_at", "merchant", "payment_type", "requested_amount", "status", "tax", "tip" ] }, "PaymentBillingAddress": { "type": "object", "description": "Billing address details", "properties": { "company": { "type": "string", "description": "Company name associated with the address", "example": "Acme Corp" }, "phone": { "type": "string", "description": "Phone number associated with the address", "example": "+1234567890" }, "email": { "type": "string", "description": "Email address associated with the address", "example": "example@domain.com" }, "first_name": { "type": "string", "description": "First name of the person associated with the address", "example": "John" }, "last_name": { "type": "string", "description": "Last name of the person associated with the address", "example": "Doe" }, "address_line_1": { "type": "string", "description": "First line of the address", "example": 123 }, "address_line_2": { "type": "string", "description": "Second line of the address", "example": "Apt 4B" }, "city": { "type": "string", "description": "City of the address", "example": "New York" }, "state": { "type": "string", "description": "State of the address", "example": "NY" }, "postal_code": { "type": "string", "description": "Postal code of the address", "example": 10001 }, "country": { "type": "string", "description": "Country of the address", "example": "USA" }, "fax": { "type": "string", "description": "Fax number associated with the address", "example": "+1234567890" } }, "required": [ "email", "phone" ] }, "ManualPaymentBody": { "type": "object", "properties": { "token": { "type": "string", "description": "Payment token", "example": "16RgvZ9XBTz4IUEIM0mD31f3808okqN2", "minLength": 1 }, "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t", "minLength": 1 }, "amount": { "type": "integer", "format": "int32", "description": "Payment amount", "example": 100 }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount", "example": 1 }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount", "example": 10 } }, "required": [ "amount", "merchant_id", "tax", "tip", "token" ] }, "InvoicePaymentBody": { "type": "object", "properties": { "merchant_id": { "type": "string", "description": "Unique identifier for the merchant", "example": "merchant_02c7h71rf3eg396idngupsr66t", "minLength": 1 }, "email_address": { "type": "string", "description": "Email address of the customer", "example": "test@test.com", "minLength": 1 }, "send_sms": { "type": "boolean", "description": "Send invoice to the customer using SMS", "example": true }, "send_email": { "type": "boolean", "description": "Send invoice to the customer using email", "example": true }, "phone_number": { "type": "string", "description": "Phone number of the customer", "example": 4695809533 }, "tip": { "type": "integer", "format": "int32", "description": "Tip amount", "example": 20 }, "items": { "type": "array", "description": "List of items", "items": { "$ref": "#/components/schemas/ItemBody" } }, "tax": { "type": "integer", "format": "int32", "description": "Tax amount", "example": 10 }, "amount": { "type": "integer", "format": "int32", "description": "Amount of the payment. If items are provided, amount should not be specified.", "example": 100 }, "sendVia": { "type": "string", "enum": [ "none", "text", "email", "both" ] }, "taxPercent": { "type": "string" } }, "required": [ "amount", "email_address", "items", "merchant_id", "sendVia", "send_email", "send_sms", "tax", "taxPercent", "tip" ] }, "ChargeListResponseDTO": { "type": "object", "properties": { "charges": { "type": "array", "items": { "$ref": "#/components/schemas/Charge" } }, "total": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer", "format": "int32" }, "page": { "type": "integer", "format": "int32" }, "size": { "type": "integer", "format": "int32" } }, "required": [ "charges", "page", "size", "total", "totalPages" ] } } } }