Skip to main content

EMerchantPay

Overview​

Gateway: https://www.emerchantpay.com/
Developer Documentation: https://emerchantpay.github.io/gateway-api-docs/?#transactions
Default Currency: USD

Request Objects: BillingAddress, CreditCard, ThreeDSecure, SoftDescriptors, StoredCredentials

Gateway Endpoints:
This implementation of EMerchantPay forwards requests to the below endpoints.
Production: https://username:[email protected]/process/TERMINAL_TOKEN/
Sandbox: https://username:[email protected]/process/TERMINAL_TOKEN

Supported Request Parameters​

Field NameTypeEMerchantPay MappingNotes
gatewaystringN/AEMerchantPay
usernamestringusernameSee Url parameters callout below.
remoteIpIPv4 or IPv6 addressremote_ipIPv4 or IPv6 address of customer
passwordstringpasswordSee Url parameters callout below.
terminalTokenstringterminalTokenSee Url parameters callout below
amountnumericamountThe amount in minor units. For example, 2000 means EUR 20.00. Max length: 12 characters.
currencyCodestringcurrencyThe three-character ISO currency code. Alpha-3 ISO currency code
consumerIdstringconsumer_id\*Requires rememberCard on first transaction before use.
rememberCardboolremember_cardPass true to get a consumerId in the response.
billingAddress.​address1stringbilling_address.​address1Primary address
billingAdress.​address2striingbilling_address.​address2Secondary address
billingAddress.​citystringbilling_address.​cityCity
billingAddress.​countrystringbilling_address.​countryThree-Character Country Code ISO country code. TokenEx will convert to ISO 3166-1 alpha-2 code.
billingAddress.​firstNamestringbilling_address.​first_nameCustomer first name
billingAddress.​lastNamestringbilling_address.​last_nameCustomer last name
billingAddress.​statestringbilling_address.​stateState code required for USA and Canada
billingAddress.​zipstringbilling_address.​zip_codeZIP code
billingAddress.​emailstringcustomer_emailMust contain valid customer E-mail
creditCard.​cvvstringcvvcvv of cc, requirement is based on terminal configuration
creditCard.​expMonthnumericexpiration_monthExpiration month as printed on credit card
creditCard.​expYearnumericexpiration_yearExpiration year as printed on credit card
creditCard.​numberstringcard_numberComplete cc number of customer
threeDSecure.​cavvstringmpi_params.​cavvVerification Id of the authentication. Please note this can be the CAVV for Visa Card or UCAF to identify MasterCard.
threeDSecure.​dSTransIdstringmpi_params.​directory_server_idThe Directory Server ID used for 3DSecure transactions through the 3DSv2 authentication protocol.
threeDSecure.​challengeIndicatorstringmpi_params.​threeds_challenge_indicatorThe 3DS challenge indicator that represents the exact indicator used during the authentication request to the MPI provider for synchronous 3DS transactions. It is optional but highly recommended for increasing the approval ratio. It can only contain one of the following values no_preference, no_challenge_requested, preference and mandate. The default value is no_preference.
threeDSecure.​ecistringmpi_params.​eciThe electronic commerce indicator. See EMerchantPay Docs.
threeDSecure.​programProtocolstringmpi_params.​protocol_versionThe used 3DS protocol version.
threeDSecure.​aCSTransIdstringmpi_params.​acs_transaction_idThe ACS Transaction ID and is optional for 3DS transactions, but highly recommended for increasing the approval ratio.
softDescriptors.​merchantNamestringdynamic_descriptor_params.​merchant_nameAllows to dynamically override the charge descriptor
softDescriptors.​merchantCitystringdynamic_descriptor_params.​merchant_cityAllows to dynamically override the merchant phone number
softDescriptors.​subMerchantIdstringdynamic_descriptor_params.​sub_merchant_idAllows to dynamically override the sub-merchant ID.
softDescriptors.merchantAddress.​countrystringdynamic_descriptor_params.​merchant_countryAllows to dynamically override the merchant country.
softDescriptors.merchantAddress.​statestringdynamic_descriptor_params.​merchant_stateAllows to dynamically override the merchant subdivision code.
softDescriptors.merchantAddress.​zipstringdynamic_descriptor_params.​merchant_zip_codeAllows to dynamically override the merchant zip/postal code. Required for VISA OCT transactions with Australian and Canadian card bins.
softDescriptors.merchantAddress.​address1stringdynamic_descriptor_params.​merchant_addressAllows to dynamically override the merchant address.
softDescriptors.merchantAddress.​address2stringdynamic_descriptor_params.​merchant_addressAllows to dynamically override the merchant address.
softDescriptors.​merchantUrlstringdynamic_descriptor_params.​merchant_urlAllows to dynamically override the merchant URL
softDescriptors.​merchantPhonestringdynamic_descriptor_params.​merchant_phoneAllows to dynamically override the merchant phone number.
softDescriptors.​merchantServiceCitystringdynamic_descriptor_params.​merchant_service_cityAllows to dynamically override the merchant service city.
softDescriptors.​merchantServiceCountrystringdynamic_descriptor_params.​merchant_service_cityAllows to dynamically override the merchant service country.
softDescriptors.​merchantServiceStatestringdynamic_descriptor_params.​merchant_service_stateAllows to dynamically override the merchant service subdivision code.
softDescriptors.​merchantServiceZipCodestringdynamic_descriptor_params.​merchant_service_zip_codeAllows to dynamically override the merchant service zip/postal code.
softDescriptors.​merchantServicePhonestringdynamic_descriptor_params.​merchant_service_phoneAllows to dynamically override the merchant service phone number.
storedCredentials.​initiatorstringrecurring_typeValid values: "merchant" or "cardholder" Used in combination with credentialStoredand conditionally transactionType if applicable.

This field is used for the inference of credential_on_file. See table below.
storedCredentials.​credentialStoredboolrecurring_typeThis field is used for the inference of credential_on_file. See table below.
storedCredentials.​transactionTypestringrecurring_type
recurring_category
credential_on_file		Valid values: "unscheduled", "recurring".

Any other string value will be forwarded.

This field is used for the inference of credential_on_file. See table below.
storedCredentials.​previousNetworkTransactionIdstringResponse scheme_transaction_identifier on initial

Request credential_on_file_​transaction_identifier on subsequent		Received from the initial response that is then passed to the subsequent request.
storedCredentials.​schemeSettlementDatestringResponse scheme_settlement_date on initial Request

Request credential_on_file_
​settlement_date on subsequent		Received from the initial response that is then passed to the subsequent request.
Url Parameters: username/password/terminalToken

These fields will be available to you through the EMerchantPay admin portal. You will add them as parameters as seen in the example request below.

Subsequent Transactions

In a CIT and MIT flow, subsequent transactions will need a different terminalToken after the initial transaction. Terminal tokens can be obtained from the EmerchantPay admin portal.

Stored Credentials Inference Tables​

The table below shows how different value combinations impact the forwarded credential_on_file field.

if transactionType is "unscheduled" and if the credential has been previously stored and the initiator is "merchant" then credential_on_file is added to the forwarded request with the value of "merchant_unscheduled"

credentialStoredinitiatortransactionTypeForwarded credential_on_file
truecardholdernullsubsequent_customer_initiated
falsecardholdernullinitial_customer_initiated
truemerchantunscheduledmerchant_unscheduled
truemerchantnullnull

If transactionType is not null and not "unscheduled," we will add recurring_type and recurring_category. The table below illustrates the various value combinations for recurring_type based on the inferredcredential_on_file indicated above.

Inferred credential_on_fileForwarded recurring_type
subsequent_customer_initiatedsubsequent
initial_customer_initiatedinitial
merchant_unscheduledsubsequent
nullsubsequent

Once recurring_type is determined, we proceed to set recurring_category based on transactionType. If transactionType is "recurring," we assign recurring_category as "subscription." For any other transactionType, recurring_category is set to match the value of transactionType.

Example Requests​

{
  "gateway": "EMerchantPay",
  "password": "<Your EMerchantPay Password>",
  "username": "<Your EMerchantPay Username>",
  "amount": 1000,
  "currencyCode": "EUR",
  "creditCard": {
    "number": "4111111111111111",
    "expMonth": 6,
    "expYear": 2026,
    "fullName": "John Doe",
    "cvv": "123"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Sesame Street",
    "zip": "10178",
    "city": "Los Angeles",
    "state": "CA",
    "country": "USA",
    "email": "[email protected]",
    "phone": "+1987987987987"
  },
  "terminalToken": "<Your EMerchantPay Terminal Token>"
}

Gateway Response Parameters​

Field NameTypeEMerchantPay MappingNotes
providerTransactionCodestringunique_idUnique id defined by gateway (must later be used if capturing, voiding or refunding a transaction)
approvedstringstatusSUCCESS, CANCELLED, AUTHORIZED, or VERIFIED and its respective statusCode is returned.
tokenExTransactionCodestringunique_idBase64 encoded unique_id; currency from rawResponse
merchantReferenceIdstringtransaction_idUnique transaction id defined by merchant
brandCategoryCodestringscheme_response_codeCurrently provided by Visa only. Specifies a category to which a decline code belongs.
recurringAdviceCodestringrecurring_advice_codeCode provided by the card network offering a suggestion of when the transaction should be retried. Currently this value is only provided by MasterCard as the Merchant Advice Code (MAC Code).
recurringAdviceDescriptionstringrecurring_advice_textThe description for the retry advice code.
gatewayErrorsobject array--See GatewayErrors callout below.
gatewayErrors[?].Codestring--See GatewayErrors callout below.
gatewayErrors[?].Messagestring--See GatewayErrors callout below.
gatewayErrors[?].SourcestringN/APossible values: Unspecified, Gateway, Processor, TokenEx.
GatewayErrors Code, Message, and source
  1. If the response from EMerchantPay is formatted in an unanticipated way, the following error will be returned. 
    {
      "code": "8012",
      "message": "Could not parse gateway response",
      "source": "TokenEx"
    }
  2. When the rawResponse from EMerchantPay contains a status of "declined" and a code between 500 and 551, the gatewayError will have two objects. gatewayErrors[0].code is mapped to code , gatewayErrors[0].message is mapped to message , and gatewayErrors[0].source will be set to "Gateway"
    For the second object gatewayErrors[1].code is mapped to response_code , gatewayErrors[1].message is mapped to technical_message , and gatewayErrors[1].source will be set to "Processor".
    EMerchantPay - Error Codes
    EMerchantPay - Issuer Response Codes 
    "gatewayErrors": [
      {
        "code": "540",
        "message": "Amount exceeds credit card limit.",
        "source": "Gateway"
      },
      {
        "code": "51",
        "message": "Not sufficient funds",
        "source": "Processor"
      }
    ]
  3. When the rawResponse from EMerchantPay does not contain a status of "approved", "error", "refunded", or "voided" gatewayErrors[0].code is mapped to code , gatewayErrors[0].message is mapped to message , and gatewayErrors[0].source will be set to "Gateway" 
    {
      "code": "340",
      "message": "Please check input data for errors!",
      "source": "Gateway"
    }

Example Responses​

{
  "gatewayResponse": {
    "rawResponse": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<payment_response>\n  <transaction_type>authorize</transaction_type>\n  <status>approved</status>\n  <cvv_result_code>M</cvv_result_code>\n  <authorization_code>843655</authorization_code>\n  <retrieval_reference_number>331922006528</retrieval_reference_number>\n  <scheme_response_code>00</scheme_response_code>\n  <unique_id>2c3d6a36542ccd053eefc1e1bad9c12b</unique_id>\n  <transaction_id>4efc3590-58df-4cd4-a5ed-3b6d722c7dc2</transaction_id>\n  <response_code>00</response_code>\n  <technical_message>TESTMODE: No real money will be transferred!</technical_message>\n  <message>TESTMODE: No real money will be transferred!</message>\n  <mode>test</mode>\n  <timestamp>2023-11-15T22:35:28Z</timestamp>\n  <descriptor>TokenEx</descriptor>\n  <amount>1000</amount>\n  <currency>EUR</currency>\n  <sent_to_acquirer>true</sent_to_acquirer>\n  <scheme_transaction_identifier>234567891234560</scheme_transaction_identifier>\n</payment_response>\n",
    "gatewayErrors": [],
    "tokenExTransactionCode": "MmMzZDZhMzY1NDJjY2QwNTNlZWZjMWUxYmFkOWMxMmI=",
    "approvalCode": "",
    "providerTransactionCode": "2c3d6a36542ccd053eefc1e1bad9c12b",
    "approved": true,
    "verificationResult": {
      "cvvRaw": "M",
      "providerParsed": {}
    },
    "networkTransactionId": "234567891234560",
    "merchantReferenceId": "4efc3590-58df-4cd4-a5ed-3b6d722c7dc2"
  },
  "referenceNumber": "23111516261111652474",
  "success": true,
  "error": "",
  "message": "",
  "thirdPartyStatusCode": "200"
}
Last updated on