COF purchase registration

General information

Payment Page supports COF purchase registration. This section covers information about COF purchases registration by using Payment Page and extends the information in the Payment models and statuses section.

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 perform refund, the merchant needs to use Gate or Dashboard/Dashboard Light.

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 1 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 Payment 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 request must contain the following required parameters:
    • project_id—the project ID obtained from ECommPay.
    • payment_id—the payment ID unique within the project.
    • customer_id—the customer ID unique within the project.
    • payment_amount—payment amount in minor currency units. To register COF purchases in terms of payment instrument verification, you need to specify the 0 value.
    • payment_currency—payment currency code according to ISO-4217 alpha-3.
    • signature—the signature that is created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
  2. To register COF purchases along with payment instrument verification, you need to additionally specify in the request the mode parameter indicating the Payment Page operation mode. For this parameter the card_verify value must be specified.
  3. In order to register COF purchase, you need to specify in the request the recurring. The value of this parameter is obtained by converting the data into a single string by using the URL-encoded algorithm. The recurring parameter contains information about COF purchase registration:
    • register—parameter indicating whether the payment should be registered as recurring. For this parameter, the true value must be specified.
    • type—type of the COF purchase. Possible values:
      • C—OneClick purchase.
      • U—autopurchase.
      • R—regular purchase.
    • period—period of performing regular payments. Possible 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—time of performing regular purchases in hh:mm:ss format. The parameter is used if the period parameter is specified in the request.
    • interval—interval of performing regular purchases from 1 to 100, for example, each three weeks or each two days. The parameter is necessarily used in conjunction with period.
  4. To register regular purchase, you can also include the following data in the recurring parameter:
    • amount—the amount of the subsequent payments in minor currency units.
    • expiry_day—the day of the COF purchase expiry date.
    • expiry_month—the month of the COF purchase expiry date.
    • expiry_year—the year of the COF purchase expiry date.
    • scheduled_payment_id—the ID of the COF purchase (for automatic debiting). The parameter is necessarily used in conjunction with start_date.
    • start_date—the start date of regular payments performing in the dd-mm-yyyy format. The parameter is necessarily used in conjunction with scheduled_payment_id.
  5. To display Payment Page in a required language, you need to additionally specify in the request the language_code parameter and the language code in accordance with ISO 639-1 alpha-2 as its value. If this parameter is not specified in the request, Payment Page is displayed either in English (for all countries except for Russia) or in Russian (for Russia), according to IP address of the customer.
  6. To add description of the payment, you need to specify in the request the payment_description parameter. The value of this parameter is displayed to the customer on the page with information about the result and to the merchant in Dashboard (Dashboard Light) and in a callback with information about the payment result.
  7. If needed, you can also add any other additional parameters supported by Payment Page in the Purchase and Card Verify operation modes. The full list of parameters for opening Payment Page is provided in the Payment Page invocation parameters section.

Thus, a correct request for COF purchases registration must include:

  • in terms of payment instrument verification—Payment Page invocation parameters required for payment instrument verification and the recurring parameter containing information about COF purchase registration.
  • in terms of purchase processing—Payment Page invocation parameters required for purchase processing and the recurring parameter containing information about COF purchase registration.
{
   "project_id": "42",
   "payment_id": "567890",
   "payment_currency": "USD",
   "payment_amount": "400",
   "customer_id": "customer_1",
   "signature": "TSzdE5rJZaATYAKoGpfXriFf82MxF...",

   "recurring": "%7B%22register%22%3A%20true%2C%22type%22%3A%20%22R%22%2C%22amount%22%3A%20400%2C%22
                 expiry_day%22%3A%201%2C%22expiry_month%22%3A%208%2C%22expiry_year%22%3A%202025%2C%2
                 2interval%22%3A%2010%2C%22period%22%3A%20%22D%22%2C%22time%22%3A%20%2210%3A00%3A00%
                 22%2C%22start_date%22%3A%20%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%20%22A2
                 323%22%7D"

   // a string obtained by encoding the following data: 
      {
        "register": true,    //COF purchase registration
        "type": "R",    //regular purchase registrartion
        "amount": 400,
        "expiry_day": 1,
        "expiry_month": 8,
        "expiry_year": 2025,    //the last payment is scheduled for August 1, 2025
        "interval": 10,
        "period": "D",    //performing withdrawals every 10 days
        "time": "10:00:00",    //performing withdrawals at 10:00:00
        "start_date": "14-05-2019",
        "scheduled_payment_id": "A2323"
      }

}

Figure: Example of the request for opening 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&region_code=RU&language_code=ru&force_payment_method=card&recurring=%7B%22register%22%3A%20true%2C%22type%22%3A%20%22R%22%2C%22amount%22%3A%20400%2C%22expiry_day%22%3A%201%2C%22expiry_month%22%3A%208%2C%22expiry_year%22%3A%202025%2C%22interval%22%3A%2010%2C%22period%22%3A%20%22D%22%2C%22time%22%3A%20%2210%3A00%3A00%22%2C%22start_date%22%3A%20%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%20%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: 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":"424242******4243",
    "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"
  },
  "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..."
}