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
Java
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:
Java
PaymentResponse decodedResponse = paymentHandler.unpackResponse(response);
The decodedResponse then contains the transaction details needed for determining the state of the transaction, like:
Java
decodedResponse.getStatus() // Easy interpreted status OK / NOK / ERROR / PENDING
decodedResponse.getTransaction() // Transaction Details.
decodedResponse.getTokenizationResult() // For Tokenized cards
decodedResponse.getClientAnswerCode() // For Client answer code
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 | ||
| Strong Customer Authentication | No | Default:true | TRUE, FALSE Required for strong customer authentication | |
| Payment Authentication Level | No | Default:Proceed when SCA successful | To continue the payment for unsuccessful authentications | |
| 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. |