BlueSnap Checkout Secure Payment Parameters

Create Token API

Request

The following are parameters that can be included in a Create Token API request:

ParameterTypeRequiredDescription
authenticationRequired3dsbooleanOptionalPass true to ignore your 3DS excluded countries setting.
cancelUrlstringRequiredURL where BlueSnap will direct the shopper if the transaction is cancelled.
challengeRequested3dsbooleanOptionalDefault is false. This should only be set to true if the merchant wishes to mandate shopper identity verification as part of the 3D Secure authentication process. See 3D Secure Guide.
currencystringOptionalCurrency code (ISO 4217) of the amount to be charged.

Required for a regular transaction. Not relevant for a subscription.
cvvstringOptionalPass mandatory to enforce collection of CVV for a saved card payment.
lineitemsarray of objectsOptional

Required for a regular transaction.
Each object in the array contains the line-item details of the transaction, such as the goods/services purchased or shipping. At least one line-item object must be included in the request.

Each object contains the following properties:

id
string
Required

amount
total price of all units in the item
decimal
Required

quantity
number of units, does not affect total charge amount
integer
Optional (Value is 1 if missing)

label
string
Required

description
string
Optional

imgUrl
string
Optional

Note: imgUrl is the relative URL of your saved image. For example: /developers/571747/download.jpg. Make sure to choose a saved image from the BlueSnap environment you're working in.

Not relevant for a subscription.
merchantTransactionIdstringOptionalMerchant's unique ID for a new transaction. 1–50 characters. Special characters are not recommended.

Not relevant for a subscription.
modestringRequiredUse the value ‘one_time’ for a regular transaction, or the value ‘subscription’ for a subscription.
onBehalfbooleanOptionalDefault 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.
planItemsarray of objectsOptional

Required for a subscription.
Not relevant for a regular transaction.

The array contains exactly one plan-item object.

The plan-item object contains the following properties:

 id 
string
Required

recurringChargeAmount
recurring charge amount for each unit
decimal 
Optional (if missing, populated with plan data)

trialPeriodDays
integer
Optional

initialChargeAmount
initial charge amount for each unit
decimal
Optional (if missing, populated with plan data)

quantity
number of units, affects total charge amount (the quantity * amount is charged, for both initial and recurring charges)
integer
Optional (Value is 1 if missing)

label
string 
Optional

description
string
Optional

imgUrl
string
Optional

Note:
- imgUrl is the relative URL of your saved image. For example: /developers/571747/download.jpg. Make sure to choose a saved image from the BlueSnap environment you're working in.
shopperIdstringOptionalID of the shopper. This can be used to associate saved details with a shopper, allowing them to use those details for the current transaction. See Returning Shoppers.
successUrlstringRequiredURL where BlueSnap will direct the shopper if the transaction is successful. For example, this might be a confirmation page.

Response

A successful response contains the following properties:

Property NameTypeDescription
jwtstringThe JSON Web Token, used to initialize the Hosted Payment Page.
merchantTransactionIdstringIf merchantTransactionId was provided in the request, the same value will appear here.

If merchantTransactionId was not provided in the request, a value will be generated by BlueSnap to identify jwt.

sdkRequest object

sdkRequest is passed to bluesnap.redirectToPaymentPage in Step 3 of the implementation process. This object contains the following properties.

PropertyTypeRequiredDescription
displayDataobjectOptionalContains your Hosted Payment Page settings. Supports these properties
jwtstringRequiredYour token from Step 2.

sdkRequest.displayData property

The displayData property of your sdkRequest object supports these properties.

PropertyTypeRequiredDescription
customFieldsarray of objects
(10 max)
OptionalEach object in the array contains data to pre-populate the checkout page custom fields. If you wish to configure custom fields, see Configuring Page Display.

Each object contains the following properties:

id
This should correspond to either the ID or the Field Label
that is configured for the custom field that you
want to pre-populate.
string
Required

value
string | boolean
Required
hiddenFieldsarray of objects
(10 max)
OptionalEach object in the array contains a
key and value pair, which will be attached
to the transaction as part of the metaData array.

Each object contains the following properties:
key
string
Required

value
string | boolean
Required
disabledCardBrandsarray of stringsOptionalThe card brands to disable for this transaction. Default is that all the supported card brands for your configuration will be available.

Supported values:
- AMEX
- ARGENCARD
- CABAL
- CARTE_BLEUE
- CENCOSUD
- CHINA_UNION_PAY
- DINERS
- DISCOVER
- ELO
- HIPERCARD
- JCB
- MASTERCARD
- NARANJA
- TARJETASHOPPING
- VISA
disableCountrySelectionbooleanOptionalDefault is false. This should only be set to true if the merchant wishes to disable country selection and they have provided a valid shopper country.
disabledPaymentMethodsarray of stringsOptionalThe payment methods to disable for this transaction. Default is that all your supported payment methods will be available.

Supported values:
- ACSS_DIRECT_DEBIT
- APPLE_PAY
- BECS_DIRECT_DEBIT
- CC
- ECP
- GOOGLE_PAY_TOKENIZED_CARD
- IDEAL
- LBT
- PAYPAL
- SEPA
- SOFORTUBERWEISUNG
iframeOptionsobjectOptionalSettings that only apply if the Hosted Payment Page is in an iframe.

Includes one optional parameter:
topRedirect
Boolean
Default: false.
If the Hosted Payment Page is open inside of an iframe and this parameter is provided and is true, redirecting to the success/cancel URLs will redirect the parent page and not just the iframe.

Note: ApplePay and PayPal are not supported in iframe mode.
languagestringOptionalLanguage code (ISO 639-1).
Default: English.

Supported values:
- en (English)
- de (German)
- nl (Dutch)
shopperInfoobjectOptionalDetails about the shopper to pre-populate the checkout page. Supports these properties.
softDescriptorstringOptionalDescription of the transaction, which appears on the shopper's credit card statement. Maximum 20 characters.

sdkRequest.displayData.shopperInfo object

Supports the following properties.

PropertyTypeRequiredDescription
address1stringOptionalThe shopper’s first address line. Only if full billing is required.
address2stringOptionalThe shopper’s second address line. Only if full billing is required.
citystringOptionalThe shopper’s city. Only if full billing is required.
countrystringOptionalThe two-letter code of the shopper's country.
emailstringOptionalThe shopper’s email address. Only if email is required.
namestringOptionalThe shopper's name.
postalCodestringOptionalThe shopper's postal code.
statestringOptionalThe two-letter code of the shopper's state. Currently supported only for the United States, Brazil, and Canada. For states in other countries, include the state within the address1 property.

Only if full billing is required.