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 regularly recurring funds transfers (debits) from the customer to the merchant by using stored payment credentials without verification of the payment instrument (i.e. by entering a card verification code). The ecommpay payment platform performs COF purchases with automatic debiting according to the payment model (learn more). If one attempt to perform a scheduled debiting is not enough (for example, if the customer's card account has insufficient balance), the debiting can be retried in the payment platform automatically (details).

Workflow

COF purchase with initiation of the first debit operation during registration

If the scheduled_payment_id parameter has been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

  1. Register a COF purchase. For more information, see Registering COF purchase.
  2. Accept a callback with the debiting result from the payment platform.
  3. Accept subsequent callbacks for each debit operation for this payment.

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

Figure 1. Processing a COF purchase with initiation of the first debit operation during registration
  1. According to the schedule, at the set time the payment platform sends the request for performing a recurrent debit operation to the payment system.
  2. The payment system processes the request and forwards it to the issuer.
  3. The issuer processes the debit operation and transfers the funds from the customer to the merchant.
  4. The issuer sends a notification with the debiting result information to the payment system.
  5. The payment system sends the notification with the debiting result information to the payment platform.
  6. The payment platform sends a callback with the debiting result to the web service.
  7. The customer receives the debiting result information from the web service.
  8. From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 1 through 7.

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.

COF purchase with a separate initiation of the first debit operation

If the scheduled_payment_id parameter has not been passed during the COF purchase registration, these are the steps to perform a COF purchase with automatic debiting:

  1. Register a COF purchase. For more information, see Registering COF purchase.
  2. Submit a request for performing a COF payment with an identifier of the debit series record.
  3. Accept a callback with the debiting result from the payment platform.
  4. Accept subsequent callbacks for each debit operation for this payment.
Figure 2. Processing a COF purchase with a separate initiation of the first debit operation
  1. The web service sends a request for debiting to the ecommpay URL.
  2. The request enters the payment platform.
  3. The payment platform accepts and processes the request.
  4. The payment platform sends the request acknowledgement and request correctness information to the web service.
  5. The payment platform sends the request for performing a debit operation to the payment system.
  6. The payment system processes the request and forwards it to the issuer.
  7. The issuer processes the debit operation and transfers the funds from the customer to the merchant.
  8. The issuer sends a notification with the debiting result information to the payment system.
  9. The payment system sends the notification with the debiting result information to the payment platform.
  10. The payment platform sends a callback with the debiting result to the web service.
  11. The customer receives the debiting result information from the web service.
  12. From this point forward, the payment platform initiates subsequent scheduled debit operations, with each following steps 5 through 11.

Request format

There are several things you need to consider when sending a request for a COF purchase with automatic debiting using a payment card:

  1. To initiate each purchase, send a separate POST request to the /v2/payment/card/recurring endpoint.
  2. Each request must include the following objects and parameters:
    • general—object with general request identification information:
      • project_id—project identifier obtained from ecommpay during integration.
      • payment_id—payment identifier, unique within the project.
      • signature—request signature generated after all required parameters are specified (details—in Signature generation and verification). (details)
    • customer—object with customer information:
      • id—customer identifier, unique within the project, the same identifier as the one used to register this COF purchase.
        Warning: Using different customer identifiers for operations performed as part of the COF purchase is not allowed.
      • ip_address—customer IP address relevant for the initiated payment.
    • payment—object with payment information:
      • amount—payment amount in the smallest currency unit.
      • currency—payment currency code in the ISO-4217 alpha-3 format.
      • cryptocurrency_type—the indicator that specifies the type of the cryptocurrency, required for Visa payments involving cryptocurrencies. This parameter should be assigned one of the following values:
        • cbdc—a central bank digital currency or tokenized deposit issued by a central bank, reserve bank, or other national monetary authority;
        • stablecoins_fiat_backed—a fiat-backed digital asset with reserves held by a licensed financial institution;
        • native_tokens—a digital currency native to a specific blockchain, required for transactions within its network, including fee payments;
        • other—a non-fiat digital asset that does not fit other types or cannot be classified at the time of transaction initiation.
    • recurring—object with the COF payment information:
      • id—identifier of the debit series received in the callback with the COF purchase registration data or assigned when the COF purchase information was migrated from another acquirer.
  3. The set of parameters required for executing a payment can vary depending on the regional characteristics and other aspects of the payment services providers. Refer to your ecommpay account manager to learn more about the providers' specifics and requirements.
  4. Additionally, any other parameters included in the specification can be used.

Thus, a correct request must contain the project identifier, basic payment information (identifier, amount, and currency code), customer IP address, signature, and the identifier of the debiting series record.

Figure 3. Example of data passed in the request to initiate a COF payment
{  
  "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
  }
}

Callback format

The payment platform communicates results of processing each debit operation in callbacks sent to your web service. These callbacks are arranged in a standard format the detailed description of which can be found in Handling callbacks.

The following callback contains information about processing 4.00 USD debit operation for card 431422******0056 of the customer with identifier customer_12 within project 42. The capability of debiting retries is not available.

Figure 4. Example of data passed in a callback with debiting results (retries capability is not set up)
{  
  "customer":{  
    "id":"customer_12"
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JOHN SMITH",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2026"
  },
  "payment":{  
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "method":"card",
    "date":"2023-06-07T06:18:02+0000",
    "status":"scheduled recurring processing",    // Payment status
    "type":"recurring",    // Payment type
    "id":"456789",
    "description":""
  },
  "project_id":42,
  "recurring":{  
    "valid_thru":"2023-07-31T00:00:00+0000",
    "currency":"USD",
    "id":1079    // Identifier of the debit series
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",    // Operation type
    "status":"success",    // Operation status
    "date":"2023-06-07T06:18:02+0000",
    "created_date":"2023-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":"2023-02-07T08:34:24+0000",
      "auth_code":"5253",
      "endpoint_id":6
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...=="
}

If the capability to perform debiting retry attempts is enabled, callbacks include the recurring_retry object. The description of its format can be found in this article.