On-demand COF purchase | ECOMMPAY Documentation

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

The payment platform performs on-demand COF purchase according to the payment model (On-demand COF purchase).

The payment workflow

To create COF purchase:

Register COF purchase. For more information, see Registering COF purchase.
Submit a request for COF purchase with ID of debiting series record.
Accept 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.

Figure 1. Processing one-click purchase

Customer initiates debiting in the web service.
The web service sends a request for debiting to the ecommpay URL.
The payment platform receives the request.
The payment platform processes the request.
The payment platform sends to the web service the information about receiving the request and the correctness of the request.
The payment platform sends request to perform payment to the payment system.
The payment system processes the request and sends it to the issuer.
The issuer processes the request and debits customer account or card.
The issuer sends notification with payment results to the payment system.
The payment system sends the notification with payment results to the payment platform.
The payment platform sends callback with debiting results to the web service.
The web service sends debiting result to customer.
From this point forward, customer can initiate subsequent debiting that follow steps 1—12.

Figure 2. Processing autopurchase

The web service sends a request for debiting to the ecommpay URL.
The request enters the payment platform.
The payment platform processes the request.
The payment platform sends to the web service the request acknowledgement and request correctness information.
The payment platform sends the request to perform purchase to the payment system.
The payment system processes the request and forwards it to the issuer.
The issuer processes the request and debits customer account or card.
The issuer sends notification with payment results to the payment system.
The payment system sends the notification with payment results to the payment platform.
The payment platform sends callback with debiting results to the web service.
The web service sends debiting result to customer.
From this point forward, customer can initiate subsequent debiting each following steps 1 through 12.

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:

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 regardless of where the payment data is stored (on the payment platform side or on the web service side)
- /v2/payment/card/sale—only for autopurchases and regular purchases with the payment data stored on the web service side
- /v2/payment/card/account_verification/token—only for autopurchases with the payment data stored on the web service side.
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 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.
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—card holder name (as specified on the card)
  - stored_card_type—purchase type (4 for autopurchase or 6 for regular purchase).
- 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).
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.

Figure 3. Example of a request to the /v2/payment/card/recurring endpoint

{  
  "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
  }
}

Figure 4. Example of a request to the /v2/payment/card/sale endpoint

{  
  "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
  }
}

Figure 5. Example of a request to the /v2/payment/card/account_verification/token endpoint

{  
  "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

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

Figure 6. Example of a callback with payment results

{  
  "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"
  },
  "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...=="
}