ConvesioPay for Platforms API

## Sections
• [Introduction](https://docs.convesiopay.com/convesiopay-for-platforms-api/introduction.md): What is ConvesioPay for Platforms? ConvesioPay for Platforms (CfP) is an API-only white-label offering that lets your platform or agency create, onboard, and fully manage sub-merchants on top of ConvesioPay’s payments infrastructure. You bring the UI — whether that is your own platform portal, a white-labeled onboarding flow, or a fully embedded merchant dashboard — and the CfP API handles everything underneath. Unlike a standard ConvesioPay integration, where each merchant logs in to their own ConvesioPay dashboard, CfP merchants interact exclusively through your platform. They do not have direct ConvesioPay dashboard access. Your platform is their interface. What can you do with this API? With the CfP Platform API you can: Onboard sub-merchants programmatically — Provision legal entities, account holders, bank accounts, upload KYC documents entirely via API. Manage payment methods — Enable or disable payment methods like credit card, Apple Pay, and Google Pay for each sub-merchant, including domain registration, verification file delivery, and merchant provisioning. Configure payment connectors — Create and manage payment processors on our orchestration layer on behalf of your sub-merchants. Handle disputes — Retrieve applicable defense reasons from ConvesioPay, accept liability, or submit a full dispute defense with supporting documents. List and monitor sub-merchants — Retrieve a paginated, filterable list of all merchants under your platform, whether active or currently onbaording and see their progress. Configure statement delivery — Connect your Google Shared Drive so that statements and data CSVs for all of your sub-merchants are delivered automatically to your platform. Who is this API for? The CfP Platform API is intended for technical teams building platform products — such as SaaS platforms, vertical software vendors, agencies, and ISOs — that need to manage payments on behalf of multiple merchants under a single integration. This is an API-only product. There is no ConvesioPay dashboard UI for CfP sub-merchants. All merchant lifecycle management is handled exclusively through this API.
• [Authentication and API Keys](https://docs.convesiopay.com/convesiopay-for-platforms-api/api-authentication/authentication-and-api-keys.md): Platform Secret Key The Platform Secret Key is the primary credential when using the CfP API as a platform owner. It identifies your platform and authorizes you to act on behalf of any sub-merchant in your platform’s partnerMerchants map. Your Platform Secret Key is provisioned for you by ConvesioPay and provided to you upon onboarding as a Platform. This key cannot be retrieved again — store it immediately in a secure secrets manager. If it is lost, a new one will have to be generated and the existing key will be invalidated. The Platform Secret Key is passed as the raw value of the Authorization header on every Platform API request: Merchant ID Header (X-Merchant-Id) Most CfP Platform API endpoints act on a specific sub-merchant. For these endpoints, you must also pass the sub-merchant’s ConvesioPay Merchant ID in the X-Merchant-Id header: ConvesioPay validates that the sub-merchant's Merchant ID supplied belongs to your platform’s partnerMerchants map. Any request referencing a merchant that does not belong to your platform will be rejected with a 403 Unauthorized response. A small number of endpoints are platform-scoped rather than merchant-scoped — specifically POST /merchant/onboarding , GET /merchants , PATCH /account , and PATCH /google-config . These endpoints resolve the platform from your secret key alone and do not require an X-Merchant-Id header. Errors Authentication failures return standard HTTP error codes: 401 Unauthorized — The Authorization header is missing or the secret key is invalid. 403 Forbidden — The request is authenticated but not permitted. This is returned when the X-Merchant-Id value does not belong to the calling platform. All error responses follow the standard CfP error envelope: JSON { "status": 403, "body": { "message": "Unauthorized" } } All API requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE - Secret keys must be stored securely. Don’t expose your secret key on a website or embed it in a mobile application. ConvesioPay retains the right to rotate your secret keys if a public leak is detected.
• [Onboarding Merchants](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/onboarding-merchants.md): As a Platform integrator, you can provision new sub-merchants end-to-end entirely via API. The Create Merchant endpoint orchestrates the full onboarding pipeline: legal entity creation, account holder setup, balance account provisioning, business line registration, store creation, and payment method scheme requests on behalf of the sub-merchant. Sub-merchant onboarding requires KYC (Know Your Customer) verification to ensure that only legitimate businesses are provisioned on your platform. In some cases, additional validation may be required beyond the initial Create Merchant request — such as clarifying information or uploading supporting documents to verify the sub-merchant's business identity or the account representative's details. When this occurs, you will receive status updates via the webhook notification URL provided during the Create Merchant request. You can use the Update Merchant and Upload Documents endpoints at any time to complete the onboarding process or to make changes after a sub-merchant has already been onboarded. Once a sub-merchant has successfully completed the onboarding process and passed KYC review, you will receive a webhook notification confirming that the sub-merchant is ready to process payments.
• [Create Merchant](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/create-merchant.md): Creates a sub-merchant entity and begins the process of onboarding them onto the platform. Onboarding requires KYC (Know Your Customer) verification to ensure that only legitimate businesses are provisioned on your platform. Upon successful completion, the new merchant’s ID is stamped onto your platform’s partnerMerchants map, making it immediately available for use with all other CfP Platform API endpoints. Onboarding Modes The onboardingMode field controls which pipeline is used: cfp — Full ConvesioPay for Platforms onboarding. The sub-merchant is provisioned under your platform’s master account, with payment revenue, refund, and chargeback funding all configured to your account automatically. Use this mode for merchants onboarded as part of your white-label platform. agency — Standard agency / ISO onboarding path. The merchant has their own independent account and bank payouts. Use this mode for standalone merchants that your agency is onboarding on their behalf. The following properties are required to use this endpoint: onboardingMode merchant business businessRepresentative bankAccount supportDetails Onboarding requests must be made server side and over HTTPS . Calls made without https:// or proper authentication will fail. NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Update Merchant](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/update-merchant.md): Updates a narrow set of merchant fields after onboarding. Each field in the updates object maps to a specific API calls to create legal entities, account holders, balance accounts, business lines, stores, and payment method schemes and is processed independently — meaning a single request can partially succeed if one field update fails while others complete successfully. All requests require the X-Merchant-Id header to identify the sub-merchant. Include only the updates fields you want to change — omitted fields are left unchanged. The following fields can be updated. Each is processed independently — include only the fields you need: Website Industry Store Status Business Details Business Representative Business Owners Support Details Platform Webhooks Updating Multiple Fields Website The merchant's business website URL. JSON { "updates": { "website": "https://new-website.com" } } Industry The merchant's industry code (similar to but not always an actual MCC). Must be a valid code from the supported industry list. Refer to the Supported Industry Codes page for more. JSON { "updates": { "industry": "5411" } } Store Status Changes the merchant's store lifecycle status. Accepted values: active — Store is active and processing payments inactive — Store is temporarily suspended closed — Store is permanently closed Setting storeStatus to closed is irreversible via API . A closed store cannot be reopened programmatically. Ensure this is intentional before submitting. JSON { "updates": { "storeStatus": "inactive" } } Business Details Updates the merchant's legal business details. Include only the fields you want to change — all fields are optional. Accepts the same country-conditional field requirements as the Create Merchant request. legalName — The registered legal name of the business doingBusinessAs — The trading name of the business, if different from the legal name businessType — The Adyen business sub-type. Required when ownershipType is organization . registeredAddress — The business's registered legal address. stateOrProvince is required for US , CA , AU , and IT . phone — The business phone number. Required when ownershipType is organization . taxId — The business tax ID. See Create Merchant for country-specific formats. taxIdType — The type of tax ID. See Create Merchant for accepted values per country. registrationNumber — Required for AU and GB only vatNumber — Required for NL and GB only countryOfGoverningLaw — Required when ownershipType is soleProprietorship JSON { "updates": { "business": { "legalName": "New Corp Name LLC", "doingBusinessAs": "DBA Name", "businessType": "privateCompany", "registeredAddress": { "street": "73 5th Avenue", "street2": "12th floor", "city": "New York", "stateOrProvince": "NY", "postalCode": "10003" }, "phone": { "number": "+16465551234", "type": "mobile" }, "taxId": "123456789", "taxIdType": "EIN", "registrationNumber": "12345678", "vatNumber": "NL123456789B01", "countryOfGoverningLaw": "US" } } } Business Representative Updates the authorized representative's details. Include only the fields you want to change. Accepts the same country-conditional field requirements as the Create Merchant request. firstName / lastName — The representative's legal name email — The representative's email address dob — Date of birth in YYYY-MM-DD format phone — The representative's phone number address — The representative's residential address. stateOrProvince is required for US , CA , AU , and IT . taxIdNumber — Personal tax ID. Required for US , CA , NL , and GB ; omit for AU . taxIdType — Type of personal tax ID. See Create Merchant for accepted values per country. identificationData — Government-issued ID. Required for AU only. jobTitle — The representative's job title associationType — Adyen association types. Required when ownershipType is organization . JSON { "updates": { "businessRepresentative": { "firstName": "Jane", "lastName": "Doe", "email": "jane@example.com", "dob": "1990-01-15", "phone": { "number": "+16465559999", "type": "mobile" }, "address": { "street": "100 Main St", "city": "Austin", "stateOrProvince": "TX", "postalCode": "73301", "country": "US" }, "taxIdNumber": "123-45-6789", "taxIdType": "SSN", "identificationData": { "number": "D12345678", "cardNumber": "1234", "issuerState": "TX" }, "jobTitle": "CEO", "associationType": ["signatory", "uboThroughControl"] } } } Business Owners Updates one or more UBOs (Ultimate Beneficial Owners). Each owner must include their id — the legal entity ID returned during the original Create Merchant onboarding response — to identify which owner record to update. Include only the fields you want to change. Accepts the same country-conditional field requirements as the Create Merchant request. The id field is required for each owner in this array. Omitting it will result in a new owner record being created rather than updating the existing one. JSON { "updates": { "businessOwners": [ { "id": "LE00000000000000000000003", "firstName": "John", "lastName": "Smith", "email": "john@example.com", "dob": "1985-06-20", "phone": { "number": "+16465558888", "type": "mobile" }, "address": { "street": "200 Broadway", "city": "New York", "stateOrProvince": "NY", "postalCode": "10007", "country": "US" }, "taxIdNumber": "987-65-4321", "taxIdType": "SSN", "identificationData": { "number": "D98765432", "cardNumber": "5678", "issuerState": "NY" }, "jobTitle": "CFO", "associationType": ["uboThroughOwnership"] } ] } } Support Details Customer support contact details for the merchant. These are displayed to cardholders on payment statements and dispute communications. This may include the default soft descriptor for the merchant and is set at the account level during onboarding. It can be overridden on a per-transaction basis by passing softDescriptor in the Checkout API payment request. JSON { "updates": { "supportDetails": { "statementDescriptor": "NEW STORE", "email": "support@store.com", "phone": "+15551234567", "address": { "street": "123 Main St", "city": "New York", "stateOrProvince": "NY", "postalCode": "10001", "country": "US" } } } } Platform Webhooks Webhook URL for this merchant that ConvesioPay will forward downstream merchant account events to. Useful for surfacing KYC and verification state changes on your platform's own UI without polling. JSON "updates": { "platformWebhooks": { "merchantAccountNotificationUrl": "https://your-platform.com/webhooks/convesio/merchant-updates-new-endpoint" } } Updating Multiple Fields All fields in the updates object are processed independently. You can include any combination of fields in a single request — each will be applied as a separate entity API call regardless of whether the others succeed or fail. JSON { "updates": { "website": "https://updated-store.com", "industry": "5812", "paymentMethod": { "paymentMethodId": "PM3227C223222B5GXC8N46BJ4", "enabled": false }, "storeStatus": "active" } } Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Update Merchant Document](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/update-merchant-document.md): Uploads a verification document for a sub-merchant as part of the KYC onboarding process. Documents are base64-encoded and attached to the appropriate legal entity record within the onboarding pipeline. The documentType field determines the type of document being uploaded and controls which entity the document is attached to when target is omitted. For documents that require explicit entity scoping — such as a specific UBO or a bank account — use the optional target field. For paged document types such as driversLicense and identityCard , the pageType field is required to indicate whether the file represents the front or back of the document. This endpoint is typically called in response to a KYC webhook notification indicating that additional documentation is required to complete the sub-merchant's onboarding. See the Onboarding Merchants page for details on the full onboarding flow and webhook notifications. All requests require the X-Merchant-Id header to identify the sub-merchant. The following properties are required to use this endpoint: merchantEmail documentType base64Content fileName Document Types ID Documents Automatically target the individual (business representative) unless target is specified. documentType Description passport Passport driversLicense Passport. Requires pageType : front or back identityCard National identity card. Requires pageType : front or back liveSelfie Live selfie photo Proof Documents Default target varies by document type — see the Target Resolution section. Omit target to use auto-resolution. documentType Description Default target proofOfAddress Bank statement or utility bill Organization or sole proprietorship proofOfResidency Government-issued correspondence Individual proofOfIndividualTaxId Personal taxation document Individual proofOfOrganizationTaxInfo Organization tax document Organization proofOfNationalIdNumber Municipal records extract Individual proofOfFundingOrWealthSource Salary slip or wealth source proof Auto-resolved proofOfOwnership Mortgage statement or ownership proof Organization proofOfIndustry Industry license or permit Auto-resolved proofOfSignatory Proof of signatory authority Organization proofOfRelationship Proof of relationship Individual vatDocument VAT registration document Organization registrationDocument Certificate of registration Organization proofOfDirector Proof of director appointment Organization constitutionalDocument Constitutional or formation document Sole proprietorship Bank Statement Automatically targets the bank account (transfer instrument). documentType Description bankStatement Bank statement for account verification Target Resolution The target field controls which Adyen legal entity within the sub-merchant's account receives the document. When omitted, the target is automatically resolved from the documentType as described in the Document Types section above. Use an explicit target value only when you need to override the default resolution — for example, to upload an ID document for a specific UBO rather than the business representative. target Routes document to (omitted) Auto-resolved from documentType individual The business representative (first individual entity) organization The organization legal entity soleProprietorship The sole proprietorship legal entity bankAccount The transfer instrument (bank account) owner:0 The first business owner in the businessOwners array owner:1 The second business owner in the businessOwners array owner:N The Nth business owner (zero-indexed) Request examples Upload a passport for the business representative JSON { "documentType": "passport", "description": "Business representative passport", "base64Content": "...", "fileName": "passport.jpg" } Upload a driver's license front for a specific business owner JSON { "documentType": "driversLicense", "description": "Owner driver's license - front", "base64Content": "...", "fileName": "license_front.jpg", "pageType": "front", "target": "owner:0" } Upload a bank statement JSON { "documentType": "bankStatement", "description": "Recent bank statement", "base64Content": "...", "fileName": "statement.pdf" } Upload a VAT document for the organization JSON { "documentType": "vatDocument", "description": "VAT registration certificate", "base64Content": "...", "fileName": "vat_cert.pdf" } Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Supported Industry Codes](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/supported-industry-codes.md): The following industry codes are accepted by the industry field in the Create Merchant and Update Merchant requests. Codes are grouped by sector for easier reference. Some industry codes require additional review before a sub-merchant can be approved to process payments. ConvesioPay will notify you via webhook if manual approval is required for a sub-merchant's industry. Agriculture, Forestry & Fishing Utilities Construction Manufacturing Wholesale Trade Retail Trade Transportation & Warehousing Information & Publishing Finance & Insurance Real Estate & Rental Professional & Technical Services Administrative & Support Services Education Healthcare & Social Services Arts, Entertainment & Recreation Accommodation & Food Services Repair & Maintenance Personal & Other Services Public Administration Restricted Industries Agriculture, Forestry & Fishing Code Industry 11 Agriculture, forestry, fishing, and hunting (11) Utilities Code Industry 2211 Electric power generation, transmission, and distribution (2211) 2212 Natural gas distribution (2212) 2213 Water, sewage, and other systems (2213) Construction Code Industry 23 Construction & installation (23) Manufacturing Code Industry 311 Food manufacturing (311) 311811 Bakeries (311811) 3121A Alcoholic beverage manufacturing (3121A) 3121B Non-alcoholic beverage manufacturing (3121B) 313 Textile mills (313) 314 Textile product mills (314) 315 Apparel manufacturing (315) 316 Leather and allied product manufacturing (316) 321 Wood product manufacturing (321) 322 Paper manufacturing (322) 323 Printing and related support activities (323) 324 Petroleum and coal products manufacturing (324) 3254 Pharmaceutical and medicine manufacturing (3254) 3255 Paint, coating, and adhesive manufacturing (3255) 3259 Other chemical product and preparation manufacturing (3259) 326 Plastics and rubber products manufacturing (326) 327 Nonmetallic mineral product manufacturing (327) 331 Primary metal manufacturing (331) 332 Fabricated metal product manufacturing (332) 333 Machinery manufacturing (333) 334 Computer and electronic product manufacturing (334) 335 Electrical equipment, appliance, and component manufacturing (335) 336 Transportation (equipment) manufacturing (336) 337 Furniture and related product manufacturing (337) 339A Jewelry, precious stone, precious metal and silverware manufacturing (339A) 339C Medical equipment and supplies manufacturing (339C) 339D Other miscellaneous durable goods manufacturing (339D) 339E Other miscellaneous nondurable goods manufacturing (339E) Wholesale Trade Code Industry 42311 Automobile and other motor vehicle merchant wholesalers (42311) 42312 Motor vehicle supplies and new parts merchant wholesalers (42312) 42313 Tire and tube merchant wholesalers (42313) 42314 Motor vehicle parts (used) merchant wholesalers (42314) 4232 Furniture and home furnishing merchant wholesalers (4232) 4233 Lumber and other construction materials merchant wholesalers (4233) 42341 Photographic equipment and supplies merchant wholesalers (42341) 42342 Office equipment merchant wholesalers (42342) 42343 Computer and computer peripheral equipment and software merchant wholesalers (42343) 42344 Other commercial equipment merchant wholesalers (42344) 42345 Medical, dental, and hospital equipment and supplies merchant wholesalers (42345) 42349 Other professional equipment and supplies merchant wholesalers (42349) 4235 Metal and mineral (except petroleum) merchant wholesalers (4235) 4236 Household appliances, electrical, and electronic goods merchant wholesalers (4236) 4237 Hardware, plumbing, and heating equipment and supplies merchant wholesalers (4237) 4238 Machinery, equipment, and supplies merchant wholesalers (4238) 42394 Jewelry, watch, precious stone, and precious metal merchant wholesalers (42394) 42399 Other miscellaneous durable goods merchant wholesalers (42399) 4241 Paper and paper products merchant wholesalers (4241) 4242 Drugs and druggists' sundries merchant wholesalers (4242) 4243 Apparel, piece goods, and notions merchant wholesalers (4243) 4244 Grocery and related products merchant wholesalers (4244) 4245 Farm product raw material merchant wholesalers (4245) 4246 Chemical and allied products merchant wholesalers (4246) 4247 Petroleum and petroleum products merchant wholesalers (4247) 4248 Beer, wine, and distilled alcoholic beverage merchant wholesalers (4248) 42491 Farm supplies merchant wholesalers (42491) 42492 Book, periodical, and newspaper merchant wholesalers (42492) 42493 Flower, nursery stock, and florists' supplies merchant wholesalers (42493) 42495 Paint, varnish, and supplies merchant wholesalers (42495) 42499 Other miscellaneous nondurable goods merchant wholesalers (42499) 42511 Business-to-business electronic markets (42511) 42512 Wholesale trade agents and brokers (42512) Retail Trade Code Industry 44111 New car dealers (44111) 4411B Used cars - reputable dealers (4411B) 44121 Recreational vehicle dealers (44121) 441222 Boat dealers (441222) 441228 Motorcycle, ATV, and all other motor vehicle dealers (441228) 4412A Mobile home dealers (4412A) 4412B Utility trailer dealers (4412B) 44132 Tire dealers (44132) 442A Furniture stores (442A) 442B Home furnishings stores (442B) 443141 Household appliance stores (443141) 443142 Electronics stores (443142) 4431A Computer software stores (4431A) 4431B Telecommunication Equipment and Telephone Stores (4431B) 44411 Home centers (44411) 44412 Paint and wallpaper stores (44412) 44413 Hardware stores (44413) 44419 Other building material stores (44419) 4451 Grocery stores, Supermarkets (4451) 4452 Specialty food stores (4452) 4453 Beer, wine, and liquor stores (4453) 44611 Pharmacies and drug stores (44611) 44612 Cosmetics, beauty supplies, and perfume stores (44612) 44613 Optical goods store (44613) 446191 Food (Health) supplement stores (nutraceuticals, food) - non-regulated (446191) 446199 All other health and personal care stores (446199) 44619A Food (Health) supplement stores (nutraceuticals, food) - regulated 2 (44619A) 4461A Nutraceutical stores (non-food) (4461A) 447 Gasoline stations (447) 44811 Men's clothing stores (44811) 44812 Women's clothing stores (44812) 44813 Children's and Infants' clothing stores (44813) 44814 Family clothing stores (44814) 44819 Other Clothing (accessories) stores (44819) 4481A Men's and Women's clothing stores (4481A) 4481B Sports and riding apparel stores (4481B) 4482 Shoe stores (4482) 44831 Jewelry stores (44831) 44832 Luggage and leather goods stores (44832) 45111 Sporting goods stores (45111) 45112 Hobby, toy, and game stores (45112) 45113 Sewing, needlework, and piece Goods stores (45113) 45114 Musical instrument and supplies stores (45114) 4512 Book stores and news dealers (4512) 4522 Department stores (4522) 4523 General merchandise stores, including warehouse clubs and supercenters (4523) 452A Buying and shopping services and clubs (452A) 4531 Florists (4531) 45321 Office supplies and stationery stores (45321) 45322 Gift, novelty, and souvenir stores (45322) 4533 Used merchandise stores (4533) 45391 Pet and Pet Supplies stores (45391) 45392 Art dealers (45392) 45393 Manufactured (mobile) home dealers (45393) 453998 All other miscellaneous store retailers (453998) 4539B Stamp and coin stores (4539B) 4539D Auction houses (4539D) 4539H Discount stores (4539H) 4539I Duty-free stores (4539I) 4539J Second hand stores (4539J) 4539K Antique stores (4539K) 4542A Vending machines (Food) (4542A) 4542B Vending machines (Non-Food) (4542B) 45431 Fuel dealers (45431) Transportation & Warehousing Code Industry 481B Other air transportation (481B) 482A Passenger rail transportation (482A) 482B Freight rail transportation (482B) 483B Ferries (483B) 483C Water Freight (483C) 484 Truck transportation (484) 4851 Urban transit systems (4851) 4852 Interurban and rural bus transportation (4852) 4853 Taxi and limousine service (4853) 4854 School and employee bus transportation (4854) 4855 Charter bus industry (4855) 4859 Other transit and ground passenger transportation (4859) 487 Scenic and sightseeing transportation (487) 48819 Other support activities for air transportation (48819) 4881A Airports, airport terminals, flying fields (4881A) 4882 Support activities for rail transportation (4882) 4883 Support Activities for water Transportation (4883) 48841 Motor vehicle towing (48841) 48849 Other support activities for road transportation (48849) 4884A Bridge and road fees, tolls (4884A) 4884B Electric vehicle charging (4884B) 4889 Other support activities for transportation (4889) 491 Postal service (491) 492 Couriers and messengers (492) 493 Warehousing and storage (493) Information & Publishing Code Industry 5111 Newspaper, periodical, book, and directory publishers (except internet, 5111) 51121 Digital goods - software applications (51121) 5112A Digital goods - audiovisual media including books, movies, and music (5112A) 5112B Digital goods - games (5112B) 51211 Motion picture and video production (51211) 51212 Motion picture and video distribution (51212) 51213 Motion picture and video exhibition (51213) 5122 Sound recording industries (5122) 515 Broadcasting (except internet, 515) 517311 Wired and Wireless Telecommunications Carriers (517311) 51731B Wireless telecommunications carriers - Prepaid (51731B) 51731D Other wireless telecommunications carriers (51731D) 5179 Other telecommunications (5179) 517911 Telecommunications Resellers (517911) 51911 News Agency (51911) 51913 Internet publishing and broadcasting and web search portals (51913) 5191A All other information services (5191A) Finance & Insurance Code Industry 52231 Mortgage and non-mortgage loan brokers (52231) 524114 Direct health and medical insurance carriers (524114) 52412 Direct insurance (except life, health, and medical) carriers (52412) 52413 Reinsurance carriers (52413) 5242 Agencies, brokerages, and other insurance related activities (5242) Real Estate & Rental Code Industry 5311 Lessors of real estate (5311) 5312 Offices of real estate agents and brokers (5312) 5313 Activities related to real estate (5313) 53211 Passenger car rental and leasing (53211) 53212 Truck, and utility trailer rental and leasing (53212) 5321B Motor home and recreational vehicle rental (5321B) 53221 Consumer electronics and appliances rental (53221) 532281 Formal wear and costume rental (532281) 532282 Video tape and disc rental (532282) 532283 Home health equipment rental (532283) 532284 Recreational goods rental (532284) 532289 All other consumer goods rental (532289) 5324 Commercial, industrial machinery and equipment rental and leasing (5324) Professional & Technical Services Code Industry 5411A Lawyers (except bankruptcy) (5411A) 541211 Offices of certified public accountants (541211) 541213 Tax preparation services (541213) 5413 Architectural, engineering, and related services (5413) 5414 Specialized design services (5414) 5415 Computer systems design and related services (5415) 5416 Management, scientific, and technical consulting services (5416) 54171 Research and development in the Physical, Engineering, and Life Sciences (54171) 5417A Ancestry research (5417A) 5417B Other research and development in the Social Sciences and Humanities (5417B) 5418 Advertising, public relations, and related services (5418) 54192 Photographic services (54192) 54194 Veterinary services (54194) 54199 All other professional, scientific, and technical services (54199) 55 Management of companies and enterprises (55) Administrative & Support Services Code Industry 5611 Office administrative services (5611) 5612 Facilities support services (5612) 5613 Employment services (5613) 56141 Document preparation services (56141) 56142 Telephone call centers (56142) 56143 Business service centers (56143) 56145 Credit bureaus (56145) 56149 Other business support services (56149) 5615 Travel arrangement and reservation services (5615) 5616A Security services (5616A) 56171 Exterminating and pest control services (56171) 56172 Janitorial services (56172) 56173 Landscaping services (56173) 56174 Carpet and upholstery cleaning services (56174) 56179 Other services to buildings and dwellings (56179) 5619 Other support services (5619) 562 Waste management and remediation services (562) Education Code Industry 6111 Elementary and secondary schools (6111) 6112 Junior colleges (6112) 6113 Colleges, universities, and professional schools (6113) 6114 Business schools, and computer and management training (6114) 6115 Technical and trade schools (6115) 61161 Fine arts schools (61161) 61162 Sports and recreation instruction (61162) 61163 Language schools (61163) 61169 All other schools and instruction (61169) 6116A Dance Schools (6116A) Healthcare & Social Services Code Industry 6211 Office of physicians (6211) 6212 Office of dentists (6212) 62131 Office of chiropractors (62131) 62132 Offices of optometrists (62132) 62133 Offices of mental health practitioners (62133) 62134 Offices of physical, occupational and speech therapists, and audiologists (62134) 62139 Offices of all other health practitioners (62139) 6214 Outpatient care centers (6214) 6215 Medical and diagnostic laboratories (6215) 6216 Home health care services (6216) 6219 Other ambulatory health care services (6219) 621A Commercial private health and e-doctor services (621A) 622 Hospitals (622) 623 Nursing and residential care facilities (623) 6241 Individual and family services (6241) 6242 Community food and housing, and emergency and other relief services (6242) 6243 Vocational rehabilitation services (6243) 6244 Child day care services (6244) 624A All other social services (624A) Arts, Entertainment & Recreation Code Industry 7111 Performing arts companies (7111) 7112 Spectator sports (7112) 7113 Promoters of performing arts, sports, and similar events (7113) 7114 Agents and managers for artists, athletes, entertainers, and other public figures (7114) 7115 Independent artists, writers, and performers (7115) 711A Ticketing agencies (711A) 712 Museums, historical sites, and similar institutions (712) 71311 Amusement and theme parks (71311) 71312 Amusement arcades (71312) 71392 Skiing facilities (71392) 71393 Marinas (71393) 71394 Fitness and recreational sports centers (71394) 71395 Bowling centers (71395) 7139A Public golf courses (7139A) 7139B Private golf courses and country clubs (7139B) 7139C All other amusement and recreation industries (7139C) 7139D Billiard and pool establishments (7139D) 7139E Aquariums, seaquariums, dolphinariums, and zoos (7139E) Accommodation & Food Services Code Industry 72111 Hotels (except casino hotels) and motels (72111) 7211A Timeshares (7211A) 7211B Other traveler accommodation (7211B) 7212 Recreational vehicle parks and recreational camps (7212) 7213 Rooming and boarding houses, dormitories, and workers' Camps (7213) 7223 Special food services (7223) 7224 Drinking places (alcoholic beverages) (7224) 722511 Full-service restaurants (722511) 722513 Limited-service restaurants (Fast food restaurants, 722513) 722514 Cafeterias, grill buffets, and buffets (722514) 722515 Snacks and nonalcoholic beverage bars (722515) Repair & Maintenance Code Industry 8111 Automotive repair and maintenance (8111) 8112 Electronic and precision equipment repair and maintenance (including computers, 8112) 8113 Commercial and industrial machinery and equipment (except automotive and electronic) repair and maintenance (8113) 8114 Personal and household goods repair and maintenance (8114) Personal & Other Services Code Industry 81211 Hair, nail, and skin care services (81211) 8121A Massage parlors (8121A) 8121B Health and beauty spas (8121B) 8122 Death care services (8122) 8123 Drycleaning and Laundry services (8123) 8129C Pseudo science services (astrology, psychokinesis, clairvoyance, fortune telling, etc.) (8129C) 8129E Other personal services (8129E) 8134 Civic and social organizations (8134) 81391 Business associations (81391) 81392 Professional organizations (81392) 81393 Labor unions and similar labor organizations (81393) 81394 Political organizations (81394) 81399 Other similar organizations (except business, professional, labor, and political organizations, 81399) Public Administration Code Industry 921 Executive, legislative, and other general government support (921) 92219 Other justice, public order, and safety activities (92219) 922A Fines and penalties of any kind (922A) 92B Other public administrations (92B) Restricted Industries The following industries may not supported on ConvesioPay and/or are subject to approval before they can fully be onboarded if at all. Code Industry 332994 Weapons and firearms, including artillery, guns, ammunition, and related components N/A Cannabis products, accessories and services N/A Sexually explicit content and services, including erotic products and literature
• [Update Platform Master Account](https://docs.convesiopay.com/convesiopay-for-platforms-api/onboarding/update-platform-master-account.md): As a CfP platform owner, you can update key attributes of your platform master account — including the master bank account used for sub-merchant revenue payouts to the platform and the hard descriptor displayed on customer payment statements. NOTE — This endpoint is available to cfp platforms only . Agency platforms cannot update master account attributes via the Platform API. Each field in the updates object maps to a specific API call and is processed independently — a single request can partially succeed if one field update fails while the other completes successfully. Include only the fields you want to change — omitted fields are left unchanged. The following fields can be updated: Bank Account Hard Descriptor Bank Account The platform master bank account used for CfP payouts. All revenue collected from CfP sub-merchants flows into this account. Updating this field replaces the bank account currently on file for the platform master account. The following bank account fields are accepted. Country-conditional requirements match those of the Create Merchant endpoint — provide only the fields applicable to your country : accountNumber — The bank account number. Format varies by the platform's business.country : US CA AU GB — Local account number (e.g. 000123456789 ) NL DE FR ES IT — Full IBAN (e.g. NL91ABNA0417164300 ) routingNumber — The payment routing number. Required for US and CA only ; omit for all other countries: US — ABA routing number, 9 digits (e.g. 021000021 ) CA — 5-digit transit number concatenated with 3-digit institution number, no separator (e.g. 0010200003 ) bsbCode — Required for AU only. 6-digit BSB code identifying the bank and branch (e.g. 062000 ). sortCode — Required for GB only. 6-digit sort code identifying the bank and branch, hyphens optional (e.g. 20-00-00 ). country — ISO alpha-2 country code of the bank account (e.g. US ). bankStatementBase64 — Base64-encoded bank statement ( pdf , jpg , or png ) for verification. Required when updating the bank account to complete the verification process. JSON { "updates": { "bankAccount": { "accountNumber": "000123456789", "routingNumber": "021000021", "bsbCode": "062-000", "sortCode": "", "country": "US", "bankStatementBase64": "5jh345l3k45j34l..." } } } Hard Descriptor The platform name portion of the hard descriptor displayed on customer payment statements. For CfP platforms, the full statement descriptor follows the format {PLATFORM_DESCRIPTOR} {SUB_MERCHANT_DESCRIPTOR}* — this field sets the platform's descriptor and the sub-merchant's descriptor (combined, separated by a space) as the hard descriptor, before the asterisk. Optionally, a soft descriptor (descriptor suffix, after the asterisk) can be provided with any additional value in the payment request using the Checkout API . Maximum length: 22 characters total (including the sub-merchant's descriptor). Keep the platform prefix as short as possible to leave room for the sub-merchant descriptor value as well — longer strings will be truncated by the card network. Allowed characters: a-z , A-Z , 0-9 , and spaces JSON { "updates": { "supportDetails": { "statementDescriptor": "MY_PLATFORM" } } } Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [List Merchants](https://docs.convesiopay.com/convesiopay-for-platforms-api/merchants/list-merchants.md): Returns a paginated list of all sub-merchants onboarded under the authenticated platform. The platform is resolved from the Authorization secret key — this endpoint is platform-scoped and does not require an X-Merchant-Id header. Results can be filtered by merchant status and a createdAt date range using the from and to query parameters. Results are paginated; use pageSize and pageNumber to navigate through large result sets. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [List Payment Processors](https://docs.convesiopay.com/convesiopay-for-platforms-api/orchestration/list-payment-processors.md): Returns all payment processors currently configured for the sub-merchant identified by the X-Merchant-Id header. These payment processors represent those available for the sub-merchant to route transactions through via the ConvesioPay orchestration layer. Each processor or "connector" has a unique connectorId , a connectorName identifying the processor, a human-readable connectorLabel , and an enabled flag. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Enable Payment Processor](https://docs.convesiopay.com/convesiopay-for-platforms-api/orchestration/enable-payment-processor.md): Creates a new payment processor or "connector" for the sub-merchant identified by the X-Merchant-Id header. The request body shape varies by processor — use the appropriate variant for the processor you are configuring. Processors are created in the enabled state by default. To disable a processor after creation, use PATCH /orchestration/connector/{connectorId} . Processor credentials are stored securely and used exclusively for routing transactions. Never expose connector private keys or passwords in client-side code. Specific Processor Examples: NMI Finix NMI JSON { "connectorName": "nmi", "enabled": true, "connectorLabel": "Primary NMI", "connectorPrivateKey": "nmi-private-security-key", "connectorPublicKey": "nmi-public-key" } Finix JSON { "connectorName": "finix", "enabled": true, "connectorLabel": "Primary Finix", "connectorPrivateKey": "finix-merchant-identity-id", "connectorPublicKey": "finix-merchant-id", "connectorUsername": "finix-api-username", "connectorPassword": "finix-api-password" } The following properties are required for all connectors: connectorName connectorLabel enabled Additional required fields vary by connectorName — see the request schema variants below. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Update Payment Processor](https://docs.convesiopay.com/convesiopay-for-platforms-api/orchestration/update-payment-processor.md): Enables, disables, relabels, or updates the credentials of an existing payment processor for the sub-merchant identified by the X-Merchant-Id header. All fields are optional — only the fields present in the request body will be updated. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [List Payment Methods](https://docs.convesiopay.com/convesiopay-for-platforms-api/payment-methods/list-payment-methods.md): Returns the current list of payment methods along with their enabled status for the sub-merchant identified by the X-Merchant-Id header. Both wallet values default to false if the wallet has not yet been configured. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Toggle Payment Method](https://docs.convesiopay.com/convesiopay-for-platforms-api/payment-methods/toggle-payment-method.md): Enables or disables Apple Pay and/or Google Pay for the sub-merchant identified by the X-Merchant-Id header. Only the wallet objects present in the request body are updated — you can toggle a single wallet without affecting the other. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [List Apple Pay Domains](https://docs.convesiopay.com/convesiopay-for-platforms-api/apple-pay/list-apple-pay-domains.md): Returns the list of Apple Pay web domains currently registered for the sub-merchant. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Get Domain Verification File](https://docs.convesiopay.com/convesiopay-for-platforms-api/apple-pay/get-domain-verification-file.md): Returns the apple-developer-merchantid-domain-association verification file binary that must be served from every domain enrolled in Apple Pay for a sub-merchant. Before registering any Apple Pay domains , the integrator or merchant must serve this exact file at the following path on each domain: The domain verification file must be accessible over HTTPS at the /.well-known/apple-developer-merchantid-domain-association path before you attempt to register the domain. Registration will fail if Apple cannot reach the file at the time of the request. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Register Apple Pay Domains](https://docs.convesiopay.com/convesiopay-for-platforms-api/apple-pay/register-apple-pay-domains.md): Registers one or more checkout domains with Apple Pay for the sub-merchant identified by the X-Merchant-Id header. Multiple domains can be registered in a single request by providing an array with more than one entry in domainNames . Before registering a domain , you must ensure the Apple Pay domain verification file is being served from https://<domain>/.well-known/apple-developer-merchantid-domain-association . Use GET /merchant/applepay/domain-file to retrieve the file. Registration will fail if Apple cannot reach the verification file at the time of the request. The following properties are required to use this endpoint: domainNames Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Unregister Apple Pay Domains](https://docs.convesiopay.com/convesiopay-for-platforms-api/apple-pay/unregister-apple-pay-domains.md): Removes one or more domains from the sub-merchant's Apple Pay merchant registration. Unregistered domains will no longer be able to present Apple Pay as a payment option. The following properties are required to use this endpoint: domainNames Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [List Google Pay Domains](https://docs.convesiopay.com/convesiopay-for-platforms-api/google-pay/list-google-pay-domains.md): Returns the list of Google Pay web domains currently registered for the sub-merchant. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Create Google Pay MID](https://docs.convesiopay.com/convesiopay-for-platforms-api/google-pay/create-google-pay-mid.md): Provisions a new Google Pay merchant for the sub-merchant identified by the X-Merchant-Id header. This endpoint provisions a ConvesioPay-managed Google Pay merchant ID. Unmanaged Google Pay MIDs (BYO Google Pay MIDs, generated from outside of ConvesioPay) are not supported. This call accepts the Google Pay Terms of Service on behalf of the sub-merchant, sets the MCC (Merchant Category Code) for the account, and performs initial provisioning with Google. By calling this endpoint you are accepting the Google Pay Acceptable Use Policy on behalf of the sub-merchant. Ensure the sub-merchant has reviewed and agreed to the Google Pay Terms of Service before making this request. Accepted MCC values: The following Merchant Category Codes are accepted by this endpoint and required by Google Pay during merchant provisioning. Select the code that most accurately reflects the sub-merchant's primary business activity. MCC Description 0000 Others 4511 Other Airlines 4722 Travel Agencies and Tour Operators 4789 Transportation Services 4814 Telecommunication Services 4816 Computer Network Services 5045 Computers, Computer Peripheral Equipment, Software 5111 Stationery, Office Supplies, Printing and Writing Paper 5192 Books, Periodicals and Newspapers 5200 Home Supply Warehouse Stores 5399 Misc. General Merchandise 5499 Miscellaneous Food Stores – Convenience Stores and Specialty Markets 5533 Automotive Parts, Accessories Stores 5699 Miscellaneous Apparel and Accessory Shops 5734 Computer Software Stores 5732 Electronics Sales 5812 Eating Places and Restaurants 5815 Digital Goods: Books, Movies, Music 5816 Digital Goods: Games 5817 Digital Goods: Applications (Excludes Games) 5941 Sporting Goods Stores 5945 Hobby, Toy, and Game Shops 5946 Camera and Photographic Supply Stores 5947 Card Shops, Gift, Novelty, and Souvenir Shops 5970 Artist's Supply and Craft Shops 5912 Drug Stores and Pharmacies 5995 Pet Shops, Pet Foods and Supplies Stores 6513 Real Estate Agents and Managers - Rentals 7011 Other Lodging — Hotels, Motels, Resorts 7012 Timeshares 7298 Health and Beauty Shop 7299 Miscellaneous Personal Services, Not Elsewhere Classified 7800 Government-Owned Lotteries (US Region only) 7801 Government Licensed On-Line Casinos (On-Line Gambling) (US Region only) 7922 Theatrical Ticket Agencies 7991 Tourist Attractions and Exhibits 7995 Betting (including Lottery Tickets, Casino Gaming Chips, Off-track Betting and Wagers) 8398 Charitable and Social Service Organizations 8651 Political Organizations 9406 Government-Owned Lotteries (Non-U.S. region) The following properties are required to use this endpoint: mcc Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Get Google Pay MID Status](https://docs.convesiopay.com/convesiopay-for-platforms-api/google-pay/get-google-pay-mid-status.md): Returns the current Google Pay merchant configuration for the sub-merchant identified by the X-Merchant-Id header, including the merchant ID, current state, registered addresses, contact details, and merchant category. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Register Google Pay Domains](https://docs.convesiopay.com/convesiopay-for-platforms-api/google-pay/register-google-pay-domains.md): Registers a checkout domain with Google Pay for the sub-merchant identified by the X-Merchant-Id header. This endpoint requires a ConvesioPay-managed Google Pay merchant ID. If you don't have one yet, you will need to Create a Google Pay MID first. Unmanaged Google Pay MIDs (BYO Google Pay MIDs, generated from outside of ConvesioPay) are not supported. The following properties are required to use this endpoint: webDomain Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Accept dispute](https://docs.convesiopay.com/convesiopay-for-platforms-api/disputes/accept-dispute.md): Accepts the dispute, acknowledging liability and waiving the right to defend it. This action is irreversible — once a dispute is accepted, it cannot be re-opened for defense. Use this endpoint when the merchant agrees with the customer's claim and does not intend to contest the chargeback. For CfP merchants, the chargeback amount will be funded from the Platform Master Account. The disputeId path parameter accepts either the internal ConvesioPay paymentId or pspReference of the disputed payment. No request body is required. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Get Defense Reasons](https://docs.convesiopay.com/convesiopay-for-platforms-api/disputes/get-defense-reasons.md): Returns the list of applicable defense reasons for the given dispute, along with the supporting document types required for each reason. Use this endpoint, before attempting to Defend a Dispute , to determine which defenseReasonCode and defenseDocumentTypeCode values are valid for the dispute you intend to defend. The disputeId path parameter accepts either the internal ConvesioPay paymentId or pspReference of the disputed payment — use whichever you have on hand. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Defend dispute](https://docs.convesiopay.com/convesiopay-for-platforms-api/disputes/defend-dispute.md): Defends the dispute by uploading supporting documents and submitting a defense reason. Before calling this endpoint, retrieve the applicable defense reasons and required document types for this specific dispute as depicted in Get Defense Reasons . The defenseReasonCode and defenseDocumentTypeCode values in your request must come from the defense reasons API response. The disputeId path parameter accepts either the paymentId or pspReference of the disputed payment. Documents should be encoded as base64 strings. Accepted MIME types include application/pdf , image/jpeg , and image/png . The following properties are required to use this endpoint: defenseReasonCode defenseDocuments Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.
• [Configure Shared Drive](https://docs.convesiopay.com/convesiopay-for-platforms-api/reporting/configure-shared-drive.md): Configures or reconfigures the Google Shared Drive target used to automatically deliver statements and data CSVs for your platform’s sub-merchants. The platform is resolved from the Authorization secret key — this endpoint is platform-scoped and does not require an X-Merchant-Id header. You will need to create a Google service account and share your target Drive folder with the service account's email address ( serviceAccountEmail ) before calling this endpoint. The service account must have at minimum Editor access on the folder. Once configured, ConvesioPay will automatically deliver statements and reporting CSVs for all sub-merchants under your platform into the specified Google Drive folder, organized by sub-merchant. The serviceAccountCredential object contains sensitive private key material. Treat it with the same care as any API secret. This endpoint must be called server side; never submit service account credentials from client-side code. All fields are required. Requests must be made server side and over HTTPS . NOTE — Your Platform Secret Key must be stored securely. Never expose it in client-side code, a browser, or a mobile application. All onboarding requests must be made server.