Registering COF purchase

Overview

To register a COF purchase with the payment platform, you need to save customer payment instrument credentials. You can do it in a variety of ways by processing payments via Gate, Payment Page (details), and Dashboard (details) as well as by migrating information about COF purchases from an external acquirer (details).

You can register a COF purchase via Gate by sending a request for one-time purchase, payment link purchase, or for payment instrument verification with parameters indicating that the payment instrument credentials need to be saved.

COF purchase is registered for the time specified in the underlying request; if this time is not specified in the request, COF purchase registration term is set to the card expiration date. Once COF purchase registration expires, the payment platform sends a callback with this information to merchant's web service. Any further purchases by using this registration are no longer possible; if web service attempts to initiate the COF purchase, the payment platform will respond with a callback with the 3184 (or 3301) error code.

Note: According to Visa and Mastercard recommendations issued in 2020, they temporary allow COF purchases with expired bank cards, provided the payment provider or the payment system support this option. In this case, purchases are possible both before and after card expiration date, if the COF registration date is set to the card expiration date. To prevent using expired bank cards for COF purchases, when registering COF purchase, set its expiry date to the date which is different from the card expiry date (see Updating debit series for more information).

COF purchase registration may be blocked for specific merchant projects or providers in which case the requests with registration demand may be declined. To prevent declining of such requests, you can contact support service at support@ecommpay.com and ask them to configure your project to ignore registration demands when processing COF purchases, if COF purchase registration is blocked.

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.

Registration procedure

To register a COF purchase, you need to send a request to initiate one of the following operations: sale, auth, account verification, or invoice and to populate the request with all the parameters required to process the operation and the parameters required to register the COF purchase.

The payment platform initiates and performs the requested operation including any auxiliary procedures which may be required. If credentials are stored on the payment platform, after the operation is successfully completed and is assigned the success status, a record about debiting series is created on the payment platform. The record is assigned the following attributes:

  • ID Once the record about debiting series is created, web service receives its ID in the callback inside the id parameter of the recurring object. You use this ID to perform and to manage COF purchases.
  • Status Any active debiting series record is assigned the active status. The status may change to canceled on merchant or customer demand and in some other cases.

If credentials are stored in the web service, a record about debiting series is not created.

The payment platform sends your web service a callback with operation result that contains ID of the debiting series record, if this record has been created. Such callback confirms that COF purchase is successfully registered.

Registration when credentials are stored by web service

There are several things you must consider when performing a COF purchase with customer instrument credentials stored by web service:

  1. You need to use a POST request to one of the following endpoints:
  2. Your request must contain all the required parameters and objects.
  3. Also, your request must include the stored_card_type parameter and specify COF purchase type by using one of the following values:

Thus, along all the required parameters, complete request must contain registration flags for selected COF purchase.

Figure 1. Example of request body with demand to register new COF purchase
{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNeR+CqGrNxYyilUwSm...=="
  },
  "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123",
      "stored_card_type": 3    // Registering autopurchase
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  },
  "payment": {
      "amount": 400,
      "currency": "USD"
  }
}

The payment platform includes the COF purchase registration information in its operation result callback to your web service. The payment platform uses the standard format for callbacks. For more information, see Callbacks.

Figure 2. Callback sample
{  
  "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_12"
  },
  "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":"8c53d11-1160d2c",
    "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":"v7KN5D/aZAdeR+CqGrNxYyilUwSm...=="
}

Registration when credentials are stored by the payment platform

There are several things you must consider when performing a COF purchase with customer instrument credentials stored by the payment platform:

  1. You need to use a POST request to one of the following endpoints:
  2. Your request must contain all the required parameters and objects.
  3. Also, your request must include a recurring object with the parameters of the COF purchase to register:
    • register—COF purchase registration flag; use true value to have the COF purchase registered.
    • type—type of the COF purchase to register, possible values:
      • C—one-click purchase
      • U—autopurchase
      • R—regular purchase
    • time—time of subsequent debiting for regular purchase in hh:mm:ss format
    • period—debiting period for regular purchase:
      • D—daily
      • W—weekly
      • M—monthly
      • Q—quarterly
      • Y—yearly
  4. You can also use other parameters of the recurring object:
    • expiry_year—expiration year of the COF purchase
    • expiry_month—expiration month of the COF purchase
    • expiry_day—expiration day of the COF purchase
    • interval—multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set period to W and interval to 3. Possible values: from 1 to 100
    • amount—amount to debit
    • start_date—date to perform the first debit
    • scheduled_payment_id—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.

Thus, along all the required parameters, complete request must contain registration flags for selected COF purchase and its type; for regular purchases, request must also contain debiting schedule.

Depending on the specific characteristics of providers involved in payment processing, the set of required parameters can vary. For the detailed information about the providers' requirements, contact the ecommpay key account manager.

Figure 3. Example of request body with COF purchase registration demand
{
  "general": {
      "project_id": 42,
      "payment_id": "567890",
      "signature": "v7KN1ZZ5D/aZAeR+CqGrwSm...=="
  },
  "card": {
      "pan": "4314220000000056",
      "year": 2025,
      "month": 8,
      "card_holder": "JUDY DOE",
      "cvv": "123"
  },
  "customer": {
      "id": "customer_12",
      "ip_address": "202.144.196.0"
  }
  "payment": {
      "amount": 400000,
      "currency": "USD"
  },
  "recurring": {
      "type": "R",
// Regular purchase
      "period": "W",
      "interval": 3,
// Debiting every third week
      "expiry_year": 2025,
      "expiry_month": 5,
      "expiry_day": 5,
// Last debiting scheduled for May 5, 2025
      "time": "10:00:00",
// Debit at 10:00:00
      "register": true,
// COF purchase registration
      "scheduled_payment_id": "567891",
      "start_date": "10-10-2020"
  }
}

The payment platform includes the COF purchase registration information in its operation result callback to your web service. The payment platform uses the standard format for callbacks. For more information, see Callbacks.

The following callback contains information about successful registration of a COF purchase with a debiting series record identifier 1001648059.

Figure 4. Callback sample with 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_12"
  },
  "recurring":{  
    "id":1001648059,    // ID of debiting series record
    "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...=="
}