Sending notifications to customers | ECOMMPAY Documentation

Overview

ecommpay payment platform supports a capability of sending notifications to inform customers about various events related to processing of their payments. As a rule, these notifications contain information about operation processing results; however, depending on the needs of the merchant, notifications can inform customers about other events, for example, an e-wallet registration as part of processing a payment request or an update of the COF purchase's terms.

Notifications are sent if the following conditions are met:

Sending notifications has been set up for the project in question.
The email of the customer has been passed to the payment platform (either in the initial request to perform a payment or in the clarification request).
The event that triggers sending of notifications has occurred.

Events which can generate notifications include both the results of operation processing as part of executing a payment (for example, operations sale, auth, cancel, payout, and refund) and the results of separate actions that are part of operation processing (for example, an update of the COF purchase's terms).

You can also send your customers purchase receipts—notifications that contain information about the purchases they made. In this case, notifications include a list of purchased items with the corresponding attributes for each item (price, quantity, description, and the amount of added VAT).

If you need a certain notification to be sent once again, contact technical support specialists support@ecommpay.com.

Sections below describe how this capability is set up, what versions of notification design can be used, and what relevant data to provide in payment requests. For more information about sent receipts to customers from Payment Page, see the section Sending receipts and notifications to customer.

Setting up

ecommpay technical support specialists enable and set up the capability of sending notifications to customers. The following settings are configured upon agreement with the merchant:

List of operations and other events to generate notifications.
Operations statuses that generate notifications (can be enabled both for the final status success and for the final status decline).
Subject line of the email with the notification (for instance, Receipt or Notification about completed purchase).
Sender's email address (can be ecommpay domain or custom domain)
Option to send blind carbon copy (bcc) of the notification to the address provided by the merchant.

Notification design

Standard template

Our standard template can only be used for notifications about the results of operation processing as part of performing a purchase and a payout as well as the result of issuing a refund.

This template includes:

Date and time of the event that occurred with the time zone of the merchant's web service specified.
Logo of ecommpay or the logo of the merchant.
Name, current address, and the registered domain name of the merchant.
Description which contains the payment or operation type set up to generate a notification.
Order number which corresponds to payment_id.
Payment method which specifies the payment instrument used.
Payment amount with the currency code.
Link to the email and the phone number of the merchant's customer support.
Link to the terms and conditions and the return policy.

Custom coded template

A custom coded template can be used for sending notifications about the results of operation processing as well as other events that occur during payment processing. Custom coded templates are developed by ecommpay specialists on the basis of the layouts provided by the merchant. These templates can include the same elements as the standard templates, with the option to modify the order in which the elements appear on the page, or they can include other elements, for example, the list of purchased items, or the details of the e-wallet registration, a warning about surpassing the daily amount limit for processed operations, or the update of the COF purchase's terms. Keep in mind that if you need a customised notification message, or the notification is sent in a language other than English (which is the default notification language), you should provide the text of the notification message to the technical support specialists.

The following are the examples of custom coded notification templates:

Notification about the end of the free trial period which does not contain any elements of the standard template (except for the logo of the merchant).
Notification with the list of purchased items which contains all elements of the standard template.

Data format

For the notification to be sent, in addition to the required parameters, the payment request should contain the following:

The email of the customer which is passed in the email parameter of the customer object.
The language code of the customer which is passed in the language parameter of the customer object when notifications are sent in a language other than English.

To add the list of purchased items to the notification, send relevant data in the receipt_data object. The receipt_data object contains the positions array which allows listing up to 50 purchased items in the notification. For each listed item, the following information can be specified:

amount—a required parameter to specify the price of the item
quantity—an additional parameter to specify the number of purchased items of the same kind
tax—an additional parameter to specify VAT rate
tax_amount—an additional parameter to specify the amount of the VAT paid
description—an additional parameter to describe the purchased item

As a rule, the receipt_data object also contains the total_tax_amount parameter specifying the total VAT amount for the entire purchase. If the VAT rate is the same for all items, then it is specified in the common_tax parameter after the total amount has been specified. If the VAT rate differs for listed items, then it is specified in the tax parameter separately for each item.

The JSON object structure is provided in the receiptdata model in Gate API specification.

In the example below, the purchase request contains the list of three items in the positions array of the receipt_data object. The VAT rates for the listed items differ; therefore, they are specified separately in the tax parameter for each item. There is no need to pass the common_tax parameter with the VAT rate for all items in this case.

Figure: Example of the purchase request with the list of purchased items

{
  "general":{
    "project_id":92724,
    "payment_id":"ECOMM-7654321-777",
    "signature":"5fgsjhgfgFxO9UaFLYGsBaisdffddgYuezUf+6VWlrsdfsH+LysUfdQM+w=="
  },
  "customer":{
    "ip_address":"128.112.0.16",
    "email":"relativeal@princeton.com"
  },
  "payment":{
    "amount":131971,
    "currency":"USD",
    "description":"Cosmoshop order"
  },
  "receipt_data":{
    "positions":[             //an array with the list of purchased items
      {
        "quantity":1,
        "amount":5990,
        "tax":20,                   //standard VAT rate
        "tax_amount":1198,
        "description":"How to communicate with aliens, a book"
      },
      {
        "quantity":3,
        "amount":2990,
        "tax":10,     //reduced VAT rate
        "tax_amount":299,
        "description":"Astronaut space food, 1-week supply"
      },
      {
        "quantity":1,
        "amount":122990,
        "tax":20,                   //standard VAT rate 
        "tax_amount":24598,
        "description":"Radio-controlled flying saucer, full size"
      }
    ],
    "total_tax_amount":26095    //total VAT amount for the entire purchase
  },
  "card":{
    "pan":"4314220000000056",
    "year":2025,
    "month":11,
    "card_holder":"Albert Astone"
  }
}