Skip to main content

Soft merchant descriptors

You can provide additional merchant specific information for the consumer’s statement by populating the soft merchant data fields. This allows your consumers to identify their transactions and get information about the business that processed the charge.

Before you begin

You must enable this feature during onboarding to use. Soft merchant data is currently supported for US, CA, and EMA merchants.

Soft merchant data

The following fields are supported for soft merchant data in the object checkoutOptions.authorization.softMerchant:

Fields for soft merchant data
Field name Description Data type
name The label given to the merchant's name as it appears on the account holder's statement. Keep in mind that:
  • This soft merchant name may be used for statement and reporting consistency, and to help reduce disputes because it is a more recognizable name to the account holder. 
  • The merchant's name typically is defaulted to the merchant's Doing Business as Name (DBA name) as stored in the Firm's merchant set up system. 
    • The default DBA name may be overridden on the transaction for certain merchants such as aggregators and petroleum merchants. 
    • This override is only allowed when there is a flag set to enable the merchant to send soft merchant information to the firm. 
  • This soft merchant information is passed to the card association along with the transaction. 
  • This soft merchant information may also be used for cases where smaller businesses or franchise outlets are making a sale in which a merchant aggregator or payment facilitator (such as Square, Stripe, Amazon etc.) processes the payment transaction on their behalf.
 String
merchantPurchaseDescription Provides textual information provided by the merchant that is specific to their internal systems or processing regarding the items, servicing, or sourcing related to the transaction. String
city A portion of a party's address which is the geographic area that is a municipality with legal power granted by a state/province charter. String (13)
email

A mail system that allows a party to send and receive messages electronically. An email address is composed of a local part and a domain part.

  • The local part is unique to the individual.
  • The domain or host name must meet specific standards required by the host that administers the email service.
 String (13)
phone  A locator whose value identifies the formatted numeric address for routing voice or data communications via telephony, to reach a party. NOTE: Telephone number formats may vary; this field can include domestic and international telephone numbers. String (13)
url Provides textual information about data for the protocol for specifying addresses on the Internet (Universal Resource Locator - URL) for the merchant's organization. String (13)
visaMerchantVerificationValueId Identifies the unique number assigned by payment brands to merchants that have registered to participate in unique interchange programs. Some of the programs that a merchant can register for are the Utility program and the Purchasing Card Large ticket. Participating in the program allows the merchants to receive a better than priced rate. String
masterCardMerchantVerificationValueId Identifies the unique number assigned by payment brands to merchants that have registered to participate in unique interchange programs. Some of the programs that a merchant can register for are the Utility program and the Purchasing Card Large ticket. Participating in the program allows the merchants to receive a better than priced rate. String
merchantIncorporationStatus

The incorporation status of the merchant location. The different statuses are:

  • 1 - Individual/Sole proprietor
  • 2 - Partnership
  • 3 - Corporation - Chapter S, C
  • 4 - Medical or legal corporation
  • 5 - Associations/estates/trusts
  • 6 - Tax exempt organizations (501C)
  • 7 - Government (Federal/state/local)
  • 8 - International organizations
  • 9 - Limited liability companies
  • 0 - Invalid value, blank - Not incorporated (default)
 String
foreignMerchantIndicator Used to identify a foreign retailer under the Visa Marketplace program Boolean
address.recipientFullName

The party's name as provided at the time the party is onboarded or updated based on firm policies and business rules that allow for such updates. Keep in mind that:

  • For an individual this field includes the first, middle, and last name. 
    • The full name can also include prefixes such as Dr. or Hon. and suffixes such as Jr or III. 
  • For non-carbon entities, the field reflects the complete legal name by which an entity is registered with a state, local or federal government.
 String
address.line1 A portion of a party's address which is the line of the unstructured (unparsed) geographic street address containing any of the following: house number, street name, street direction, street type, dwelling type and number, PO Box number, rural delivery route number. String
address.line2 A portion of a party's address which is the line of the unstructured (unparsed) geographic street address continued. String
address.line3 A portion of a party's address which is the line of the unstructured (unparsed) geographic street address continued. String
address.city A portion of a party's address which is the geographic area that is a municipality with legal power granted by a state/province charter. String
address.state Classifies a geographic area that represents a first level, legal and political subdivision of a country; for example, Virginia, Bavaria. String
address.country A code that identifies the country that is recognized as an independent political unit in world affairs. This data element is a child of the Country Code CDE and valid values are based on ISO standards. String
address.postalCode The portion of a party's address that is the encoded representation of a geographic area to facilitate mail delivery services. String
merchantCategoryCode MCC or Merchant Category Code. Defaults to MCC configured at the merchant profile level. Some configurations allow multiple MCC's under a single Merchant ID. Sending an MCC not configured will result in an error. String (4)

The following is an example of how soft merchant data is sent:

HTTP method: POST

Endpoint: /checkout/intent

Scenario: Sending soft merchant data in the intent request.

Json
{
    "merchantOrderNumber": "{{merchantOrderNumber}}",
    "currencyCode": "USD",
    "cart": {
        "totalTransactionAmount": 1000
    },
    "consumer": {
        "email": "customer@jpmchase.com",
        "billingAddress": {
            "recipientFullName": "John Smith",
            "line1": "1 Main St",
            "city": "San Francisco",
            "state": "CA",
            "country": "US",
            "postalCode": "95000"
        }
    },
    "checkoutOptions": {
        "authorization": {
            "authorizationType": "AUTH_METHOD_CART_AMOUNT",
            "softMerchant": {
                "name": "Best",
                "merchantPurchaseDescription": "po123",
                "city": "Tampa",
                "phone": "111-222-3333",
                "visaMerchantVerificationValueId": "visa123",
                "foreignMerchantIndicator": false,
                "merchantIncorporationStatus": "6",
                "address": {
                    "line1": "123 unreal st",
                    "city": "tampa",
                    "state": "FL",
                    "country": "usa",
                    "postalCode": "33601"
                }
            }
        },
        "capture": {
            "captureMethod": "CAPTURE_METHOD_NOW"
        },
        "consumerProfileOptions": {
            "isSaveConsumerProfile": "false"
        }
    }
}

Response:

Json
{
    "checkoutSessionToken": "rewyjWQiOiJiZGMxMDM0YS01MTBhLTQxNjktYjlmMy0zNmZkOWRiOGExNGIiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJrc2kiOiI4MDYyNjgyYmY3MDM1YWE0OTIwZmVlZmVjY2ViODQ2MyIsImlzcyI6ImNoZWNrb3V0IiwibWlkIjoiOTkyMzAzODIwOTEwIiwib2lkIjoiOWI4ZmJkYTgtNGU2Ni00YWI0LTkwMDgtNDFjMDQwMDU4MWNjIiwibXNyIjoiIiwic3BpIjoiYzI4YmY2NzktOGQxOS00Nzc3LThkYjctOGIyMDhiODNjM2RlIiwicCI6ImluIiwiUm9sZSI6WyJUUkFOU0FDVElPTkFMX0NIRUNLT1VUX1NIT1BQRVIiXSwibW9yIjoiMTIzNDU2Nzg5MTIzNDY2NDIxOTEwIiwib2QiOiJhMDgzM2ZlMTA2NWRhOasdNDNhNzM4ZWJiMTc4ODM5Y2Y4Yjg0YmZkMTlkMjU3NTFhZmUzMjhkNzllYWEyNWQxMWI0NzU5NWQ3ODVjYTkwMDYwMjFlMTlkYWRhZjcxNTJhYTY3YWY4MzljYWY3NTVlMGFmYzExNDQ4N2Y3NTgyNiIsImV4cCI6MTcxMzg5OTkzOCwiaWF0IjoxNzEzODkyNzM4LCJqdGkiOiJjMGE0MTFmOC02ODIxLTQyNDktOTU0ZS01NzFlOGQxOTViMTgiLCJjaWQiOiJhY2VlMjdjMC05OTc4LTQwNGEtYjM2NC0yYTcwODU2MTVkN2EifQ.Uri52i0PvLTlyaxIyzoR4uE_zKYntatCf3uF8tkPuiEtKwhGWw_Wbk-lFdJS0I5QwvNHSICgFsvktKRiAaAU17HgzDIs9ItBTRheRtDICB1IXLYhchThUvhwyli6M_Lr02ZqZGkwIcuIl7hvKPjJjRWvWS5UDx5cpTS31dQ4-a-m-cosFYPmCMKlpnB5sPd4jVB5zJsnbJU8V1cH4zBpvSaZfTzR6-U8eWt_V4PEiL0JiV-GRyDjLgnjfsR_g9p2ayaBY_ym_rMkzWlJmfVDT5Sddt-pFM6xlSB2h_jlhAydyzlL7KpSXshBKj_8fkbg0TMepbsmwxHq4ZjPQ0vplk",
    "redirectedUrl": ""
}

Sub-merchant data

For those who aggregate transactions submitted to J.P. Morgan on behalf of multiple merchants (sub-merchants), we provide the means to send sub-merchant identifying fields as required by the card brands. This can be accomplished by sending soft merchant data and sub-merchant data fields in your API request to identify the sub-merchant.

To identify your sub-merchant, you can submit the following fields in the object checkoutOptions.authorization.subMerchantSupplementalData.merchantIdentification:

Fields to identify sub-merchant
Field name Description Data type
subMerchantId Identifies a merchant's account as it appears on the accountholder's statement. String
serviceEntitlementNumber Identifies a unique number assigned to a merchant by a payment brand to process conveyed transactions. String
sellerIdentifier

A unique number generated by the firm to identify the individual Transaction Division processing using the Payment Brand (AMEX Opt Blue, Discover Conveyed, etc.) conveyed settlement program under the Firm's Service Entitlement (SE) Number.

In the Payment Brand's conveyed settlement program, the merchant does not have an SE Number (AMEX, Discover, etc.). The Firm owns the merchant relationship and provides all the merchant servicing and support.

 String

Create a checkout session