Sending order parameters

You will process an order by sending order parameters to CertoConnect server. This must be a HTTP POST request to "https://www.certoconnect.com/payment" with order parameters in the body of the request.

As soon as the params are submitted, CertoConnect checkout page will appear. Optionally it can also be shown in iframe.

CertoConnect accepts the following parameters:

  • order[user_id] - unique ID of your account with CertoConnect
  • order[number] - ID of your shopping cart, identifying a particular purchase in your shop
  • order[email] - e-mail of the customer (optional)
  • order[total_amount] - total amount to be paid for the order, in lowest monetary units (e.g. send "1000" (1000 cents) to request a payment of $10 for payments in US dollars) (required parameter)
  • order[shipping_amount] - shipping fee amount, in lowest monetary units (e.g. send "1000" (1000 cents) to request a payment of $10 for payments in US dollars) (optional parameter)
  • order[currency] - currency of the payment (3-letter code, e.g. "USD" for US dollars) (required parameter)
  • order[success_url] - if provided we will redirect customer to this URL when the order has been successfully processed
  • order[fail_url] - if provided we will redirect customer to this URL when the order has been declined or cancelled
  • order[notification_url] - if provided, we will send notifications to this URL when the order has been processed
  • order[signature] - is used to check integrity of important order parameters (see below)

In addition to the basic information, you should specify one or more line items included in the order. Each line item is represented by the following parameters:

  • order[line_items_attributes][][name] - name of the line item
  • order[line_items_attributes][][amount] - sum paid for the line item
  • order[line_items_attributes][][quantity] - quantity of the products presented in the line item

Note: CertoConnect validates if total_amount equals to sum of line items amount x line items quantity plus shipping fee amount (if it was sent).

You also can add any number of your own parameters in the section 'tracking_params' to track orders. Here is an example:

  • order[tracking_params][oscommerce_id]
  • order[tracking_params][lottery_winner]

These parameters will posted back to you in both cases: with the server to server notification to notification_url and when user will be redirected to success_url of fail_url you passed to us with other order parameters.

Signing

To prevent hijacking of the important order parameters when they are being passed to the gateway you must provide an additional parameter named signature.

The signature is built by concatenating your Secret and a combination of "key=value" pairs sorted alphabetically by key. The keys are: currency, number and total_amount. The resulting string should be encoded using SHA1 cryptographic hash function.

For example, for the following parameters:

  • order[currency] - "USD"
  • order[number] - "777"
  • order[total_amount] - "1000"
  • secret - "YOUR_SECURE_WORD"

you should build a string:

YOUR_SECURE_WORDcurrency=USDnumber=777total_amount=1000

and encode it with SHA1. The signature will be:

37d993576dbc5b9e5cb61fa4234b923c66e0c4ad

Example

When sent via a form from a web page, the order parameters are represented in HTML as follows:

<form action="https://www.certoconnect.com/payment" method="POST">
  <input name="order[user_id]" type="text" value="2">
  <input name="order[number]" type="text" value="777">
  <input name="order[total_amount]" class="amount" type="text" value="1000">
  <input name="order[currency]" class="currency" type="text" value="USD">
  <input name="order[line_items_attributes][][name]" class="name" type="text" value="Handbag">
  <input name="order[line_items_attributes][][amount]" class="amount" type="text" value="1000">
  <input name="order[line_items_attributes][][quantity]" type="text" value="1">
  <input name="order[line_items_attributes][][product_id]" class="number" type="text">
  <input name="order[tracking_params][oscommerce_id]" class="number" type="text" value="123">
  <input name="order[tracking_params][lottery_winner]" class="number" type="text" value="true">
  <input name="order[signature]" type="hidden" value="a80354c4896112d9bca427d54d84a356dbead230">
  <input type="submit" value="Pay">
</form>