Merchant Management
API's to create and manage merchants
Introduction
Merchants (mid) in TxShield are treated as the parent node of a Tree. The layer underneath the Merchant is the Retailer (rid) and the lowest node is a Site (sid).
Merchant --> Retailer --> Site
A Site is the object that actions / transactions are done on, in the system. If I wanted to process cred card transaction, i would create a payment Site, and use the credentials for that site to process payments. If I wanted to 3ds Authentications, I would create a 3ds Site and use those credentials to do 3ds Authentications with the 3ds SDK.
To create a Merchant, you will need to call the merchant create endpoint. This will return a Merchant id (mid). You can then use this mid to create a Retailer by call the retailer create endpoint. This will return a Retailer Id (rid). Using the rid you can then create a Site by calling the site create endpoint. This will return a Site Id (sid).
Authentication
Every call on this page requires a Bearer token to be sent in the Authorization header. You can obtain a Bearer token from the System Administrator.
Merchant, Retailer, Site.
Merchant Create
POST /api/v3/merchant/create HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 146
{
"name": "text",
"payments": true,
"threeDS": true,
"alerts": true,
"cbm": true,
"order_insights": true,
"oi_merchant_id": "text",
"remarks": "text",
"themeid": 1
}
{
"status": "text",
"msg": "text",
"mid": 1
}
Create a new merchant in the system. This call will return a MID that can be used to create Retailers. list of available themes can be retrieved from the themes endpoint.
Example JSON data.
{
"name": "New Merchant",
"payments": true,
"threeDS": true,
"alerts": true,
"cbm": true,
"order_insights": true,
"oi_merchant_id": "",
"remarks": "My New Merchant",
"themeid": 0
}
Merchant Details
Merchant Id for get merchant details
POST /api/v3/merchant/{mid}/details HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
{
"name": "text",
"oi_merchant_id": "text",
"remarks": "text",
"themeid": 1,
"status": "text"
}
Returns the details of a Merchant, doesn't have any body parameters.
Retailer Create
Merchant Id that related to retailer and retailer site
POST /api/v3/retailer/mid/{mid}/create HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 116
{
"name": "text",
"currency": "text",
"margin_percentage": 1,
"contact_email": "text",
"remarks": "text",
"description": "text"
}
{
"status": "text",
"msg": "text",
"rid": 1
}
Creates a new Retailer, you will need the mid of the Merchant that you want to attach the retailer too. A list of available currencies can be found at the currency endpoint. Example JSON data
{
"name": "New Retailer",
"currency": "USD",
"margin_percentage": 0,
"contact_email": "[email protected]",
"remarks": "Created At xx",
"description": "For my USD Sites"
}
Retailer Details
Retailer Id for get retailer details
POST /api/v3/retailer/{rid}/details HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
{
"name": "text",
"rcode": "text",
"remarks": "text",
"description": "text",
"margin_percentage": "text",
"contact_email": "text",
"currency": "text",
"status": "text"
}
Returns the details of a Retailer
Site Create
Merchant Id that related to retailer and retailer site
Retailer Id that related to retailer site
support_group(id) is required field and not allowed for 0, for more information about support_group please see the endpoint /api/v3/datasource/supportgroup
cat_id is required field and not allowed for 0, for more information about cat_id please see the endpoint /api/v3/datasource/sitecategory
POST /api/v3/site/mid/{mid}/rid/{rid}/create HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 129
{
"name": "text",
"reseller_id": 1,
"url": "text",
"remarks": "text",
"description": "text",
"currency": "text",
"support_group": 1,
"cat_id": 1
}
{
"status": "text",
"msg": "text",
"sid": 1,
"rcode": "text"
}
Create a new Site, You will need the mid and rid of the merchant/retailer you want this site attached too. A list of available resellers can be found at the reseller endpoint. A list of available support groups can be found at the support group endpoint. A list of available categories can be found at the categories endpoint. Example JSON data:
{
"name": "string",
"reseller_id": 0,
"url": "string",
"remarks": "string",
"description": "string",
"currency": "string",
"support_group": 0,
"cat_id": 0
}
Site Details
Retailer Site Id for get site details
POST /api/v3/site/{sid}/details HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
{
"name": "text",
"category": "text",
"emaildomain": "text",
"payments": {
"details": {
"sid": 1,
"rid": 1,
"mid": 1,
"mtid": 1,
"name": "text",
"description": "text",
"remarks": "text",
"url": "text",
"tx_notification_email": 1,
"support_group": 1,
"support_site": "text",
"support_email": "text",
"support_phone": "text",
"cat_id": 1,
"status": "text",
"reseller_id": 1,
"skip_ccv": 1,
"currency": "text",
"creation_date": "text",
"notify_email": "text",
"allow_rebilling": 1,
"allow_refund": 1,
"allow_refund_time": 1,
"ftid": 1,
"first_transaction_alert": 1,
"cbreportemail": "text",
"margin_percentage": 1,
"stop_send_email": 1,
"tradable": 1,
"fx_provider_link": "text",
"fx_provider_auth": "text",
"smtpsetting": "text",
"customer_comm": 1,
"autorefundonCB": 1,
"auth_expiry_days": "text",
"bin_currency": 1,
"shipperid": "text",
"skip3d2": 1,
"emaildomain": "text",
"proceedeveniffail": 1,
"cart_margin_percentage": 1,
"shipping_n_tracking": 1
},
"balance": 1,
"accessRecords": [
{
"plid": 1,
"gxsid": 1,
"tx_actions": "text",
"mxsid": 1,
"name": "text",
"descriptor": "text",
"currency_code": "text",
"pay_method": "text",
"default_gateway": 1,
"test_mode": 1,
"max_limit_tx": "text",
"max_limit_30days": "text",
"secureplid": 1,
"reseller_group_id": 1,
"rates_base_id": 1,
"paiid": 1
}
]
},
"threeDS": {
"details": {
"sid": 1,
"rid": 1,
"mid": 1,
"mtid": 1,
"name": "text",
"description": "text",
"remarks": "text",
"url": "text",
"tx_notification_email": 1,
"support_group": 1,
"support_site": "text",
"support_email": "text",
"support_phone": "text",
"cat_id": 1,
"status": "text",
"reseller_id": 1,
"skip_ccv": 1,
"currency": "text",
"creation_date": "text",
"notify_email": "text",
"allow_rebilling": 1,
"allow_refund": 1,
"allow_refund_time": 1,
"ftid": 1,
"first_transaction_alert": 1,
"cbreportemail": "text",
"margin_percentage": 1,
"stop_send_email": 1,
"tradable": 1,
"fx_provider_link": "text",
"fx_provider_auth": "text",
"smtpsetting": "text",
"customer_comm": 1,
"autorefundonCB": 1,
"auth_expiry_days": "text",
"bin_currency": 1,
"shipperid": "text",
"skip3d2": 1,
"emaildomain": "text",
"proceedeveniffail": 1,
"cart_margin_percentage": 1,
"shipping_n_tracking": 1
},
"settings": {
"sid": 1,
"clientMode": "text",
"enableResult": "text",
"disableChallenge": "text",
"enable3ds1Frictionless": "text",
"enable3DS1Only": "text",
"requestorName": "text",
"requestorURL": "text",
"authenticationInd": "text",
"challengeInd": "text",
"acctType": "text",
"acquirerBin": "text",
"acquirerMid": "text",
"acquirerMerchantPwd": "text",
"mcc": "text",
"merchantCountryCode": "text",
"merchantName": "text",
"messageCategory": "text",
"purchaseCurrency": "text",
"transType": "text",
"verbose": 1,
"masterAcquirerBin": "text",
"masterAcquirerMid": "text",
"JCBAcquirerBin": "text",
"JCBAcquirerMid": "text",
"CUPAcquirerBin": "text",
"CUPAcquirerMid": "text",
"AMEXAcquirerBin": "text",
"AMEXAcquirerMid": "text"
},
"shieldSettings": {
"skip3d2": 1,
"three_ds_provider": "text",
"threedsprotocolversion": "text",
"paayauth3d2": "text",
"gpay_merchant_token": "text",
"gpay_merchant_id": "text",
"gpay_base_url": "text",
"hitrust_account_id": "text",
"hitrust_password": "text",
"hitrust_base_url": "text",
"hitrust_mastercard_prefix": "text"
}
},
"alert": {
"details": {
"sid": 1,
"rid": 1,
"mid": 1,
"mtid": 1,
"name": "text",
"description": "text",
"remarks": "text",
"url": "text",
"tx_notification_email": 1,
"support_group": 1,
"support_site": "text",
"support_email": "text",
"support_phone": "text",
"cat_id": 1,
"status": "text",
"reseller_id": 1,
"skip_ccv": 1,
"currency": "text",
"creation_date": "text",
"notify_email": "text",
"allow_rebilling": 1,
"allow_refund": 1,
"allow_refund_time": 1,
"ftid": 1,
"first_transaction_alert": 1,
"cbreportemail": "text",
"margin_percentage": 1,
"stop_send_email": 1,
"tradable": 1,
"fx_provider_link": "text",
"fx_provider_auth": "text",
"smtpsetting": "text",
"customer_comm": 1,
"autorefundonCB": 1,
"auth_expiry_days": "text",
"bin_currency": 1,
"shipperid": "text",
"skip3d2": 1,
"emaildomain": "text",
"proceedeveniffail": 1,
"cart_margin_percentage": 1,
"shipping_n_tracking": 1
},
"settings": {
"alertapiurl": "text",
"descriptorid": "text",
"username": "text",
"password": "text",
"default_dispute_action": "text",
"max_refund_amount": 1,
"alert_triggeremail": 1,
"alert_email": "text",
"shieldrdr_review_email": "text",
"statusupdate_url": "text"
},
"accessRecords": [
{
"plid": 1,
"gxsid": 1,
"tx_actions": "text",
"mxsid": 1,
"name": "text",
"descriptor": "text",
"currency_code": "text",
"pay_method": "text",
"default_gateway": 1,
"test_mode": 1,
"max_limit_tx": "text",
"max_limit_30days": "text",
"secureplid": 1,
"reseller_group_id": 1,
"rates_base_id": 1,
"paiid": 1
}
]
}
}
Returns the details of a site. Doesn't have any body params.
Site List
POST /api/v3/site/list HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
{
"list": [
{
"sid": 1,
"name": "text"
}
]
}
Returns a list of sites. Doesn't have any body params.
Site Payment
Merchant Id that related to retailer and retailer site
Retailer Id that related to retailer site
Retailer Site Id that related retailer site proceed to setup payment info
allowed for 0 or 1 only
for more information about Fraud Template (ftid) please see the endpoint /api/v3/datasource/fraudtemplate
allowed for 0 or 1 only
allowed for 0 or 1 only
allowed for 0 or 1 only
allowed for 0 or 1 only
allowed for 0 or 1 only
one of the value from [0,10,25,50,100,200,500,-1] per day; 0 = Never, -1 = Unlimited
one of the value from [0,1,2,3,4,5,6,7,8,9,10,15,20] Day(s); 0 = Not Active
allowed for 0 or 1 only
POST /api/v3/site/mid/{mid}/rid/{rid}/sid/{sid}/payment HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 263
{
"stop_send_email": 1,
"ftid": 1,
"skip_ccv": 1,
"bin_currency": 1,
"allow_rebilling": 1,
"proceedeveniffail": 1,
"margin_percentage": "text",
"first_transaction_alert": 1,
"notify_email": "text",
"allow_refund": 1,
"allow_refund_time": 1,
"emaildomain": "text",
"shipping_n_tracking": 1
}
{
"msg": "text",
"details": "text"
}
Marks a site as a Payment site. Once set to payment, the site can never be changed to 3ds or Alert. A list of available fraud templates can be retrieved from the fraud template endpoint. Example JSON data.
{
"stop_send_email": 0,
"cbreportemail": "string",
"ftid": 0,
"skip_ccv": 0,
"bin_currency": 0,
"allow_rebilling": 0,
"proceedeveniffail": 0,
"margin_percentage": "string",
"first_transaction_alert": 0,
"notify_email": "string",
"allow_refund": 0,
"allow_refund_time": 0,
"emaildomain": "string",
"shipping_n_tracking": 0
}
Site 3ds
Merchant Id that related to retailer and retailer site
Retailer Id that related to retailer site
Retailer Site Id that related retailer site proceed to setup payment info
POST /api/v3/site/mid/{mid}/rid/{rid}/sid/{sid}/3ds HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 971
{
"settings": {
"clientMode": "text",
"enableResult": "text",
"disableChallenge": "text",
"enable3ds1Frictionless": "text",
"enable3DS1Only": "text",
"requestorName": "text",
"requestorURL": "text",
"authenticationInd": "text",
"challengeInd": "text",
"acctType": "text",
"acquirerMerchantPwd": "text",
"mcc": "text",
"merchantCountryCode": "text",
"merchantName": "text",
"messageCategory": "text",
"purchaseCurrency": "text",
"transType": "text",
"verbose": 1,
"acquirerBin": "text",
"acquirerMid": "text",
"masterAcquirerBin": "text",
"masterAcquirerMid": "text",
"JCBAcquirerBin": "text",
"JCBAcquirerMid": "text",
"CUPAcquirerBin": "text",
"CUPAcquirerMid": "text",
"AMEXAcquirerBin": "text",
"AMEXAcquirerMid": "text"
},
"shieldsettings": {
"skip3d2": 1,
"three_ds_provider": "text",
"threedsprotocolversion": "text",
"paayauth3d2": "text",
"gpay_merchant_token": "text",
"gpay_merchant_id": "text",
"gpay_base_url": "text",
"hitrust_account_id": "text",
"hitrust_password": "text",
"hitrust_base_url": "text",
"hitrust_mastercard_prefix": "text"
}
}
{
"msg": "text",
"details": "text"
}
Mark a site as a 3ds site. Once set to 3ds, the site can never be changed to Payment or Alert. Example JSON data
{
"settings": {
"clientMode": "string",
"enableResult": "string",
"disableChallenge": "string",
"enable3ds1Frictionless": "string",
"enable3DS1Only": "string",
"requestorName": "string",
"requestorURL": "string",
"authenticationInd": "string",
"challengeInd": "string",
"acctType": "string",
"acquirerMerchantPwd": "string",
"mcc": "string",
"merchantCountryCode": "string",
"merchantName": "string",
"messageCategory": "string",
"purchaseCurrency": "string",
"transType": "string",
"verbose": 0,
"acquirerBin": "string",
"acquirerMid": "string",
"masterAcquirerBin": "string",
"masterAcquirerMid": "string",
"JCBAcquirerBin": "string",
"JCBAcquirerMid": "string",
"CUPAcquirerBin": "string",
"CUPAcquirerMid": "string",
"AMEXAcquirerBin": "string",
"AMEXAcquirerMid": "string"
},
"shieldsettings": {
"skip3d2": 0,
"three_ds_provider": "string",
"threedsprotocolversion": "string",
"paayauth3d2": "string",
"gpay_merchant_token": "string",
"gpay_merchant_id": "string",
"gpay_base_url": "string",
"hitrust_account_id": "string",
"hitrust_password": "string",
"hitrust_base_url": "string",
"hitrust_mastercard_prefix": "string"
}
}
Site Alert
Merchant Id that related to retailer and retailer site
Retailer Id that related to retailer site
Retailer Site Id that related retailer site proceed to setup alert info
one of the value from [match,match_n_refund]
allowed for 0 or 1 only
POST /api/v3/site/mid/{mid}/rid/{rid}/sid/{sid}/alert HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 233
{
"alertapiurl": "text",
"descriptorid": "text",
"username": "text",
"token": "text",
"default_dispute_action": "text",
"max_refund_amount": 1,
"alert_triggeremail": 1,
"alert_email": "text",
"shieldrdr_review_email": "text",
"statusupdate_url": "text"
}
{
"msg": "text",
"details": "text"
}
Set a site as an Alert site. Once set to Alert it can never be changed to Payment or 3ds. Example JSON data
{
"alertapiurl": "string",
"descriptorid": "string",
"username": "string",
"token": "string",
"default_dispute_action": "string",
"max_refund_amount": 0,
"alert_triggeremail": 0,
"alert_email": "string",
"shieldrdr_review_email": "string",
"statusupdate_url": "string"
}
Supporting Data
County List
POST /api/v3/datasource/country HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"abrv_two": "text",
"name": "text",
"name_soundex": "text",
"abrv_numeric": "text",
"abrv_currency": "text",
"symbol": "text",
"abrv_three": "text"
}
]
List of countries and their country codes.
Currency List
POST /api/v3/datasource/defaultcurrency HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
{
"AUD": "Australian Dollar",
"BTC": "Bitcoin",
"BRL": "Brazil real",
"GBP": "British Pound",
"BGN": "Bulgarian lev",
"CAD": "Canadian Dollar",
"COP": "Columbian Peso",
"CZK": "Czech koruna",
"DKK": "Danish krone",
"EEK": "Estonian kroon",
"EUR": "Euro",
"GHS": "Ghana Cedi",
"GLD": "Gold",
"HKD": "Hong Kong Dollar",
"HUF": "Hungarian forint",
"ISK": "Iceland krona",
"INR": "Indian Rupee",
"IDR": "Indonesian Rupee",
"JPY": "Japanese Yen",
"LVL": "Latvian lats",
"LTL": "Lithuanian Litas",
"MYR": "Malaysian ringgit",
"MXN": "Mexican peso",
"NZD": "New Zealand Dollar",
"NGN": "Nigerian Naira",
"NOK": "Norwegian krone",
"PEN": "Nuevo Sol (Peru)",
"OMR": "Omani rial",
"ARS": "Peso (Argentina)",
"CLP": "Peso (Chile)",
"UYU": "Peso (Uruguay)",
"PHP": "Philippine peso",
"PLN": "Polish zloty",
"RON": "Romanian lei",
"RUB": "Russian Ruble",
"SGD": "Singapore Dollar",
"ZAR": "South African rand",
"KRW": "South Korean Won",
"SEK": "Swedish krona",
"CHF": "Swiss franc",
"TWD": "Taiwan Dollar",
"THB": "Thai Baht",
"TRY": "Turkish Lira",
"USD": "US Dollar",
"VND": "Vietnam Dong",
"WST": "Western Samoan Tala",
"CNY": "Yuan Renminbi"
}
A list of supported currency and their currency codes.
Fraud Template List
POST /api/v3/datasource/fraudtemplate HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"ftid": 1,
"name": "text"
}
]
A list of currently setup Fraud Templates.
Reseller List
Retailer id from txshield core
POST /api/v3/datasource/reseller HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Content-Type: application/x-www-form-urlencoded
Accept: */*
Content-Length: 9
"rid=1"
[
{
"reseller_id": 1,
"name": "text",
"currency": "text"
}
]
A list of available resellers.
Support Group List
POST /api/v3/datasource/supportgroup HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"sgid": "text",
"name": "text",
"email": "text"
}
]
A list of support groups.
Theme List
POST /api/v3/datasource/theme HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"themeid": "text",
"theme_name": "text",
"dashboard_url": "text",
"from_email_address": "text",
"from_name": "text"
}
]
A list of available themes.
Site Category List
POST /api/v3/datasource/sitecategory HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"cat_id": "text",
"category": "text",
"parent": 1
}
]
A list of available site categories.
Payment Method List
POST /api/v3/datasource/paymentmethods HTTP/1.1
Host: uat.txshield.payshield.ai
Authorization: Bearer JWT
Accept: */*
[
{
"pmid": "text",
"pay_method": "text",
"type": "text",
"regex": "text",
"display": "text",
"pending_reminders": "text"
}
]
A list of supported Payment Methods.
Last updated