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.

Each COF purchase is registered for a defined period. If the merchant does not specify parameters defining this period, the platform applies default values corresponding either to the expiry date of the relevant payment card or to a period of 10 years from the month in which the COF purchase was registered (details). Once the period the COF purchase was registered for expires, the payment platform sends a callback with this information to merchant's web service. Any further debiting within this purchase is no longer possible; if web service attempts to initiate the debit operation, 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 Handling 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 registering 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—indicator that specifies whether a COF purchase should be registered.
    • type—type of the COF purchase to register, possible values:
      • C—one-click purchase
      • U—autopurchase
      • R—regular purchase
    • time—time of performing subsequent debits (for a regular COF purchase) in the hh:mm:ss format. The parameter is used if the period parameter is specified in the request.
    • period—frequency of debits (for a regular COF purchase), 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—yearly
  4. You can also use other parameters of the recurring object:
    • amount—fixed amount of subsequent debits (for a regular COF purchase) in the smallest currency unit.
    • interval—multiplier to increase debiting frequency (i.e. the interval of performing regular COF purchases). This parameter is used in conjunction with the period parameter and should be assigned a numeric value from 1 to 100. For example, if you need to charge the customer every third week, you can set period to W and interval to 3.
    • start_date—date on which the first debit operation is performed (for a COF regular purchase). This parameter is used in conjunction with the scheduled_payment_id parameter and should be specified in the DD-MM-YYYY format.
    • expiry_day—calendar day on which the specified duration period of the COF purchase will end (the value should be provided as an integer from 1 to 31, without a leading zero, in accordance with the Gregorian calendar).
    • expiry_month—month in which the specified duration period of the COF purchase will end (the value should be provided as an integer from 1 to 12, without a leading zero, in accordance with the Gregorian calendar).
    • expiry_year—year in which the specified duration period of the COF purchase will end (in the YYYY format, in accordance with the Gregorian calendar).
      Note: If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:
      • For standard card payments—the corresponding parameter value (day, month, year) is determined based on the expiry date of the specified payment card.
      • For other available methods—the corresponding parameter value is determined as follows:
        • Calendar day—the last calendar day of the relevant month (as specified in the expiry_month parameter or corresponding to the COF purchase registration date).
        • Month—the month in which the COF purchase was registered.
        • Year—the year that is 10 years after the year in which the COF purchase was registered.

      Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

    • 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 Handling 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...=="
}