Specification

Required 
You have two merchant numbers: a test merchant number (used for testing only) and production merchant number for real payments. Find your merchant numbers in the Bambora menu under Settings -> Payment system.

Required
The currency parameter accepts the currency number as well as the currency code, e.g. 208 or DKK. Find a complete list of valid currencies here.

Required
The amount specified in minor units. For the currency GBP, the amount must be specified in “pennies”. An amount of GBP 104,99 must be specified as 10499. For currencies without minor units, the amount 95 is specified as 95.

The parameter doesn’t accept any separators (e.g. dot (.) as thousands separator).

amount can be set to 0 (zero) if subscription is enabled.

The order ID from your own system. This order ID is used as reference between your own system and Bambora. Any numbers from 0-9 and characters from a-Z are allowed.

Non-numeric characters will be stripped for Swedbank.

Notice!
Nets/Teller supports up to 9 characters in the order ID.
Bambora and Swedbank support a maximum of 12 characters.

Define which payment window to use. If you have several shops/domains and want to open different payment windows (with different logos or settings) for each domain, use the parameter windowid to govern which window to open.

You can see your payment windows in the Bambora administration under Settings -> Payment window.

This parameter is used to activate the mobile payment window. Please note that not all payment methods are supported by the mobile payment window.

Name	Value
Deactivated	0
Auto detect (default)	1
Force	2

A payment collection is a grouping of all the different payment types. By setting this value, the payment window will open with this collection method selected.

Customer choice	0
Payment cards	1
Giftcard	6
Home banking	2
Invoice	3
Mobile	4
Other	5
ViaBill	7

You can lock your payment collection method if paymentcollection is set. This means the customer cannot change the collection method. For instance, if you only want to accept payments by payment card, set paymentcollection to 1 and lockpaymentcollection to 1.

Disabled	0
Enabled	1

The paymenttype parameter is used to define which payment types logos to show. You can define multiple payment types by separating the values with comma (,). For instance, if you only want to accept Dankort, Visa, and MasterCard, use the following value: 1,3,4. This will not block payments from payment types not defined. Contact Bambora if you don’t want to accept payments from a specific payment type.

A defined payment type is ignored if paymentcollection is set and the payment type is not in this collection.

Name	Value	Payment method
Dankort/Visa Dankort	1	Payment cards
Visa / Visa Electron	3	Payment cards
Mastercard	4	Payment cards
JCB	6	Payment cards
Maestro	7	Payment cards
Diners Club	8	Payment cards
American Express	9	Payment cards
Forbrugsforeningen	11	Payment cards
Danske Netbetalinger	13	Home banking
PayPal	14	Other
Klarna	17	Invoice
SveaWebPay	18	Invoice
SEB (SE)	19	Home banking
Nordea (SE)	20	Home banking
Handelsbanken (SE)	21	Home banking
Swedbank (SE)	22	Home banking
ViaBill	23	ViaBill
Beeptify	24	Other
iDEAL	25	Home banking
Paii	27	Mobile
Brandts Gavekort	28	Giftcard
MobilePay Online	29	Mobile
Ekspress Bank	31	Other
Masterpass	34	Other

This is the language displayed in the payment window. If you use auto detection and the found language is not available, the language shifts to English.

If this parameter is not defined, the default setting is Danish.

You can edit the texts shown in the payment window. To do so, go to Settings -> Payment window in your Bambora administration, and open the translation tool. Next, click on ‘Create language’, choose the language you want to create, and attach it to a country. Press the button ‘Edit translations’ by the language you just created. You will now see the language files, and you can edit the translations for the language.

Auto Detect (default)	0
Danish	1
English	2
Swedish	3
Norwegian	4
Greenlandic	5
Icelandic	6
German	7
Finnish	8
Spanish	9
French	10
Polish	11
Italian	12
Dutch	13

The encoding of your data. The standard format is UTF-8.

This parameter overrides parts of the payment window stylesheet. To use this parameter, a valid http or https URL pointing to the location of your stylesheet must be specified.

Note: The CSS needs to be placed at a valid domain added in our systems

Please download our example of a CSS stylesheet here.

Set a custom theme for the mobile window with this parameter.

Our mobile theme can be downloaded from here.

Enable this parameter to capture payments instantly (as soon as they are authorised). By default, this value is 0, and the payment must be captured manually in the Bambora administration.

You may only use this parameter if the goods are delivered instantly, such as downloads or services.

Notice!
When using instantcapture for payments to Teller, two operations are made: authorize and capture. Sometimes the capture fails, which results in a complete decline of the transaction.

Capture manually	0
Enabled	1

If an order is split into several deliveries, this parameter can be enabled to capture the payments as the deliveries are shipped. As such, you can split the payment into two or more transactions and capture smaller parts of the amount one at a time.

At this point, Nets and Teller are the only acquirers that support split payments. The other acquirers will be added later.

Notice!
If splitpayment is enabled and is not supported by the acquirer, the payment will be processed as a regular payment which cannot be split into several transactions.

splitpayment is not available for 3D Secure payments.

Disabled	0
Enabled	1

The URL to which customers are sent when the payment is approved and the payment window is closed. If ownreceipt is set to 1, the customer is sent directly to the accepturl.

This is a URL the customers are directed to if the payment window is closed before the payment is completed. This is only used if windowstate is 3.

Notice!
The domain must be registered in your Bambora administration under Settings -> Payment system. If the domain is not registered, you will get an error message.

This URL is used to update the ordering system, also called (I)PN or (Instant) Payment Notification. When the payment is approved, ePay calls this URL as if it was an accepturl (server to server).

Notice!
The domain must be added in your Bambora administration under Settings -> Payment system. If the domain is not registered, you will get an error message.

If you use callbacks, you can set this parameter to determine when your callbackurl is called.

Asynchronously	0
Enabled	1

When using this parameter, the customers are redirected to your accepturl as soon as the payment is made. The receipt shown in the payment window is skipped. A valid accepturl must be defined to use ownreceipt.

Receipt in the payment window	0
Own receipt	1

This defines a text shown in the payment window while the payment is being completed, and on the receipt. The text will appear on the printout of the receipt.

The group to which the payment is associated. The parameter is a string which can contain a-Z and 0-9. If the group doesn't exist, it is automatically created when you start using the parameter.

Click here to read more about groups.

This is the description of the payment. This description can be seen in the Bambora administration. Please remember to use encoding to avoid issues with special characters.

This field is used to create an MD5 stamp in the internet shop, which is validated by Bambora to avoid customers manipulate with the data. The stamp has to be created by the value of all parameters sent to Bambora combined with the Bambora secret key.

Examples are available here.

If this parameter is enabled, a subscription is created. The amount can be set to 0 (zero) to create a new subscription without completing a transaction. A unique subscriptionid will be returned to your accepturl and callbackurl.

When you want to make a new authorisation on your subscription, you must complete it through our subscription web service.

Disabled (default)	0
Create subscription	1
Update subscription	2

Notice
A subscription cannot be created if you're using one of the following payment methods:

• Nordea e-betaling
• Danske Netbetaling
• PayPal
  
  

When subscription = 2, subscriptionid must be the ID of the subscription you want to update.

This can be used in connection with subscription. If subscription is set to 1, a name or reference can be specified. If not set, the value of orderid will be used as the subscriptionname.

Use this to receive an email with information about the payment when it is completed. This is NOT used for your customer's order confirmation.

This field is used in order to track your orders using Google Analytics. Typically it will be in the form UA-XXXXX-X.

In Analytics, these pages are the tracked:

/epay-close.html => Payment window is closed.
/epay-decline.html => Payment rejected - the customer can try again.
/epay-accept.html => Payment accepted.
/epay-payment.html => Customer is sent to the payment window.
/epay-selectpayment.html => Customer chooses payment.

You have to set up 'cross domain auto linking' to track correctly. Please read more here: https://developers.google.com/analytics/devguides/collection/analyticsjs/cross-domain#autolink

If you want to track your conversions, we recommend that you use ownreceipt to send your customer to your own order receipt page.

This defines the background color for the payment window if windowstate is either 1 or 2. For windowstate = 1, the background color is affected by the opacity parameter.

This specifies the opacity of the backgroundcolor if windowstate is 1. The opacity can be set to a value between 0 and 100.

This overwrites the text shown when a payment is declined.

Define a time span in which it is possible to complete the payment. The value of timeout equals the number of minutes, e.g. "15" for 15 minutes.

The invoice parameter is used to handle invoice payments. Click here to read more about invoice data.

The accountinformation object must be converted to a JSON string and added to the paymentwindow request

Name	Values	Comment
authentication.data	Type: string	Data that documents and support the method used by the customer to authenticate to the account.
authentication.method	Type: string Values: "NoAuthentication", "FederatedId", "ThirdPartyAuthentication", "FidoAuthenticator"	Method used by the customer to authenticate, or log in, to the account.
authentication.timestamp	Type: string	Date and time, in ISO 8601 format, when the customer authenticated.
prior3dsauthentication.data	Type: string	Data that documents and support 3DS authentication of the customer prior to this transaction.
prior3dsauthentication.method	Type: string Values: "FrictionlessAuthenticationOccurredByAcs", "CardholderChallengeOccurredByAcs", "AvsVerified", "OtherIssuerMethods"	3DS authentication method of the customer prior to this transaction.
prior3dsauthentication.reference	Type: string Values: UUID	Reference, as a UUID, to the 3DS authentication of the customer prior to this transaction.
prior3dsauthentication.timestamp	Type: string	Date and time, in ISO 8601 format, when the 3DS authentication happened.
createdindicator	Type: string Value: "NoAccount", "CreatedDuringTransaction", "LessThan30Days", "Between30And60Days", "MoreThan60Days"	Length of time the customer has had the account used with this purchase. This value can be set if the exact account creation date is unknown
createddate	Type: string	The date, in ISO 8601 format, when the customer account used with this purchase was created.
changedindicator	Type: string Values: "ChangedDuringThisTransaction", "LessThan30Days", "Between30And60Days", "MoreThan60Days"	The length of time since the customer account used with this purchased was last changed, including billing or shipping address, new payment account, or new user(s) added. This value can be set if the exact account changed date is unknown.
changeddate	Type: string	The date, in ISO 8601 format, when the customer account used with this purchase was last changed, including billing or shipping address, new payment account, or new user(s) added.
nameidenticaltoshippingaddressname	Type: boolean	Indication if customer/cardholder name is identical to shipping address name.
passwordchangedindicator	Type: string Values: "NoChange", "ChangedDuringThisTransaction", "LessThan30Days", "Between30And60Days","MoreThan60Days"	The length of time since the customer account used with this purchase had a password change or account reset. This value can be set if the exact password change date is unknown.
passwordchangeddate	Type: string	The date, in ISO 8601 format, when the customer account used with this purchase had a password change or account reset.
shippingaddressfirstusedindicator	Type: string Values: "ThisTransaction", "LessThan30Days", "Between30And60Days", "MoreThan60Days"	The length of time since the shipping address used for this purchase was first used by the customer. This value can be set if the exact date is unknown.
shippingaddressfirstuseddate	Type: string	The date, in ISO 8601 format, when the shipping address used for this purchase was first used by the customer.
shippingaddressidenticaltobillingaddress	Type: boolean	Indication if customer billing address is identical to the shipping address.
transactionspast24hours	Type: integer	Transactions, both approved and declined, during the past 24 hours for this customer account, across all payment accounts and methods.
transactionspastyear	Type: integer	Transactions, both approved and declined, during the past year for this customer account, across all payment accounts and methods.
transactionsapprovedpastsixmonths	Type: integer Max value: 999	Approved transactions, or purchases, for this customer account during the last six months
paymentaccountcreatedindicator	Type: string Values: "NoAccount", "DuringThisTransaction", "LessThan30Days", "Between30And60Days", "MoreThan60Days"	The length of time since the payment account used for this purchase was created with the customer account. This value can be set if the exact date is unknown.
paymentaccountcreateddate	Type: string	The date, in ISO 8601 format, when the paymen account used for this purchase was created with the customer account.
provisionattemptspast24hours	Type: integer	The number of tokenize card attempts, successful or not, during the past 24 hours.
suspiciousactivity	Type: boolean	Indication if any suspicious activity, including fraud, has been experienced on the account.

Example

"accountinformation": { "authentication": { "data": "", "method": "No3DSRequestorAuthenticationOccurred", "timestamp": "2016-04-30T00:00:00.000Z" }, "prior3dsauthentication": { "data": "", "method": "FrictionlessAuthenticationOccurredByAcs", "reference": "0a137f3d-9fcf-4040-b6c7-e596cb79d953", "timestamp": "2016-04-30T00:00:00.000Z" }, "createdindicator": "NoAccount", "createddate": "2016-04-30T00:00:00.000Z", "changedindicator": "ChangedDuringThisTransaction", "changeddate": "2016-04-30T00:00:00.000Z", "nameidenticaltoshippingaddressname": True, "shippingaddressfirstusedindicator": "ThisTransaction", "shippingaddressfirstuseddate": "2016-04-30T00:00:00.000Z", "shippingaddressidenticaltobillingaddress": True, "transactionspast24hours": 1, "transactionspastyear": 17, "transactionsapprovedpastsixmonths": 34, "passwordchangedindicator": "NoChange", "passwordchangeddate": "2016-04-30T00:00:00.000Z", "paymentaccountcreatedindicator": "NoAccount", "paymentaccountcreateddate": "2016-04-30T00:00:00.000Z", "provisionattemptspast24hours": 3, "suspiciousactivity": False } 

Type: integer 
Max value: 9999

The minimum number of days between authorizations on the subscription. Use 1 for irregular intervals or if unknown. If no value is supplied we will default the value to 1.

Type: string

The expiration date of the subscription, when no further authorizations will be made, in ISO 8601 format. If no values is supplied we will set a value based on the card expiration date.

The merchantrisk object must be converted to a JSON string and added to the paymentwindow request

Name	Values	Comment
shippingmethod	Type: string Values: "ShipToBillingAddress", "ShipToAnotherVerifiedAddress", "ShipToAddressDifferentThanBillingAddress", "PickUpAtLocalStore", "DigitalGoods", "TravelAndEventTicketsNotShipped", "Other"	Shipping method chosen for this purchase.
deliverytimeframe	Type: string Values: "ElectronicDelivery", "SameDayShipping", "OvernightShipping", "TwoDayOrMoreShipping"	Delivery time frame for this purchase.
deliveryemail	Type: string	The email address used for delivery for purchase that requires electronic delivery.
reorderitemsindicator	Type: string Values: "FirstTime", "Reordered"	Indication if the customer has ordered the item(s) previously.
orderavailability	Type: string Values: "MerchandiseAvailable", "FutureAvailablility"	The order availability for this purchase.
preorderavailabilitydate	Type: string	For a pre-order purchase, the expected date, in ISO 8601 format, when the order will be available.
giftcard.currency	Type: string Length: 3	For prepaid or gift cards purchased, the currency of the cards in ISO 4217 format.
giftcard.amount	Type: integer Min value: 0	For prepaid or gift cards purchased, the total amount in minorunits of the cards.
giftcard.count	Type: integer Min value: 0 Max value: 99	The number of prepaid or gift cards purchased.

Example

"merchantrisk": { "shippingmethod": "ShipToCardholdersBillingAddress", "deliverytimeframe": "SameDayShipping", "deliveryemail": "john.doe@example.com", "reorderitemsindicator": "FirstTime", "orderavailability": "MerchandiseAvailable", "preorderavailabilitydate": "2016-04-30T00:00:00.000Z", "giftcard": { "currency": "SEK", "amount": 123, "count": 1 } } 

Type: string 
Values: "recurring", "cardonfile"

Indicates if the subscription is a recurring payment subscription or a cardonfile subscription. Default is recurring.

Default: "recurring"

Type: string 
Values: "none", "require3d"

The security level to be used for SCA. No value means "no preference" and decision will be up to issuer, whereas "None" means SCA excemption, and "Required3D" means mandate SCA.

Type: string 
Values: "LowValuePayment"

The exemption to be used, if omitted, exemption is not attempted for payment.