--- title: "Registers a new merchant." method: POST path: "/merchants" --- # Registers a new merchant. `POST /merchants` ## Request - Base URL: `https://api.test.kalixa.com/payment-service/v6` - URL: `https://api.test.kalixa.com/payment-service/v6/merchants` - Auth: HTTP basic Registers a new merchant. ## Request body - NewMerchant: Contains the data of the new merchant. - `name` string, required: A short text, usually the company name or abbreviation. Used for display and filtering purposes in the PS Admin tool. - `legalName` string, required: The company name as it is officially incorporated. Used for reports and invoices and is also shown in the footer area of the PXP Financial Checkout. - `incorporationAddress` Address, required: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `operationAddress` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `billingAddress` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `legalForm` 'NonProfitCorporation' | 'Partnership' | 'PrivateCompany' | 'PublicListedCompany' | 'SoleProprietor' | 'SoleTrader' | 'Trust' | 'UnincorporatedAssociation', required: The legal form of the company. Used by the PXP Financial Risk Team. - `merchantCategoryCode` string: The MCC code which identifies the type of business conducted as ISO 18245 4-digit code (https://en.wikipedia.org/wiki/ISO_18245). Used for PXP Financial risk screening, partner commissioning and by the card schemes. - `pciLevel` integer: The Payment Card Industry level of the merchant. Used by the PXP Financial Risk Team. The PCI Level of a merchant can be either 1, 2, 3 or 4. See https://developer.kalixa.com/docs/required-documents#section-pci-documents for more information about PCI levels and the related documents. - `incorporationDate` string, required: The exact starting date of the corporation, as it appears on the company registry of the country of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `incorporationNumber` string, required: The federal number assigned to the business in the company registry at the time of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `taxNumber` string, required: The Taxpayer Identification Number (TIN) of the primary location in which the merchant is doing business. Used for screening purposes by the PXP Financial Risk Team. - `paymentMethodConfig` object: Contains payment method specific configuration items. - `cardDeposit` object - `useAccountStatusInquiry` boolean: The information if Account Status Inquiry is required (true) or not (false). Used for activating of the Card Verification Payment Methods in Payment Service in case the value is true. - `baseCurrencyCode` string: The reporting currency of the merchant as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217). Used in PXP Financial reports for aggregating authorized amounts in different currencies. If not provided, the default value is EUR. - `estimatedMonthlyVolumeInEUR` number, required: An amount in EUR that gives an indication of the expected monthly turnover of the merchant. Used for screening purposes by the PXP Financial Risk Team. - `lowestAmountPerTransactionInEUR` number: An amount in EUR that gives an indication of the minimum limit for authorized amounts. Used for screening purposes by the PXP Financial Risk Team. - `highestAmountPerTransactionInEUR` number: An amount in EUR that gives an indication of the maximum limit for authorized amounts. Used for screening purposes by the PXP Financial Risk Team. - `averageAmountPerTransactionInEUR` number, required: An amount in EUR that gives an indication of the average authorization amounts. Used for screening purposes by the PXP Financial Risk Team. - `estimatedNumberOfTransactionsPerMonth` number: An estimate about the number of authorizations per month. Used for screening purposes by the PXP Financial Risk Team. - `isStartUp` boolean: The information if the merchant is a start up company. Used by the PXP Financial Risk Team. - `isChargebackOrFraudAnalysisProcessInPlace` boolean: The information if the merchant has a chargeback or fraud analysis process in place. Used by the PXP Financial Risk Team. - `isRegulatedByAMLGuideline` boolean: The information if the merchant's business is regulated by AML guidance. Used by the PXP Financial Risk Team. - `settlementCurrencies` string[]: A list of all currencies required for settlements. Used by the PXP Financial Pre-Screening Team. - `fraudRatiosForThePastMonths` object[]: Contains a list of fraud ratios for the last three months for the specific card schemes (Visa, Mastercard), expressed in percentage. Applicable for merchants that are already accepting cards. - `cardScheme` 'Mastercard' | 'Visa': The card scheme for which the fraud ratios are provided. - `months` number[]: The fraud ratios for the last 3 months - `chargebackCountRatiosForThePastMonths` object[]: Contains a list of chargeback count ratios for the last three months for the specific card schemes (Visa, Mastercard), expressed in percentage. Applicable for merchants that are already accepting cards. - `cardScheme` 'Mastercard' | 'Visa': The card scheme for which the chargeback ratios are provided. - `months` number[]: The chargeback count ratios for the last 3 months - `companyPhoneNumber` string, required: The primary phone number to be used to contact the merchant. Used for screening purposes by the PXP Financial Risk Team. - `licenseOrAuthorizationNumber` string: The number of the license/authorization held by the merchant, if such a license is required to operate the business. Used for screening purposes by the PXP Financial Risk Team. - `businessLicenseExpirationDate` string: The date when the business license/authorization expires. Only needs to be provided in case such a license is required to operate the business. Used for screening purposes by the PXP Financial Risk Team. - `deliveryOrFulfillmentTimeframe` 'Instant' | 'UpTo7' | 'UpTo14' | 'UpTo30' | 'MoreThan30': The delivery or fulfilment time for the items/goods/services that are sold by the merchants shops. Used for screening purposes by the PXP Financial Risk Team. - `vatNumber` string: The value added tax identification number or VAT identification number (VATINT) of the primary location in which the merchant is doing business. Used for financial purposes. - `preScreenMerchantId` string: The unique identifier of the approved PreScreenMerchant element which was received in the response of a newPreScreenMerchant request (if applicable). Used for verifying that the pre-screened Merchant was approved. - `partnerId` string, required: The id of the partner that is submitting this onboarding request. This id is assigned upon partner onboarding and should be used for all applications. - `shops` NewNestedShop[], required: Contains an optional list of shops that the merchant sells items or services from. Shops can be registered also later on with a separate POST /shops call. - `name` string, required: A short text, usually the shop name or abbreviation. Used for display and filtering purposes in the PS Admin tool. - `cardAcceptanceMode` 'CP' | 'CNP', required: The information if the Shop operates in card present (CP) or card not present (CNP) mode. Used for setting up the Shop correctly with the Card Schemes. - `isMotoOnlyBusiness` boolean: The information if a card not present (CNP) shop processes only MOTO transactions. Used to decide if a URL needs to be provided. - `url` string: The URL of the shop's main website where the items/goods/services are sold if cardAcceptanceMode equals CNP (ecommerce). The URL of the company website if cardAcceptanceMode equals CP (POS). Used for screening purposes by the PXP Financial Risk Team. - `domainOwnership` 'Own' | 'RetailPlatform': The information if the domain is owned by the merchant or its belongs to a retail platform. Used by the PXP Financial Risk Team. - `activationState` 'LiveAcceptingCards' | 'LiveNotAcceptingCards' | 'Test' | 'BetaVersion': The information if the provided URL is already live or still in a test mode. Used by the PXP Financial Risk Team. - `countryCode` string, required: The country code of the country out of which this website operates or does the main business as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). Used for screening purposes by the PXP Financial Risk Team. - `billingDescriptor1` string, required: The name of the Shop in a way the customer recognizes it. Used for card transactions and will appear on the 1st line of the billing descriptor. - `billingDescriptor2` string, required: Usually the location out of which the shop operates. Used for card transactions acquired by PXP Financial and will appear on the 2nd line of the billing descriptor. - `volumeSpreadByProcessing` VolumeSpreadByProcessing: An indication how the volume is expected to be distributed across different types of transactions. Expressed in percentage which needs to sum up to 100. Applicable only for shops where cardAcceptanceMode equals CNP (ecommerce). Used for screening purposes by the PXP Financial Risk Team. - `ecom` integer: E-commerce transactions. - `moto` integer: Mail or Telephone Order transactions. - `recurring` integer: Recurring e-commerce transactions. - `volumeSpreadByRegion` VolumeSpreadByRegion: An indication how the volume is expected to be distributed across regions. Expressed in percentage which needs to sum up to 100. Applicable only for shops where cardAcceptanceMode equals CNP (ecommerce). Used for screening purposes by the PXP Financial Risk Team. - `northAmerica` integer: Percentage of transactions in North America. - `europeanEconomicArea` integer: Percentage of transactions in the european economic area. - `asia` integer: Percentage of transactions in Asia. - `latinAmerica` integer: Percentage of transactions in Latin America. - `others` integer: Percentage of transactions in other regions. - `volumeSpreadByScheme` VolumeSpreadByScheme: An indication how the volume is expected to be distributed across schemes. Expressed in percentage which needs to sum up to 100. Applicable only for shops where cardAcceptanceMode equals CNP (ecommerce). Used for screening purposes by the PXP Financial Risk Team. - `visa` integer: Percentage of processed transactions for VISA. - `mastercard` integer: Percentage of processed transactions for Mastercard. - `others` integer: Percentage of processed transactions for other schemes. - `questionAnswerPairs` NewNestedQuestionAnswerPair[], required: Contains a list of questions and answers. Used for risk screening purposes. - `questionId` string: The predefined literal id of the question. See https://developer.kalixa.com/v1.0/docs/questions for more information. - `answer` string: The answer to the question, as provided by the merchant. Used for screening purposes. - `preScreenShopId` string: The unique identifier of the approved PreScreenShop element which was received in the response of a newPreScreenMerchant request (if applicable). Used for verifying that the pre-screened Shop was approved. - `relatedPeople` NewNestedRelatedPerson[]: Contains an optional list of all relevant people PXP Financial needs to be aware of. This includes owners, shareholders, technical or operational contacts, etc. Related people can be registered also later on with a separate POST /related-people call. - `roles` string[], required: A list of roles the person holds. See https://developer.kalixa.com/v1.0/docs/mandatory-data-per-cdd-level#section-related-people for more information about conditionally mandatory parameters. - `firstname` string, required: The persons first name. - `lastname` string, required: The persons last name. - `address` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `phoneNumber` string: A landline or mobile number where the person can be contacted, including country prefix. Used for contacting this person by PXP Financial if necessary. - `dateOfBirth` string: The date of birth of the person. Used for screening purposes by the PXP Financial Risk Team. - `skypeName` string: The skype contact, if available. Used for contacting this person by PXP Financial if necessary. - `email` string: The persons valid email address. Used for contacting this person by PXP Financial if necessary. - `shareOrOwnershipPercentage` number: A percentage amount that indicates the ownership participation of the person. Used for screening purposes by the PXP Financial Risk Team. - `passportOrGovernmentNumber` string: The unique identifier of the persons Passport or government number. Used for screening purposes by the PXP Financial Risk Team. - `passportOrGovernmentIDExpirationDate` string: The date when the passport or the government-ID expires. Used for screening purposes by the PXP Financial Risk Team. - `isListedOnPEP` boolean: The information if the related person is listed on PEP. PEP is short for 'politically exposed person', a natural person who is or who has been entrusted with prominent public functions. Used by the PXP Financial Risk Team. - `relatedCompanies` NewNestedRelatedCompany[]: Contains an optional list of all related companies PXP Financial needs to be aware of. This could be the case if the company is owned, wholly or in part, by another company, which would need to be disclosed to PXP Financial. Related companies can be registered also later on with a separate POST /related-companies call. - `roles` string[], required: A list of roles that this company takes in the context of this application. - `name` string, required: The legal company name. Used for screening purposes by the PXP Financial Risk Team. - `incorporationAddress` Address, required: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `taxNumber` string, required: The taxpayer Identification Number (TIN) of the company. Used for screening purposes by the PXP Financial Risk Team. - `incorporationDate` string, required: The exact starting date of the corporation, as it appears on the company registry of the country of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `incorporationNumber` string, required: The federal number assigned to the business in the company registry at the time of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `shareOrOwnershipPercentage` number: A percentage amount that indicates the ownership participation of the person. Used for screening purposes by the PXP Financial Risk Team. - `bankAccounts` NewNestedBankAccount[]: Contains an optional list of bank accounts in case funds should be settled directly to the merchant. Bank accounts can be registered also later on with a separate POST /bank-accounts call. - `bankName` string, required: The name of the bank at which this account is held. Used for settlement purposes. - `accountNumber` string: The account number of the bank account. Should only be provided if the account does not have an IBAN. Used for settlement purposes if no IBAN provided. - `bankCode` string: The bank code of the bank at which this account is held. Should only be provided if the account does not have a BIC code. Used for settlement purposes if no BIC provided. - `countryCode` string, required: The country code for the country in which this account was created as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `currencyCode` string, required: The currency code for the currency in which the account is held as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217). - `holderName` string, required: The name of the person that is registered as the account holder. - `iban` string: The IBAN of the account. Used for settlement purposes. - `bic` string: The BIC code of the bank at which this account is held. - `questionAnswerPairs` NewNestedQuestionAnswerPair[], required: Contains a list of questions and answers. Used for risk screening purposes. - `questionId` string: The predefined literal id of the question. See https://developer.kalixa.com/v1.0/docs/questions for more information. - `answer` string: The answer to the question, as provided by the merchant. Used for screening purposes. ## Response `201` Successful operation - Merchant: Contains the merchant data. - `id` string: The unique identifier of the merchant, which was received in the response of a new merchant registration. - `name` string: A short text, usually the company name or abbreviation. Used for display and filtering purposes the PS Admin tool. - `legalName` string: The company name as it is officially incorporated. Used for reports and invoices and is also shown in the footer area of the PXP Financial Checkout. - `incorporationAddress` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `operationAddress` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `billingAddress` Address: Contains the address of a merchant, person or company. - `street` string, required: The Street including housenumber, housename, etc. - `city` string, required: The name of the city. - `postalCode` string, required: The postal code of the address. - `country` string, required: The address country code as ISO 3166-1 alpha-2 (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). - `legalForm` 'NonProfitCorporation' | 'Partnership' | 'PrivateCompany' | 'PublicListedCompany' | 'SoleProprietor' | 'SoleTrader' | 'Trust' | 'UnincorporatedAssociation': The legal form of the company. Used by the PXP Financial Risk Team. - `merchantCategoryCode` string: The MCC code which identifies the type of business conducted as ISO 18245 4-digit code (https://en.wikipedia.org/wiki/ISO_18245). Used for PXP Financial risk screening, partner commissioning and by the card schemes. - `pciLevel` integer: The Payment Card Industry level of the merchant. Used by the PXP Financial Risk Team. The PCI Level of a merchant can be either 1, 2, 3 or 4. See https://developer.kalixa.com/docs/required-documents#section-pci-documents for more information about PCI levels and the related documents. - `incorporationDate` string: The exact starting date of the corporation, as it appears on the company registry of the country of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `incorporationNumber` string: The federal number assigned to the business in the company registry at the time of incorporation. Used for screening purposes by the PXP Financial Risk Team. - `taxNumber` string: The taxpayer Identification Number (TIN) of the primary location in which the merchant is doing business. Used for screening purposes by the PXP Financial Risk Team. - `paymentMethodConfig` object: Contains payment method specific configuration items. - `cardDeposit` object - `useAccountStatusInquiry` boolean: The information if Account Status Inquiry is required (true) or not (false). Used for activating of the Card Verification Payment Methods in Payment Service in case the value is true. - `baseCurrencyCode` string: The reporting currency of the merchant as ISO 4217 3-digit code (https://en.wikipedia.org/wiki/ISO_4217). Used in PXP Financial reports for aggregating authorized amounts in different currencies. - `estimatedMonthlyVolumeInEUR` number: An amount in EUR that gives an indication of the expected monthly turnover of the merchant. Used for screening purposes by the PXP Financial Risk Team. - `lowestAmountPerTransactionInEUR` number: An amount in EUR that gives an indication of the minimum limit for authorized amounts. Used for screening purposes by the PXP Financial Risk Team. - `highestAmountPerTransactionInEUR` number: An amount in EUR that gives an indication of the maximum limit for authorized amounts. Used for screening purposes by the PXP Financial Risk Team. - `averageAmountPerTransactionInEUR` number: An amount in EUR that gives an indication of the average authorization amounts. Used for screening purposes by the PXP Financial Risk Team. - `estimatedNumberOfTransactionsPerMonth` number: An estimate about the number of authorizations per month. Used for screening purposes by the PXP Financial Risk Team. - `isStartUp` boolean: The information if the merchant is a start up company. Used by the PXP Financial Risk Team. - `isChargebackOrFraudAnalysisProcessInPlace` boolean: The information if the merchant has a chargeback or fraud analysis process in place. Used by the PXP Financial Risk Team. - `isRegulatedByAMLGuideline` boolean: The information if the merchant's business is regulated by AML guidance. Used by the PXP Financial Risk Team. - `isQualifiedForFastOnboarding` boolean: The result if the merchant is qualified for fast onboarding after evaluation of the prescreen data. - `settlementCurrencies` string[]: A list of all currencies required for settlements. Used by the PXP Financial Pre-Screening Team. - `fraudRatiosForThePastMonths` object[]: Contains a list of fraud ratios for the last three months for the specific card schemes (Visa, Mastercard), expressed in percentage. Applicable for merchants that are already accepting cards. - `cardScheme` 'Mastercard' | 'Visa': The card scheme for which the fraud ratios are provided. - `months` number[]: The fraud ratios for the last 3 months - `chargebackCountRatiosForThePastMonths` object[]: Contains a list of chargeback count ratios for the last three months for the specific card schemes (Visa, Mastercard), expressed in percentage. Applicable for merchants that are already accepting cards. - `cardScheme` 'Mastercard' | 'Visa': The card scheme for which the chargeback ratios are provided. - `months` number[]: The chargeback count ratios for the last 3 months - `state` string: The current state of the merchant. Used for identifying the activation or blocking status. - `stateReason` string: Additional details for the current merchant state. Used for providing a reason for the current merchant state. - `cardPresentMid` string: The merchant identifier to be used in payment initiations for a card present (CP/POS) shop. Applicable only for merchants with shops where cardAcceptanceMode equals CP (POS). See https://developer.kalixa.com/docs/cp-cnp-merchant-shops#section-submitting-card-payments-for-pos-cp-shops for more information about submitting card payments for POS (CP) shops. - `partner` ObjectWithId: Contains only the id of the resource. Used for future extensibility. - `id` string: The id of the resource. - `companyPhoneNumber` string: The primary phone number to get in contact - `licenseOrAuthorizationNumber` string: The number of the license/authorization held by the merchant. - `businessLicenseExpirationDate` string: The date when the business license/authorization expires. Used for screening purposes by the PXP Financial Risk Team. - `deliveryOrFulfillmentTimeframe` 'Instant' | 'UpTo7' | 'UpTo14' | 'UpTo30' | 'MoreThan30': The delivery or fulfilment time for the items/goods/services that are sold by the merchants shops. Used for screening purposes by the PXP Financial Risk Team. - `vatNumber` string: The value added tax identification number or VAT identification number (VATINT) of the primary location in which the merchant is doing business. Used for financial purposes. - `documents` ObjectWithId[]: Contains a list of documents assigned for this merchant. - `id` string: The id of the resource. - `shops` ObjectWithId[]: Contains a list of shops registered for this merchant. - `id` string: The id of the resource. - `relatedPeople` ObjectWithId[]: Contains a list of persons related to this merchant. - `id` string: The id of the resource. - `relatedCompanies` ObjectWithId[]: Contains a list of companies related to this merchant. - `id` string: The id of the resource. - `bankAccounts` ObjectWithId[]: Contains a list of bank accounts related to this merchant. - `id` string: The id of the resource. - `questionAnswerPairs` QuestionAnswerPair[]: Contains a list of previously submitted questions and answers for the new shop. - `questionId` string: The predefined literal id of the question. See https://developer.kalixa.com/v1.0/docs/questions for more information. - `answer` string: The answer to the question, as provided by the merchant. Used for screening purposes. ## Other responses - `400`: Error occurred --- [API](https://skmtc.dev/kalixa/apis/payment-service-v6-merchant-onboarding.md) - [All operations](https://skmtc.dev/kalixa/apis/payment-service-v6-merchant-onboarding/llms.txt) - [OpenAPI document](https://skmtc.dev/kalixa/apis/payment-service-v6-merchant-onboarding/revisions/066120f66046?raw)