COF purchase with automatic debiting

Overview

COF purchase with automatic debiting is a payment type which uses a single initial request to make a series of fund transfers from customer to merchant by using stored payment credentials without validation of the payment instrument (such as card validation code).

The payment platform performs COF purchase with automatic debiting according to the payment model (see Scheduled COF purchase for details).

The payment workflow

To perform COF purchase with automatic debiting:

1. Register COF purchase. For more information, see Registering COF purchase.
2. Submit a request for COF payment with ID of debit series record. (You can omit this step, if your initial registration request contained the scheduled_payment_id parameter.)
3. Accept callback with debiting result from the payment platform.
4. Accept subsequent callbacks for each debit operation for this payment.

To update or cancel COF purchase or to refund one or more debit transactions, you need to submit the corresponding requests to the payment platform. (For more information, see Managing debiting series of COF purchase.)

The sections that follow discuss formats for requests and callbacks; for general information about using the API, see Interaction concepts. Information about possible statuses of this payment type can be found in the corresponding article.

Request format

This section describes format of the requests for COF purchases with automatic debiting using payment cards. There are several things you must consider when submitting such requests:

1. You need to use a POST request to the /v2/payment/card/recurring endpoint.
2. Your request must contain the following parameters and objects:
   • general—object with general request identification information:
     • project_id—project ID obtained from ecommpay
     • payment_id—payment ID, must be unique within the project
     • signature—signature created after you specify all the required parameters (For more information about signing requests, see Signature generation and verification.)
   • customer—object with customer information:
     • ip_address—customer IP
     • id—the ID of the customer within the merchant project
   • payment—object with payment information:
     • amount—payment amount in minor currency units
     • currency—payment currency according to ISO-4217 alpha-3
   • recurring—object with the COF payment information:
     • id—ID of debit series received in the callback with COF purchase registration data
3. Additionally, you can use any other parameters as indicated in the specification.

Thus, a complete request must contain project ID, payment ID, signature, customer IP, payment amount and currency, and ID of debit series record.

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.

{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"K5D/aZAMdeR+YyilUwS=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079
  }
}

Calback format

The payment platform includes the COF purchase registration information in its 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 debiting 4,00 USD to card 431422******0056 of the customer with ID customer_12 within the 42 project. The callback also notifies that subsequent debiting is possible.

{  
  "customer":{  
    "id":"customer_12"
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "payment":{  
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "method":"card",
    "date":"2019-06-07T06:18:02+0000",
    "status":"scheduled recurring processing",    // Payment status
    "type":"recurring",    // Payment type
    "id":"456789",
    "description":""
  },
  "project_id":42,
  "recurring":{  
    "valid_thru":"2019-07-31T00:00:00+0000",
    "currency":"USD",
    "id":1079    // ID of debit series record
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",    // Operation type
    "status":"success",    // Operation status
    "date":"2019-06-07T06:18:02+0000",
    "created_date":"2019-06-07T06:18:02+0000",
    "request_id":"5cfa0199c33071",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":6,
      "payment_id":"1192",
      "date":"2018-02-07T08:34:24+0000",
      "auth_code":"5253",
      "endpoint_id":6
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...=="
}