getRedirectData

getRedirectDataRequest fields

field (type, required)

description

merchantID
(stringID, required)

Merchant ID

redirectParameters
(paymentMethodSelectionWithDetailsRedirectParemeters or paymentMethodDetailsRedirectParameters, required)

Use xsi:type=paymentMethodSelectionWithDetailsRedirectParameters for redirecting the customer to Payment Selection Page

Use xsi:type=paymentMethodDetailsRedirectParameters for redirecting the customer to the Payment Detail Page

Both inherit from redirectParameters.

redirectParameters.shopID
(stringID, required)

Shop ID

redirectParameters.httpMethod
(httpMethod , required)

Possible values are: POST/GET. Correspond to the HTTP Method to be used

redirectParameters.returnUrl
(stringID, required)

URL where the customer should be redirected, in case he wants to go back to the merchant´s website.
If provided a back-link will be displayed in the payment pages.
The URL must start with http or https.

redirectParameters.languageCode
(twoLetterCode)

ISO code of the language required for the customer (e.g. en, de, fr). Default value is English

redirectParameters.currencyCode
(threeLetterCode, required)

The ISO code of the currency

redirectParameters.countryCode
(twoLetterCode, required)

The two letters ISO code of the customer’s country
The payment options to be displayed are based on this information.

redirectParameters.additionalDetails
(sequence of keyValueBasePairs)

A collection of string/string key-value pairs with additional data for the Payment Method Selection and/or Details Page

redirectParameters.shoppingCart
(shoppingCart)

List of items of the shopping cart purchased by the customer.
This parameter is mandatory for the payment method PayByInvoiceDeposit (235)

redirectParameters.user
(user, required)

all payment transactions are associated to an end customer; the following fields enable the association and store the customer information. If a transaction is sent with a new customer ID (id), then PXP Financial Payment Service will register that customer; if a transaction is sent with an existent customer ID (ID), all the information related to that customer will be updated

redirectParameters.merchantTransactionID
(stringID, required)

Merchant’s transaction ID

redirectParameters.grossAmount
(money)

The amount that should be payed by the customer. Can be omitted only for payment methods where an amount is not applicable (e.g. Card Verifications)

redirectParameters.expirationTimeSpanInSeconds
(nonNegativeInt)

If specified, the customer has to complete the request within the provided time:

  • Minimum allowed is 60 seconds
  • Maximum allowed is 900 seconds (15 minutes)

If not specified Checkout default expiration applies which is set to 15 minutes.
If a value with less than 60 seconds or more than 900 seconds is sent, the system also applies 15 minutes.

In case of a session expiration the customer is redirected to the error-URL provided in parameter redirectParameters.errorUrl. This does not apply for the following use-cases:

  • User closes the browser
  • User was redirected to provider

If configured for a merchant, additionally a redirect parameter is sent with key "reason" and value "timeout", so that the merchant can apply different actions on his end. Example: https://merchant.com/error?reason=timeout
Important: This configuration (to receive the "reason=timeout" key in the URL ) needs to be requested via the PXP support team.

redirectParameters.successUrl
(string, required)

URL where the customer should be redirected, when the payment was successful
If the URL links to a directory or root directory of a webserver and includes GET parameters, be sure to use a slash (‘/’) before the question-mark (‘http://example.org/?am=10’ instead of ‘http://example.org?am=10’).

The URL must start with http or https.

redirectParameters.pendingUrl
(string, required)

URL where the customer should be redirected, when the payment was pending

(Only payment methods where customer is redirected to the provider)

The URL must start with http or https.

redirectParameters.errorUrl
(string, required)

URL where the customer should be redirected, when the payment was unsuccessful

The URL must start with http or https.

redirectParameters.cancelUrl
(string, required)

URL where the customer should be redirected, when the payment was cancelled

(Only payment methods where customer is redirected to the provider)

The URL must start with http or https.

redirectParameters.refusedUrl
(string, required)

URL where the customer should be redirected, when the payment was refused

(Only payment methods where customer is redirected to the provider)

The URL must start with http or https.

redirectParameters.paymentDirection
(paymentDirection, required)

Applicable ONLY for Payment Selection Page (xsi:type=paymentMethodSelectionWithDetailsRedirectParameters)

If “Deposit” is entered, then all deposit payment options will be displayed

If “Withdrawal” is entered, then all withdrawal payment options will be displayed

redirectParameters.paymentMethodID
(keyStringValuePair, required)

Applicable ONLY for Payment Detail Page (xsi:type=paymentMethodDetailsRedirectParameters)

Required, when specific method should be
displayed

redirectParameters.isPaymentMethodChangeAllowed
(boolean, required)

Applicable ONLY for Payment Detail Page (xsi:type=paymentMethodDetailsRedirectParameters)

If the user is redirected directly to the payment detail page, this parameter is mandatory. It determines if the payment methods can be changed by the user ("true") or not ("false").

getRedirectDataRequest.additionalData key-values

Supported functionalities:

  • Shipping Information: it is possible to store per payment transaction shipping data like the address, applicable for non-digital goods. This can be used for all payment methods, and in PayPal enables the service “Guaranteed Payment”
  • 3D Secure (3DS): these fields enable the control of 3D Secure; whether to be applied and the verification level
  • Address Verification Service (AVS): these fields enable the control of AVS; whether to be applied and the applicable policy
  • Financial Services Check: for merchants with category code 6012 that process with Visa, these additional fields are mandatory
  • Recurring Payments (Transaction Agreements)

key (value type, functionality)

value

SkinID
(string)

SkinID of the Skin that should be used for the layout of the checkout pages (displayed to customer).
If value is specified as a SkinID and this skin can be retrieved, then this skin will be used for the layout of the checkout pages. If the provided SkinID cannot be retrieved, same functionality as for “null” value.
If value is specified as “null”, and an active skin (for the Shop) can be retrieved, then the Checkout is using the active skin. If no active skin can be retrieved, PXP Financial´s default skin (layout) will be displayed.
By configuration in the PXP Financial Admin Tool (self service), several Skins can be saved for a Merchant, but only one Skin can be activated per Shop. For further details about layout changes and Skin Management please refer to the “PXP Financial Device Responsive Checkout Layout Integration Manual 1.0”.

description
(string)

Information about items selected for purchase that should be displayed on the Payment Pages

device
(string)

If request was initiated from a mobile device, this parameter should be “M”. Otherwise it can be empty

Used for payment methods: PayPal ExpressCheckout Deposit

shippingName
(string, Shipping)

Name of the recipient of the delivery (shipment)
(maximum 32 characters)

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingStreet
(string,Shipping)

Street of the customer´s shipping address
(maximum 200 characters)

  • for Paypal ExpressCheckout Deposit: House name, number, and number extension should be included

  • for Klarna Deposit: only the Street name should be included; extra fields for House name, number and extension

shippingHouseNumber
(string,Shipping)

House number or name of the customer´s shipping address.

Either house number or house name is required

Used for payment methods:

  • Klarna Deposit

shippingHouseName
(string,Shipping)

House name of the customer´s shipping address.

Either house number or house name is required

Used for payment methods:

  • Klarna Deposit

addressHouseNumberExtension
(string,Shipping)

House number extension (if applicable) of the customer´s shipping address.

Used for payment methods:

  • Klarna Deposit

shippingPostalCode
(string,Shipping)

Postal code of the customer´s shipping address
(maximum 20 characters)

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingCity
(string,Shipping)

City of the customer´s shipping address
(maximum 40 characters)

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingState
(string,Shipping)

State or province of the customer´s shipping address. Applicable for U.S.
(maximum 40 characters)

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingCountryCode2
(string,Shipping)

ISO code of the shipping country

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingTelephoneNumber
(string,Shipping)

The phone number of the recipient of the delivery or shipment.

Used for payment methods:

  • PayPal ExpressCheckout Deposit
  • Klarna Deposit

shippingMethod
(string,Shipping)

Shipping method

Used for payment methods:

  • PayPal ExpressCheckout Deposit

shippingTotal
(string,Shipping)

Total amount by shipping

Used for payment methods:

  • PayPal ExpressCheckout Deposit

IsThreeDSecureRequired
(string,3DS)

If 3D Secure is not required for this particular payment, flag it as “false”. If parameter not sent or sent as "true", a 3DS check is done in case 3Ds is enabled for the merchant in general.

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

IsThreeDSecureConditionalRequired
(string,3DS)

If parameter is not sent, default is "false".
If sent as "true", the Smart 3DS feature is enabled which will let the PXP Financial System decide dynamically, depending on the rules set up for/by the merchant, if 3D Secure should be used to authenticate a customer or not.
Further information about Smart 3D Secure.

Note: Either parameter IsThreeDSecureConditionalRequired or IsThreeDSecureRequired can be sent. Combining both parameters is not possible.

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

Applicable for 3DS 1.0 and for 3DS 2.0 in case PSD2 is not mandated (e.g. outside Europe)

AVSCountry
(string,AVS)

Customer country

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

AVSStreetAddress
(string,AVS)

Street name of customer´s address.
Number or flat number are not relevant, but floor number it is

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

AVSPostCode
(string,AVS)

Post code of customer´s address

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

AVSPolicy
(string,AVS)

Policy selected by the merchant.
PXP Financial offers 5 options; value = 1, 2, 3, 4, or 5. Please see Card Deposits with AVS for more information.

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

performAVS
(string,AVS)

If required to be performed, then populate value as “true”, otherwise “false”

Used for payment methods:

  • Visa
  • Maestro
  • Mastercard Deposit

RecipientLastName
(string,Financial Services Check)

Last name of the card holder on whose behalf the payment is done

Used for payment methods:

  • Visa Deposit

RecipientDateofBirth
(string,Financial Services Check)

Date of birth of the card holder on whose behalf the payment is done

Used for payment methods:

  • Visa Deposit

RecipientPostCode
(string,Financial Services Check)

Postal code of the card holder on whose behalf the payment is done

Used for payment methods:

  • Visa Deposit

RecipientAccountNumber
(string,Financial Services Check)

Account number of the card holder on whose behalf the payment is done

Used for payment methods:

  • Visa Deposit

rid
(string)

Specifies reference ID. It can be used in affiliate programs

Used for payment methods:

  • Skrill Deposit

DepartureDate
(datetime)

Date that the consumer’s travel will begin.
This field is for Airline Companies only. It should not be sent for travel merchants.

Used for payment methods:

  • Visa Deposit
  • MasterCard Deposit
  • Diners Deposit

PaymentAction
(string)

Decide whether to continue with a payment after receiving payment data. Expected values: Sale, Authorization, Order.
Sale – This is a final sale for which you are requesting payment (default).

Authorization – This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.

Order – This payment is an order authorization subject to settlement with PayPal Authorization and Capture.

Used for payment methods:

  • PayPal ExpressCheckout Deposit (version 121)

AddressOverride
(integer)

Shipping address override by data sent by merchant

Used for payment methods:

  • PayPal ExpressCheckout Deposit (version 121)

TransactionPlanID
(guid, Recurring Payments)

Should be GUID e.g: ae71b062-8ae4-49fe-8f67-ac4ad5937b99
Should be preregistered with PXP Financial.

Required for creationTypeID 4(EcomRecurring).
Not required for other creationTypeID

ClientSystemTransactionAgreementID
(string, Recurring Payments)

ClientSystemTransactionAgreementID is set by the merchant. It does not have to be unique.

Required for creationTypeID 4 (EcomRecurring).
Not required for other creationTypeID.

TransactionAgreementStartDate
(datetime, Recurring Payments)

The date and time in UTC format when the recurrence should start. Every time the interval of the recurrence scheme has been passed, a new payment with the data of the first payment (which was used for registering the recurrence) will be created.

TransactionAgreementAmount
(decimal, Recurring Payments)

The amount of the recurring transaction.

Required only if TransactionAgreementCurrencyCode is specified. Otherwise not required.

TransactionAgreementCurrencyCode
(string, Recurring Payments)

The ISO code of the currency.
If not specified, currency from user data is used.
If currency cannot be found in user data, exception is thrown.

Required only if TransactionAgreementAmount is specified. Otherwise not required.

TransactionAgreementAcknowledgementText
(string, Recurring Payments)

The custom text provided by merchant which will be used to replace the default acknowledgement checkbox text displayed on payment details page.

UserConsentForStoredAccount
(boolean)

Applicable only for Merchants that implement the user consent checkbox functionality on their checkout pages.

The PXP Financial Hosted Payment Pages offer this functionality out of the box, so the merchant need not implement to ask for a user consent in their checkout pages.

For Visa, MasterCard and Maestro payments the user must give his consent to store the card credentials. This must be flagged explicitly before initiating the subsequent payments based on the "Card On File" credentials.
Applicable only when the user enters new card details, not when the payment is done with an already stored card (token).

"true": the user has given his consent
"false": the user has not given his consent
If parameter provided as true or false, the PXP Financial Hosted Payment Pages will not display the user-consent checkbox and will not ask the customer for consent, as the decision has been made already before.
If parameter not provided (normal use-case), the PXP Financial Hosted Payment Pages will display the user-consent checkbox and ask the customer to give his approval.

Note: If the user is supposed to make a Card Verification only, then sending UserConsentForStoredAccount=false is not applicable as the purpose of Card Verification is to create stored card tokens which can later on be used for "Card On File" payments by the merchant. In such a case the UserConsentForStoredAccount should be sent as "true" or not at all so that the customer can give his consent in the Checkout.

DeviceType
(string)

The type of the device which has been used by the user. Can be used as decision parameter for Smart 3D Secure

CardholderHomePhone
(string)

The home phone number provided by the cardholder. If provided and in case the card is enrolled for 3DS 2.0, this information will be forwarded to the issuing bank and can help to achieve a frictionless authentication.

CardholderMobilePhone
(string)

The mobile phone number provided by the cardholder. If provided and in case the card is enrolled for 3DS 2.0, this information will be forwarded to the issuing bank and can help to achieve a frictionless authentication.

CardholderWorkPhone
(string)

The phone number at the working place provided by the cardholder. If provided and in case the card is enrolled for 3DS 2.0, this information will be forwarded to the issuing bank and can help to achieve a frictionless authentication.

CardholderEmail
(string)

The email address provided by the cardholder. If provided and in case the card is enrolled for 3DS 2.0, this information will be forwarded to the issuing bank and can help to achieve a frictionless authentication.

ScaPolicyID
(integer)

The policy type that the merchant wants to apply for the particular transaction.
If a value is provided, this will override what is configured against the merchant.
PXP Financial offers 4 options; value = 1, 2, 3 or 4. Please see PSD2 Information Hub for more information.

ScaChallengeIndicator
(integer)

Indicates the merchant's preference for a challenge for the particular transaction.
If requesting a challenge, then scaExemption cannot be applied.
PXP Financial offers 4 options; value = 1, 2, 3 or 4. Please see PSD2 Information Hub for more information.

ScaExemptionID
(integer)

Indicates the exemption type that the merchant wants to request for the particular transaction.
If a value is specified, this will overide the scaPolicy logic.
PXP Financial offers 6 options; value = 1, 2, 3, 4, 5 or 6. Please see Please see PSD2 Information Hub for more information.

ScaExemptionFlowID
(integer)

Indicates at which stage the merchant wishes the exemption to be applied.
The default value will be authentication if supported for the exemption type being requested.
PXP Financial offers 2 options; value = 1 or 2. Please see PSD2 Information Hub for more information.

ThreeDSecureAuthorisationPolicyID
(integer)

The 3DS authorisation policy type that the merchant wants to apply for the particular transaction. If not provided, PXP Financial system will apply the default policy which is configured for the merchant.
Please see 3DS Authorisation Policies for more information.

CardholderName
(string)

Optional. The name of the card holder. Should only be provided, if the merchant wants to pre-fill this name in the input field for “Card Holder” on the detail page for a card payment method in Checkout (not applicable on the cards group page).
The customer will not be able to change this value in the checkout page.
Accepted characters: letters, blanks and "-"
Regex: ^[^\d`[email protected]#$%^\x26*()_+=\x3C,>/?\x22:;{[]}|\]+$

MaskedCardNumber
(string)

Optional. The masked card number of the card which the customer must use on the checkout page. Should only be provided, if the merchant wants to pre-fill the card number and allow the customer to only enter the missing (masked) digits of the card. This feature works on the detail page for a card payment method in Checkout (not applicable for the cards group page).
Accepted characters: digits and stars *; the MaskedCardNumber must start with digits or stars and must end with at least 4 digits. It is allowed to send max. 6 digits + stars + 4 digits in the end. Blanks are not allowed.
The number of stars sent is the maximum number of missing digits that the checkout will allow the customer to enter.
Example: 4111******111111
Regex: ^(([*]{6,14})|([0-9]{1,6}[*]{4,14}))[0-9]{4,6}$

getRedirectDataResponse fields

field (type, required)

description

redirectData
(redirectData or redirectDataWithPost, required)

Contains the output parameters of the response.

Can be of xsi:type=redirectData in case of redirection with GET or xsi:type=redirectDataWithPost in case of redirection with POST.

redirectDataWithPost inherits from redirectData.

redirectData.redirectData
(string, required)

The URL the customer should be redirected to

redirectData.dataFields
(array of keyStringValuePair, required)

Applicable ONLY for Redirect with POST (xsi:type=redirectDataWithPost)

The collection of name-values to be posted in the redirectUrl upon redirection

📘

Note

Read the following table in conjunction with the Sample Requests file, folder getRedirectData:
o getRedirectData_Payment Selection Page
o getRedirectData_Payment Detail Page
o getRedirectData_Payment Selection Page_Withdrawals

Language
Authentication
Basic
base64
: