/api/v1/omnipay/merchantDetails/{mid}

put https://cat-webfarm.1dc.com/boarding-ui-cat/external-api/maintenance/api/v1/omnipay/merchantDetails/{mid}

Response

Response body

object

hierarchy

object

required

merchantLevelCode

string

required

The hierarchy level at which the merchant will be boarded.

GROUP SUB_GROUP MEMBER

parentInternalMerchantId

string

required

length between 8 and 8

The internal OmniPay MID to which the merchant needs to be linked to as a child merchant. When populated should be an existing group /sub group merchant MID

merchantStatus

string

required

Status of the merchant i.e. Closed, Active, Suspended etc.

requiredDetails

object

required

externalMerchantId

string

length between 1 and 20

Merchant number to be used throughout the authorization and clearing cycle.

tradeName

string

length between 1 and 22

Merchant Trade Name. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.

companyName

string

length ≤ 35

Merchant's legal company name. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.

legalForm

string

length between 3 and 3

Company entity type for information purposes only, no impact to transaction processing. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal legalFormIndex when creating or editing an existing merchant profile.

languageIndex

string

length between 3 and 3

Merchant language for information purposes only, no impact to transaction processing. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal languageIndex when creating or editing an existing merchant profile.

mcciso

string

length between 4 and 4

Merchant category code (ISO 18245 ), depending on the client region setting this value may be used for clearing transactions to the scheme.

residentStatusCode

string

The residency status of the merchant. Indicates whether the merchant is a resident or non-resident for information purposes only, no impact to transaction processing.

NA RESIDENT NON_RESIDENT

accountOfficerIndex

string

length between 3 and 3

Merchant account officer; the possible values can be customized per institution, use 000=N/A if not relevant for the institution. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference_data endpoint with query parameter classification equal accountOfficerIndex when creating or editing an existing merchant profile.

retailerClassificationCode

string

length between 3 and 3

An RCC identifies the type of business performed within a merchant outlet. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal retailerclassification when creating or editing an existing merchant profile.

branchIndex

string

length between 3 and 3

Merchant branch; the possible values can be customized per institution, use 000=N/A if not relevant for the institution. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal branchIndex when creating or editing an existing merchant profile.

eCommerceIndCode

string

Field is used for the quarterly stats which are sent to the schemes.

TRADITIONAL_ONLY ECOMMERCE_ONLY BOTH

optionalDetails

object

required

registrationNo

string

length ≤ 15

The merchant registration number is a field that is conditional based on the configuration setup of an institution. By default, this field is mandatory, but it can be made optional at the institution level. If the field is provided in the payload, it must have a minimum length of 5 characters. Note that this value will be encrypted before storage, as it is considered PII data. To ensure proper encryption, a minimum length of 5 characters is required.

vatRegNo

string

length ≤ 15

Merchant registered value added tax number (VAT) . Note this value will be encrypted prior to be stored as this is considered PII data.

secondaryTaxId

string

length ≤ 15

Additional tax ID used by Canadian based merchants with provinces supporting two separate taxes (federal and provincial tax). If provided, then the value must be Upper Case Alphanumeric and minimum of 5 character length. Note this value will be encrypted prior to be stored as this is considered PII data. To suppport encryption process, minimum of 5 character length must be provided. If a user want to delete the value for this field as part of merchant maintenance API i.e. null value, then it is allowed to pass the empty string.

contractReference

string

length ≤ 8

Application contract reference number. This is a free format field for information purpose only.

bankReference

string

length ≤ 8

Merchant bank reference number. This is a free format field, where the value can be defined by the merchant/acquirer, information purposes only, no impact to transaction processing

dynamicPricing

boolean

Indicate if the merchant uses dynamic pricing

merchantGradeIndex

string

length between 3 and 3

Merchant grouping by business type and volume. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal merchantGradeIndex when creating or editing an existing merchant profile.

prosaDeterminant

string

length between 8 and 8

Unique identifier of the business by the Internetwork, used by PROSA to process transactions. If a merchant have PROSA acquiring service assigned, then this field is mandatory. Spaces allowed only if a merchant does not have the PROSA acquiring service assigned.

prosaBDUNumber

string

length between 8 and 8

Local number to identify Mexican merchant regulated by Mexican authorities, handled by PROSA. If a merchant have PROSA acquiring service assigned, then this field is mandatory. Zeroes allowed only if a merchant does not have PROSA acquiring service assigned.

signerDateOfBirth

date

length between 8 and 8

Indicates Date of Birth of the Seller's Authorized Signer. The Seller is a legal representative of the business from merchant side. The format is YYYYMMDD. If a merchant have AMEX Optblue acquiring service assigned, then this field is mandatory. Zeroes allowed only if merchant does not have AMEX Optblue acquiring service assigned.

contracts

array of objects

contracts

object

paymentMethodIndex

string

length between 3 and 3

Institution defined value related to a specific payment interface. Default to spaces when no values provided. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal paymentMethodIndex when creating or editing an existing merchant profile.

protectAgainstFXChange

boolean

Defaults to false

Flag to indicate if the merchant is protected against currency fluctuations on the event the transaction is disputed and the transaction currency is different to the merchant funding currency.

clientRegionIndex

string

length between 3 and 3

The selected client region will determine how the transactions are settled to the scheme. For a list of valid regions use Acquirer Profile API GET acquirerprofile/v1.0/reference-data endpoint with query parameter clasifications equal clientRegionIndex when creating or editing an existing merchant profile.

reclassBillbackIndicatorCode

string

required

Indicator to pass the Reclass fee to the merchant. Reclass Fees can only be passed to the merchant when configured for the Institution.

NA NO_BILLBACK AUT_BILLBACK_DR AUT_BILLBACK_ALL MANUAL_BILLBACK

withholdVatTariffIndex

string

length between 6 and 6

The withhold vat tariff id for the institution. For a list of valid codes use Acquirer Profile API GET tariff endpont when creating or editing an existing merchant profile.

regionalTaxIndex

string

length between 3 and 3

Indicator if regional tax to be generated or not.

location

object

country

string

length between 3 and 3

ISO-3166 alpha country code representing the country the merchant is located in, the values are restricted based on institutions configuration. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal countryCode when creating or editing an existing merchant profile.

state

string

length ≤ 3

Code representing the state the merchant is located in. If the country selected is United States, Canada or Italy, this field is mandatory. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.

cityUrl

string

required

length ≤ 13

Merchant city for physical merchants, URL for ecommerce merchants. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.

Merchant telephone number. The format should be 'Country code' (numeric value) followed by '-' followed by actual phone number (numeric value). For Merchant Maintenance API, empty string can be passed if a user wants to delete the value.

string

length ≤ 15

zip

string

length ≤ 11

Merchant zip/postcode

street

string

length ≤ 40

Merchant street. There is no pattern defined for this field. UTF8 characters (extended ASCII characters) are supported for this field. Maximum length of this field is defined in bytes and special character of any extended ASCII character can be more than 1 byte for each character. Consumer should consider number of bytes for maximum length determination. For example, if consume wants to provide three 2-bytes ASCII character, then actual length of the provided data is 6, not 3.

serviceTelNo

string

length ≤ 16

Merchant service telephone number

countyIndex

string

length between 3 and 3

County id where the merchant is located. As per Institution configuration. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal countyIndex when creating or editing an existing merchant profile.

fax

string

length ≤ 15

Merchant fax number

salutation

string

Title to be assigned to the main contact of the merchant.

THE_DIRECTOR THE_OWNER THE_PROPRIETOR

regionOverrideFlag

boolean

Flag relevant to institutions processing Payment Facilitator Single MID Model for user defined regions. If the value passed as empty string, then default value 'false' is considered.

municipalityIndex

string

length between 5 and 5

Municipality id where the merchant is located. As per Institution configuration. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal municipalityIndex when creating or editing an existing merchant profile.

url

string

length ≤ 75

A valid URL/website address of the e-commerce merchant. Applicable for MasterCard e-commerce transactions. If not provided at the transaction level, OmniPay will retrieve it from the merchant profile and include it in the scheme clearing file and respective merchant profile reporting. However, if this optional field is provided, it cannot consist solely of spaces or zeros.

schemeDetails

object

crossBorderFeeCode

string

Indicates whether a merchant is liable for corss boder fees for MasterCard, Visa both.

NONE MASTERCARD VISA BOTH

masterCardIPQualificationCode

string

The MasterCard interchange program qualification lists the interchange programs for MasterCard.

NA CHARITY MASTERCARD_AID TRANCHE_2 TRANCHE_3 LOW_VALUE_PAYMENTS GAMBLING SMALL_MERCHANT

masterCardIPValue

string

length ≤ 10

The MasterCard interchange program value field assigned by MasterCard for the corresponding interchange program.

visaIPQualificationCode

string

The Visa interchange program qualification lists the possible interchange program for Visa.

NA VAU_VALIDATED VISA_SPEND_QUALF_IND VISA_EPS VISA_MVV_PROGRAM LOW_VALUE_PAYMENTS CHARITY SG_EZ_LINK SG_STRATGC_SUPERMRKT SG_STRATGC_GOVERNMNT BILL_PAY VISA_INDIAN_FUND_TXN HK_STRATGC_GOV SG_STRATGC_ULITITIES SG_STRATGC_VISA_BPAY TH_STRATGC_4 TH_STRATGC_5 TH_STRATGC_8 SMALL_MERCHANT CPS_RETAIL VISA_MVV_PROGRAM_CLR INDIA_PM_CARES

visaIPValue

string

length ≤ 10

This Visa interchange program value field is assigned by Visa for the corresponding interchange program.

paymentLowValue

boolean

Defaults to false

Flag to determine if the merchant is eligible to qualify for UK domestic low value E-Commerce.

cbdipVisaSmiCode

string

length between 9 and 9

Single merchant identifier (SMI) provided by Visa when merchant is registered with cross border interchange program CBDIP

mcPaymentFacilitatorId

string

length ≤ 11

MasterCard registered payment facilitator id for merchants processing PF transactions

visaPaymentFacilitatorId

string

length between 8 and 8

Visa registered payment facilitator id for merchants processing PF transactions

mcIndependentSalesOrgId

string

length ≤ 11

MasterCard registered ISO for merchants processing ISO transactions

visaCanIasfFee

boolean

Indicator if Visa international acquirer service Fee (IASF) cross border fee applies on all transactions assessed in Canada for non canadian issued cards.

viLacFeeCode

string

Indicator for which VISA cross border fees (ISA, IA or both) in the Latin America and Caribbean (LAC) to be applied.

NA VISA_LAC_IA_FEE VISA_LAC_ISA_FEE BOTH_LAC_FEES

mcLacFeeCode

string

Indicator for which MC cross border fees (CB , CB Rebate or both) in the Latin America and Caribbean (LAC) to be applied.

NA MC_LAC_CB MC_LAC_CB_REBATE MC_LAC_BOTH

mcAbvFeeInd

boolean

Indicator if MasterCard acquirer brand volume fee is applicable for the merchant

visaEuFeeIndCode

string

Indicator for which EU fee to be charged for the merchant located in Europe. VISA_IA_FEE indicates fee to be charged for international non-Ecommerce transactions and VISA_ECOM_FEE indicates fee to be charged for international Ecommerce transactions.

NEITHER VISA_IA_FEE VISA_ECOM_FEE BOTH_VISA_EU_FEES

mcIntlEcomFee

boolean

Indicates the enabling of the MasterCard International Ecommerce Fee, available options depends on the institution configuration.

viUsApIafFee

string

length between 3 and 3

Indicator for which VISA fees (AP IAF, US IAF, both or neither) to be enabled, available options depends on the institution configuration. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal viUsApIafFee when creating or editing an existing merchant profile.

globalTravelB2BFeeInd

string

length between 3 and 3

Indicates whether the MasterCard Global Wholesale Travel Transaction Program B2B Fee should be charged to the merchant. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal globalTravelB2BFeeInd when creating or editing an existing merchant profile.

mcCnpMotoFee

string

It supports the activation of the MC scheme fee.

NO_FEE MC_CNP_FEE_ONLY MC_MOTO_FEE_ONLY BOTH_MC_CNP_&_MOTO_FEE

mcPifFeeInd

boolean

Indicator whether the MasterCard Processing Integrity Fee is applicable for the merchant. If the value passed as empty string, then default value 'false' is considered.

dinersIntesCode

string

length ≤ 4

Unique identifier assigned by Diners to merchants who have agreement for preferred interchange rates. This field is cleared to scheme. (Value can be same across multiple MIDs). If provided, then it must be minimum of 3-digit numeric value and Maximum of 4-digit numeric value. The field is defined as alphanumeric because to allow user to pass empty string in Merchant Maintenance API only to delete the value when in case merchant come out of registration with Diners for this special interchange program.

amexModelIndex

string

length between 3 and 3

Flag to determine which AMEX clearing model to be applied for AMEX transactions. For merchant boarding API, if the object is not provided or provided with value '000', then CAPN AMEX clearing model is defaulted if AMEX acquiring service is enabled for a merchant. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference_data end-point with query parameter classification equal amexModelIndex. Note that if a value '001' (AMEX GNS) provided for this field, then there will be a cross validation applied against valid Client refernece Type '201---Amex' assigned to the merchant with 10-digit AMEX SE number populated as client reference value.

merchantCountryOfOrigin

string

length between 3 and 3

Alpha country code representing the merchant country of origin for government controlled merchants. For eg. Merchant (Indian Embassy) located in Ireland should have value populated as "IND" (India) in this field. If the field is provided with 3 spaces then default value N/A will be assigned.

mvi

string

Flag to identify if the merchant participates in the Visa Merchant Volume Indicator (MVI) programme or not. If provided, then it should be one of the valid value. Merchants can be flagged as MVI participant (via Merchant Maintenance) only after successful boarding.

NOT_ELIGIBLE VISA_ELIGIBLE

pagobancomatIndex

string

length between 3 and 3

Indicates when Pagobancomat transactions are flagged as bill payment. Available options depends on the institution configuration. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference_data endpoint with query parameter classification equal pagobancomatIndex when creating or editing an existing merchant profile.

salesDetails

object

accSignedDate

date

required

Date merchant was signed up. Format YYYYMMDD

accCreationDate

date

required

Date merchant was created in the system. Format YYYYMMDD

accApprovalDate

date

required

Date merchant application was approved. Format YYYYMMDD

salesAgentId

string

required

length between 8 and 8

Code of sales agent associated with the sales process. Available options depends on the institution configuration. For a list of valid status codes use Acquirer Profile API GET acquirerprofile/v1.0/reference-data endpoint with query parameter clasifications equal salesAgentId.

businessOwnerId

string

required

length between 8 and 8

Code of the business owner associated with the sales process. Available options depends on the institution configuration. For a list of valid status codes use Acquirer Profile API GET acquirerprofile/v1.0/reference-data endpoint with query parameter clasifications equal businessOwnerId.

salesChannel

string

length between 3 and 3

Institution specific user defined list of potential sales channels. For a list of valid codes use Acquirer Profile API get acquirerprofile/v1.0/reference-data endpoint with query parameter classification equal salesChannelIndex when creating or editing an existing merchant profile.

salesCurrencyCode

string

required

length between 3 and 3

ISO 4217 Apha Currency code of amount fields displayed

signedSalesValue

string

signedAverageTicketValue

string

length ≤ 18

Contracted sales value for the merchant. Whether this value is per week, per month, per year, etc. is defined at institution level. Format NNN.NN

salesLead

string

length ≤ 15

Name or description of the sales lead

signedNumberSales

string

length ≤ 18

Contracted number of sales for the merchant. Whether this value is per week, per month, per year, etc. is defined at institution level

priorityMemo

string

length ≤ 100

Free text for additonal note

Language


xxxxxxxxxx
15
1
curl --request PUT \
2
     --url https://cat-webfarm.1dc.com/boarding-ui-cat/external-api/maintenance/api/v1/omnipay/merchantDetails/mid \
3
     --header 'accept: */*' \
4
     --header 'content-type: application/json' \
5
     --data '
6
{
7
  "contracts": {
8
    "protectAgainstFXChange": false,
9
    "reclassBillbackIndicatorCode": "NA"
10
  },
11
  "schemeDetails": {
12
    "paymentLowValue": false
13
  }
14
}
15
'

Click Try It! to start a request and see the response here! Or choose an example:

*/*

200OK