Onboarding

# JSON Request The following shows the request structure, and which fields are mandatory or optional ### Request structure - requestId: Mandatory identifier that you can use to track your request status - payload: Mandatory list of applications to submit (at least one required) ```json { "requestId":"{{requestId}}", "payload":{ "applications":["MERCHANT_NAME","LINKED_CHAIN","MCC","SCHEMES_OVERRIDING","ADDRESS","ACCEPTED_CARDS","FEES","SERVICES","HOLD","RELEASE","CLOSURE","ADDING_TERMINALS"] } } ``` ### Application structure - merchants: Mandatory list of merchant within the application (at least one required) - Chain: Optional merchant chain details ```json { "merchants":[...], "chain":{...} } ``` ### Merchant structure - merchantId: Mandatory unique merchant id - merchantName: Mandatory merchant name - legalName: Mandatory legal name - website: mandatory merchant website URL for ecommerce merchants - merchantType: Mandatory type, list of accepted values shown below - subMerchantType: Optional accept list of values shown below. - mmc: Mandatory 4 digit MCC code for merchant - relationshipManager: Optional value for officer name - debitAccountNumOrIban: Mandatory bank debit account - creditAccountNumOrIban: Mandatory bank credit account - merchantCurrency: Mandatory merchant base currency code - statementDeliveryType: Mandatory type of delivery, find list of accepted values - paymentMode: Mandatory mode of payment, find list of accepted values - kyc: Mandatory boolean if KYC merchant - trn: Mandatory merchant TRN - fundSettlementLevel: Optional selection of level, either O Payout (default) or U Payup - legalType: Optional legal type, find list of accepted values - addresses: Mandatory list of merchant addresses, at least one required - configurations: Mandatory object for merchant configuration (see configurations section) - services: Optional list of services for merchant (see services section) - terminals: Optional list of merchant terminal (see terminals structure) - vatEnabled: optional field to identify either the merchant is VAT enabled or not - storeType: optional field can accept one of these values STANDARD, CASH_ADVANCE, MOTO, ECOM and QR by default it is STANDARD - gatewayType: optional value can accept any string and it is the gateway name for example NE and NGAPP for QR - bankName: optional field (used as birthname in IBAN amendment for NI) ```json { "merchantId":"200600060180", "merchantName":"abcdef", "legalName":"AABC", "website":"https://merchantwebsite.ae", "merchantType":"POS | ECOM", "subMerchantType" : "BATCH_AUTH | BS | E3 | EM | EN | KI | MPOS | NGECOM | NGPOS | O1 | O2 | O3 | UT | QR-MERCHANT-APP", "mcc":5814, "rm":"Digital Onboarder", "debitAccountNumOrIban":"A12321584", "creditAccountNumOrIban":"A12321584", "merchantCurrency":"AED", "statementFrequency":"DAILY | WEEKLY | MONTHLY", "statementDeliveryType":"Email | Fax", "paymentMode":"EFT | EQ | FN |IFT | MC | NN | OB | TT", "kyc":true, "statementDay":28, "trn":"000000000000000", "fundSettlementLevel":"O | U", "legalType":"LLC | SOLE_PROPRIETOR | PARTNERSHIP | FREE_ZONE", "addresses":[...], "configurations":{...}, "services":[...], "terminals":[...], "vatEnabled": true | false, "storeType" : "STANDARD | CASH_ADVANCE | MOTO | ECOM | QR", "gatewayType" : "NE" } ``` ### Address structure - addressType: Mandatory type of address, default address is used for any type not explicitly defined - name: Mandtory name for address - lastName: optional field for last name - countryCode: Mandatory country code - state: Optional state (max 4 alhabetic letters) - city: Mandatory - state: optional - phone: Optional - mobile: optional - postalCode: Mandatory Field - pobox: Optional - longitude: Optional (coordinates) - latitude: Optional (coordinates) - fax: Optional - email: Mandatory email - additionalEmail: Optional and it is used as charge back mail in case of settlement address - addressLines: Optional list of address lines - addressSwift: optional field represent the address location - birthName: optional used as bank name in case of payment address ```json { "addressType":"STMT_ADDR | PAYM_ADDR", "name":"AABC", "countryCode":"ARE", "state":"DXB", "city":"Dubai", "phone":"12345678900", "postalCode":"0000000784", "pobox":"644973", "longitude":"55.3418550", "latitude":"25.2044464", "fax":"", "email":"example@email.com", "addressLines":[ "addressLine1", "addressLine2" ] } ``` ### Merchant configurations structure - overrideDefaultSchemesMcc: Optional , should be set to true in case the mcc or merchant name is defferent in the other schemes. - commissionSettlement: Mandatory, find list of accepted values, the reoccurrence of the commission settlement. - refundControlValue: Mandatory in case of complex pricing structure and optional in case of simple pricing structure, find list of accepted values, G (without commission and fee) , R (with commission and fee) ,C (only fee without commission) , N (only commission without fee). - acceptedCardSchemes: Mandatory list of supported card schemes (see schemes section) - fees: Mandatory list of pricing fees - settlement: Mandatory Object that contains the Settlement info. - statementFrequency: Mandatory frequrency of statement, find list of accepted values - statementDay: Optional in case of Daily settlement - statementSecondDay: Mandatory in SEMI_WEEKLY, FORTNIGHTLY and SEMI_MONTHLY - flexiCutoff: Optional Object that contains the info for flexi cutoff time and date in case its enabled for the merchant. - enableFlexiCutoff: Mandatory in case merchant enabled cutoff - flexiCutoffTime: string contains the cutoff time in format "hhmm" - flexiCutoffDay: number represent the day, values should be for example "1" or "2" - acquirerChargebackDebit; - visaMVV: optional String Merchant Verification value and used for NI Only - visaFPI: Optional String for NI only - acquirerInternationalRepricingFlag : option boolean for NI only - exceptionApproverFlag: Optional boolean for NI only - acquirerInternationalAirlineFlag: Optional boolean for NI Only - highRiskFlag: Optional boolean for NI Only - visaAirlineRoutingEnabled: Optional boolean for NI Only - mcAirlineRoutingEnabled: Optional boolean for NI Only - visaTransactionComponentRecord : Optional boolean for NI Only - approverName: Optional String for NI Only - wechatMerchantType: Optional String for NI Only - acquirerWechatRate: Optional String for NI Only - alipayMerchantType: Optional String for NI Only - acquirerAlipayRate: Optional String for NI Only - alipayMcc: Optional String for NI Only - alipayPID: Optional String for NI Only - smartBundleValue: Optional String for NI Only - mcp: Optional boolean for NI Only - pwcb: purchase with cashback Optional boolean for NI Only - merchantRiskType: Optional String for NI Only - swiftIntermediateBank: Optional String for NI Only - collateralStatus: Optional String for NI Only - creationDate: Optional String for NI Only must be send in this format "yyyy-MM-dd" - releaseDate: Optional String for NI Only must be send in this format "yyyy-MM-dd" - collateralAmount: Optional String for NI Only - flexiCutoffTimeOptional String for NI Only must be send in this format "hhmm" - flexiCutoffDayOptional String for NI Only and represents number of days for example 1,2 - airlineMerchantCode: Optional boolean for NI Only - routCode: Optional String for NI Only - refundFeePercentage: Optional boolean for NI Only, By defualt its fixed amount if this flag does not set to true. - merchantSize: Optional String for NI Only ```json { "overrideDefaultSchemesMcc":true | false, "commissionSettlement":"NEXT_STTLM | M1", "refundControlValue":"C | R | G | N | Z", "acceptedCardSchemes":[...], "fees":[...], "settlement": { "statementFrequency": "DAILY | SEMI_WEEKLY | WEEKLY | FORTNIGHTLY | SEMI_MONTHLY | MONTHLY", "statementDay" : 1, "statementSecondDay" : 15 }, "flexiCutoff" : { "enableFlexiCutoff" : true, "flexiCutoffTime" : "1130", "flexiCutoffDay" : "2" } } ``` ### Merchant card schemes structure - cardScheme: Mandatory, list of supported values, it is the scheme name - tariffRate: mandatory in simple price structure and not required in complex one, tariff rate for the provided scheme - acceptedCardModes: Mandatory in case of complex price structure and not required in simple price structure. - schemeOverrideValue: Mandatory if overrideDefaultSchemesMcc assigned to true, contains the dbaName/merchantid and mcc in diffrenet schemes if the merchant has diferent values in the provided scheme. - acquirerRefund: Optional flag for NI only to identify if acquirer refont for schemes exipt VISA and MC and these two on Mode Level, by defualt it false - acceptedCardModes.acquirerRefund : this field under mode is used for Visa and MC only as the acquirer refund on mode level in these two schemes ```json { "cardScheme":"VISA | MC | PL | JCB | CUP | MER | QPR | DCI | AMEX", "tariffRate":"0.0", "acceptedCardModes":[ { "modeName":"ELECTRONIC | MANUAL | PREMIUM | INTERNATIONAL | DOMESTIC", "rate":"1.75", "acquirerRefund":true } ], "schemeOverrideValue":{ "dbaName":"merchantSchemeName", "mcc":1234 } } ``` ### Merchant fees structure - feeTypeName: Mandatory, list of provided values, represents the fee type for the merchant. - reOccurrenceFrequency: Mandatory, list of provided values, reoccurrence of fee value applying. - feeValue: Mandatory, fee value for the provided fee. - feeClassifier: an optional field, used for EXCESSIVE fees Only ```json { "feeTypeName":"MIS | ACQ_MMBR_FEE | MFEE_STRT | MFEE_FRD_HND | TRANS_FEE | REFUND_FEE | EXCESSIVE_CHARGEBACK_FEE | EXCESSIVE_FRAUD_FEE | EXCESSIVE_REFUND_FEE", "reOccurrenceFrequency":"DAILY | WEEKLY | MONTHLY | QUARTERLY | SEMI_ANNUAL | ANNUALLY", "feeValue":0, "feeClassifier" : "COUNT | VOLUME" } ``` ### Merchant DCC service structure - serviceType: Mandatory, must be "DCC" for DCC service - dccProvider: Mandatory, lisy of provided values, PP (planet payment) ,FX (Fexco) - daysOfMonth: Optional, number of the month days for DCC provider - dccAcquirerRate: Mandatory, dcc acquirer rate of each transaction - dccMerchantMarkupRate: Mandatory, markup rate for merchant. - dccMarkupRate: Mandatory, markup rate. ```json { "serviceType":"DCC", "dccProvider":"FX | PP", "dccSettlementFrequency":"MONTHLY | WEEKLY | DAILY", "daysOfMonth":31, "dccAcquirerRate":0.22, "dccMerchantMarkupRate":0.25, "dccMarkupRate":5.99 } ``` ### Merchant MC-3D secure service structure - serviceType: Mandatory, must be "MC_3D_SECURE" for mc 3d service ```json { "serviceType":"MC_3D_SECURE" } ``` ### Self-care service structure - serviceType: Mandatory, must be "SELF_SERVICE" for Self-care service - selfServiceUser: Mandatory {first Name (Mandatory), last name (Mandatory) , email (Mandatory)} ```json { "serviceType":"SELF_SERVICE", "firstName":"ABC", "lastName":"CBA", "email":"no@thanks.com" } ``` ### MCP service structure - serviceType: Mandatory, must be "MCP" multi currency pricing service ```json { "serviceType":"MCP" } ``` ### Merchant NGO service structure - serviceType: Mandatory, must be "NGO" for NGO service - organizationName: Optional, Merchant Organization Name ex. "Okuneva Group INC", this value will be used in case neither the organizationName nor chainName provided in the chain Object. if (NGO->organizationName, chain->organizationName, chain->chainName) not provided, merchantName will be passed as an organizationName. - channels: Optional, ECOM/MOTO. - currencyLimits: Optional, map of supported currencies and there corresponding limits, if not provided currencies used in the payment methods will be used along with the Merchant Currency, with a limit of 0. - paymentMethodCurrenciesMap: Optional, Payment Methods (VISA | MASTERCARD | DISCOVER | JCB | DINERS_CLUB_INTERNATIONAL | AMERICAN_EXPRESS) and the list of supported currencies by each payment method. if payment methods not provided then both VISA and MASTERCARD along with the currency limits currencies, and merchantCurency will be used. - propositionServices: Optional, services supported by this merchant/terminals - enable3DS: Optional, default false, Enable 3D secure feature. - user: Mandatory merchant user, if provided, all its data are mandatory, but mobile number is optional ```json { "serviceType":"NGO", "organizationName":"ANY VALID NAME", "channels":{ECOM|MOTO}, "currencyLimits":{ "AED":9900, "USD":98, "INR":1000 }, "paymentMethodCurrenciesMap":{ "VISA":["AED","USD","INR"], "MASTERCARD":["AED","USD","INR"] }, "propositionServices":[ "invoicing", "mcp", "samsung-pay", "apple-pay", "pay-by-token", "stand-alone-refund", "virtual-terminal", "decision-manager-post-auth", "issuer-data" ], "enable3DS":"true/false", "user": { "email": "test@ni.ae", "firstName": "SF", "lastName": "UAT" } } ``` ### Merchant terminals structure - terminalId: Mandatory, terminal (device) ID - terminalName: Optional, alphanumeric, 23 chars - terminalType: Mandatory, alphabetic string, one of available types shown below - maker: Optional, alphabetic string - terminalModel: Optional, alphabetic string - communicationMethod: Mandatory, list of provided values - dccEnabled: optional: boolean - fees: Mandatory, terminal fees {fee name , fee value} ```json { "terminalId":"13004710", "terminalName": "terminal_NAME", "terminalType":"PC | PC_B | PC_H | PC_V | HYPERCOM_H | WINCOR_XML | LOMNI_L | OMNI_S | OMNI_Q | INGENICO | OMNI_B | BULL_AMADEO | OLIVETTY | OMNI_H | BULL_AMADEO_B | BULL_AMADEO_H | NURIT2050 | NURIT2085 | BULL_ALTO_B | BULL_ALTO_H | BULL_QUESTAR_10 | DATACARD_J | TRANZ330 | TRANZ340 | OMNI395 | OMNI420 | SCS | HYPERCOM_B", "maker":"NGINX", "terminalModel":"VX680", "communicationMethod":"SG | GPRS_SIM", "dccEnabled":false, "fees":[ { "feeType":"SIM_FEE | GPRS_FEE | RENTAL_FEE | INSURANCE_FEE", "feeValue":1.5 } ] } ``` ### Application chain structure - chainId: Mandatory chain ID (Way4 setup) - chainName: Mandatory chain name - groupCode: Mandatory code for chain group (WAY4 code) - chainLevelReportRequired: Mandatory boolean if reporting on chain level is required - groupLevelReportingRequired: Mandatory boolean if reporting on group level is required - organizationName: optional, in case NGO Service provided, this value will be set as an organizationName for all NGO merchants in this application.s - alreadyExist: an optional field used to identify that this chain is already boarded in Way4 and no need to board it again, By default it is false which means the chain will be newly boarded. ```json { "chainId":"987654321", "chainName":"Company1", "groupCode":"OTH", "chainLevelReportRequired":false, "groupLevelReportingRequired":false, "organizationName":"Organization Name", "alreadyExist" : true | false } ```