Parameters for Hosted Payment Page

This document contains the following information:BuyNow Parameters BuyNow Hosted Payment Page Parameters

   Introduction
   Hosted Payment page parameters
   Payment Page general parameters
   Payment options
     Hiding payment methods
     Pre-selecting a payment method
   Billing information
   Shipping information
   Invoice information
   Shopper information
   Encrypted parameters

 

Introduction

Hosted Payment Page parameters are values that can be included within the URL of your Hosted Payment page. You can use these parameters to add, update, and customize fields on the page.

For example, if you would like the checkout page to always appear in Danish and show the currency in Euros, regardless of where the shopper's IP address is located, you can include the language and currency parameters in the URL as follows:

https://checkout.bluesnap.com/buynow/checkout?merchantid=12345&language=DANISH&currency=EUR

👍

Note

In addition to the parameters below, you can also pass Metadata parameters.

📘

Override price

If you want to override the price that appears on the checkout page, use the override price capability, which is based on an encrypted parameter.

 

Hosted Payment Page Parameters

The following parameters can be used exclusively with the Hosted Payment Page.

ParameterTypeDescription
amount1stringThe default amount currency is USD. If the amount needs to be charged in a different currency, specify the currency code.

One‑time Payments:

  • If amount is included, the shopper is charged that amount.

  • If amount is not included, the shopper is presented with a screen where they can enter the amount.

Subscriptions, either of the following:

  1. If plan[plan ID]=# parameter is included, this parameter is optional.

    • If amount is included, the included value overrides the initial charge amount of the plan.

    • If amount is not included, the shopper is charged the standard subscription amount.



  2. If ondemand parameter is set to true, this parameter is optional.

    • If amount is included, the included value sets the initial charge amount of the subscription.

    • If amount is not included, there is no initial charge amount.



merchantidintegerYour BlueSnap merchant ID. This parameter is required.
Example: merchantid=500604
plan[plan ID]=#integerOne-time Payments: N/A
Subscriptions: This parameter is required.
Indicate the plan’s ID in [Plan ID] so the payment page includes the correct details. Or, indicate the default purchase quantity in #. (If the quantity is not included, the default quantity is 1.)
Examples: plan457865, plan234587=3
recurringamount1numberOne-time Payments: N/A
Subscriptions: This parameter is optional. Overrides the recurring charge amount of the plan.
Example: recurringamount=16.50
trialperioddays1integerOne-time Payments: N/A
Subscriptions: This parameter is optional.
Overrides the trial period days of the plan.
Example: trialperioddays=7
ondemandbooleanSupports on-demand subscriptions. Default = false

1 Parameter must be encrypted to be passed in the query string of the payment page URL.
 
Back to Top


 

Payment Page General Parameters

ParameterTypeDescription
autosubmitY/NAutomatically selects all the default values on the page and then automatically submits the page. Only functions if all of the following apply:

All the mandatory fields (required for the selected payment method) are supplied and valid
There are no errors in the page
* No mandatory checkbox for shopper consent appears in the page
backtosellervisibleY/NDefines whether the "Continue" button appears on the "Thank You" page
browsertitlestringDefines the title of the browser page, which appears in the browser tab
browsertitlevisibleY/NDefines whether the title of the browser page is visible
companylogovisibleY/NDefines whether the company logo is visible
currency3‑letter code from ISO‑4217 (case‑insensitive)Currency to display on the order page
Example: EUR
currencyvisibleY/NIndicates if the shopper currency preference field is visible. Y=Visible (Default=Y)
currencydisableY/NIndicates if the shopper currency preference field is disabled. Y=Disabled (Default=N)
forceDesktopY/NIndicates whether to force the desktop skin to display, regardless of the shopper's device
forceMobileY/NIndicates whether to force the mobile skin to display, regardless of the shopper's device
languagestringAvailable values:
ALBANIAN, ARABIC, BRAZILIAN, BULGARIAN, CZECH, DANISH, DUTCH, ENGLISH, FINNISH, FRENCH, GERMAN, HEBREW, HUNGARIAN, ITALIAN, JAPANESE, KOREAN, LITHUANIAN, NORWEGIAN, POLISH, PORTUGUESE, RUSSIAN, SERBIAN, SLOVAK, SPANISH, SWEDISH, TURKISH

Example: DANISH
languagevisibleY/NIndicates if the shopper language preference field is visible.Y=Visible (Default=Y)
languagedisableY/NIndicates if the shopper language preference field is disabled. Y=Disabled (Default=N)
merchanttransactionid
or
merchant.transaction.id
string Unique ID that the merchant assigns to the transaction/order, up to 50 characters. Special characters are not recommended.

Example: 1000
referrerinteger For affiliation: the affiliate ID
Example: 123585
sealmcafeevisibleY/NDefines whether the McAfee secure seal is visible
sealverisignvisibleY/NDefines whether the Verisign secure seal is visible
sealvisibleY/NDefines whether the secure seal is visible
softdescstring Soft descriptor that should appear on the shopper’s card bill
Example: Pizza House Inc
storecardvisibleY/NDefines whether the Securely store card for recurring payments option is visible (Default=Y)
storeidinteger Store ID
Example: 155
submitvisibleY/NIndicates whether the submit button is visible
testModeY/NIndicates whether this is a test of the BuyNow flow
tidstring For affiliation: the transaction ID
Example: 12345

Back to Top


 

Payment Options

You can use Hosted Payment Page parameters to perform useful tasks, such as:

📘

Payment methods must be enabled in the Merchant Portal

Before the following payment option parameters can be used, the payment methods you intend to use must be enabled to “Show” in the Merchant Portal. For example, if you want to use the paymentecp parameter, ECP must be enabled for your account.

 

Hiding payment methods

You can use these parameters to hide (or disable) specific payment methods.

ParameterTypeDescription
payment[paymentMethod]Y/NIndicates if the specified payment method is visible in "Payment Options" section

Available paymentMethod values:
alipay, applepay, banktransfer, boletoBancario, cc, ecp, googlepay, moneybookers, paypal, paysafecard, realtimebank1, sepadd, skrill, wire

Examples: paymentcc=N, paymentpaypal=N, paymentwire=N
paymentmethodsvisibleY/NIndicates if the payment options widget is visible
alipayY/NIndicates if Alipay is visible in the "Payment Options" section
applepayY/NIndicates if ApplePay is visible in the "Payment Options" section
banktransferY/NIndicates if Bank Transfer is visible in the "Payment Options" section
boletoBancarioY/NIndicates if Boleto Bancario is visible in the "Payment Options" section
ccY/NIndicates if Credit Cards is visible in the "Payment Options" section
ecpY/NIndicates if ECP is visible in the "Payment Options" section
googlepayY/NIndicates if Google Pay is visible in the "Payment Options" section
moneybookersY/NIndicates if Moneybookers (aka. Skrill) is visible in the "Payment Options" section
paypalY/NIndicates if PayPal is visible in the "Payment Options" section
paysafecardY/NIndicates if paysafe is visible in the "Payment Options" section
realtimebankY/NIndicates if real time bank transfer is visible in the "Payment Options" section
skrillY/NIndicates if Skrill (aka. Moneybookers) is visible in the "Payment Options" section
wireY/NIndicates if Wire is visible in the "Payment Options" section
ccnumbervisibleY/NIndicates if the CC number field is visible (Default=Y)
cctypevisibleY/NIndicates if the CC type field is visible (Default=Y)
cctypedisableY/NIndicates if the CC type field is disabled. Y=Disabled (Default=N)
ccdatevisibleY/NIndicates if the CC expiration date field is visible (Default=Y)
ccdatedisableY/NIndicates if the CC expiration date field is disabled. Y=Disabled (Default=N)
expirationmonthinteger CC expiration month
Example: 12
expirationyearinteger CC expiration year
Example: 2022
ccstartdatevisibleY/NIndicates if the CC start date field is visible (Default=Y, if start date is applicable for the selected CC type)
ccstartdatedisableY/NIndicates if the CC start date field is disabled. Y=Disabled (Default=N)
ccstartmonthinteger CC start month
Example: 09
ccstartyearinteger CC start year
Example: 2015
cccodevisibleY/NIndicates if the CC security code field is visible (Default=Y, if start date is applicable for the selected CC type)
cccodedisableY/NIndicates if the CC security code field is disabled. Y=Disabled (Default=N)
 

📘

1For payment methods, the realtimebank option for payment[paymentMethod] in hiding payment methods includes GIROPAY, IDEAL, and SOFORTUBERWEISUNG. All four must be set to hidden or visible as a group using the realtimebank option.

 

Pre-selecting a payment method

You can use the following parameter to pre-select a payment method for your shopper on the checkout page.

ParameterTypeDescription
selectedPaymentMethodstring Specifies the default selected payment method when the shopper sees the checkout page.

Available PaymentMethod values:
ALIPAY, APPLE_PAY, BANKTRANSFER, BOLETO_BANCARIO, CC, ECP,GIROPAY2, IDEAL2, MONEYBOOKERS, PAYPAL, PAYSAFECARD, SEPA_DIRECT_DEBIT, SOFORTUBERWEISUNG2, WALLET_MP, WALLET_VISA, WIRE

Example: selectedPaymentMethod=SEPA_DIRECT_DEBIT

📘

2 GIROPAY, IDEAL, and SOFORTUBERWEISUNG are set to visible or hidden as a group using the realtimebank option for payment[paymentMethod] in Hiding Payment Methods.

Also, if you want to have one of these payment methods pre-selected, you must have the country and currency set as well. For example: Even if you preselect GIROPAY, it is not pre-selected for a shopper is located in the US. In this example, you must set &selectedPaymentMethod=GIROPAY&country=de&currency=eur

Back to Top


 

Billing Information

You can use these parameters to pre-populate billing detail fields on the checkout page, and to customize which options appear.

ParameterTypeDescription
billingfirstnamestring First name
Example: John
billinglastnamestring Last name
Example: Doe
billingfullNamestring Full billing name
Example: JohnDoe
billingaddress1string Address line 1
Example: 1234 St. James Dr.
billingaddress2string Address line 2
Example: Suite 123
billingcitystring City
Example: San Diego
billingstatestring State
Example: CA
billingzipcodestring ZIP code or postal code
Example: 78467
billingcountry2‑letter code from ISO_3166‑1Country
Example: US
billinginfocheckboxvisibleY/NIndicates if the billing info check box is visible. Y=Visible (Default=N)
billinginfovisibleY/NIndicates if the billing info widget is visible. Y=Visible (Default=N; As default, it is shown only if the shopper checks the billing info checkbox.)
billinginfodisableY/NIndicates if the billing info widget is disabled. Y=Disabled (Default=N)
billingfullnamevisibleY/NIndicates if the billing full name field is visible. Y=Visible (Default=Y)
billingfullnamedisableY/NIndicates if the billing full name field is disabled. Y=Disabled (Default=N)
billingfirstnamevisibleY/NIndicates if the billing first name field is visible. Y=Visible (Default=Y)
billingfirstnamedisableY/NIndicates if the billing first name field is disabled. Y=Disabled (Default=N)
billinglastnamevisibleY/NIndicates if the billing last name field is visible. Y=Visible (Default=Y)
billinglastnamedisableY/NIndicates if the billing last name field is disabled. Y=Disabled (Default=N)
billingaddress1visibleY/NIndicates if the billing address 1 field is visible. Y=Visible (Default=Y)
billingaddress1disableY/NIndicates if the billing address 1 field is disabled. Y=Disabled (Default=N)
billingaddress2visibleY/NIndicates if the billing address 2 field is visible. Y=Visible (Default=N)
billingaddress2disableY/NIndicates if the billing address 2 field is disabled. Y=Disabled (Default=N)
billingcityvisibleY/NIndicates if the billing city field is visible. Y=Visible (Default=Y)
billingcitydisableY/NIndicates if the billing city field is disabled. Y=Disabled (Default=N)
billingzipvisibleY/NIndicates if the billing zip code field is visible. Y=Visible (Default=Y)
billingzipdisableY/NIndicates if the billing zip code field is disabled. Y=Disabled (Default=N)
billingcountryvisibleY/NIndicates if the billing country field is visible. Y=Visible (Default=Y)
billingcountrydisableY/NIndicates if the billing country field is disabled. Y=Disabled (Default=N)
billingstatevisibleY/NIndicates if the billing state field is visible. Y=Visible (Default=Y; only if relevant by the selected country)
billingstatedisableY/NIndicates if the billing state field is disabled. Y=Disabled (Default=N)

Back to Top


 

Shipping Information

You can use these parameters to pre-populate shipping detail fields on the checkout page, and to customize which options appear.

📘

Note

Shipping information fields are displayed on the checkout page if the 'Collect Shipping Address' option is enabled in the contract's settings (under General Settings > Miscellaneous).

ParameterTypeDescription
shippingfirstnamestring First name
Example: John
shippinglastnamestring Last name
Example: Doe
shippingfullNamestring Full name
Example: JohnDoe
shippingaddress1string Address line 1
Example: 1234 St. James Dr.
shippingaddress2string Address line 2
Example: Suite 123
shippingcitystring City
Example: San Diego
shippingstatestring State
Example: CA
shippingzipcodestring ZIP code or postal code
Example: 78467
shippingcountry2‑letter code from ISO_3166‑1Country
Example: US
shippinginfocheckboxvisibleY/NIndicates if the shipping info checkbox is visible. Y=Visible (Default=N)
shippinginfovisibleY/NIndicates if the shipping info widget is visible. Y=Visible (Default=N; As default, it is shown only if the shopper checks the shipping info checkbox)
shippinginfodisableY/NIndicates if the shipping info widget is disabled. Y=Disabled (Default=N)
shippingfirstnamevisibleY/NIndicates if the shipping first name field is visible. Y=Visible (Default=Y)
shippingfirstnamedisableY/NIndicates if the shipping first name field is disabled. Y=Disabled (Default=N)
shippinglastnamevisibleY/NIndicates if the shipping last name field is visible. Y=Visible (Default=Y)
shippinglastnamedisableY/NIndicates if the shipping last name field is disabled. Y=Disabled (Default=N)
shippingfullnamevisibleY/NIndicates if the shipping full name field is visible. Y=Visible (Default=Y)
shippingfullnamedisableY/NIndicates if the shipping full name field is disabled. Y=Disabled (Default=N)
shippingaddress1visibleY/NIndicates if the shipping address 1 field is visible. Y=Visible (Default=Y)
shippingaddress1disableY/NIndicates if the shipping address 1 field is disabled. Y=Disabled (Default=N)
shippingaddress2visibleY/NIndicates if the shipping address 2 field is visible. Y=Visible (Default=N)
shippingaddress2disableY/NIndicates if the shipping address 2 field is disabled. Y=Disabled (Default=N)
shippingcityvisibleY/NIndicates if the shipping city field is visible. Y=Visible (Default=Y)
shippingcitydisableY/NIndicates if the shipping city field is disabled. Y=Disabled (Default=N)
shippingzipvisibleY/NIndicates if the shipping zip code field is visible. Y=Visible (Default=Y)
shippingzipdisableY/NIndicates if the shipping zip code field is disabled. Y=Disabled (Default=N)
shippingcountryvisibleY/NIndicates if the shipping country field is visible. Y=Visible (Default=Y)
shippingcountrydisableY/NIndicates if the shipping country field is disabled. Y=Disabled (Default=N)
shippingstatevisibleY/NIndicates if the shipping state field is visible. Y=Visible (Default=Y, but only if relevant for the selected country)
shippingstatedisableY/NIndicates if the shipping state field is disabled. Y=Disabled (Default=N)

Back to Top


 

Invoice Information

You can use these parameters to pre-populate invoice detail fields on the checkout page, and to customize which options appear.

ParameterTypeDescription
invoiceinfovisibleY/NIndicates if the invoice info is visible. Y=Visible
invoiceaddress1string Address line 1 on the invoice
Example: 1234 St. James Dr.
invoiceaddress1visibleY/NIndicates if the address 1 field is visible. Y=Visible
invoiceaddress1disableY/NIndicates if the address 1 field is disabled. Y=Disabled
invoiceaddress2string Address line 2 on the invoice
Example: Suite 100
invoiceaddress2visibleY/NIndicates if the address 2 field is visible. Y=Visible
invoiceaddress2disableY/NIndicates if the address 2 field is disabled. Y=Disabled
invoicecitystring City on the invoice
Example: San Diego
invoicecityvisibleY/NIndicates if the city field is visible. Y=Visible
invoicecitydisableY/NIndicates if the city field is disabled. Y=Disabled
invoicecompanynamestring Company name on the invoice
Example: Acme
invoicecompanynamevisibleY/NIndicates if the company name field is visible. Y=Visible
invoicecompanynamedisableY/NIndicates if the company name field is disabled. Y=Disabled
invoicecountry2‑letter code from ISO_3166‑1Country on the invoice
Example: US
invoicecountryvisibleY/NIndicates if the country field is visible. Y=Visible
invoicecountrydisableY/NIndicates if the country field is disabled. Y=Disabled
invoiceemailstring Email on the invoice
Example: [email protected]
invoiceemailvisibleY/NIndicates if the email field is visible. Y=Visible
invoiceemaildisableY/NIndicates if the email field is disabled. Y=Disabled
invoicefirstNamestring First name on the invoice
Example: John
invoicefirstnamevisibleY/NIndicates if the first name field is visible. Y=Visible
invoicefirstnamedisableY/NIndicates if the first name field is disabled. Y=Disabled
invoicefullNamestring Full name on the invoice
Example: John Doe
invoicefullnamevisibleY/NIndicates if the full name field is visible. Y=Visible
invoicefullnamedisableY/NIndicates if the full name field is disabled. Y=Disabled
invoicelastNamestring Last name on the invoice
Example: Doe
invoicelastnamevisibleY/NIndicates if the last name field is visible. Y=Visible
invoicelastnamedisableY/NIndicates if the last name field is disabled. Y=Disabled
invoicestatestring State on the invoice
Example: CA
invoicestatevisibleY/NIndicates if the state field is visible. Y=Visible
invoicestatedisableY/NIndicates if the state field is disabled. Y=Disabled
invoicetitlestring Title on the invoice
Example: Mr
invoicetitlevisibleY/NIndicates if the title field is visible. Y=Visible
invoicetitledisableY/NIndicates if the title field is disabled. Y=Disabled
invoiceworkphonestring Work phone number on the invoice
Example: 800-123-4567
invoicephonevisibleY/NIndicates if the phone number field is visible. Y=Visible
invoicephonedisableY/NIndicates if the phone number field is disabled. Y=Disabled
invoicezipcodestring ZIP code on the invoice
Example: 01234
invoicezipvisibleY/NIndicates if the ZIP code field is visible. Y=Visible
invoicezipdisableY/NIndicates if the ZIP code field is disabled. Y=Disabled

Back to Top


 

Shopper Information

You can use these parameters to pre-populate shopper information fields on the checkout page, and to customize which options appear.

ParameterTypeDescription
titlestring Title
Example: Mr
companynamestring Company name
Example: Best Company
firstnamestring First name
Example: John
lastnamestring Last name
Example: Doe
fullnamestring Full name
Example: JohnDoe
emailstring Email
Example: [email protected]
address1string Address line 1
Example: 1234 St. James Dr.
address2string Address line 2
Example: Suite 123
citystring City
Example: San Diego
statestring State
Example: CA
zipstring ZIP code or postal code
Example: 78467
workphonestring Work phone number
Example: 3456789123
faxnumberstring Fax number
Example: 9876543333
personalIdstring Personal identification number for shoppers in Brazil (CPF/CNPJ).
Example: personalId=61.384.546/0001-88
shoppersprefvisibleY/NIndicates if the shopper language and currency preference fields are visible. Y=Visible (Default=Y)
shoppersprefdisableY/NIndicates if the shopper language and currency preference fields are disabled. Y=Disabled (Default=N)
shopperinfovisibleY/NIndicates if the shopper information fields are visible. Y=Visible (Default=Y)
shopperinfodisableY/NIndicates if the shopper information fields are disabled. Y=Disabled (Default=N)
accountdetailsinfovisibleY/NIndicates if the shopper account details are visible. Y=Visible
companynamevisibleY/NIndicates if the company name field is visible. Y=Visible (Default=N)
companynamerequireY/NIndicates if the company name field is mandatory. (Default=N)
companynamedisableY/NIndicates if the company name field is disabled. Y=Disabled (Default=N)
titlevisibleY/NIndicates if shopper's title field is visible. Y=Disabled (Default=N)
titlerequireY/NIndicates if shopper title is mandatory. (Default=N)
titledisableY/NIndicates if shopper title field is disabled. Y=Disabled (Default=N)
firstnamevisibleY/NIndicates if shopper first name field is visible. Y=Visible (Default=Y)
firstnamedisableY/NIndicates if the shopper first name field is disabled. Y=Disabled (Default=N)
lastnamevisibleY/NIndicates if shopper last name field is visible. Y=Visible (Default=Y)
lastnamedisableY/NIndicates if the shopper last name field is disabled. Y=Disabled (Default=N)
fullnamevisibleY/NIndicates if shopper full name field is visible. Y=Visible (Default=Y)
fullnamedisableY/NIndicates if the shopper full name field is disabled. Y=Disabled (Default=N)
emailvisibleY/NIndicates if the shopper email field is visible. Y=Visible (Default=Y)
address1visibleY/NIndicates if the address line 1 field is visible. Y=Visible (Default=Y)
address1disableY/NIndicates if the address line 1 field is disabled. Y=Disabled (Default=N)
address2visibleY/NIndicates if the address line 2 field is visible. Y=Visible (Default=N)
address2requireY/NIndicates if the address line 2 field is mandatory. (Default=N)
address2disableY/NIndicates if the address line 2 field is disabled. Y=Disabled (Default=N)
cityvisibleY/NIndicates if the city field is visible. Y=Visible (Default=Y)
citydisableY/NIndicates if the city field is disabled. Y=Disabled
zipvisibleY/NIndicates if the ZIP code field is visible. Y=Visible (Default=Y)
zipdisableY/NIndicates if the ZIP code field is disabled. Y=Disabled (Default=N)
countryvisibleY/NIndicates if the shopper’s country field is visible. Y=Visible (Default=Y)
countrydisableY/NIndicates if the shopper’s country field is disabled. Y=Disabled (Default=N)
statevisibleY/NIndicates if the shopper’s state field is visible. Y=Visible (Default=Y, but only if relevant for the selected country)
statedisableY/NIndicates if the shopper’s state field is disabled. Y=Disabled (Default=N)
phonevisibleY/NIndicates if the shopper’s phone field is visible. Y=Visible (Default=Y)
phonedisableY/NIndicates if the shopper’s phone field is disabled. Y=Disabled (Default=N)
faxvisibleY/NIndicates if the shopper’s fax field is visible. Y=Visible (Default=N)
faxrequireY/NIndicates if fax field is mandatory. (Default=N)
faxdisableY/NIndicates if the shopper’s fax field is disabled. Y=Disabled (Default=N)

Back to Top


 

Encrypted Parameters

BlueSnap supports a number of parameters that should be encrypted before they are added to the URL. The list below describes these parameters. For instructions on using BlueSnap's API to encrypt the parameters, see Encrypt Parameters.

ParameterTypeDescription
thankyou.backtosellerurlstring URL where the shopper will be directed after completing the purchase. The URL must be encoded, as shown in the example.
Example:
https%3A%2F%2Fmywebsite.com%2Fmypage %3Finv%3D!%7Binvoice.id%7D
shopperIdstring Used for Auto Login
ID of the shopper

Example: 19505364

Note: When this parameter is passed, the request must also include the expirationInMinutes parameter.
expirationInMinutesstring Used to set the minutes until the page expires. Max. 1440 minutes (24hr)
Note: Returning shoppers only; otherwise, no maximum.

Example: 300
pageNamestring Used for Auto Login
Name of the page where the shopper will be directed

Example: AUTO_LOGIN_PAGE
taxCodestring The taxCode used to calculate the taxability of the product being purchased based on the shopper's country and zip code.
To determine the correct tax code, refer to https://taxcode.avatax.avalara.com/

Example: DG010200
challenge.requestedstringIndicates if challenge should be forced on the shopper as a part of 3DS.
merchantIdintegerYour BlueSnap merchant ID. This parameter is required.
Example: merchantid=500604
onBehalfbooleanDefault is false. This should only be set to true if the transaction is completed on behalf of the shopper and not by the shopper themselves.

 
Back to Top