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:

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

  1. Customer initiates debiting in the web service.
  2. The web service sends a request for debiting to the ECommPay URL.
  3. The payment platform receives the request.
  4. The payment platform processes the request.
  5. The payment platform sends to the web service the information about receiving the request and the correctness of the request.
  6. The payment platform sends request to perform payment to the payment system.
  7. The payment system processes the request and sends it to the issuer.
  8. The issuer processes the request and debits customer account or card.
  9. The issuer sends notification with payment results to the payment system.
  10. The payment system sends the notification with payment results to the payment platform.
  11. The payment platform sends callback with debiting results to the web service.
  12. The web service sends debiting result to customer.
  13. From then on, customer can initiate subsequent debiting that follow steps 1—12.

Figure: Processing autopurchase

  1. The web service sends a request for debiting to the ECommPay URL.
  2. The request enters the payment platform.
  3. The payment platform processes the request.
  4. The payment platform sends to the web service the request acknowledgement and request correctness information.
  5. The payment platform sends the request to perform purchase to the payment system.
  6. The payment system processes the request and forwards it to the issuer.
  7. The issuer processes the request and debits customer account or card.
  8. The issuer sends notification with payment results to the payment system.
  9. The payment system sends the notification with payment results to the payment platform.
  10. The payment platform sends callback with debiting results to the web service.
  11. The web service sends debiting result to customer.
  12. 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:

  1. 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.
  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
    • payment—object with payment information:
      • amount—payment amount in minor currency units
      • currency—payment currency according to ISO-4217 alpha-3
  3. Depending on the endpoint, you must add the following objects and parameters in the request:
    • The id parameter of the recurring 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 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).
  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.

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