Payment Page Parameters¶
Request Parameters¶
The following parameters may be used when initiating a PaymentAPI Request.
| Parameter | Required? | Name | Comment | Valid values | Max length |
|---|---|---|---|---|---|
| MID | Yes | A | Merchant ID | ||
| Sub-merchant ID | No | B | Sub-merchant ID | ||
| POS ID | Check with integration manager | C | Point Of Sale ID, default ”0” | ||
| Transaction channel | Yes | D | Transaction channel. Typically “Web Online”. | Web Online, Mail, Telephone, Fax, FaceToFace, Cash Register | |
| Transaction type | No | E | Transaction type | debit,authorize,refund | |
| Token | No | F | Previously stored token | ||
| Order ID | Yes | G | Order ID | 50 | |
| Order description | No | H | Order description | ||
| Order Detail Description | No | I | Order Detail Description | ||
| Amount | Yes | J | Order amount,with decimal. Limit defined in integration | Example: 3.47 | |
| Currency | Yes | K | Three alphabetic letter, ISO-4217 code | 3 | |
| VAT amount | No | L | VAT (Value Added Tax) amount. | ||
| VAT rate | No | M | VAT rate | ||
| Country | Yes | T | Country code. ISO-3166, e.g. US. Used together with language to form the locale being used by Payment | 2 | |
| Language | Yes | U | Language. ISO 639-1, e.g. en. Used together with country to form the locale being used by Payment Page | 2 | |
| Return URL | Yes | V | URL for consumer redirect back to merchant. | ||
| Time limit | No | W | Maximum time in seconds for request to be valid or zero if not used. | ||
| Additional parameters | No | Y | Additional parameters. Used for ${param.*} in template. Name-value pair, separated by ‘#’. E.g. “PARAM1=VALUE1#PARAM2=VALUE2#” | ||
| Payment method ID | No | Z | Used when the consumer selects the payment method at the merchant site. | ||
| Store Flag | No | AA | Indicates that a token should be stored | 0=Store not used, 1=Store and Debit/Authorize, 2=Store only | 1 |
| Template reference | No | AB | Template reference. Specifies which page to present. | ||
| Billing address line 1 | No | AG | Billing address line 1 | ||
| Billing address line 2 | No | AH | Billing address line 2 | ||
| Billing city | No | AI | Billing city | ||
| Billing state province | No | AJ | Billing state province | ||
| Billing zip code | No | AK | Billing zip code | ||
| Billing country | No | AL | Billing country code. ISO-3166, e.g. US. | 2 | |
| Billing e-mail address | No | AM | Billing e-mail address | ||
| Billing phone | No | AN | Billing phone number | ||
| Billing mobile phone | No | AO | Billing mobile phone number | ||
| Billing Last Name | Check with integration manager | AP | Billing Last Name. Will be concatenated with Billing first name to form a Billing full name. | ||
| Billing First Name | Check with integration manager | AQ | Billing First Name. Will be concatenated with Billing last name to form a Billing Full Name | ||
| Billing full name | Check with integration manager | AR | Billing full name. Instead of using first+last name the full name can be submitted directly. | ||
| Shipping address line 1 | No | AS | Shipping address line 1 | ||
| Shipping address line 2 | No | AT | Shipping address line 2 | ||
| Shipping City | No | AU | Shipping City | ||
| Shipping State Province | No | AV | Shipping State Province | ||
| Shipping zip code | No | AW | Shipping zip code | ||
| Shipping Country | No | AX | Shipping Country Code. ISO-3166, e.g. US. | 2 | |
| Shipping e-mail address | No | AY | Shipping e-mail address | ||
| Shipping phone | No | AZ | Shipping phone number | ||
| Due date | No | BA | Due date for payment. If not set, then max configured is used instead. | ||
| Payment Plan Code | No | BB | 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 | BC | Billing Company Name | ||
| Billing buyer VAT number | No | BD | Billing buyer VAT number | 25 | |
| Billing buyer type | No | BE | Billing buyer type | Individual Business | |
| Shipping Company Name | No | BG | Shipping Company Name | ||
| Shipping Address Line 3 | No | BH | Shipping Address Line 3 | ||
| Billing Address Line 3 | No | BJ | Billing Address Line 3 | ||
| Birth date | No | BT | Birth Date | ||
| Company responsible birth date | No | CB | Birth date of the responsible person at the company | ||
| Company responsible full name | No | CN | Full Name of the responsible person at the company | 50 | |
| Company responsible VAT number | No | CV | VAT(Value Added Tax) number for the responsible person at the company | 25 | |
| Recurring Type | No | EA | Recurring type. Mandatory for SEPA Direct Debit. | NOT_RECURRING,FIRST_RECURRING,SUBSEQUENT_RECURRING,LAST_RECURRING | |
| POS description | No | PD | Point of sale description | ||
| Shipping mobile phone | No | AAA | Shipping mobile phone | ||
| Shipping Last Name | No | AAB | Shipping Last Name. Will be concatenated with Shipping first name to form a Shipping Full Name | ||
| Shipping First Name | No | AAC | Shipping First Name. Will be concatenated with Shipping last name to form a Billing Full Name | ||
| Shipping full name | No | AAD | Instead of using first+last name the full name can be submitetd directly | ||
| Billing SSN | No | AAE | Billing Social Security Number | 30 | |
| Company tax ID | No | AAF | Company tax ID | 50 | |
| Gender | No | AAG | Gender, used for fraud screening for some payment methods | ||
| Billing Street Name | No | AAH | Street name | ||
| Billing House Number | No | AAI | House Number | ||
| Billing House Extension | No | AAJ | House extensiona (for example “B”) used for Klarna in certain countries. | ||
| Shipping Street Name | No | AAK | See Billing Street Name | ||
| Shipping House Number | No | AAL | See Billing House Number | ||
| Shipping House Extension | No | AAM | See Billing House Number | ||
| Shipping CareOf | No | AAN | C/O address (if used by the consumer ). | ||
| Authorization Type | No | AAO | Authorization type: Mastercard and Visa now require merchants to define authorization attempts as either a pre-authorization or a final-authorization. Final-authorizaton is not supported by Visa, but only applicable for Mastercard. | UNDEFINED, PRE_AUTHORIZATION, FINAL_AUTHORIZATION | |
| AuthenticationRedirect | No | AAP | It specifies whether the transaction would go through 2-step authentication flow or not | REDIRECT: Client accepts receiving an authentication redirect in the response.NOREDIRECT: Client does not accept an authentication redirect in the response. This is the default behavior.REDIRECTONLY: Only receive an authentication redirect and have no payment transaction executed. | |
| Line item ID | Yes (if line items are sent) | LIA For each line item a suffix is needed e.g. LIA_1 | Line item ID. | 16 | |
| Line item description | No | LIB For each line item a suffix is needed e.g. LIB_1 | Line item description | ||
| Line item amount | Yes (if line items are sent) | LIC For each line item a suffix is needed e.g. LIC_1 | |||
| Line item quantity | Yes (if line items are sent) | LID For each line item a suffix is needed e.g. LID_1 | Line item quantity | ||
| Line tax amount | No | LIE For each line item a suffix is needed e.g. LIE_1 | Line item tax amount | ||
| Line tax rate | No | LIF For each line item a suffix is needed e.g. LIF_1 | Line item tax rate | ||
| Stored credential indicator | No | AAT | Indicates if the transaction is initiated by card holder or merchant. Indicates if stored credentials are initially stored or re-used | CIT_FIRST_TIME:Card holder initiated transaction that stores credentials for the first time CIT_USE_STORED: Card holder initiated transaction using previously stored credentials MIT_USE_STORED: Merchant initiated transaction using previously stored credentials | |
| Stored Credential reason | Yes (if stored credential indicator sent) | AAU | Indicate the purpose for using stored credential | UNSCHEDULED:Transaction using stored credentials for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date.RECURRING:Transaction using stored credentials for fixed, regular intervals.RESUBMISSION:Transaction using stored credentials to perform a resubmission for a previously declined authorization.DELAYED_CHARGES:Transaction using stored credentials to process a supplemental account charge after original services have been rendered and respective payment has been processed.NO_SHOW:Transaction using stored credentials to process a charge due to card holder failing to meet agreed cancellation policy.UNDEFINED:Undefined | |
| Scheme reference id | No | AAV | Set SchemeReferenceID received in a previous transaction, an initial stored credential transaction or a subsequent transaction where initiate reference has been provided. |
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? | Name | Comment | Valid values | Max length |
|---|---|---|---|---|---|
| PurchaseInstallment | No | ABA | Indicates the maximum number of authorisations permitted for instalment payments | 02 | 3 |
| AcctID | No | ABC | Additional information about the account optionally provided by the 3DS Requestor | 64 | |
| AcctType | No | ABD | Indicates the type of account, eg: 02 = Credit | 02 | 2 |
| AddrMatch | No | ABE | Indicates whether the Cardholder Shipping Address and Cardholder Billing Address are the same | Y | 1 |
| MessageCategory | No | ABF | Identifies the category of the message for a specific use case, eg : 01 = PA (Payment) | 02 | 2 |
| PurchaseDate | No | ABG | Date and time of the purchase expressed in UTC | 20201126115044 | 14 |
| TransType | No | ABH | Identifies the type of transaction being authenticated, eg: 01 = Goods/ Service Purchase | 01 | 2 |
| ThreeRIInd | No | ABI | Indicates the type of 3RI request, eg: 02 = Instalment transaction | 02 | 2 |
| ThreeDSRequestorAuthenticationInd | No | ABJ | Indicates the type of Authentication request, eg: 01 = Payment transaction | 01 | 2 |
| ThreeDSRequestorChallengeInd | No | ABK | Indicates whether a challenge is requested for this transaction, eg: 04=Challenge requested (Mandate) | 04 | 2 |
| ChallengeWindowSize | No | ABL | Dimensions of the challenge window that has been displayed to the Cardholder, eg: 01 = 250 x 400 | 01 | 2 |
| ShipIndicator | No | ABM | Indicates shipping method chosen for the transaction, eg : 01 = Ship to cardholder’s billing address | 01 | 2 |
| DeliveryTimeframe | No | ABN | Indicates the merchandise delivery timeframe,eg; 03 = Overnight shipping | 03 | 2 |
| DeliveryEmailAddress | No | ABO | For Electronic delivery, the email address to which the merchandise was delivered | 254 | |
| ReorderItemsInd | No | ABP | Indicates whether the cardholder is reordering previously purchased merchandise,eg: 01 = First time ordered | 01 | 2 |
| PreOrderPurchaseInd | No | ABQ | Indicates whether Cardholder is placing an order for merchandise with a future availability or release date,eg: 01 = Merchandise available | 01 | 2 |
| PreOrderDate | No | ABR | For a pre-ordered purchase, the expected date that the merchandise will be available | 20211123 | 8 |
| GiftCardAmount | No | ABS | 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). | 0123 | 15 |
| GiftCardCurr | No | ABT | For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card | 3 | |
| GiftCardCount | No | ABU | For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased | 2 | |
| ChAccAgeInd | No | ABV | Length of time that the cardholder has had the account with the 3DS Requestor,eg: 04 = 30−60 days | 04 | 2 |
| ChAccDate | No | ABW | Date that the cardholder opened the account with the 3DS Requestor | 20190413 | 8 |
| ChAccChangeInd | No | ABX | 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 | 02 | 2 |
| ChAccChange | No | ABY | 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 | 04 | 2 |
| ChAccPwChangeInd | No | ABZ | Indicates the length of time since the cardholder’s account with the 3DS Requestor had a password change or account reset,eg: 01 = No change | 01 | 2 |
| ChAccPwChange | No | ACA | Date that cardholder’s account with the 3DS Requestor had a password change or account reset | 20200413 | 8 |
| NbPurchaseAccount | No | ACB | Number of purchases with this cardholder account during the previous six months | 13 | 4 |
| ProvisionAttemptsDay | No | ACC | Number of Add Card attempts in the last 24 hours | 6 | 3 |
| TxnActivityDay | No | ACD | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 hours | 15 | 3 |
| TxnActivityYear | No | ACE | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year | 002 | 3 |
| ShipAddressUsageInd | No | ACF | Indicates when the shipping address used for this transaction was first used with the 3DS Requestor,eg: 01 = This transaction | 01 | 2 |
| ShipAddressUsage | No | ACG | Date when the shipping address used for this transaction was first used with the 3DS Requestor | 20190620 | 8 |
| ShipNameIndicator | No | ACH | Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction,eg: 01 = Account Name identical to shipping Name | 01 | 2 |
| PaymentAccInd | No | ACI | Indicates the length of time that the payment account was enrolled in the cardholder’s account with the 3DS Requestor | 01 | 2 |
| PaymentAccAge | No | ACJ | Date that the payment account was enrolled in the cardholder’s account with the 3DS Requestor | 20190504 | 8 |
| SuspiciousAccActivity | No | ACK | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account,eg: 01 = No suspicious activity has been observed | 01 | 2 |
| ThreeDSReqAuthMethod | No | ACL | 3DS 2.0 extra authentication information about how the 3DS Requestor authenticated the cardholder before or during the transaction, eg: 08 = SRC Assurance Data | 02 | 2 |
| ThreeDSReqAuthTimestamp | No | ACM | 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 | 201912120646 | 12 |
| ThreeDSReqPriorRef | No | ACN | 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 | ACO | 3DS 2.0 extra authentication information about how the 3DS Requestor authenticated the cardholder as part of a previous 3DS transaction, eg: 03 = AVS verified | 02 | 2 |
| ThreeDSReqPriorAuthTimestamp | No | ACP | 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, eg: Date format = YYYYMMDDHHMM | 202012112242 | 12 |
| SCA | No | ACY | It specifies whether Strong Customer Authentication is required or not | Enforced: PaymentPage will start with a 3DSecure call, Optional: Payment will start with Authorize/Debit, and in the response if the answer code is related to step up, then the PaymentPage would continue with a 3DSecure flow(handled internally), and then Authorize/Debit again. | |
| PaymentAuthenticationLevel | No | ADA | It specifies whether to continue the payment for unsuccessful authentications or not | Proceed when SCA Successful, Proceed when SCA Attempted, Proceed without SCA |
Response Details¶
| Parameter | Name | Comment |
|---|---|---|
| MID | A | Merchant ID |
| Status | B | Status |
| TransactionId | C | Transaction ID |
| PaymentMethod | D | PaymentMethod Used |
| Order ID | E | The order ID set by the merchant |
| Timestamp | F | Timestamp |
| VEResId | G | VEResId. Only for 3Dsecure |
| PAResId | H | PAResId. Only for 3Dsecure |
| DDDSStatus | I | 3Dsecure status. Only for 3Dsecure |
| POSId | J | POSId |
| CardTxType | K | Card Transaction type. |
| CardTxId | L | Card transaction ID. Only for card payment |
| CardType | M | Card type. Only for card payment |
| Token | N | A reference to a stored payment instrument. |
| ExpirationDate | P | Card expiration date. |
| StoreCardType | Q | Store card type for a store transaction. |
| IbpTxId | R | IBP transaction ID. Only for IBP payment |
| IbpTxType | S | IBP transaction type. Only for IBP payment |
| Redirected | T | Redirected status, true if the consumer was redirected to a third party site during the session at Payment Page |
| MaskedCardNumber | U | Masked card number. |
| StoreMaskedCardNumber | V | Masked card number for a stored token. |
| StoreExpirationDate | W | Expiration date for a stored token e.g. card expiration date. |
| EftReferenceId | X | Reference returned for an EFT payment |
| EftPaymentSlipUrl | Y | Payment slip URL returned for an EFT payment |
| EftTxId | Z | EFT transaction ID returned for an EFT payment |
| DirectDebitTxId | AA | Direct Debit transaction ID |
| PayoutTxid | AB | Payout transaction ID |
| AVS answer code | AC | AVS answer code |
| AVS response | AD | AVS response |
| Acquirer answer code | AE | Acquirer answer code |
| Client answer code | AF | Client answer code |
| CVV answer code | AG | CVV answer code |
| CVV response | AH | CVV response |
| Payment method name | AI | Name of payment |
| Acquirer authorization code | AJ | Authorization code returned from acquirer |
| House Extension | AK | As entered by Consumer at the payment page (only certain countries) |
| House Number | AL | As entered by Consumer at the payment page (only certain countries) |
| Street Name | AM | As entered by Consumer at the payment page (only certain countries) |
| Gender | AN | As entered by Consumer at the payment page (only certain countries) |
| Birth Date | AO | As entered by Consumer at the payment page (only certain countries) |
| Answer Description | AU | Text description of the Acquirer answer code |
| Payment Plan Code | AV | As selected by Consumer at the payment page |
| Social Security Number (or similar like “Personnummer”) | AW | As entered by Consumer at the payment page |
| First Name | AX | As entered by Consumer at the payment page |
| Last Name | AY | As entered by Consumer at the payment page |
| City | AZ | As entered by Consumer at the payment page |
| Country Code | AAA | As entered by Consumer at the payment page |
| Zip Code | AAB | As entered by Consumer at the payment page |
| Address Line 1 | AAC | As entered by Consumer at the payment page (only certain countries) |
| Scheme reference Id | ABB | This field is only returned if Stored Credential Indicator has been provided in the request. |
| Authentication status | AAY | Status returned by different authentication methods |
Details on the Status¶
| Status | Description |
|---|---|
| OK | The payment has been successfully processed. |
| 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. |
| REQUIRED | Status returned by Initiate and Continue Authentication request that indicates Complete authentication is required and once Complete authentication is successful 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 Continue Authentication request that indicates authentication is attempted and partially successful. |
| TRY_AGAIN | Status returned by Initiate and Continue Authentication request that indicates authentication is not successful. |