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:
    • period—frequency of debits (for a regular COF purchase), possible values:
      • D—daily
      • W—weekly
      • M—monthly (if the set day is not available in the next month, for example, 31, the payment is performed on the last day of the month)
      • Q—quarterly
      • Y—yearly
    • interval—multiplier to increase debiting frequency (i.e. the interval of performing regular COF purchases). This parameter is used in conjunction with the period parameter and should be assigned a numeric value from 1 to 100.
    • time—time of performing subsequent debits (for a regular purchase) in hh:mm:ss format. The parameter is used if the period parameter is specified in the request.
    • amount—fixed amount of subsequent debits in the smallest currency unit.
    • start_date—date on which the first debit operation is performed (for a COF regular purchase). This parameter is used in conjunction with the scheduled_payment_id parameter and should be specified in the DD-MM-YYYY format.
    • expiry_day—calendar day on which the specified duration period of the COF purchase will end (the value should be provided as an integer from 1 to 31, without a leading zero, in accordance with the Gregorian calendar).
    • expiry_month—month in which the specified duration period of the COF purchase will end (the value should be provided as an integer from 1 to 12, without a leading zero, in accordance with the Gregorian calendar).
    • expiry_year—year in which the specified duration period of the COF purchase will end (in the YYYY format, in accordance with the Gregorian calendar).
      Note: If any of the parameters defining the expiry date of the COF purchase is not provided in the request, the following default values apply:
      • For standard card payments—the corresponding parameter value (day, month, year) is determined based on the expiry date of the specified payment card.
      • For other available methods—the corresponding parameter value is determined as follows:
        • Calendar day—the last calendar day of the relevant month (as specified in the expiry_month parameter or corresponding to the COF purchase registration date).
        • Month—the month in which the COF purchase was registered.
        • Year—the year that is 10 years after the year in which the COF purchase was registered.

      Accordingly, if only the year is specified, for standard card payments the day and month are taken from the expiry date of the relevant card and combined with the specified year. For an alternative payment method, the expiry date is set to the last calendar day of the month in which the COF purchase was registered and the specified year.

    • 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.

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 Handling 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 Handling 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...=="
}