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).
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: 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 then on, customer can initiate subsequent debiting that follow steps 1—12.
Figure: 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 now on, 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.
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:
- You need to use a POST request to one of the following endpoints: /v2/payment/card/recurring or /v2/payment/card/sale. You use the latter, if the payment credentials are stored in the web service and you use autopurchase or regular purchase.
- Your request must contain the following parameters and objects:
general
—object with general request identification information:project_id
—project ID obtained from ECommPaypayment_id
—payment ID, must be unique within the projectsignature
—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
—IP addressid
—the ID of the customer within the merchant project
payment
—object with payment information:amount
—payment amount in minor currency unitscurrency
—payment currency according to ISO-4217 alpha-3
- Depending on the endpoint, you must add the following objects and parameters in the request:
- The
id
parameter of therecurring
object inside the request to the /v2/payment/card/recurring endpoint must contain ID of debit series record previously 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 numberyear
—card expiration yearmonth
—card expiration monthcard_holder
—card holder name (as specified on the card)stored_card_type
—purchase type (4
for autopurchase or6
for regular purchase).
- The
- 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: 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: 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": "4242424242424243", "year": 2025, "month": 8, "card_holder": "JOHN SMITH", "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 Callbacks.
The following callback contains information about debiting 4,00 USD
to card 424242******4243
of the customer with ID customer_12
within the 42
project.
Figure: 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":"424242******4243", "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...==" }