NAV Navbar
Logo
Subscription
version 3.4
PHP Perl

Create a subscription order

Examples are for Verotel FlexPay PHP client library

<?php
// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

$subscriptionUrl = $flexpayClient->get_subscription_URL([
    "subscriptionType" => "recurring",
    "name" => "Test subscription",
    "trialAmount" => 5,
    "trialPeriod" => 'P7D',
    "priceAmount" => 12.64,
    "priceCurrency" => "EUR",
    "period" => 'P30D',
]);

Examples are for Verotel FlexPay Perl client library

use Verotel::FlexPay qw/get_subscription_URL/;

my $purchase_url = get_subscription_URL('FlexPay Signature Key',
    shopID => 12345,
    subscriptionType => "recurring",
    name => "Test subscription",
    trialAmount => 5,
    trialPeriod => 'P7D',
    priceAmount => 12.64,
    priceCurrency => "EUR",
    period => 'P30D'
);

The "startorder" subscription request is used to redirect buyer to the Verotel Order Page to process subscription with a given amount, duration and currency.

HTTP request

Verotel
GET https://secure.verotel.com/startorder?

CardBilling
GET https://secure.billing.creditcard/startorder?

BitsafePay
GET https://secure.bitsafepay.com/startorder?

Bill
GET https://secure.bill.creditcard/startorder?

GayCharge
GET https://secure.gaycharge.com/status/order?

Query parameters

Parameter Type Required Description
version Number mandatory version version of the FlexPay call, 3.4 for this version
shopID Number mandatory numerical ID of the website in the Verotel system
type String mandatory subscription
priceAmount Number mandatory priceAmount amount to be processed in nnn.nn format
priceCurrency Number mandatory priceCurrency 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 system
period String mandatory duration in ISO8601 format, for example: P30D, minimum is 7 days for recurring and 2 days for on-time
subscriptionType String mandatory one-time or recurring
NOTE: DDEU and BTC only support one-time
trialAmount Number optional
recurring only
amount to be processed in nnn.nn format for the initial trial period, minimum is 2 days
trialPeriod String optional
recurring only
duration in ISO8601 format, for example: P30D
name String optional description of the product. Text is displayed on the order page - max 100 printable characters
paymentMethod String optional 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

If oneClickToken is sent, the payment method must be set to CC
referenceID String optional merchant's reference identifier. It must be unique if provided
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
backURL String optional URL for redirect after successful transaction - max 255 characters
declineURL String optional URL for redirect after declined transaction - max 255 characters
email String optional email of the buyer. If not set, it will be collected on the Order Page
NOTE: email is excluded from signature calculations (max 100 chars else it will be ignored)
signature String mandatory Signature calculation

Success redirect

After a successful transaction, the buyer is redirected to a nominated "Success URL" and a set of data describing the sale is sent along as HTTP parameters.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String one-time or recurring
event String initial
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
priceAmount Number amount to be processed in nnn.nn format
priceCurrency String 3 char ISO code of the Sale currency
period String subscription duration in ISO8601 format
trialAmount Number amount to be processed (max 2 decimal places, stripped zeroes) for the initial trial period
trialPeriod String duration in ISO8601 format
expiresOn or nextChargeOn Date date of next rebill or expiry date [yyyy-mm-dd] eq. "2015-04-24"
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 payment method, CC, DDEU or BTC
signature String Signature calculation

Postbacks

Examples are for Verotel FlexPay PHP client library

<?php
require_once 'vendor/autoload.php';

// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

if (!$flexpayClient->validate_signature($_GET)){
    http_response_code(500);
    echo "ERROR - Invalid signature!";
    exit;
}

// handle correct postback
...

echo "OK";

Examples are for Verotel FlexPay Perl client library

use CGI;
use Verotel::FlexPay qw/validate_signature/;

my $cgi = new CGI;

if (!validate_signature('FlexPay Signature Key', %{$cgi->Vars})) {
    print $cgi->header( -status => '500' );
    exit;
}

// handle correct postback
...


print $cgi->header( -status => '200' );
print 'OK';

After every sale or transaction based action a corresponding postback is sent to the registered Postback URL.

Postback data are sent as GET request.

Verifying postback

As a security measure postback have to be validated that it contains correctly computed Signature.

Responding to postback

The Verotel system expects HTTP status code 200 and plain text OK response.

Initial postback

The initial 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.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String one-time or recurring
event String initial
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
transactionID Number identifier of the transaction in the Verotel system (only avaible for postbacks version 2)
priceAmount Number amount to be processed in nnn.nn format
priceCurrency String 3 char ISO code of the Sale currency
period String subscription duration in ISO8601 format
trialAmount Number amount to be processed (max 2 decimal places, stripped zeroes) for the initial trial period
trialPeriod String duration in ISO8601 format
expiresOn or nextChargeOn Date date of next rebill or expiry date [yyyy-mm-dd] eq. "2015-04-24"
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 payment method, CC, DDEU or BTC
signature String Signature calculation
truncatedPAN String Truncated (masked) payment instrument identification, e.g. card number
CCBrand String Only present if paid via Credit Card, represents the card brand, e.g. VISA

Rebill postback

Rebill postback call is sent to the merchant's URL immediately after a successful rebill transaction.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring
event String rebill
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
transactionID Number identifier of the transaction in Verotel system
amount Number amount to be processed in nnn.nn format
currency String 3 char ISO code of the Sale currency
nextChargeOn Date date of next rebill [yyyy-mm-dd] eq. "2015-04-24"
subscriptionPhase String normal or discounted
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 payment method, CC, DDEU or BTC
signature String Signature calculation

Extend postback

Merchant or Verotel support may grant extra days to an active subscription. This means that the expiration date or the date of the next planned rebill gets shifted by number of days to the future. The extend postback is then sent to merchant's postback URL to notify the merchant about that the subscription got extended.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring or one-time
event String extend
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
nextChargeOn or expiresOn Date date when cancelled or one-time subscription expires, or date of the next planned rebill [yyyy-mm-dd] e.g "2015-04-24"
subscriptionPhase String trial normal discounted
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
signature String Signature calculation

Downgrade postback

If Merchant or Verotel support changes the next rebill price the Downgrade postback call is sent

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring or one-time
event String downgrade
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
amount Number amount to be processed in nnn.nn format
currency String 3 char ISO code of the Sale currency
subscriptionPhase String normal
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
signature String Signature calculation

Cancel postback

Cancel postback call is sent to the merchant's URL after the subscription is cancelled by the buyer, merchant, Verotel support or by the system.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring
event String cancel
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
expiresOn Date expiry date [yyyy-mm-dd] eq. "2015-04-24"
cancelledBy String user support merchant system
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
signature String Signature calculation

Uncancel postback

Occasionally, buyers wish to revert cancellation of their subscription. Uncancel can be done only by Verotel support. The postback call is sent to the merchant's postback URL immediately after the subscription was uncancelled.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring
event String uncancel
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
nextChargeOn Date date of the next planned rebill [yyyy-mm-dd] eq. "2015-04-24"
subscriptionPhase String trial normal discounted
uncancelledBy String support
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
signature String Signature calculation

Expiry postback

Expiry postback call is sent to the merchant's postback URL when the subscription gets terminated. The reason for the termination could be the end of a cancelled subscription, declined rebill transaction or termination by Verotel support or the merchant.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String recurring or one-time
event String expiry
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
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
signature String Signature calculation

Credit postback

Credit postback call is sent to the merchant's postback URL when any transaction of the subscription is credited by merchant, Verotel support or by system (e.g. when an automated refund is performed). The refund also terminates subscription.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
event String credit
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
priceAmount Number amount of refunded transaction
priceCurrency String refunded transaction currency
transactionID Number transaction id of credit transaction
parentID Number transaction id of transaction which was credited
subscriptionType String recurring or one-time
subscriptionPhase String terminated or normal (for partial credit without terminate initiated)
type String subscription
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
signature String Signature calculation

Chargeback postback

Chargeback postback call is sent to the merchant's postback URL when sale transaction is chargebacked. This also blacklists the buyer.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
event String chargeback
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
priceAmount Number amount of chargebacked transaction
priceCurrency String chargebacked transaction currency
transactionID Number transaction id of credit transaction
parentID Number transaction id of transaction which was credited
subscriptionType String recurring or one-time
subscriptionPhase String terminated
type String chargeback
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
signature String Signature calculation

Upgrade postback

Upgrade postback call is sent to the merchant's postback URL when the subscription is switched from one plan to another. The postback is sent instead of the Successful sale postbacks when the new subscription the buyer is switching to is successfully created and the previous subscription is terminated in Verotel system (No Expiry postback is sent). See “FlexPay API Upgrade” document for more details.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String one-time or recurring
event String upgrade
referenceID String merchant reference identifier if provided in the first sale.
saleID Number identifier of the sale in the Verotel system
transactionID Number identifier of the transaction in the Verotel system (only avaible for postbacks version 2)
precededBySaleID Number Identifier of the previous sale the enduser is switching from
priceAmount Number amount to be processed in nnn.nn format
priceCurrency String 3 char ISO code of the Sale currency
period String subscription duration in ISO8601 format
expiresOn or nextChargeOn Date date of next rebill or expiry date [yyyy-mm-dd] eq. "2015-04-24"
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 payment method, CC, DDEU or BTC
signature String Signature calculation
truncatedPAN String Truncated (masked) payment instrument identification, e.g. card number
CCBrand String Only present if paid via Credit Card, represents the card brand, e.g. VISA

Status page request

Examples are for Verotel FlexPay PHP client library

Symfony\Component\Yaml\Yaml package used to parse status page. Packagist

<?php
// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

$statusURL = $flexpayClient->get_status_URL(['saleID' => 123456]);

$statusPageData = Symfony\Component\Yaml\Yaml::parse(file_get_contents($statusURL));

// handle data fetched from status page

Examples are for Verotel FlexPay Perl client library

use Verotel::FlexPay qw/get_status_URL/;
use LWP::Simple;

my $url = get_status_URL('FlexPay Signature Key', shopID => 12345, saleID => 98765);
my $content = get $url;

print $content;

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.

HTTP request

Verotel
GET https://secure.verotel.com/status/order?

CardBilling
GET https://secure.billing.creditcard/status/order?

BitsafePay
GET https://secure.bitsafepay.com/status/order?

Bill
GET https://secure.bill.creditcard/status/order?

GayCharge
GET https://secure.gaycharge.com/status/order?

Query parameters

Parameter Type Description
version Number 3.4
shopID Number numerical ID of the website in the Verotel system
referenceID String Merchant's reference identifier if provided (referenceID OR saleID must be posted - NOT BOTH)
saleID Number Verotel saleID identifier (referenceID OR saleID must be posted - NOT BOTH)
signature String Signature calculation

Response

Parameter Description
response FOUND - purchase record found and returned
NOTFOUND - purchase not found
ERROR - error (see 'error' key)
error message (for response=ERROR)
saleID identifier of the transaction in Verotel System
shopID ID of website 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 processed in nnn.nn format
priceCurrency 3 char ISO code of the Sale currency
trialAmount trial period processed amount
trialPeriod duration of trial period in ISO8601 format
discountAmount reccurring amount after cancel discount confirmation by buyer
period duration in ISO8601 format, for example: P30D
description Product description text - max 100 printable characters
type purchase or subscription
subscriptionType one-time or recurring
expired yes or no
expiresOn date of subscription expiration in ISO8601 format
referenceID Merchant reference identifier - max 100 printable characters
name name of the buyer
email 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
cancelled yes or no
cancelledOn Timestamp of cancellation
cancelledBy user support merchant system
expiresOn when subscription will be terminated
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)

Cancel subscription request

Examples are for Verotel FlexPay PHP client library

<?php
// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

$cancelSubscriptionURL = $flexpayClient->get_cancel_subscription_URL([
    "saleID" => 654321
]);

Examples are for Verotel FlexPay Perl client library

use Verotel::FlexPay qw/get_cancel_subscription_URL/;

my $upgrade_subscription_url = get_cancel_subscription_URL('FlexPay Signature Key',
    shopID => 12345,
    saleID => 654321
);

To allow your subscribers to cancel their subscriptions on your website you can now generate a subscription specific cancel URL.

HTTP request

Verotel
GET https://secure.verotel.com/cancel-subscription?

CardBilling
GET https://secure.billing.creditcard/cancel-subscription?

BitsafePay
GET https://secure.bitsafepay.com/cancel-subscription?

Bill
GET https://secure.bill.creditcard/cancel-subscription?

GayCharge
GET https://secure.gaycharge.com/status/order?

Query parameters

Parameter Type Required Description
version String mandatory version version of the FlexPay call, 3.4 for this version
shopID Number mandatory numerical ID of the website or shop in Verotel system
saleID Number mandatory Verotel saleID identifier
signature String mandatory Signature calculation

Upgrade subscription request

Examples are for Verotel FlexPay PHP client library

<?php
// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

$upgradeSubscriptionURL = $flexpayClient->get_upgrade_subscription_validation_spec([
    "period" => 'P30D',
    "name" => 'Upgrade to one year subscription'
    "precedingSaleID" => 123456,
    "priceAmount" => 20,
    "priceCurrency" => 'USD',
    "period" => 'P1Y',
    "upgradeOption" => 'extend',
]);

Examples are for Verotel FlexPay Perl client library

use Verotel::FlexPay qw/get_upgrade_subscription_URL/;

my $upgrade_subscription_url = get_upgrade_subscription_URL('FlexPay Signature Key',
    shopID => 12345,
    period => 'P30D',
    name => 'Upgrade to one year subscription'
    precedingSaleID => 123456,
    priceAmount => 20,
    priceCurrency => 'USD',
    period => 'P1Y',
    upgradeOption => 'extend'
);

Subscription upgrade allows switching from one currently active subscription to a new one with new pricing and rebill period. It is possible to switch between recurring and one-time subscriptions, between payment methods and change the periods and amounts.

If successful – an upgrade postback is sent, the current subscription is terminated in Verotel system (the expiry postback is not send in this case) and the buyer continues with the new subscription.

Upgrade Options

The optional upgradeOption parameter specifies how the remaining time from the previous sale is handled: * extend - Any remaining time from previous sale is added to the initial period of the new subscription. This is also how the remaining time is handled if the “upgradeOption” parameter is not specified. * lost - Any remaining time from previous sale is ignored/lost.

Constructing the Upgrade request

The "upgrade" request is used to redirect buyer to the Verotel Order Page in order to process superseding subscription with a given amount, duration and currency.

The upgrade request is like the startorder request but the type needs to be “upgradesubscription” and there is mandatory precedingSaleID parameter.

Please note that referenceID parameter is not accepted in the upgrade request. If referenceID was supplied initially in the startorder of the preceding subscription, it is copied over to the new upgraded subscription.

HTTP request

Verotel
GET https://secure.verotel.com/startorder?

CardBilling
GET https://secure.billing.creditcard/startorder?

BitsafePay
GET https://secure.bitsafepay.com/startorder?

Bill
GET https://secure.bill.creditcard/startorder?

GayCharge
GET https://secure.gaycharge.com/status/order?

Query parameters

Parameter Type Required Description
version Number mandatory version version of the FlexPay call, 3.4 for this version
shopID Number mandatory numerical ID of the website in the Verotel system
type String mandatory upgradesubscription
precedingSaleID Number mandatory Identificator of sale the buyer is upgrading from
priceAmount Number mandatory amount to be processed in nnn.nn format
priceCurrency Number mandatory priceCurrency 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 system
period String mandatory duration in ISO8601 format, for example: P30D, minimum is 7 days for recurring and 2 days for on-time
subscriptionType String mandatory one-time or recurring
NOTE: DDEU and BTC only support one-time
name String optional description of the product. Text is displayed on the order page - max 100 printable characters
upgradeOption String optional lost or extend - – this option defines how to deal with the remaining period from the previous sale, if not provided the remaining period is added to new sale (“same as “extend”)
paymentMethod String optional 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

If oneClickToken is sent, the payment method must be set to CC
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
backURL String optional URL for redirect after successful transaction - max 255 characters
email String optional email of the buyer. If not set, it will be collected on the Order Page
NOTE: email is excluded from signature calculations (max 100 chars else will be ignored)
signature String mandatory Signature calculation
trialAmount Number optional amount to be processed (max 2 decimal places, stripped zeroes) for the initial trial period
trialPeriod String optional duration in ISO8601 format

Success redirect

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String one-time or recurring
event String initial
referenceID String merchant reference identifier. It must be unique if provided
saleID Number identifier of the sale in the Verotel system
priceAmount Number amount to be processed in nnn.nn format
priceCurrency String 3 char ISO code of the Sale currency
period String subscription duration in ISO8601 format
trialAmount Number amount to be processed (max 2 decimal places, stripped zeroes) for the initial trial period
trialPeriod String duration in ISO8601 format
expiresOn or nextChargeOn Date date of next rebill or expiry date [yyyy-mm-dd] eq. "2015-04-24"
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 payment method, CC, DDEU or BTC
signature String Signature calculation

Upgrade postback

Upgrade postback call is sent to the merchant's postback URL when the subscription is switched from one plan to another. The postback is sent instead of the Successful sale postbacks when the new subscription the buyer is switching to is successfully created and the previous subscription is terminated in Verotel system (No Expiry postback is sent). See “FlexPay API Upgrade” document for more details.

Parameter Type Description
shopID Number numerical ID of the website in the Verotel system
type String subscription
subscriptionType String one-time or recurring
event String upgrade
referenceID String merchant reference identifier if provided in the first sale.
saleID Number identifier of the sale in the Verotel system
transactionID Number identifier of the transaction in the Verotel system (only avaible for postbacks version 2)
precededBySaleID Number Identifier of the previous sale the enduser is switching from
priceAmount Number amount to be processed in nnn.nn format
priceCurrency String 3 char ISO code of the Sale currency
period String subscription duration in ISO8601 format
expiresOn or nextChargeOn Date date of next rebill or expiry date [yyyy-mm-dd] eq. "2015-04-24"
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 payment method, CC, DDEU or BTC
signature String Signature calculation
truncatedPAN String Truncated (masked) payment instrument identification, e.g. card number
CCBrand String Only present if paid via Credit Card, represents the card brand, e.g. VISA

Signature calculation

Examples are for Verotel FlexPay PHP client library

<?php
// get your brand instance (Verotel, CardBilling, BitsafePay, Bill, GayCharge Payments)
$brand = Verotel\FlexPay\Brand::create_from_merchant_id(/* Your customer ID */ '9804000000000000');

$flexpayClient = new Verotel\FlexPay\Client(/* shop ID */ 12345, "FlexPay Signature Key", $brand);

$computed_signature = $flexpayClient->get_signature([
    'description' => 'Super video download',
    'priceAmount' => '9.99',
    'priceCurrency' => 'USD',
    'shopID' => 12345,
    'version' => 3.4,
]);

Examples are for Verotel Flexpay Perl client library

use Verotel::FlexPay qw/get_signature/;

my $computed_signature = get_signature('FlexPay Signature Key',
    description => 'Super video download',
    priceAmount => '9.99',
    priceCurrency => 'USD',
    shopID => 12345,
    version => 3.4
);

The signature used in FlexPay requests and postbacks is calculated as SHA-1 hash (hexadecimal output) from the request parameters.

The first parameter has to be your signatureKey, followed by the parameters ordered alphabetically by their names.

Optional arguments that are used (have value) must be contained in the signature calculation. Optional arguments that are not used must not be contained in the signature calculation.

The email parameter in "startorder" request is not included in the signature calculations.

It is mandatory to convert arguments values into UTF-8 before computing the signature.

e.g.

signature = sha1_hex( signatureKey + ":description=" + description + ":period=" + period + ":priceAmount=" + priceAmount + ":priceCurrency=" + priceCurrency + ":referenceID=" + referenceID + ":shopID=" + shopID + ":subscriptionType=" + subscriptionType + ":type=" + type + ":version=" + version )

Example calculation

Parameter Value
(signatureKey) BddJxtUBkDgFB9kj7Zwguxde4gAqha
description Super video download
priceAmount 9.99
priceCurrency USD
custom1 xxyyzz
shopID 64233
type purchase
version 3

Signature calculation using the values above

signature = sha1_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:custom1=xxyyzz:description=Super video download:priceAmount=9.99:priceCurrency=USD:shopID=64233:type=purchase:version=3) => a043071d3db1d3bbacee04e1eaf07da0d3ab1d17

The FlexPay purchase request then is

https://secure.verotel.com/startorder?custom1=xxyyzz&description=Super+video+download&priceAmount=9.99&priceCurrency=USD&shopID=64233&type=purchase&version=3&signature=a043071d3db1d3bbacee04e1eaf07da0d3ab1d17

Payment processor

Processor name Allowed payment method Base URL
Verotel CC DDEU BTC https://secure.verotel.com/
CardBilling CC https://secure.billing.creditcard/
BitsafePay CC DDEU BTC https://secure.bitsafepay.com/
Bill CC DDEU BTC https://secure.bill.creditcard/
GayCharge CC DDEU BTC https://secure.gaycharge.com/