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.

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

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