Specification
This section describes the available parameters separately.
merchantnumberRequired
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 ePay menu under Settings -> Payment system.
currencyRequired
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.
amountRequired
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.
orderid
The order ID from your own system. This order ID is used as reference between your own system and ePay. Any numbers from 0-9 and characters from a-Z are allowed.
Non-numeric characters will be stripped for Swedbank.
Nets/Teller supports up to 9 characters in the order ID. ePay and Swedbank support a maximum of 12 characters.
windowid
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 ePay administration under Settings -> Payment window.
mobile
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 |
paymentcollection
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.
| Name | Value |
|---|---|
| Customer choice | 0 |
| Payment cards | 1 |
| Giftcard | 6 |
| Home banking | 2 |
| Invoice | 3 |
| Mobile | 4 |
| Other | 5 |
| ViaBill | 7 |
lockpaymentcollection
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.
| Name | Value |
|---|---|
| Disabled | 0 |
| Enabled | 1 |
paymenttype
The paymenttype parameter is used to define which payment type logos to show. You can define multiple payment types by separating the values with a 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 ePay 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 |
language
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 ePay 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 |
encoding
The encoding of your data. The standard format is UTF-8.
cssurl
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 to our systems
Please download our example of a CSS stylesheet here.
mobilecssurl
Set a custom theme for the mobile window with this parameter.
Our mobile theme can be downloaded from here. Start by importing this into ThemeRoller. Modify the theme and download it. Upload the *.css file to your website, and set the mobilecssurl to the public location. The mobile window will now use your custom theme.
instantcapture
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 ePay administration.
You may only use this parameter if the goods are delivered instantly, such as downloads or services.
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.
| Name | Value |
|---|---|
| Capture manually | 0 |
| Enabled | 1 |
splitpayment
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.
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.
| Name | Value |
|---|---|
| Disabled | 0 |
| Enabled | 1 |
accepturl
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.
cancelurl
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.
The domain must be registered in your ePay administration under Settings -> Payment system. If the domain is not registered, you will get an error message.
callbackurl
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).
The domain must be added in your ePay administration under Settings -> Payment system. If the domain is not registered, you will get an error message.
instantcallback
If you use callbacks, you can set this parameter to determine when your callbackurl is called.
| Name | Value |
|---|---|
| Asynchronously | 0 |
| Enabled | 1 |
ownreceipt
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.
| Name | Value |
|---|---|
| Receipt in the payment window | 0 |
| Own receipt | 1 |
ordertext
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.
group
The group to which the payment is associated. The parameter is a string that can contain a-Z and 0-9. If the group doesn't exist, it is automatically created when you start using the parameter.
Read more about groups in the FAQ.
description
This is the description of the payment. This description can be seen in the ePay administration. Please remember to use encoding to avoid issues with special characters.
hash
This field is used to create an MD5 stamp in the internet shop, which is validated by ePay to avoid customers manipulating the data. The stamp has to be created by the value of all parameters sent to ePay combined with the ePay secret key.
subscription
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.
You need a separate agreement with your acquirer to use this feature. Please contact your acquirer for more information.
| Name | Value |
|---|---|
| Disabled (default) | 0 |
| Create subscription | 1 |
| Update subscription | 2 |
A subscription cannot be created if you're using one of the following payment methods:
- Nordea e-betaling
- Danske Netbetaling
- PayPal
subscriptionid
When subscription = 2, subscriptionid must be the ID of the subscription you want to update.
subscriptionname
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.
mailreceipt
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.
googletracker
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 tracked:
| URL | Description |
|---|---|
| /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.
backgroundcolor
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.
opacity
This specifies the opacity of the backgroundcolor if windowstate is 1. The opacity can be set to a value between 0 and 100.
declinetext
This overwrites the text shown when a payment is declined.
timeout
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.
invoice
The invoice parameter is used to handle invoice payments. Click here to read more about invoice data.
accountinformation
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 }
recurringfrequency
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.
recurringexpiration
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.
merchantrisk
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 } }
subscriptiontype
Type: string
Values: "recurring", "cardonfile"
Indicates if the subscription is a recurring payment subscription or a cardonfile subscription. Default is recurring.
Default: "recurring"
securitylevel
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.
securityexemption
Type: string
Values: "LowValuePayment"
The exemption to be used, if omitted, exemption is not attempted for payment