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). During the validity period of a COF purchase, subsequent debits may be processed through the same acquirer (or provider) or through different ones. When different acquirers or providers are involved, it is important to use specialised identifiers for the registration operation and the debiting series. These identifiers are assigned by the card networks and used for end-to-end tracking of activities related to COF purchases (see below for details). Once the COF purchase registered through the Ecommpay platform 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 that restrictions on registering COF purchases may apply in certain cases. Such restrictions can be related to the business category, project specifics, or other factors and may result in payments being declined by Ecommpay and providers involved in processing these payments. For information about restrictions refer to your account manager. In addition, the processing of requests can also be configured so that, where restrictions on registering COF purchases apply, the relevant parameters are ignored (i.e. the payments are processed with these parameters omitted).

Moreover, sometimes COF purchases that have already been registered may need to be registered again due to changes in the rules applied by card networks and payment providers. In such cases, information about all COF purchases registered in the Ecommpay platform that require re-registration to enable further processing is sent to the merchant’s specialists, usually by email (the email is sent to a previously agreed upon email address and contains a list of the relevant identifiers of COF purchases). Upon receiving this information, the merchant should notify each customer that the existing debiting series will be discontinued and that a new COF purchase needs to be initiated. Once the customer's consent has been obtained, the merchant should register a new COF purchase and process subsequent debiting within it, using new identifiers and other relevant parameters.

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.

Also note that the Ecommpay technical support can assist you with configuring callbacks sent when COF purchases are registered, so that these callbacks include specialised identifiers of the registration operations and debiting series assigned by the global card networks. These identifiers are passed in the scheme_id and transaction_link_id parameters and are required when subsequent debits for COF purchases registered through Ecommpay are processed through other acquirers (and vice versa, when subsequent debits are processed through Ecommpay for COF purchases registered through other acquirers; details).

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:
   • /v2/payment/card/sale—when processing a one-time one-step purchase
   • /v2/payment/card/auth—when processing a one-time two-step purchase
   • /v2/payment/card/account_verification—when verifying the payment instrument
   • /v2/payment/card/account_verification/token when verifying the payment instrument with the use of a token
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:
   • 3—autopurchase
   • 5—regular purchase (except for requests to the endpoint /v2/payment/card/account_verification/token).

Thus, along all the required parameters, complete request must contain registration flags for selected 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"
  }
}

Information about registering a COF purchase is communicated in callbacks with operation results sent from the payment platform to the web service. The format of these callbacks conforms to the standard one described in this article. By agreement with the Ecommpay technical support, callbacks can also be configured to include specialised identifiers of registration operations and debiting series assigned by the global card networks, provided in the scheme_id and transaction_link_id parameters (details).

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