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.

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.

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:
   • /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"
  }
}

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.

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