Technical details
Constructing purchase "startorder" request
FlexPay purchase call is used to redirect buyer to the Verotel Order Page in order to process the purchase sale.
The "startorder" request for FlexPay purchase consists of number of parameters passed to "https://secure.verotel.com/startorder?" for Verotel accounts or "https://secure.billing.creditcard/startorder?" for CardBilling accounts and is secured by a signature.
| Parameter | Type | Optional / Mandatory | Description |
|---|---|---|---|
| backURL | string | optional | URL for redirect after successful transaction. NOTE: Max 255 charactersSupported from version 3.2 |
| custom1 | string | optional | pass-through variable - max 255 printable characters |
| custom2 | string | optional | pass-through variable - max 255 printable characters |
| custom3 | string | optional | pass-through variable - max 255 printable characters |
| description | string | mandatory | description of the product. Text is displayed on the order page |
| string | optional | email of the buyer. If not set, it will be collected on the Order PageNOTE: email is excluded from signature calculations | |
| oneClickToken | string | options | The one-time oneClickToken from previous purchase.NOTE: oneClickToken is excluded from signature calculationsSupported from version 3.2 |
| paymentMethod | string | optionalmandatory if oneClickToken is used | payment method, "CC", "DDEU" or "BTC"(if not set then buyers can choose from available payment methods)Note: DDEU is available only in DE, AT, CH, BE, IT, NL, ES and FR |
| priceAmount | number | mandatory | amount to be processed in nnn.nn format |
| priceCurrency | string | mandatory | 3 char ISO code, must be one of the Sale currencies (USD, EUR, GBP, AUD, CAD, CHF, DKK, NOK, SEK)Note: only EUR is can be used for DDEU payment method |
| referenceID | string | optional | Merchant's reference identifier. It must be unique if provided |
| shopID | number | mandatory | numerical ID of the shop or website in the Verotel system |
| signature | string | mandatory | security token to verify the integrity of the postback data (see Calculating signature) |
| type | string | mandatory | "purchase" |
| version | number | mandatory | version of the FlexPay call, "3.2" for this version |
Example "startorder" request:
Since the Payment method was not specified this opens a page which lets the buyer to select from the available payment methods. (DDEU is not offered as the sale currency is USD)
Data posted to success URL upon the FlexPay Subscription transaction (OK data)
After a successful transaction, the buyer is redirected to a nominated "Success URL" or to URL defined in backURL parameter and a set of data describing the sale is sent along as HTTP parameters.
| Parameter | Type | Description |
|---|---|---|
| custom1 | string | pass-through variable - max 255 printable characters |
| custom2 | string | pass-through variable - max 255 printable characters |
| custom3 | string | pass-through variable - max 255 printable characters |
| paymentMethod | string | Used payment method, "CC", "DDEU" or "BTC" |
| priceAmount | number | amount to be processed in nnn.nn format |
| priceCurrency | string | 3 char ISO code of the Sale currency |
| referenceID | string | Merchant's reference identifier if provided. |
| saleID | number | identifier of the sale in the Verotel system |
| shopID | number | numerical ID of the shop or website in the Verotel system |
| signature | string | security token to verify the integrity of the postback data (see Calculating signature) |
| type | string | "purchase" |
"OK data" postback call
The successful sale postback is sent to the nominated "Postback URL" immediately after the sale has been processed.
The postback is sent only for successfully approved transactions. The data in the postback provide essential information about the sale. If more information is needed, for example billing address or email address of the buyer, the merchant should query the status page.
Important: The Verotel system expects "OK" response within 30 seconds.. If no such response is received, an automatic refund is initiated. (Or in case of BTC payment a notification is sent to merchant, support and enduser).
| Parameter | Type | Description |
|---|---|---|
| custom1 | string | pass-through variable - max 255 printable characters |
| custom2 | string | pass-through variable - max 255 printable characters |
| custom3 | string | pass-through variable - max 255 printable characters |
| oneClickToken | string | If the feature is enabled - oneClickToken valid for next purchase |
| paymentMethod | string | payment method, "CC", "DDEU" or "BTC" |
| priceAmount | number | amount to be processed (max 2 decimal places, stripped zeroes) |
| priceCurrency | string | 3 char ISO code of the Sale currency |
| referenceID | string | merchant reference identifier. It must be unique if provided |
| saleID | number | identifier of the sale in the Verotel system |
| shopID | number | numerical ID of the shop or website in the Verotel system |
| signature | string | security token to verify the integrity of the postback data (see Calculating signature) |
| type | string | "purchase" |
FlexPay status page request
A status of a sale made with a FlexPay API can be reviewed by querying the status page. Status page provides complete information about the sale, the buyer, and its status.
Status request URL: "https:// secure.verotel.com/status/order?" (Verotel) or "https://secure.billing.creditcard/status/order?" (CardBilling) followed by parameters in the table bellow:
| GET parameters in response | Description |
|---|---|
| **referenceID (optional)** | Merchant's reference identifier if provided (referenceID OR saleID must be posted - NOT BOTH) |
| **saleID (optional)** | Verotel saleID identifier (referenceID OR saleID must be posted - NOT BOTH) |
| shopID | numerical ID of the website or shop in Verotel system |
| signature | SHA-1 hash generated on data listed above and Merchant's private key stringsha1_hex(signatureKey + ":referenceID=" + referenceID + ":saleID=" + saleID + ":shopID=" + shopID +":version=" + version) |
| version | Version of the Verotel Purchase OrderPage protocol: "3.2" |
Example:
Flexpay Purchase Status response:
The date returned to the status request is in plain-text and contains lines with parameterName, colon, parameterValue:
| Output parameter name | Description |
|---|---|
| response | FOUND - purchase record found and returnedNOTFOUND - purchase not foundERROR - error (see 'error' key) |
| error | message (for response=ERROR) |
| saleID | identifier of the transaction in Verotel System |
| shopID | ID of the website or shop in Verotel system |
| paymentMethod | an identifier of payment method that was used for the transaction. Can be one of following: "Credit Card", "Direct Debit EU" or "Bitcoin" |
| priceAmount | amount to be processed. in nnn.nn formatt |
| priceCurrency | 3 char ISO code of the Sale currency |
| description | Product description text |
| referenceID | Merchant reference identifier |
| name | name of the buyer |
| email address of the buyer | |
| country | selected or detected country ISO code (ISO 3166-1-alpha-2 code) |
| oneClickToken | If the feature is enabled - Currently valid oneClickToken |
| btc_transaction_status | Only for Bitcoin sales: The status of Bitcoin transaction as set by the postback from Bitcoin processor:"paid" - the transaction was successfully sent to the processor"complete" - the transaction was confirmed and processed completely"invalid" - the transaction could not be processed, it was unsuccessful |
| createdOn | Timestamp of purchase creation |
| saleResult | purchase processing result (APPROVED) |
| billingAddr_fullName | billing address: full name field value |
| billingAddr_company | billing address: company field value |
| billingAddr_addressLine1 | billing address: 1st line field value |
| billingAddr_addressLine2 | billing address: 2nd line field value |
| billingAddr_city | billing address: city name |
| billingAddr_zip | billing address: zip code / postal code |
| billingAddr_state | billing address: US state code (ISO 3166-2) |
| billingAddr_country | billing address: country ISO code (ISO 3166-1-alpha-2 code) |
Example response:
response: FOUND shopID: 60678 paymentMethod: Credit Card priceAmount: 51.20 priceCurrency: EUR description: some description of product referenceID: AX62362I3 saleID: 13029033 saleResult: APPROVED name: John Black email: [email protected] country: CZ oneClickToken: 286D9498-3A02-11E6-8531-A779FE751966 billingAddr_fullName: John Black billingAddr_company: billingAddr_addressLine1: Longstreet 3782/13 billingAddr_addressLine2: billingAddr_city: London billingAddr_zip: 73811 billingAddr_state: billingAddr_country: GB