COF purchase registration

Notice: This article that covers registering COF purchases via Payment Page and describes requests and callbacks that are used in case of card payments.

In addition, use the following materials to gain a fuller understanding of processing COF purchases:

  • articles On-demand COF purchase and Scheduled COF purchase in the section Payment models and statuses that provide a general description of processing COF purchases in the ecommpay payment platform and cover information about operations utilised to execute a payment of this type and statuses that are assigned to the payment and the operations performed within it.
  • articles of the Payment methods section containing a description of COF purchase registration via Payment Page with the focus on the specific features of the payment method used and information about relevant requests and callbacks.

General information

The ecommpay payment platform allows you to register COF purchases in a variety of ways by processing payments via Payment Page, Gate (details), and Dashboard (details) as well as by migrating information about COF purchases and payment card tokens (details). This article covers information about registering COF purchases via Payment Page by performing one-time purchases and payment instrument verification.

Recurring purchase is a payment type which uses only one request to make one (recurring) transfer of funds from customer to merchant. Recurring payments are processed by using previously stored payment credentials with no need for validation of the payment instrument (such as card validation code, or CVC).

Support for COF purchases processing may be convenient when building lasting customer relationships when you would like to offer your customers an option to make purchases with no extra effort on their side.

In terms of processing COF purchase registration using Payment Page, the basic steps that the customer performs may be selecting payment instrument, specifying its details and waiting for notification about the payment processing result.



The payment platform supports the following COF purchase types:

  • OneClick purchases are initiated by the customer and do not depend on any schedule or predetermined payment amount. For instance, the customer can make a one-click purchase in order to watch a movie online.
  • Autopurchases are initiated by merchant and do not depend on any schedule or predetermined payment amount. For example, when customer's mobile phone account balance falls below specific threshold, merchant may automatically top up the account.
  • Regular purchases are initiated by the merchant and are based on specific schedule and fixed amount. The schedule may be stored either on the payment platform side or in your web service. For instance, weekly payment for online subscription may be regularly debited to customer's account.

Registration of any type of COF purchase requires customer's consent for storage of their payment information and its usage on certain terms.

COF purchase is registered by using the Purchase and Card Verify operation modes. To initiate COF purchase processing, change its terms, cancel it, or to issue a refund, the merchant can use Gate (for all types of COF purchases) and Dashboard (for regular COF purchases).

If there are changes in the payment provider's service settings, you may need to register COF purchase again. In such cases, the merchant receives an email from the ecommpay technical support with a list of IDs of COF purchases that should be re-registered. For this registration, merchant must notify customers of the termination of previous debits and the need to initiate new ones by unlinking the saved card, and then initiate registration in the platform. Each newly registered COF purchase receives a new ID, which is sent to the merchant in the callback with information on successful registration.

Workflow

COF purchase registration by using Payment Page requires the merchant web service to do the following:

  1. Create and send a request for opening Payment Page to the payment platform.
  2. Receive callback with the result of the request processing from the payment platform.

COF purchase registration may involve auxiliary procedures:

  • 3‑D Secure authentication, in terms of which the customer is transferred to the service of the issuer where the customer needs to complete authentication using the code received by SMS or performing other required steps, or loading page is displayed (while issuer confirms authentication with no user input required).
  • Customer authentication on merchant's request, in terms of which an additional page is displayed and the customer needs to enter special verification code received by SMS or in a bank statement; this type of authentication involves a temporary hold of the agreed amount on the customer's account. This type of authentication can be used instead of 3‑D Secure authentication or in addition to it.
  • Submission of additional payment information, in terms of which notification and additional fields to be completed are displayed on the payment form. The fields should be completed on the same page of the payment form.

These procedures do not require any additional effort on the merchant's web service side, but usually require customer effort.

The following sections cover information about request and callback formats to use when registering COF purchases by using payment cards. For more information about request and callback formats to use when registering COF purchases by using alternative payment methods, see Methods.

Request format

The format of the request for opening Payment Page to register COF purchases is the same as the format described in the Payment Page API Description. When creating request, you should consider the following:

  1. The basic minimum of parameters required for any payment must be specified:
    • project_id—project identifier obtained from ecommpay
    • payment_id—payment identifier unique within the project
    • customer_id—customer identifier unique within the project
    • payment_amount—payment amount in the smallest currency unit (to register COF purchases in terms of payment instrument verification, you need to specify the 0 value)
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format
    • signature—request signature generated after all required parameters were specified (for more information, see the section Signature generation and verification)
  2. For registering a COF purchase along with payment instrument verification, the mode parameter should be additionally specified. This parameter indicates the Payment Page operation mode and should have the card_verify value.
  3. For specifying the properties of a COF purchase, the request should contain the recurring parameter as a JSON object—if the payment form is opened via the JavaScript library of ecommpay—or as a string generated as a result of URL encoding—if the payment form is opened via another method. The recurring parameter must contain the main details about COF purchase registration:
    • register, boolean—parameter which indicates whether the payment should be registered as recurring and which should be assigned the true value.
    • type, string—COF purchase type which should be assigned one of the following values:
      • C—one-click purchase
      • U—autopurchase
      • R—regular purchase
    • period, string—frequency of debits (for a regular purchase), this parameter should be assigned one of the following values:
      • D—daily
      • W—weekly
      • M—monthly (if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month)
      • Q—quarterly
      • Y—annually
    • time, string—time of performing subsequent debits (for a regular purchase) in hh:mm:ss format. The parameter is used if the period parameter is specified in the request.
    • interval, integer—interval of performing regular purchases. This parameter should be assigned a numeric value from 1 to 100 (for example, each three weeks) and is necessarily used in conjunction with the period parameter.
  4. For specifying the properties of a regular purchase, the recurring parameter can also contain other details:
    • amount, integer—fixed amount of subsequent debits in the smallest currency unit
    • expiry_day, integer or string—COF purchase expiry day
    • expiry_month, integer or string—COF purchase expiry month
    • expiry_year, integer—COF purchase expiry year
    • start_date, string—date on which the first debit is performed in the dd-mm-yyyy format (the parameter is necessarily used in conjunction with the scheduled_payment_id parameter)
    • scheduled_payment_id, string—identifier assigned to the payment within which scheduled debits are performed; it must differ from the identifier of the payment made to register a COF purchase and must be unique within the project; (also, not to be confused with the debiting series record identifier specified in the id parameter of the recurring object that is passed in the callback with the COF purchase registration information)
      Warning: If the identifier that should be assigned to the COF purchase (scheduled_payment_id) matches the identifier of the payment made to register a COF purchase (payment_id), the request to register a COF purchase is declined.
  5. To make sure that all required parameters are specified if the capability of collecting such customer data is not implemented (details), pass at least one of the following parameters in the request: customer_email or customer_phone.
  6. For displaying the payment form to the customer in a specified language, the language_code parameter should be used with the language code specified in the ISO 639-1 alpha-2 format. If this parameter is not specified, the payment form is displayed in the language selected automatically (by the browser language, by the region, or by default—learn more).
  7. For adding a payment description, the payment_description parameter can be used. The value of this parameter is a string displayed to the customer on the page with the information about the operation result and to the merchant in the Dashboard interface and sent to the merchant in the callback with information about the payment result.
  8. Additionally, it is possible to use any other parameters available for the Purchase and Card Verify modes of the Payment Page operation. The full list of parameters for opening Payment Page is provided in the Parameters for opening payment form section.

Thus, a request for COF purchases registration must include:

  • in terms of payment instrument verification—parameters for opening Payment Page for payment instrument verification and the recurring parameter with information about COF purchase registration.
  • in terms of purchase processing—parameters for opening Payment Page for processing a purchase and the recurring parameter with information about COF purchase registration.
Figure 1. Example of the COF purchase data included in the recurring parameter
{
    "register": true,     //COF purchase registration
    "type": "R",          //regular purchase registrartion
    "amount": 400,
    "expiry_day": 1,
    "expiry_month": 8,
    "expiry_year": 2025,  //last payment is scheduled for August 1, 2025
    "interval": 10,
    "period": "D",        //debiting every 10 days
    "time": "10:00:00",   //debiting at 10:00:00
    "start_date": "14-05-2019",
    "scheduled_payment_id": "A2323"
}
Figure 2. Example of the recurring parameter with data encoded into a URL string
"recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22
                 expiry_day%22%3A1%2C%22expiry_month%22%3A8%2C%22expiry_year%
                 22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%
                 22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%
                 22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D"
Figure 3. Example of calling the EPayWidget object
EPayWidget.run(
    { payment_id: '567890',
      payment_amount: '400',
      customer_id: 'customer1',
      customer_phone: '44991234567',
      payment_currency: 'USD',
      project_id: 42,
      force_payment_method: 'card',
      recurring: '{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}',
      signature: 'qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...' },
    'post')
Figure 4. Example of a URL for redirecting the customer to Payment Page
https://paymentpage.ecommpay.com/payment?signature=qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...&payment_id=567890&payment_amount=400&payment_currency=USD&project_id=42&customer_id=customer_1&customer_phone=44991234567&force_payment_method=card&recurring=%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry_day%22%3A1%2C%22expiry_month%22%3A8%2C%22expiry_year%22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D

Callback formats

The format of the callback to notify the merchant about the result of purchase processing or payment instrument verification with COF purchase registration is the same as the format described in the Callbacks section.

The following is an example of a callback with information about successful registration of COF purchase using the card 431422******0056 ; COF purchase is registered for the customer customer_10 in terms of the project 42.

Figure 5. Example of a callback which contains information about COF purchase registration
{  
  "project_id": 42,
  "payment":{  
    "id": "567890",
    "type": "purchase",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "method": "card",
    "sum":{  
      "amount": 400,
      "currency": "USD"
    },
    "description": ""
  },
  "account":{  
    "number": "431422******0056",
    "token": "d927d3f006008edf5c07661",
    "type": "visa",
    "card_holder": "JUDY DOE",
    "expiry_month": "08",
    "expiry_year": "2025"
  },
  "customer":{  
    "id": "customer_1"
  },
  "recurring":{  
    "id": 1001648059,    // ID of the record about a range of withdrawals
    "currency": "USD",
    "valid_thru": "2019-05-20T00:00:00+0000"
  },
  "scheme_id":"MCS38A0790706",
  "operation":{
    "id": 22136002040,
    "type": "sale",
    "status": "success",
    "date": "2019-05-14T12:52:45+0000",
    "created_date": "2019-05-14T12:52:42+0000",
    "request_id": "8c77279053d011-1160421d51e11f87d2c",
    "sum_initial":{  
      "amount": 400,
      "currency": "USD"
    },
    "sum_converted":{  
      "amount": 400,
      "currency": "USD"
    },
    "provider":{  
      "id": 414,
      "payment_id": "00200011764",
      "date": "2019-05-14T12:52:55+0000",
      "auth_code": "231567",
      "endpoint_id": 414
    },
    "code": "0",
    "message": "Success",
    "eci": "07"
  },
  "signature": "v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm..."
}