Managing debiting series of a COF purchase

The payment platform allows you to manage debiting for any COF purchase types by doing the following:

  • getting information about debiting series
  • updating COF purchase parameters: change debit amount and expiration date for all COF purchase types and modify debit schedule for regular COF purchases
  • cancelling COF purchase at any time

Note that customer can at any time contact the issuer and have COF purchase cancelled. In this case, any following debiting operation is cancelled and the stored payment instrument credentials are deleted from the payment platform.

In addition, you can manage settings of regular COF purchases by using Dashboard.

Getting information about debiting series

There are several things you must consider when sending a request for information about debit series:

  1. You need to use a POST request to one of the /v2/payment/card/recurring/info 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
      • signature—signature created after you specify all the required parameters (For more information about signing requests, see Signature generation and verification.)
    • ID of the debit series inside the id parameter of the recurring object previously received in the callback with COF purchase registration information

Thus, complete request must contain project ID, signature, and ID of debit series.

Figure 1. Sample contents of request for information about debit series
{  
  "general":{  
    "project_id":42,
    "signature":"v7KNMpfogMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}

The payment platform uses the standard format for response with debit series information. For more information about response format, see Response format.

The following response contains information about debiting 4,00 USD to card 431422******0056 of the customer with ID customer_12 within the 42 project. The response also notifies that subsequent debiting is possible.

Figure 2. Sample information about debit series in a response
{  
  "project_id":42,
  "recurring":{ 
    "id":1079,    // Debit series ID
    "type": "R",
    "period": "W",
    "period_interval": 3,
    "start_date": "2020-10-20",
    "start_time": "10:00:00",
    "amount": 100,
    "last_payment_at": "0000-00-00 00:00:00",
    "valid_thru": "2025-05-25 00:00:00",
    "status": "active",
    "currency": "USD"
  }
}

Updating debit series

There are several things you must consider when sending a request for updating debit series:

  1. You need to use a POST request to one of the /v2/payment/card/recurring/update 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.)
    • recurring—object with the COF payment information:
      • id—ID of debit series received in the callback with COF purchase registration data
  3. You need also use other parameters of the recurring object:
    • expiry_year—expiration year of the COF purchase
    • expiry_month—expiration month of the COF purchase
    • expiry_day—expiration day of the COF purchase
    • interval—multiplicator to increase debiting period, for example if you need to run debiting every third week, you can set period to W and interval to 3. Possible values: from 1 to 100
    • amount—amount to debit after registration
    • 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
    • period—debiting period:
      • D—daily
      • W—weekly
      • M—monthly
      • Q—quarterly
      • Y—yearly
    • time—time of subsequent debiting in the hh:mm:ss format
    • start_date—date to perform the first debit

Thus, complete request must contain project ID, payment ID, signature, ID of debit series, and debit series parameters to update.

Figure 3. Sample contents of request for updating debit series
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "recurring":{  
    "id":1079,
    "interval":3,
    "period":"M",
    "time":"12:00:00"
  }
}

The payment platform uses the standard format for callbacks with information about updating debit series. For more information about callback format, see Callbacks.

The following callback affirms that COF purchase is set to perform debiting every third month at 12:00:00.

Figure 4. Sample callback with information about COF purchase update
{  
  "project_id":123,
  "recurring":{
    "id":1079,               // ID of debit series record
    "currency":"USD",
    "status":"active",       // Debit series status
    "type":"R",
    "expiry_month":"5",      // Month when COF purchase expires
    "expiry_year":"2025",    // Year when COF purchase expires
    "period":"M",            // Debiting period
    "period_interval":3,
    "time":"12:00:00"        // Time to perform debiting
  },
  "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...=="
}

Cancel COF purchase

There are several things you must consider when sending a request to cancel COF purchase:

  1. You need to use a POST request to one of the /v2/payment/card/recurring/cancel 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.)
    • ID of the debit series inside the id parameter of the recurring object previously received in the callback with COF purchase registration information

Thus, complete request must contain project ID, payment ID, signature, and ID of debit series.

Figure 5. Sample contents of request for cancelling debit series
{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"VftZ1ZZ5D/aMdeR+CqilUwSm...=="
  },
  "recurring":{  
    "id":1079
  }
}

The payment platform uses the standard format for callbacks with information about cancelling COF purchase. For more information about callback format, see Callbacks.

The following callback update that the COF purchase with ID 1079 has been cancelled.

Figure 6. Sample callback with information about cancelling COF purchase
{  
  "project_id":42,
  "recurring":{  
    "id":1079,           // Debit series ID
    "currency":"USD",
    "status":"canceled", // Status indicates COF purchase is cancelled
    "type":"R",
    "expiry_month":"5",
    "expiry_year":"2025",
    "period":"M",
    "period_interval":3,
    "time":"12:00:00"
  },
  "signature":"MpfogAxwRItZ1Z/AeMde+GrNYyUwSm...=="
}