COF purchase registration

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).

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)
   Warning: Starting August 12, 2024, Visa Rules will be updated to expand the set of parameters mandatory for processing Visa card payments with the 3‑D Secure authentication. Parameters that will be required in such cases are customer_email and customer_phone (details). These parameters can be included in the requests for opening Payment Page or collected from customers (details).
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 COF 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
   • scheduled_payment_id, string—identifier that should be assigned to the COF purchase for debits to be initiated automatically (this parameter is necessarily used in conjunction with the start_date parameter)
   • 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)
5. 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).
6. 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.
7. 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.

{
    "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"
}

"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"

EPayWidget.run(
    { payment_id: '567890',
      payment_amount: '400',
      customer_id: 'customer1',
      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')

https://paymentpage.ecommpay.com/payment?signature=qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...&payment_id=567890&payment_amount=400&payment_currency=USD&project_id=42&customer_id=customer_1&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.

{  
  "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..."
}