Skip to content

Device Payment API Server Side and Parameters

Getting Started

First, acquire a PaymentHandler that will hold keys and addresses. Then you can create a PaymentRequest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
PaymentHandler paymentHandler = new PaymentHandler(
        new JKSKeyHandlerV6("keystore.jks", "keystore-password",
                "merchant-alias", "worldline-alias"),
        "https://worldline-endpoint/");

PaymentRequest paymentRequest = new PaymentRequestBuilder()
        .setMid(1234567890L)
        .setOrderId("orderid")
        .setAmount(new BigDecimal(100.00))
        .setCurrency("USD")
        .setConsumerCountry("US")
        .setConsumerLanguage("en")
        .createPaymentRequest();

String deviceAPIRequest = paymentHandler.createDeviceAPIRequest(paymentRequest);

The last step above will sign, encrypt, base64 encode and wrap the request for use with the Worldline JavaScript API.

Decrypting and unpacking the response from Device Payment API

Upon return from the Device Payment API, the response must be decrypted in order to retrieve details on the success of the transaction, stored token etc.

The response from the Device Payment API is gotten by unpack:

PaymentResponse decodedResponse = paymentHandler.unpackResponse(response);

The decodedResponse then contains the transaction details needed for determining the state of the transaction, like:

decodedResponse.getStatus() // Easy interpreted status OK / NOK / ERROR / PENDING
decodedResponse.getTransaction() // Transaction Details.
decodedResponse.getTokenizationResult() // For Tokenized cards
decodedResponse.getAuthenticationStatus() // Easy interpreted status SUCCESSFUL / CONTINUE

For a complete list of response fields, see the response table below.

Request Parameters

The following parameters may be used when initiating a Device PaymentAPI Request.

Parameter Required? Comment Valid values Max length
MID Yes Merchant ID
Sub-merchant ID No Sub-merchant ID
POS ID No Point Of Sale ID, default ”0” Check with integration manager
Transaction channel Yes Default: ”Web Online” Web Online, Mail, Telephone, Fax, FaceToFace, Cash Register
AutoCapture No Default: true TRUE, FALSE
Token No Token of stored card
Order ID Yes Merchant assigned Order ID 50
Order description No Order description
Order Detail Description No Order Detail Description
Amount Yes Order amount,with decimal. Limit defined in integration Example: 3.47
Currency Yes Three alphabetic letter, ISO-4217 code 3
VAT amount No VAT (Value Added Tax) amount.
VAT rate No VAT rate
Country Yes Country code. ISO-3166, e.g. US. 2
Language Yes Language. ISO 639-1, e.g. en. 2
Time limit No Maximum time in seconds for request to be valid or zero if not used.
Payment method ID No Used when the consumer selects the payment method at the merchant site. Default: 1000 (Unspecified card)
Store Flag No Indicates that a token should be stored 0=Store not used, 1=Store and Debit/Authorize, 2=Store only
Billing address line 1 No Billing address line 1
Billing address line 2 No Billing address line 2
Billing city No Billing city
Billing state province No Billing state province
Billing zip code No Billing zip code
Billing country No Billing country code. ISO-3166, e.g. US.
Billing e-mail address No Billing e-mail address
Billing phone No Billing phone
Billing mobile phone No Billing mobile phone number
Billing Last Name No Billing Last Name. Will be concatenated with Billing first name to form a Billing full name.
Billing First Name No Billing First Name. Will be concatenated with Billing last name to form a Billing Full Name
Billing full name Check with integration manager Billing full name. Instead of using first+last name the full name can be submitted directly.
Shipping address line 1 No Shipping address line 1
Shipping address line 2 No Shipping address line 2
Shipping City No Shipping City
Shipping State Province No Shipping State Province
Shipping zip code No Shipping zip code
Shipping Country No Shipping Country Code. ISO-3166, e.g. US.
Shipping e-mail address No Shipping e-mail address
Shipping phone No Shipping phone number
Due date No Due date for payment. If not set, then max configured is used instead.
Payment Plan Code No Payment plan code is used to break up a payment into multiple payments(paid over time, usually monthly). This code describes the length and type of installment that should be used
Billing Company Name No Billing Company Name
Billing buyer VAT number No Billing buyer VAT number
Billing buyer type No Billing buyer type Individual Business
Shipping Company Name No Shipping Company Name
Shipping Address Line 3 No Shipping Address Line 3
Billing Address Line 3 No Billing Address Line 3
Birth date No Birth Date
Company responsible birth date No Birth date of the responsible person at the company
Company responsible full name No Full Name of the responsible person at the company 50
Company responsible VAT number No VAT(Value Added Tax) number for the responsible person at the company 25
POS description No POS description
Shipping mobile phone No Shipping mobile phone
Shipping Last Name No Shipping Last Name. Will be concatenated with Shipping first name to form a Shipping Full Name
Shipping First Name No Shipping First Name. Will be concatenated with Shipping last name to form a Billing Full Name
Shipping full name No Instead of using first+last name the full name can be submitetd directly
Billing SSN No Billing Social Security Number 30
Company tax ID No Company tax ID 50
Gender No Gender, used for fraud screening for some payment methods
Billing Street Name No Street name, used together with House Number instead of ”Address Line 1” for Klarna in certain countries
Billing House Number No House Number, used together with Street Name instead of ”Address Line 1” for Klarna in certain countries
Shipping Street Name No Shipping Street Name
Shipping House Number No Shipping House Number
Authorization Type No Authorization type: Mastercard now require merchants to define authorization attempts as either a pre-authorization or a final-authorization. Final authorizations that meetMastercard criteria will be free of scheme fee impact but pre-authorizations and undefined authorization attempts will be subject to additional scheme fees. UNDEFINED, PRE_AUTHORIZATION, FINAL_AUTHORIZATION

Request Parameters specific to 3D Secure

The following parameters may be used along with the Request Parameters mentioned above to initiate a 3DS Request.

Parameter Required? Comment Valid values Max length
PurchaseInstallment No Indicates the maximum number of authorisations permitted for instalment payments Value should be greater than 1 3
AcctID No Additional information about the account optionally provided by the 3DS Requestor 64
AcctType No Indicates the type of account for a multi-account card product 01 = Not Applicable, 02 = Credit, 03 = Debit, 04–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo), 80–99 = DS or Payment System-specific 2
AddrMatch No Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same Y = Shipping Address matches Billing Address, N = Shipping Address does not match Billing Address 1
MessageCategory No Identifies the category of the message for a specific use case 01 = PA (Payment), 02 = NPA (Non-Payment), 03–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo), 80–99 = Reserved for DS use 2
PurchaseDate No Date and time of the purchase expressed in UTC Format accepted: YYYYMMDDHHMMSS 14
TransType No Identifies the type of transaction being authenticated 01 = Goods/ Service Purchase, 03 = Check Acceptance, 10 = Account Funding, 11 = Quasi-Cash Transaction, 28 = Prepaid Activation and Load Note: Values derived from the 8583 ISO Standard 2
ThreeRIInd No Indicates the type of 3RI request 01 = Recurring transaction, 02 = Instalment transaction, 03 = Add card, 04 = Maintain card information, 05 = Account verification, 06 = Split/delayed shipment, 07 = Top-up, 08 = Mail Order, 09 = Telephone Order, 10 = Whitelist status check, 11 = Other payment, 12–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo), 80–99 = Reserved for DS use 2
ThreeDSRequestorAuthenticationInd No Indicates the type of Authentication request 01 = Payment transaction, 02 = Recurring transaction, 03 = Instalment transaction, 04 = Add card, 05 = Maintain card, 06 = Cardholder verification as part of EMV token ID&V, 07–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo), 80–99 = Reserved for DS use 2
ThreeDSRequestorChallengeInd No Indicates whether a challenge is requested for this transaction 01 = No preference, 02 = No challenge requested, 03 = Challenge requested (3DS Requestor preference), 04 = Challenge requested (Mandate), 05 = No challenge requested (transactional risk analysis is already performed), 06 = No challenge requested (Data share only), 07 = No challenge requested (strong consumer authentication is already performed), 08 = No challenge requested (utilise whitelist exemption if no challenge required), 09 = Challenge requested (whitelist prompt requested if challenge required) 2
ChallengeWindowSize No Dimensions of the challenge window that has been displayed to the Cardholder 01 = 250 x 400, 02 = 390 x 400, 03 = 500 x 600, 04 = 600 x 400, 05 = Full screen 2
ShipIndicator No Indicates shipping method chosen for the transaction 01 = Ship to cardholder’s billing address, 02 = Ship to another verified address on file with merchant, 03 = Ship to address that is different than the cardholder’s billing address, 04 = “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields), 05 = Digital goods (includes online services, electronic gift cards and redemption codes), 06 = Travel and Event tickets, not shipped, 07 = Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.) 2
DeliveryTimeframe No Indicates the merchandise delivery timeframe 01 = Electronic Delivery, 02 = Same day shipping, 03 = Overnight shipping, 04 = Two-day or more shipping 2
DeliveryEmailAddress No For Electronic delivery, the email address to which the merchandise was delivered 254
ReorderItemsInd No Indicates whether the cardholder is reordering previously purchased merchandise 01 = Merchandise available, 02 = Future availability 2
PreOrderPurchaseInd No Indicates whether Cardholder is placing an order for merchandise with a future availability or release date 01 = Merchandise available, 02 = Future availability 2
PreOrderDate No For a pre-ordered purchase, the expected date that the merchandise will be available Format accepted: Date format = YYYYMMDD 8
GiftCardAmount No For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). Example: gift card amount is USD 123.45: Values accepted: 123, 0123, 00123 15
GiftCardCurr No For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card 3
GiftCardCount No For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased 2
ChAccAgeInd No Length of time that the cardholder has had the account with the 3DS Requestor 01 = No account (guest check-out), 02 = Created during this transaction, 03 = Less than 30 days, 04 = 30−60 days, 05 = More than 60 days 2
ChAccDate No Date that the cardholder opened the account with the 3DS Requestor Format accepted: Date format = YYYYMMDD 8
ChAccChangeInd No Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added 01 = Changed during this transaction, 02 = Less than 30 days, 03 = 30−60 days, 04 = More than 60 days 2
ChAccChange No Length of time since the cardholder’s account information with the 3DS Requestor was last changed, including Billing or Shipping address, new payment account, or new user(s) added 01 = Changed during this transaction, 02 = Less than 30 days, 03 = 30−60 days, 04 = More than 60 days 2
ChAccPwChangeInd No Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset 01 = No change, 02 = Changed during this transaction, 03 = Less than 30 days, 04 = 30−60 days, 05 = More than 60 days 2
ChAccPwChange No Date that cardholder’s account with the 3DS Requestor had a password change or account reset Format accepted: Date format = YYYYMMDD 8
NbPurchaseAccount No Number of purchases with this cardholder account during the previous six months 13 4
ProvisionAttemptsDay No Number of Add Card attempts in the last 24 hours Example values accepted: 2, 02, 002 3
TxnActivityDay No Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours Example values accepted: 2, 02, 002 3
TxnActivityYear No Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year Example values accepted: 2, 02, 002 3
ShipAddressUsageInd No Indicates when the shipping address used for this transaction was first used with the 3DS Requestor 01 = This transaction, 02 = Less than 30 days, 03 = 30−60 days, 04 = More than 60 days 2
ShipAddressUsage No Date when the shipping address used for this transaction was first used with the 3DS Requestor Format accepted: Date format = YYYYMMDD 8
ShipNameIndicator No Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction 01 = Account Name identical to shipping Name, 02 = Account Name different than shipping Name 2
PaymentAccInd No Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor 01 = No account (guest check-out), 02 = During this transaction, 03 = Less than 30 days, 04 = 30−60 days, 05 = More than 60 days 2
PaymentAccAge No Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor Format accepted: Date format = YYYYMMDD 8
SuspiciousAccActivity No Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account 01 = No suspicious activity has been observed, 02 = Suspicious activity has been observed 2
ThreeDSReqAuthMethod No 3DS 2.0 extra authentication information about how the 3DS Requestor authenticated the cardholder before or during the transaction 01 = No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest), 02 = Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials, 03 = Login to the cardholder account at the 3DS Requestor system using federated ID, 04 = Login to the cardholder account at the 3DS Requestor system using issuer credentials, 05 = Login to the cardholder account at the 3DS Requestor system using third-party authentication, 06 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator, 07 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator (FIDO assurance data signed), 08 = SRC Assurance Data, 09–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) 80–99 = Reserved for DS use 2
ThreeDSReqAuthTimestamp No 3DS 2.0 extra authentication information of Date and time in UTC about how the 3DS Requestor authenticated the cardholder before or during the transaction Format accepted: Date format = YYYYMMDDHHMM 12
ThreeDSReqPriorRef No Data that documents and supports a specific authentication process about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction. 20,000
ThreeDSReqPriorAuthMethod No 3DS 2.0 extra authentication information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction 01 = Frictionless authentication occurred by ACS, 02 = Cardholder challenge occurred by ACS, 03 = AVS verified, 04 = Other issuer methods, 05–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo), 80–99 = Reserved for DS use 2
ThreeDSReqPriorAuthTimestamp No 3DS 2.0 extra authentication information of Date and time in UTC about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction Format accepted:
Date format = YYYYMMDDHHMM 12

Response Details

Parameter Description Example
Status Transaction status. See below. OK
MerchantId MerchantId, same as in request. Assigned by Worldline 1234567890
OrderId OrderId, same as in request. Unique order ID assigned by merchant. redbike-47123
POSId Point of sale ID, same as in request. 0
TransactionId Worldline Transaction reference of the payment. 12345678901
Payment method name Payment Method name, either the resolved card payment method. Mastercard, Nordea
Transaction Description Description of the transaction performed Transaction Accepted
Token In case that the request was done with a request to store the payment method, the token represents the assigned token to use in further recurring transactions. 9000123123112234
Token Masked Card The masked card number, fist 6 and last 4, of the successful tokenization 543215xxxxxx1234
Token Expiry date The expiry of the card number that was tokenized 03-2020
Currency Currency used in the transaction BRL
Order Amount The amount expected to be paid on the transaction 100.00
Fulfilment Amount The amount that was successfully authorized with the acquirer 100.00
Captured Amount The amount that was requested to be captured. In this API, this would be the same as fulfilment amount if auto-capture flag was used in the request, otherwise 0. 100.00
Refunded Amount The amount requested to be refunded on the order. This is usable in split tender payments, where there could be several transactions on an order. 0.00
Transaction State A high-level state on the transaction; Processed, Declined or System Error. Processed
PaymentSlip Url Link to payment slip in case of wire transfer payment mode https://sandbox.ebanxpay.com/print/?hash=5cdbfc9faeec46d7bf74edc7020ea7fbd54b58149acb0202
Authentication Status Status returned by different authentication methods REQUIRED
Authentication Status Description Descriptive text matching AuthenticationStatus.

Details on the Status

Status Description
OK The payment has been successfully processed.
AUTHENTICATION Status returned by authentication request.
NOK The payment was not completed. The user has used several attempts to submit a payment and ultimately been redirected back to the merchant due to exceeding the (configurable) maximum number of retries. NOK may also be returned if Worldline detects a possible fraud attempt.
USERCANCEL The consumer pressed a cancel button.
TIMEOUT The consumer tried to initiate a payment after the timeout set by the merchant has expired.
PENDING The final status of the payment is not yet determined. The final status of the payment will be notified via a notification, in a report or pulled from Worldline Web Interface depending on your setup. Note that this is an expected result for many payment methods.
ERROR The Device Payment API has detected that there is something wrong in the URL content or the configuration of the merchant. If this result status is encountered, the merchant should review their parameters and contact Worldline if the problem cannot be identified.

Details on the Authentication Status

Authentication Status Description
SUCCESSFUL Status returned by Initiate, Continue or Complete Authentication request that indicates the authentication is successful and can proceed with the existing card payment flow.
CONTINUE Status returned by Initiate Authentication request that indicates the next step is Continue Authentication which is optional.
REQUIRED Status returned by Initiate and Continue Authentication request that indicates Complete authentication is required and once Complete authentication is successful can proceed with the card payment flow.
NOT_REQUIRED Status returned by Initiate Authentication request that indicates Continue and Complete authentication is not required and can proceed with the existing card payment flow.
ATTEMPTED Status returned by Initiate, Continue and Complete Authentication request that indicates authentication is attempted.
TRY_AGAIN Status returned by Initiate, Continue and Complete Authentication request that indicates authentication is not successful.