createBillingOnDemand
Syntax
createBillingOnDemand(
purchase_id,
product_id,
payment_plan=array(),
tracking=array(),
placeholders=array(),
settings=array(),
addons=array()
)
Creates a special order form URL that can be customized for the visitor. For example, customer data can be entered and, if necessary, can be read-only. The prices can also be changed.
Together with our PHP connector class, we provide a sample PHP script. You can find it in the ZIP archive in the file examples/buyurl.php.
Access rights
Full access required.
In addition, the “Billing on demand” right must be enabled for the vendor account.
Arguments
purchase_id – The reference order. This order must have been made with a payment method that supports rebilling.
product_id – The product ID in Digistore24
payment_plan – An array with the data of the purchase price/payment plan. All fields are optional.
- payment_plan[first_amount] – The purchase price (or the first payment for subscription and installment payments) e.g. 17.99
- payment_plan[other_amounts] – For subscription and installment payments, the amount of follow-up payments e.g. 39.50
- payment_plan[currency] – The three-character currency code e.g. EUR or USD. If this is not specified, Digistore will try to determine the currency automatically.
- payment_plan[number_of_installments] – For installments: Number of payments (including the first)
- payment_plan[first_billing_interval] – For subscription and installment payments: The time interval between the purchase and second installment. The default is 1 month (“1_month). Examples of possible values are: “10-day”, “12_month” etc.
- payment_plan[other_billing_intervals] – As above, only for the second and any further payments
- payment_plan[test_interval] – Enters a test interval. The payment does not start until after the test period. The format is as above e.g. “1_month”.
- payment_plan[template] – ID of the payment method used as a template. All values that are not specified in the API call are then copied from the selected template. The payment methods (including the IDs) can be found in the product editor in the tab “Payment method”.
- payment_plan[upgrade_type]– defaults to upgrade. The given order is upgraded. Possible values for upgrade_type:
- upgrade - the rebilling of the given order (upgrade_order_id) is stopped. The unused rebilling amount is credited to the new order. Product acces is granted immediately.
- downgrade - the billing starts at the end of the current billing interval of the previous order. The previous order is then stopped.
tracking – An array with the data for tracking. All fields are optional.
- tracking[custom] – The custom value that you as a vendor can transfer to the order form via the GET parameter “custom”, which will then be looped through. Use this value as an order reference for your own system. In the IPN notification for the purchase order, the value of this field is then transferred as custom. This is the same in the API functions listPurchases() and getPurchase().
- tracking[affiliate] – The affiliate's Digistore24 ID. If it is not valid, the function will return an error.
- tracking[campaignkey] – The campaign key (of the affiliate)
- tracking[trackingkey] – The vendor's tracking key (which can also be transferred as the GET parameter “ds24tr” to the order form)
placeholders – An array with placeholders for the product title and product description.
Example: Enter this array for the placeholders [size] and [color]:
array( size => XL, color => Blue )
The square brackets are automatically added to the name of the placeholder.
You can then use these placeholders in the product title e.g. T-shirt size [size], color [color].
The order form will then display: T-shirt size XL, color blue.
For the array keys, please only use the characters a-z, A-Z, 0-9, _ and –
The following characters are not allowed as array values: < > & # ; “ ‚ ` ´
The function getPurchase() lists these placeholders when details about an order are requested.
These placeholders are transferred with IPN notifications. Here, the name is preceded by a “placeholder”, e.g. placeholder_size = XL.
settings – Further settings for the order form (all optional):
- settings[voucher_code] – This voucher will be taken into account when payment is made.
- settings[quantity] – The quantity of the main product. Default is 1.
- settings[product_country] – The country code (two letters) – if the main product requires the country to be specified (e.g. for seminars) and it differs from the country set in the Digistore24 backoffice.
addons – A list of add-on products as a two-dimensional array. First dimension is an index (integer starting with 0), second dimension is the fields e.g.
addons[0][product_id]=12345
addons[0][first_amount]=27.99
Any number of add-ons can be added. Use these keys for each addon:
- product_id
- first_amount – For subscription/installment payment: The first amount
- other_amounts – For subscription/installment payment: The amount of the follow-up payments
- single_amount – For single payments: The purchase amount
- quantity – Default is 1.
- currency – If prices are given, a currency should be specified at least for the first add-on (this is then valid for all further add-ons). The default currency is EUR. The prices will be converted to the purchase currency if necessary.
- is_quantity_editable_after_purchase – Y/N – Can the buyer change the quantity after the purchase (e.g. to book additional packages)? Default: N
- product_country – The country code (two letters) of the product country – if the product requires the country to be specified (e.g. for seminars) and it differs from the country set in the Digistore24 backoffice.
Return data
created_purchase_id: The ID of the new order
payment_status: The payment status of the payment
payment_status_msg: Payment status in readable form
billing_status: Status of the new order e.g. completed or paying
billing_status_msg: Order status in readable form