--- title: "Retrieve Reference Data" method: GET path: "/reference-data" tags: ["Generic Acquirer Setup"] --- # Retrieve Reference Data `GET /reference-data` Some fields for merchant boarding or maintenance require (or accepts) a value from a predefined list configured per acquirer, any other value submitted is rejected. These fields are categorized as 'Classification' and are listed in the classification enum query parameter. The classification matches the actual field name from the Boarding/Maintenance API requests. This end point provides the consumer with the list of Classifications and it's respective values (description and index) that can be submitted. When no Classification is submitted, by default the API response will contain all possible Classifications and their respective values. ## Query parameters - `classification` 'legalFormIndex' | 'languageIndex' | 'accountOfficerIndex' | 'branchIndex' | 'paymentAdviceGenerationIndex' | 'paymentMethodIndex' | 'clientRegionIndex' | 'tierStructureIndex' | 'countryCode' | 'state' | 'countyIndex' | 'municipalityIndex' | 'pagobancomatIndex' | 'salesAgentId' | 'businessOwnerId' | 'salesChannelIndex' | 'deliveryMethodIndex' | 'statementTypeIndex' | 'calendarTypeIndex' | 'paymentFormatIndex' | 'clearingEntityIndex' | 'jcbStateCodeIndex' | 'jcbAreaCode1Index' | 'jcbArea2Index' | 'clientFeeIndex' | 'configOfTerminalIndex' | 'terminalTypeIndex' | 'serviceProviderIndex' | 'acquiringProfileIndex' | 'instructionTypeIndex' | 'merchantGradeIndex' | 'retailerclassification' | 'regionalTaxIndex' | 'propertyIndex' | 'viUsApIafFee' | 'requestIdIndex' | 'globalTravelB2BFeeIndIndex' | 'merchantStatusIndex' | 'amexModelIndex' | 'merchantSizeIndex' | 'accountCurrency' | 'fundingRejectStatus' | 'fxCategory' | 'mcpRateType' | 'tierPricingFlag' - `offset` integer - `limit` integer ## Headers - `Content-Type` 'application/json' | 'application/json;charset=UTF-8', required - `FSV-Interaction-Id` string, required - `Institution-Number` string, required - `Environment` string, required ## Response `200` OK - InlineResponse200 — An API response. The API response will be either a `SUCCESS` or an `ERROR`. A partial success or warning scenario will be treated as a Success with embedded messages in the meta data. A full success may not have messages. The API response will contain at least one of the following top level members." - `meta` MetaType — Supplementary information about the data. - `paging` PagingMetaType — Map containing pagination related information about data. - `count` integer — Total number of records present in system which can be retrieved. - `totalPages` integer — Total number of pages with maximum limit taken into account. - `currentOffset` integer — Current offset used in request. - `currentNumberOfRetrievedRecords` integer — Current number of retrieved records. - `maxLimit` integer — Maximum limit of records that can be retrieved. - `hasMoreRecords` boolean — Indicates if there are more records available. - `pageNumber` integer — Current page number. - `sorting` SortingMetaType — Map containing sorting related information about data. - `sort` string — Indicates the elements the current data is sorted with and the direction of sorting. - `messages` ErrorType[] — Messages related to request processing or response data - any additional information or warnings to be returned in the case of a successful API call. - `id` string — Generated message identifier for particular request, helping to locate server logs. - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page. - `title` string, required — Short description of the error. Not for displaying purposes. - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes. - `source` SourceType — Object containing references to the source of the message. - `pointer` string — Indicates the element in the request document which caused the error. - `parameter` string — Indicates which query parameter caused the error. - `header` string — Indicates which header caused the error. - `data` object[] — "Contains the primary data to be returned as the API response. Use this object only when respnse type is an array. It will not be returned in case of error." - `internalAccountNumber` string — This is the internal account number that is auto-generated by bankworks when an account is created. The combination of institution number and this fields makes a unique key that identifies an account. - `accountType` OPYAccountAccountTypeObj — Index of the account type to be assigned to the merchant. - `accountTypeIndex` string — Numeric Code. - `accountTypeDescription` string — Contains description associated to a code in English. - `accountCurrencyCode` string — ISO 4217 currency of the account selected, possible values are restricted based on the institution configuration. For a list of valid codes use Acquirer Profile API GET /service-contracts/serviceContractIndex/account-settlement. - `billingLevel` boolean — Indicates if the account will be settled to on a funding. Billing accounts should have the Bank Account details filled. - `accountStatus` 'ACTIVE' | 'CLOSED' | 'SUSPENDED' | 'COLLECT_EPS' | 'SUSPENSE_ACCT' — Status of the account, the main values can be Active or Closed - `receiverCountryCode` string — ISO-3166 alpha country code for the merchant's bank country. Mandatory if billing level is set to true. If not provided while adding a merchant account then system will default to null. - `paymentReference` string — For institutions using IFS funding file this field should contain the direct debit contract number (required for merchant debits). For others it is a reference text to display on merchant's bank statement if supported on the funding file. - `statementType` OPYAccountStatementTypeObj — Statement type to be generated. Allowed to provide valid value if the institution level configuration enabled to override at merchant level. If no value provided while adding a merchant account, then system will default to "900". - `statementTypeIndex` string — Numeric Code. - `statementTypeDescription` string — Contains description associated to a code in English. - `statementGenerationCode` 'SUPPRESS' | 'GENERATE' | 'GENERATE_IF_ACTIVITY' | 'GENERATE_IF_NO_ACTIVITY' — Option for statement generation. - `annualFeeDueDate` string — YYYYMMDD Date which the annual fee for this account should be generated - `calendarTypeIndex` OPYAccountCalendarTypeObj — Defines the scheme exception days when calculating the funding date of merchant payments as per the institution configuration. If not populated, will default to "NA" - `calendarTypeIndex` string — Numeric Code. - `calendarTypeDescription` string — Contains description associated to a code in English. - `liabilityAccount` string — TBC - `sepaDirectDebitSeq` 'FRST' | 'RCUR' — Identifies the direct debit sequence i.e. transaction details attached to the payment information block such as first (FRST) or recurring (RCUR). - `parentInternalMerchantId` string — 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 - `parentTradeName` string — 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. - `payable` MerchantAccountPayable - `bankName` string — Merchant's bank name, When Billing Level set to true Bank Name must be populated. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `accountName` string — Merchant's bank account name. Mandatory if billing level is set to true. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `counterBankNumber` string — Clearing number of the merchant's bank i.e. the sort code or BSB number (Australia). - `accountNumber` string — Merchant's bank account number. This is considered PII data; the value will be encrypted prior to storing. - `bankTelephone` string — The telephone number of the merchant bank. Mandatory if billing level is set to true. - `bankContactName` string — Name of contact at the merchant's bank. Mandatory if billing level is set to true. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `correspondentBankNo` string — For institutions using IFS funding file this field should contain the swift code of the receiving bank (mapped to international bank code field on the IFS file). Default to zeros if not applicable for the merchant being set up. - `iban` string — International Bank Account Number (IBAN) is a series of alphanumeric characters that uniquely identifies a customer's account held at a bank anywhere in the world. this is considered PII data; the value will be encrypted prior to storing - `customerPaymentText` string — Additional text that may be used to identify a payment item on the merchants statement. Only valid for institutions using IFS funding solution. - `bankCity` string — Credit account bank city optional field. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `paymentFormat` OPYAccountPayablePaymentFormatObj — Format to be used to present payments to the clearing entity. Only appliable to institutions using the IFS file for funding merchants. - `paymentFormatIndex` string — Numeric Code. - `paymentFormatDescription` string — Contains description associated to a code in English. - `clearingEntity` OPYAccountPayableClearingEntityObj — The financial institution that will receive the payment. Only applicable to institutions using the IFS file for funding merchants. - `clearingEntityIndex` string — Numeric Code. - `clearingEntityDescription` string — Contains description associated to a code in English. - `correspondentBankAccount` string — Bank account for the correspondent bank. Note that this field is not allowed to modify if ceiling limit functionality is enabled for an institution. - `calendarDays` string — Number of days to be added to the posting date to calculate the payment/collection funding date - `paymentDelayDays` string — Number of days to hold payment to the merchant - `ceilingLimit` string — Indicates maximum ceiling amount limit for the merchant payment that is allowed at merchant's billing level account. Provide this field only if merchant account level ceiling limit functionality is enabled for an institution, otherwise omit it. If ceiling limit provided in the payload, then correspondentBankAccount should not be provided in the payload and vice versa. Merchant account currency represents the currency of this amount. Format is NNNNNNNNNNN.NNNN - `receivable` MerchantAccountReceivable - `bankName` string — Debit account merchant's bank name. When Billing Level set to true then bank name must be populated. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `accountName` string — Debit account merchant's bank account name. Mandatory if billing level is set to true. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `counterBankNumber` string — Clearing number of the merchant's bank i.e. the sort code or BSB number (Australia). - `accountNumber` string — Debit account clearing number of the merchant's bank. Mandatory if billing level is set to true. This is considered PII data; the value will be encrypted prior to storing. - `bankTelephone` string — Debit account bank telephone number. - `bankContactName` string — Name of contact at the merchant's bank. Mandatory if billing level is set to true. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `correspondentBankNo` string — Debit account bank swift code. - `iban` string — Debit account International Bank Account Number (IBAN) is a series of alphanumeric characters that uniquely identifies a customer's account held at a bank anywhere in the world. It typically contains a two-character ISO country code, two check digits for validation purposes followed by the domestic bank code and account number. This is considered PII data; the value will be encrypted prior to storing. - `customerPaymentText` string — Debit account additional text that may be used to identify a payment item on the merchants statement - `bankCity` string — Debit account bank city optional field. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `paymentFormat` OPYAccountReceivablePaymentFormatObj — Debit account format to be used to present payments to the clearing entity. Only applicable to institutions using the IFS file for funding merchants. - `paymentFormatIndex` string — Numeric Code. - `paymentFormatDescription` string — Contains description associated to a code in English. - `clearingEntity` OPYAccountReceivableClearingEntityObj — Debit account financial institution that will receive the collection. Only applicable to institutions using the IFS file for funding merchants. - `clearingEntityIndex` string — Numeric Code. - `clearingEntityDescription` string — Contains description associated to a code in English. - `correspondentBankAccount` string — Bank account for the correspondent bank. Note that this field is not allowed to modify if ceiling limit functionality is enabled for an institution. - `calendarDays` string — Number of days to be added to the posting date to calculate the payment/collection funding date - `collectionDelayDays` string — dDaysDr = Delay days debit. This field indicates the number of days to hold collection - `ddMandateReference` string — A Direct Debit Mandate is a unique reference used for SEPA and BACS collections that authorizes the biller to collect payments from the payer at any time. This field is mandatory for certain payment formats or settlement methods, depending on the configuration of the institution. Currently, certain validations are applied only for the BACS payment format, while validations for SEPA are not supported. It is consumer responsibility to provide this field only for applicable merchant accounts that has been setup for BACS collections into funding file. Any extended ASCII characters contain 2 bytes, and UTF8 characters (which include extended ASCII characters) are supported in this field. The maximum length of this field is defined in bytes, and special characters of any extended ASCII character can be more than 1 byte for each character. Consumers should take the number of bytes into consideration when determining the maximum length. For example, if a consumer wants to provide three 2-byte ASCII characters, the actual length of the provided data is 6, not 3. - `errors` ErrorType[] — "Contains one or more error messages and is mutually exclusive with the data item. This will not be returned in success scenarios." - `id` string — Generated message identifier for particular request, helping to locate server logs. - `code` string, required — Machine readable, unique code of the message related to particular case within operation execution. For complete list of codes please refer to API portal, messages page. - `title` string, required — Short description of the error. Not for displaying purposes. - `detail` string — Provides additional low-level details about the error to assist with troubleshooting. Not for displaying purposes. - `source` SourceType — Object containing references to the source of the message. - `pointer` string — Indicates the element in the request document which caused the error. - `parameter` string — Indicates which query parameter caused the error. - `header` string — Indicates which header caused the error. - `links` LinksType — Contains the links to retrieve the resources exposed as part of this API. - `self` string — The link to the primary resource being retrieved in the request. - `first` string — This is to provide the link to retrieve the first record/page. This SHOULD be used in case server provides pagination of the resource. - `last` string — This is to provide the link to retrieve the last record/page. This SHOULD be used in case server provides pagination of the resource. - `prev` string — This is to provide the link to retrieve the previous record/page. This SHOULD be used in case server provides pagination of the resource. - `next` string — This is to provide the link to retrieve the last record. This SHOULD be used in case server provides pagination of the resource ## Other responses - `400` — Bad Request - the request could not be interpreted by the server due to incorrect syntax. The client SHOULD NOT repeat the request without modifications. - `401` — Authentication error - `403` — Forbidden error i.e. Consumer token credentials are valid but lack of permissions to do this action. - `404` — Record does not exist. - `500` — Internal Server Error --- [API](https://skmtc.net/fiserv/apis/acquirer-profile-in-design.md) · [All operations](https://skmtc.net/fiserv/apis/acquirer-profile-in-design/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/fiserv/acquirer-profile-in-design/versions/dd7ef6ce81a1/schema)