Create a subscription order

Examples are for Verotel FlexPay PHP client library

$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 FlexPay Java client library

URL purchaseUrl = flexPayClient.subscriptionBuilder()
    .withAmount("14".toBigDecimal(), SaleCurrency.EUR)
    .withDescription("test description")
    .withPaymentMethod(PaymentMethod.CC)
    .withSubscriptionType(SubscriptionType.recurring)
    .withPeriod("P10D")
    .build();

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/startorder?

YoursafeDirect
GET https://secure.yoursafedirect.com/startorder?

Query parameters

Success redirect

After a successful transaction the buyer is redirected to one of these:

• The default website Flexpay success URL (Setup in Control Center/Setup Websites/Website detail/FlexPay Options)
• The URL set in successURL Flexpay parameter – overrides the website Flexpay success URL

Postbacks

Examples are for Verotel FlexPay PHP client library

$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(400);
    echo "ERROR - Invalid signature!";
    exit;
}

// handle correct postback
...

echo "OK";

Examples are for FlexPay Java client library

// pass GET params received in postback
Boolean paramsAreVerified = flexPayClient.validateSignature(Map.of(...));

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

Important: The Verotel system expects HTTP status code 200 and plain text "OK" response. The response must be returned within 30 seconds.

Initial postback

The initial sale postback is sent to the website "Flexpay 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 HTTP status code 200 and plain text "OK" response. The response must be returned within 30 seconds.

Rebill postback

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

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.

Downgrade postback

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

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.

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.

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.

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.

Chargeback postback

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

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.

Status page request

Examples are for Verotel FlexPay PHP client library

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

$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 FlexPay Java client library

URL statusUrl = flexPayClient.getStatusUrlBySale(123456);

// fetch URL 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?

YoursafeDirect
GET https://secure.yoursafedirect.com/status/order?

Query parameters

Response

Cancel subscription request

Examples are for Verotel FlexPay PHP client library

$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 FlexPay Java client library

URL cancelUrl = flexPayClient.getCancelSubscriptionUrl(1234);

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/cancel-subscription?

YoursafeDirect
GET https://secure.yoursafedirect.com/cancel-subscription?

Query parameters

Upgrade subscription request

Examples are for Verotel FlexPay PHP client library

$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_URL([
    "period" => 'P30D',
    "name" => 'Upgrade to one year subscription'
    "precedingSaleID" => 123456,
    "priceAmount" => 20,
    "priceCurrency" => 'USD',
    "period" => 'P1Y',
    "upgradeOption" => 'extend',
]);

Examples are for FlexPay Java client library

URL upgradeSubscriptionURL = flexpayClient.getUpgradeSubscriptionUrl(
    1234    // preceding sale ID
    "P12D", // period
    SubscriptionType.recurring,
    BigDecimal.valueOf(24), //  price amount
    SaleCurrency.EUR,       // price currency
);

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/startorder?

YoursafeDirect
GET https://secure.yoursafedirect.com/startorder?

Query parameters

Success redirect

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.

Signature calculation

Examples are for Verotel FlexPay PHP client library

$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' => 4,
]);

Examples are for FlexPay Java client library

String computedSignature = flexpayClient.getSignature(Map.of(
    "description", "Super video download",
    "priceAmount", "9.99",
    "priceCurrency", "USD",
    "shopID", 12345,
    "version", 4
));

If you are using one of our client libraries, signature calculation is handled by the library.

The signature used in FlexPay requests and postbacks is calculated as SHA-256 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 = sha256_hex( signatureKey + ":description=" + description + ":period=" + period + ":priceAmount=" + priceAmount + ":priceCurrency=" + priceCurrency + ":referenceID=" + referenceID + ":shopID=" + shopID + ":subscriptionType=" + subscriptionType + ":type=" + type + ":version=" + version )

Example calculation

Signature calculation using the values above

signature = sha256_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:custom1=xxyyzz:description=Super video download:priceAmount=9.99:priceCurrency=USD:shopID=64233:type=purchase:version=4) => ccaf2357fe330654322a1b0f3f92984b3fe2a1462d6fc5082650a00c5ada2f2a

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=4&signature=ccaf2357fe330654322a1b0f3f92984b3fe2a1462d6fc5082650a00c5ada2f2a

Payment processor