v1
latestOpenAPI 3.0.02026-07-2480677847.6 KBEndpoint
On-board a new merchant
By default it creates a merchant application with status Approved and processes the application so that a merchant is created in the OmniPay platform. Once the merchant is created they platform will accept transactions for the merchant as well as send the funding instructions for the merchant to be paid. The default create option can be overridden using the intent query param.
post/merchants
Query parameters
intent'CREATE' | 'BATCH' | 'VALIDATE' required
This parameter can be used to override the default CREATE option. Use VALIDATE to validate the payload and not create the merchant, a success response will have status 202. Use BATCH to submit the merchant application and let the schedule batch process to create the merchant in the platform, a success response will have status 201.
Headers
Content-Type'application/json' | 'application/json;charset=UTF-8' required
Standard HTTP Header; Represents the format of the payload being provided in the request. This must be set to application/json and applicable for POST/PATCH.
Correlation-Idstring required
Example:9591e6d8-0d70-11ea-8d71-362b9e155667
An RFC4122 UUID used as to trace requests. This is an unique ID consumer generate per API request. This ID is used mutually to track consumer API requests. Fiserv OmniPay recommend this is built in with 128-bit UUID format.
Environmentstring required
For test environment, specific test environment name should be passed (e.g. "bwu15"). Contact OmniPay Project team to get confirmation on the test environment to be used. For production, value "prod" should be populated.
institutionNumberstring required
Institution number (8-digit number) for which you wish to board the merchant. This information defines the acquirer for the merchant.
Request body
Example request
{
"detail": {
"hierarchy": {
"internalMerchantId": "00000000",
"merchantLevelCode": "MEMBER",
"parentInternalMerchantId": "00101010"
},
"requiredDetails": {
"externalMerchantId": "00000075999959",
"tradeName": "Insomnia",
"companyName": "Omnipay Ltd.",
"legalFormIndex": "001",
"languageIndex": "001",
"mcciso": "8021",
"eCommerceIndCode": "BOTH",
"residentStatusCode": "NA",
"accountOfficerIndex": "000",
"retailerClassificationCode": "798",
"branchIndex": "000"
},
"optionalDetails": {
"registrationNo": "000000000000000",
"vatRegNo": "MT 10644256",
"contractReference": "00000000",
"bankReference": "00000000",
"floorLimitCurrencyCode": "EUR",
"paymentAdviceGenerationIndex": "000",
"paymentDeliveryMethodCode": "NA",
"merchantGradeIndex": "001",
"secondaryTaxID": "MT 10644256",
"prosaDeterminant": "Determin",
"prosaBDUNumber": "12345678",
"signerDateOfBirth": "20201030",
"merchantLongName": "Omnipay Ltd.",
"mcpRateType": "E",
"domesticMcc": "8021"
},
"contract": {
"serviceContractIndex": "497",
"clientTariffIndex": "000321",
"postingTariffIndex": "503",
"settlementMethodIndex": "179",
"paymentMethodIndex": "000",
"protectAgainstFXChange": true,
"clientRegionIndex": "901",
"tierStructureIndex": "000",
"reclassBillbackIndicatorCode": "NA",
"withholdIncomeTariffIndex": "001007",
"withholdVatTariffIndex": "001007",
"regionalTaxIndex": "000",
"tierPricingFlag": "000"
},
"location": {
"countryCode": "IRE",
"state": "MYS",
"cityUrl": "Paris",
"zip": "D18 R529",
"street": "Rue Raynouard 24",
"serviceTelNo": "0123456789111",
"countyIndex": "840",
"telephone": "0353-1234567891",
"regionOverrideFlag": true,
"url": "www.abc.com"
},
"schemeDetails": {
"crossBorderFeeCode": "NONE",
"masterCardIPQualificationCode": "NA",
"masterCardIPValue": "00000055",
"visaIPQualificationCode": "NA",
"visaIPValue": "401938547",
"cbdipVisaSmiCode": "aTT345200",
"mcPaymentFacilitatorId": "12345",
"mcIndependentSalesOrgId": "1234",
"viLacFeeCode": "NA",
"mcLacFeeCode": "MC_LAC_BOTH",
"visaEuFeeIndCode": "BOTH_VISA_EU_FEES",
"viUsApIafFee": "003",
"pagobancomatIndex": "000",
"visaPaymentFacilitatorId": "AbC12345",
"mcCnpMotoFee": "NO_FEE",
"dinersIntesCode": "123",
"amexModelIndex": "001",
"merchantCountryOfOrigin": "IRE",
"merchantSizeIndex": "003",
"globalFees": [
{
"feeIndex": "060",
"feeMode": true,
"cardOrganization": "002"
}
],
"upiIPQualificationCode": "AMPET1",
"marketPlaceId": "23412345",
"stagedDigitalWalletId": "23456454",
"rampProviderId": "45321456",
"acquirerBusinessId": "61234456",
"mcStagedDigitalWalletId": "12345678910"
},
"salesDetails": {
"accSignedDate": "20200615",
"accCreationDate": "20200615",
"accApprovalDate": "20200615",
"salesAgentId": "99999999",
"businessOwnerId": "99999999",
"salesChannelIndex": "000",
"salesCurrencyCode": "EUR",
"signedSalesValue": "10.0",
"signedAverageTicketValue": "10.0",
"salesLead": "Free text",
"signedNumberSales": "50",
"priorityMemo": "Free text for any addition notes or other information"
}
},
"addresses": [
{
"contactName": "Joe Smith",
"line1": "15 Beach Street",
"line2": "4th Zone",
"line3": "Bremen",
"line4": "Saxony",
"line5": "Ireland",
"postCode": "D18 R219",
"city": "Frankfurt",
"state": "TX2",
"countryCode": "IRE",
"telephone": "00353112345678",
"fax": "5351456789",
"email": "abc@omnipay.com",
"effectiveDate": "20201010",
"lastUpdatedBy": "John Smith",
"lastUpdated": "20210406"
}
],
"accounts": [
{
"internalAccountNumber": "90000001001",
"accountCurrencyCode": "EUR",
"accountStatus": "ACTIVE",
"receiverCountryCode": "IRE",
"paymentReference": "999999999999999999",
"statementGenerationCode": "SUPPRESS",
"annualFeeDueDate": "20201231",
"liabilityAccount": "IR21A123456",
"sepaDirectDebitSeq": "FRST",
"parentInternalMerchantId": "00101010",
"parentTradeName": "Insomnia",
"payable": {
"bankName": "Bank of Dublin",
"accountName": "John Doe Debit Account",
"counterBankNumber": "13165987",
"accountNumber": "ZZ999999999999999",
"bankTelephone": "00535125412123",
"bankContactName": "Frank Castle",
"correspondentBankNo": "ZZZZZZZZZZZ",
"iban": "ZZ99999999999999999999",
"customerPaymentText": "9999999999",
"bankCity": "Dublin",
"correspondentBankAccount": "ZZ 9842512858747",
"calendarDays": "000",
"paymentDelayDays": "000",
"ceilingLimit": "1000.12"
},
"receivable": {
"bankName": "Sample Bank Name",
"accountName": "John Doe Debit Account",
"counterBankNumber": "13165987",
"accountNumber": "ZZ9999999999999999",
"bankTelephone": "003531234567",
"bankContactName": "Frank Castle",
"correspondentBankNo": "ZZ99999999",
"iban": "ZZ999999999999999999999",
"customerPaymentText": "item number 6478",
"bankCity": "Dublin",
"correspondentBankAccount": "ZZ 9842512858747",
"calendarDays": "000",
"collectionDelayDays": "000",
"ddMandateReference": "12345678NWMA02"
}
}
],
"services": [
{
"status": "ACTIVE",
"floorLimit": "000000000000000000",
"limitCurrency": "EUR",
"jcbStateCodeIndex": "TXT",
"jcbAreaCode1Index": "01",
"jcbArea2Index": "01",
"merchantSubId": "000001",
"acquirerNoOfInstallment": 4,
"lastUpdatedBy": "John Smith",
"lastUpdated": "20210406"
}
],
"references": [
{
"referenceValue": "Yes",
"lastUpdatedBy": "John Smith",
"lastUpdated": "20210406"
}
],
"merchantDevices": [
{
"externalTerminalId": "54999530",
"serialNumber": "123456789",
"contactName": "John Doe",
"terminalLocation": "Munich",
"telephone": "003531123456",
"schemeId": "000000",
"accountCurrencyCode": "EUR",
"systemBatchId": "234234",
"feeEffeciveDate": "20200615",
"lastFeeDate": "20200615",
"clientFeeIndex": "402",
"feeExpiryDate": "20200615",
"configOfTerminalIndex": "001",
"installDate": "20200615",
"activeDate": "20200615",
"terminationDate": "20200615",
"terminalPassword": "password",
"terminalTypeIndex": "000",
"terminalCountryCode": "IRE",
"serviceProviderIndex": "001",
"emv": true,
"city": "Valletta",
"acquiringProfileIndex": "000",
"templateId": "C234",
"amexPhoneNo1": "00012458754865148",
"amexPhoneNo2": "00012458754865148",
"relatedTId": "FreeText",
"waiver": "waiver02",
"socCode": "00054214",
"setupFee": "3232000",
"gprsRentalAmount": "325",
"gprsRental": "Monthly",
"installed": "Installed",
"workStation": "Terminal WONO"
}
],
"merchantAccountFees": [
{
"recordIdNumber": "9999999999",
"accountCurrencyCode": "EUR",
"effectiveDate": "20200615",
"expiryDate": "99991231",
"feeBaseCurrencyCode": "EUR",
"feePercentage": "5.0",
"feeBase": "100.0",
"feeMinimum": "13.0",
"feeMaximum": "13.0",
"triggerHighValue": "250.0",
"triggerLowValue": "0.10",
"triggerVolumeHigh": "250",
"triggerVolumeLow": "250",
"lastUpdated": "20210406",
"lastUpdatedBy": "John Smith"
}
],
"transactionCharges": [
{
"recordIdNumber": "9999999999",
"effectiveDate": "20200615",
"expiryDate": "99991231",
"feePercentage": "5.0",
"feeBase": "250.0",
"feeMinimum": "250.0",
"feeMaximum": "250.0",
"chargeCurrencyCode": "EUR",
"chargeTierLevel": "Not Applicable",
"lastUpdatedBy": "John Smith",
"lastUpdated": "20210406"
}
],
"merchantRequest": [
{
"requestIndex": "001"
}
],
"paymentInstructions": [
{
"accountTypeIndex": "470",
"accountCurrencyCode": "GBP",
"instructionTypeIndex": "001",
"deductionStartDate": "20201030",
"deductionEndDate": "20201030",
"deductionPercentage": "5.0",
"deductionMinAmount": "250.0",
"deductionMaxAmount": "250.0",
"deductionBaseAmount": "250.0",
"deductionTotalCnt": "100000",
"deductionTotalAmount": "100000",
"factorAgent": "James Kirk",
"note": "Free text to leave any extra notes"
}
],
"merchantProperties": [
{
"propertyIndex": "001",
"propertyValue": "6,000,000,000"
}
]
}Response
The merchant successfully created.
Example response
{
"meta": {
"paging": {
"count": 100,
"totalPages": 10,
"currentOffset": 1,
"currentNumberOfRetrievedRecords": 10,
"maxLimit": 10,
"hasMoreRecords": true,
"pageNumber": 1
},
"sorting": {
"sort": "name,-startDate"
},
"messages": [
{
"id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
"code": "ACCOUNT_NUMBER_NOT_FOUND",
"title": "The authorization credentials required for this request are invalid.",
"detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
"source": {
"pointer": "/dogs/name",
"parameter": "type",
"header": "type"
}
}
]
},
"data": [
{
"internalAccountNumber": "90000001001",
"accountCurrencyCode": "EUR",
"accountStatus": "ACTIVE",
"receiverCountryCode": "IRE",
"paymentReference": "999999999999999999",
"statementGenerationCode": "SUPPRESS",
"annualFeeDueDate": "20201231",
"liabilityAccount": "IR21A123456",
"sepaDirectDebitSeq": "FRST",
"parentInternalMerchantId": "00101010",
"parentTradeName": "Insomnia",
"payable": {
"bankName": "Bank of Dublin",
"accountName": "John Doe Debit Account",
"counterBankNumber": "13165987",
"accountNumber": "ZZ999999999999999",
"bankTelephone": "00535125412123",
"bankContactName": "Frank Castle",
"correspondentBankNo": "ZZZZZZZZZZZ",
"iban": "ZZ99999999999999999999",
"customerPaymentText": "9999999999",
"bankCity": "Dublin",
"correspondentBankAccount": "ZZ 9842512858747",
"calendarDays": "000",
"paymentDelayDays": "000",
"ceilingLimit": "1000.12"
},
"receivable": {
"bankName": "Sample Bank Name",
"accountName": "John Doe Debit Account",
"counterBankNumber": "13165987",
"accountNumber": "ZZ9999999999999999",
"bankTelephone": "003531234567",
"bankContactName": "Frank Castle",
"correspondentBankNo": "ZZ99999999",
"iban": "ZZ999999999999999999999",
"customerPaymentText": "item number 6478",
"bankCity": "Dublin",
"correspondentBankAccount": "ZZ 9842512858747",
"calendarDays": "000",
"collectionDelayDays": "000",
"ddMandateReference": "12345678NWMA02"
}
}
],
"errors": [
{
"id": "dd4ba13c-4a3c-4078-a31f-35ac9c07a8f7",
"code": "ACCOUNT_NUMBER_NOT_FOUND",
"title": "The authorization credentials required for this request are invalid.",
"detail": "SQLException found while trying to establish the connection with table TUKCDHN.",
"source": {
"pointer": "/dogs/name",
"parameter": "type",
"header": "type"
}
}
],
"links": {
"self": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=3&limit=10",
"first": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=1&limit=10",
"last": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=10&limit=10",
"prev": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=2&limit=10",
"next": "https://api.firstdata.com/ipp/accounts-management/v1/accounts?offset=4&limit=10"
}
}