Merchant Management

Application

Merchant Application

The merchant data structure holds information about you, the merchant (acceptor). These fields can be used to override the information that is shown on the cardholder statement.

Parameters

Feild	Required	Format	Description
`merchant.id`	Mandatory	N15[0-9]15	Acquirer-assigned Merchant identifier.
`merchant.name`	Mandatory	An75[\s\S]100	The registration name of the merchant.The merchant’s legal business name. This may differ from the `merchant.business`
`merchant.business`	Mandatory	AN22[\s\S]22	The name of the merchant. It will normally make up the first line of the card holder statement.
`merchant.website`	Optional	AN100[\s\S]100	This normally makes up the second line of the card holder statement.
`merchant.street`	Mandatory	AN100[\s\S]100	The location of the merchant outlet where the transaction took place. If the merchant does not operate from a fixed location or is an online merchant, you must provide the details of the merchant’s principle place of business. Principle place of business is defined as the same country as the merchant location (i.e. the operating country). For example, Merchant ABC in India would require an address in India, not the headquarters in the US. Cannot be a PO box.
`merchant.postcode`	Mandatory	AN10[A-Za-z0-9-]10	The postal code or zip code of the merchant
`merchant.city`	Mandatory	AN50[a-zA-Z0-9]50	The city of the merchant
`merchant.state`	Mandatory	AN50[a-zA-Z0-9]50	The county, state or region of the merchant
`merchant.country`	Mandatory	A2[A-Za-z]2	The country of the merchant
`merchant.phone`	Mandatory	AN25[a-zA-Z0-9+-.]25	The merchant's phone number.
`merchant.mmcc`	Mandatory	AN4[0-9]4	The merchant's category code ( MasterCard).
`merchant.vmcc`	Mandatory	AN4[0-9]4	The merchant's category code ( Visa).
`merchant.pfId`	Mandatory	AN11[\s\S]11	The Payment Facilitators assigned by Mastercard of the merchant
`merchant.isoId`	Optional	AN8[\s\S]8	The Independent Sales Organization(Mastercard use only) of the merchant
`merchant.submerchantId`	Optional	AN15[\s\S]15	The id of the sub-merchant of the payment facilitator.
`merchant.pfAbbv`	Optional	AN7[\s\S]7	Abbv. name of the payment facilitator
`merchant.` `nationalTaxIdentificationNumber`	Optional	AN14	The government-assigned number used by the merchant for tax reporting purposes. It is also known as the Business Registration ID
`merchant.` `locationStreetAddress1`	Optional	AN60[\s\S]60	The location of the merchant outlet where the transaction took place. If the merchant does not operate from a fixed location or is an online merchant, you must provide the details of the merchant’s principle place of business. Principle place of business is defined as the same country as the merchant location (i.e. the operating country). For example, Merchant ABC in India would require an address in India, not the headquarters in the US. Cannot be a PO box.
`merchant.mcc2`	Optional	UN4[0-9]4	The acquirer has the option to provide up to 10 MCCs for a particular merchant location; mcc2 to mcc10 fields can be left blank if they do not apply. This is usually applicable to merchant superstores who deal with multiple lines of business.
`merchant.mcc3`	Optional	UN4[0-9]4
`merchant.mcc4`	Optional	UN4[0-9]4
`merchant.mcc5`	Optional	UN4[0-9]4
`merchant.mcc6`	Optional	UN4[0-9]4
`merchant.mcc7`	Optional	UN4[0-9]4
`merchant.mcc8`	Optional	UN4[0-9]4
`merchant.mcc9`	Optional	UN4[0-9]4
`merchant.mcc10`	Optional	UN4[0-9]4
`merchant.aggregatorID`	Conditional	AN8[a-zA-Z0-9]8	The payment Facilitator ID assigned by Visa to the Payment Facilitator who is processing the merchant's transactions. Required if the merchant processes through a Visa payment facilitator or a marketplace.
`merchant.aggregatorName`	Conditional	AN25[a-zA-Z0-9]25	The name of the aggregator processing this merchant’s payment. Required if Aggregator ID is populated.
`merchant.aggregatorType`	Conditional	AN1	The name of the aggregator processing this merchant’s payment. Value:P Payment Facilitator M Marketplace
`merchant.aggregatorAbbv`	Conditional	AN7[a-zA-Z0-9]7	Abbv.name of the aggregator
`merchant.corporateStatus`	Mandatory	UN1	Identified whether the merchant is a sole proprietor or not. Value: 0 Not a Sole Proprietor 1 Individual/Sole Proprietor
`merchant.corporateName`	Optional	AN55[\s\S]100	The name of the corporation that owns the merchant. This field is applicable if another company owns the merchant in a hierarchical fashion.
`merchant.dateDesigned`	Mandatory	UN8 ccyymmdd	The relationship start date when the store (location) was signed up by the acquirer or payment facilitator
`merchant.mvvID`	Conditional	AN10[a-fA-F0-9]10	A unique Merchant Verification Value (MVV) assigned for each Visa SMB merchant

resourcePath=/pay/v3/merchant/create

curl http://host:port/pay/v3/merchant/create \
  -d "entityId= tEntity1" \
  -d "entityType=PARTICIPATOR" \
  -d "merchant.id= 010100215311001" \
  -d "merchant.name=Test Merchant AAA" \
  -d "merchant.business=AAA" \
  -d "merchant.website=www.aaa.com" \
  -d "merchant.street= No.111, Merchant Street " \
  -d "merchant.postcode=123456" \
  -d "merchant.city=shanghai" \
  -d "merchant.state=shanghai" \
  -d "merchant.country=CN" \
  -d "merchant.mmcc=5311" \
  -d "merchant.vmcc=5311" \
  -d "merchantTransactionId= mer202001021101011230000" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

In response , system will generate an access token for the merchant automatically. Merchant administrator can change the token in merchant service portal. Below is a Sample Response：

{
  "id":"872b883720a8d9d82d23131d21e14765",
  "result":{
    "code":"000.000.000",
    "description":"Transaction succeeded"
  },
  "merchant":{
    "id":"010100215311001",
    "token":OGFjN2E0Yzk3NTQxNTM2YjAxNzU0Njc3MTEyMDBiYjl8Z0U3R3RUamJmdw=="
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 09:01:05.208+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_71665329ea9642e19b409bb793a9b80f"
}

Terminal Application

The POS terminal data structure holds information about POS-terminal.

Parameters

Feild	Required	Format	Description
`pos.terminalId`	Mandatory	AN8[a-zA-Z0-9_]8	Id assigned by the acquirer.
`pos.merchantId`	Mandatory	AN8[a-zA-Z0-9_]8	Merchant ID to which POS belongs
`pos.name`	Mandatory	AN32[a-zA-Z0-9_]32	Terminal name assigned by the merchant
`pos.deviceId`	Mandatory	N32[0-9]32	Serial number of the terminal.
`pos.deviceInfo`	Mandatory	AN32[a-zA-Z0-9_]32	Device Info.Possible values:`PAX_S800` `VERIFONE_E335` ....
`pos.terminalType`	Optional	AN32[a-zA-Z0-9_]32	Terminal Type. Possible values:- `POS` `mPOS` `DigitalQR` `WEB`
`pos.postcode`	Optional	AN10[A-Za-z0-9-]10	The postal code or zip code of the terminal
`pos.pinEntryCapability`	Mandatory	AN1[A-Za-z0-9-]1	Indicates if the terminal is currently able to handle PIN. Possible values: 0:Unknown 1:Available 2:Not available 3:mPOS software-based PIN 8:PINpad is not operative now
`pos.digitalId`	Optional	AN15[A-Za-z0-9-]15	The digital id assigned by the acquirer
`pos.acctId`	Optional	AN15[A-Za-z0-9-]15	The account id assigned by the acquirer

resourcePath=/pay/v3/terminal/create

curl http://host:port/pay/v3/terminal/create \
-d "entityId= tEntity1" \
-d "entityType=PARTICIPATOR" \
-d "pos.merchantId= 010100215311001" \
-d "pos.name=Test Terminal" \
-d "pos.terminalId=12345678" \
-d "pos.terminalType=POS" \
-d "pos.postcode=123456" \
-d "pos.pinEntryCapability=1" \
-d "merchantTransactionId= mer2020010310611220000" \
-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Sample Response：

{
  "id":"872b883720a8d9d82d23131d21e14765",
  "result":{
    "code":"000.000.000",
    "description":"Transaction succeeded"
  },
  "merchant":{
    "id":"010100215311001"
  },
  "pos":{
    "terminalId":"12345678"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-03 09:01:05.208+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_71665329ea9642e19b409bb793a9b80f"
}

Update Information

Merchant Id and Terminal Id cannot be updated after it created and the other information can be updated with following two APIs.

Update merchant information:

resourcePath=/pay/v3/merchant/update/{merchantId}

curl http://host:port/pay/v3/merchant/update/010100215311001 \
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "merchant.street= No.222, Merchant Street " \
  -d "merchant.postcode=222222" \
  -d "merchantTransactionId= mer202001051101011230000" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Update terminal information:

resourcePath=/pay/v3/terminal/update/{terminalId}

curl http://host:port/pay/v3/terminal/update/12345678 \
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "pos.pinEntryCapability=2" \
  -d "merchantTransactionId= mer2020010310611220000" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

3DS Merchant Enrollment

This API is used to manage merchant participation in Mastercard Identity Check on EMV 3DS (3DS2).

Enroll 3DS Merchant

resourcePath=/pay/v3/merchant/3dsenroll

curl http://host:port/pay/v3/merchant/3dsenroll \
  -d "entityId= tEntity1" \
  -d "entityType=PARTICIPATOR" \
  -d "merchant.id= 010100215311001" \
  -d "merchantTransactionId= mer202001021101011230000" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Below is an example of response:

{
  "id":"872b883720a8d9d81343123b0fbcd176",
  "result":{
    "code":"000.000.000",
    "description": "Transaction succeeded"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-18 12:51:05.326+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_71665329ea9642e19b409bb793a9b80f"
}

Delete 3DS Merchant

Parameters

Feild	Required	Format	Description
`threeDSecure.` `deleteReason`	Conditional(Required only if action is set to "DELETE")	String	Description: Reason to delete the merchant enrolment Values: "Data Entry Error", "Merchant No Longer Participating", "Acquirer Reference ID Change", "Acquirer Primary ICA Change", "Other"

resourcePath=/pay/v3/merchant/3dsdelete

curl http://host:port/pay/v3/merchant/3dsdelete \
  -d "entityId= tEntity1" \
  -d "entityType=PARTICIPATOR" \
  -d "merchant.id= 010100215311001" \
  -d "merchantTransactionId= mer202001021101011230000" \
  -d "threeDSecure.deleteReason= TEST" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Below is an example of response:

{
  "id":"872b883720a8d9d81343123b0fbcd176",
  "result":{
    "code":"000.000.000",
    "description": "Transaction succeeded"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-18 12:51:05.326+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_71665329ea9642e19b409bb793a9b80f"
}

Status Maintenance

Please use status maintenance API to close or terminate the merchant / terminal.

Merchant Status

The possible value of the merchant.status is the following:

NORMAL Normal status
CLOSED Closed by bank
BLOCKED Temporarily Stopped
TERMINATED Voluntarily Closed

tip

If the merchant status is closed or terminated, it is not allowed to set normal status in API.

And there is an optional field merchant.securityStatus and the security status will not affect the transactions.

SUSPECTED Fraud detected
IDVERIFIED ID verified

Merchant is a mandatory field in this API. Below is an sample:

resourcePath=/pay/v3/merchant/status/

curl --location --request POST 'https://domain/pay/v3/merchant/status' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'entityId=Entity1' \
  --data-urlencode 'entityType=PARTICIPATOR' \
  --data-urlencode 'merchantTransactionId=a6728948-5be2-4979-ad57-650ce85b64c3' \
  --data-urlencode 'merchant.id=202500002222' \
  --data-urlencode 'merchant.status=NORMAL' \
  --data-urlencode 'merchant.securityStatus=SUSPECTED'

Terminal Status

Below is the possible value of terminal.status:

NORMAL
CLOSED
BLOCKED
TERMINATED

Update terminal status:

resourcePath=/pay/v3/terminal/status/

curl --location --request POST 'https://host:port/pay/v3/terminal/status' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'entityId=Entity1' \
  --data-urlencode 'entityType=PARTICIPATOR' \
  --data-urlencode 'merchantTransactionId=a6728948-5be2-4979-ad57-650ce85b64c3' \
  --data-urlencode 'merchant.id=202500002222' \
  --data-urlencode 'pos.terminalId=10200222' \
  --data-urlencode 'terminal.status=NORMAL'

Inquiry

Merchant Inquiry

Merchant Information and status Inquiry API. The response will include the merchant information and merchant status (also include 3DS enrolment status)

resourcePath=/pay/v3/merchant/Inquiry

Terminal Inquiry

Terminal Information and status Inquiry API. The response will include the terminal information and terminal status.

resourcePath=/pay/v3/terminal/Inquiry

Application​

Merchant Application​

Parameters​

Terminal Application​

Parameters​

Update Information​

3DS Merchant Enrollment​

Enroll 3DS Merchant​

Delete 3DS Merchant​

Parameters​

Status Maintenance​

Merchant Status​

Terminal Status​

Inquiry​

Merchant Inquiry​

Terminal Inquiry​

Application

Merchant Application

Parameters

Terminal Application

Parameters

Update Information

3DS Merchant Enrollment

Enroll 3DS Merchant

Delete 3DS Merchant

Parameters

Status Maintenance

Merchant Status

Terminal Status

Inquiry

Merchant Inquiry

Terminal Inquiry