Payment Service Merchant Account Mapping

A typical Payment Gateway Provider supports different merchant accounts to which the payment is requested. A Payment Gateway Provider might also support sub-accounts from which payments of a similar category can be made. For example, a merchant might want all payments by credit card processed by merchant account A and everything else processed by merchant account B. However, both merchant account A and merchant account B exist under a parent account X. The Payment Service determines the merchant account to use when it receives a payment request.

The payment request can be made by a payment method type or a payment type.

A payment method type is the way in which the payment is made (such as by CreditCard, PayPal, or GooglePay). A payment type is the reason the payment is requested (recharge, purchase, or recurring).

You can define a merchant account map in the /opt/mtx/conf/payment-service.yaml file that maps a payment method type to a merchant account (merchant ID). You must configure the merchantAccountLookupType and the merchant accounts that are used. The map key values are determined by the merchantAccountLookupType (for example, a CreditCard for payment method type). The value is an object representing the merchant account. You can specify an ID and a key for each merchant account. The ID represents the merchant account ID and the key can be a password or secret key. This is by the specific Payment Gateway Provider and how it implements merchant accounts.

Payment Method Type

When the merchantAccountLookupType is payment method type, the key value is extracted from the payment method type field of the payment request message. It is also possible for a Payment Gateway Provider implementation to provide additional values. For example, the Braintree Payment Gateway Provider provides additional values that include the card type appended to the payment method type.

The following is a sample configuration for a merchantAccountLookupType of payment method type merchant account mapping:

payment:
  gateway:
    braintree:
      configs:
        default:
          merchantAccountLookupType: PaymentMethodType
          merchantAccountLookup:
            AmexExpressCheckoutCard:
              id: merchantId01
            AndroidPayCard:
              id: merchantId02
            ApplePayCard:
              id: merchantId03
            CoinbaseAccount:
              id: merchantId04
            CreditCard:
              id: merchantId05
            "[CreditCard.AmericanExpress]":
              id: merchantId05
            EuropeBankAccount:
              id: merchantId06
            MasterpassCard:
              id: merchantId07
            PayPalAccount:
              id: merchantId08
            UnknownPaymentMethod:
              id: merchantId05
            UsBankAccount:
              id: merchantId10
            VenmoAccount:
              id: merchantId11
            VisaCheckoutCard:
              id: merchantId12

Payment Type

When the merchantAccountLookupType is payment type, the value is determined by using the payment operation description and recurring flag from the incoming payment request message.

If the payment request is marked as recurring, then the payment type is recurring.
If the payment operation description field value is RECH, then it is marked as recharge.
If the payment operation description value is PURC, then it is marked as purchase.

It is possible for a payment gateway implementation to provide the IDs of catalog items that relate to topup offers. If the PURC entry in the payment operation description is linked to an ID that is in this list, then the payment type value is changed to recharge.

The following is a sample configuration for a merchantAccountLookupType of payment type merchant account mapping:

payment:
  gateway:
    acmebank:
      configs:
        default:
          merchantAccountLookupType:PaymentType
          merchantAccountLookup[recurring]:
            id:merchantId01
          merchantAccountLookup[recharge]:
            id:merchantId02
          merchantAccountLookup[purchase]:
            id:merchantId03

For more information about payment operation descriptions, see the discussion about Pay Now operations.

For an example of merchant account mapping, see the discussion about mapping payment methods in Braintree.