On-demand COF purchase

Overview

On-demand COF purchase is a payment type which uses a single initial request to make one (recurring) transfer of funds from customer to merchant by using previously stored payment credentials without validation of the payment instrument (such as card validation code).

On-demand COF purchases can be processed if one of the following conditions is met:

• These purchases were initially registered in the payment platform (details).
• Information about these purchases was migrated from an external acquirer (details).
• Information about these purchases was not migrated to the platform, but you have coordinated their processing with your ecommpay account manager, and it has been set up for the project.

In the ecommpay payment platform, on-demand COF purchases are processed according to the payment model (details) and the workflow described in this article. Note that conditions pertinent to registration as well as steps of the registration flow do not apply to COF purchases registered anywhere else but the ecommpay platform. In addition, the following applies to COF purchases that were registered elsewhere and the information of which was not migrated to the platform:

• If the capability to perform such purchases is set up for the project, then other kinds of COF purchases (registered in the platform or migrated to it) cannot be processed within this project.
• If payments are made with cards issued in the EEA, the merchant is responsible for registering COF purchases in compliance with the Strong Customer Authentication (SCA) requirement of the revised Directive on payment services (PSD2).

The payment workflow

To create a COF purchase:

1. Register a COF purchase. For more information, see Registering COF purchase.
2. Submit a request for a COF purchase with identifier of debiting series record.
3. Accept a callback with debiting result from the payment platform.

For each subsequent debiting, you need to resubmit request for COF purchase and accept the callback with the debiting result.

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 on-demand debiting using payment cards. There are several things you must consider when submitting such requests:

1. The request must be sent with the use of the POST method to one of the following endpoints:
   • /v2/payment/card/recurring—for all types of COF purchases that were initially registered in the ecommpay platform or that were migrated to the platform, regardless of where the payment details are stored (in the payment platform or the merchant's web service).
   • /v2/payment/card/sale—for COF purchases with the payment details stored in the merchant's web service, regardless of where the COF purchase was initially registered.
   • /v2/payment/card/auth—only for autopurchases and regular COF purchases with the payment details stored in the merchant's web service, regardless of where the COF purchase was initially registered.
   • /v2/payment/card/account_verification/token—only for autopurchases that were initially registered in the ecommpay platform or that were migrated to the platform, with the payment details stored in the merchant's web service.
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 address relevant for the initiated payment
     • 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.
   • payment—object with payment information:
     • amount—payment amount in minor currency units
     • currency—payment currency according to ISO-4217 alpha-3
     • cryptocurrency_type—the indicator that specifies the type of the cryptocurrency, required for Mastercard and 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
3. Depending on the endpoint, you must add the following objects and parameters in the request:
   • The request to the /v2/payment/card/recurring endpoint must contain the id parameter in the recurring object, and the value of this parameter must be the identifier of the debit series record received in the callback with registration information.
   • The requests to the /v2/payment/card/sale endpoint must contain the card object with the following parameters:
     • pan—card number
     • year—card expiration year
     • month—card expiration month
     • card_holder—name of the cardholder, passed if this parameter is required for the specific project (the name must be spelled as specified on the card; note that if you want to make this parameter optional instead of required, it can only be done upon consultation with your account manager which includes examination and assessment of associated risks)
     • stored_card_type—purchase type (4 for autopurchase or 6 for regular purchase)
     • scheme_id—identifier of the initial operation of the COF purchase registration. This identifier is assigned by the global card network (Mastercard or Visa), is required when a COF purchase is registered in the European Economic Area, and can be specified in other cases.
   • The requests to the /v2/payment/card/account_verification/token endpoint must contain the stored_card_type parameter of the card object, and this parameter must have the value 4 (autopurchase).
4. 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 either of the following: ID of debit series record or payment card credentials and COF purchase type.

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":"v7KNMp5D/aZAeb0VMdeR+CqGSm...=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{  
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079    // ID of debit series record
  }
}

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "card": {
    "pan": "4314220000000056",
    "year": 2025,
    "month": 8,
    "card_holder": "JOHN SMITH",
    "stored_card_type": 4    // Automatic debiting
  }
}

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "token":"pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7",
  "card":{
    "stored_card_type": 4    // Automatic debiting
  }
}

Callback format

Results of processing COF purchases are communicated in callbacks with information about each performed debiting sent from the payment platform to the web service. The format of these callbacks conforms to the standard one described in this article. In addition, callbacks can be configured to include the scheme_id parameter that will contain the identifier of the operation that registered a COF purchase on the side of the global card network. To have it set up, you need to contact the ecommpay technical support.

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.

{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "method":"card",
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "recurring":{  
    "id":1079,
    "currency":"USD",
    "valid_thru":"2022-10-31T00:00:00+0000"
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "created_date":"2019-09-04T12:57:53+0000",
    "request_id":"0b9f9e57a50-61da119c",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":414,
      "payment_id":"0020000000072964",
      "date":"2019-09-04T12:58:03+0000",
      "auth_code":"634R",
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success"
  },
  "scheme_id": "MCS38A0790706",
  "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...=="
}