initiatePayment

initiatePaymentRequest fields

field (type, required)

description

merchantID
(stringID, required)

Merchant ID

shopID
(stringID, required)

Shop ID

merchantTransactionID
(stringID, required)

Merchant’s transaction ID, corresponding to the customer's order or any customer account-related activity at merchant (e.g. payout)

paymentMethodID
(positiveInt, required)

The Payment Method ID used for this payment. See Payment Methods.

amount
(nonNegativeMoney)

Amount to be charged to the customer credit card or account at provider

Note: the amount to be charged includes the shopFee (for description see the following row)

Required for all payment methods except credit card verifications

shopFee
(positiveMoney)

Fee amount to be paid by the customer

userID
(stringID, required)

Customer ID

userData
(userData)

Every payment is associated with a user (customer). The following fields allow association and store of customer information related to a specific transaction. Every time the information is sent, it will be updated on the customer level.

UserData type has all fields of the User type excluding the userID.

userIP
(IPAddress)

IP of the customer's browser whcih triggered the payment request

userSessionID
(userSessionID, required)

The session ID of the customer at the merchant web site

creationTypeID
(positiveInt, required)

Defines the channel through which the payment is triggered. See Creation Types for a list of values.

shoppingCart
(shoppingCart)

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

shippingDetails
(shippingDetailss)

It is possible to store per payment transaction shipping data like the address or other relevant details, which is commonly applicable for non-digital goods

specificPaymentData
(array of keyValueBasePairs)

Additional (e.g. method-specific) information to process the payment

paymentAccountID
(stringID)

The token associated to a credit or debit card number. It is used to indicate the corresponding card to apply the charge

When the first authorization is triggered by the customer, in the notification back to your system, this information is provided. Please see 2.1.3.4 handlePaymentStateChangedNotificationResponse Description

paymentAccount
(paymentAccountData)

The payment account (e.g. card) used for this payment, if any. Used for all payment methods requiring a single payment account.
See below for the properties of paymentAccountData.

paymentAccount.isvisible
(boolean)

If true (default) shows the previously used payment account in PXP Financial Payment Hosted Pages for this the customer

paymentAccount.specificPaymentAccountData
(array of keyValueBasePairs)

Payment account type-specific data (e.g. card data like cardNumber, expiryDate)

paymentAccounts
(array of paymentAccountInputData)

Used for payment methods allowing multiple payment accounts, e.g. TSI Direct Deposit with multiple vouchers

initiatePaymentRequest.specificPaymentData key-values

Each payment method requires certain key-values to be present in the specificPaymentData collections, as described in the sections in Payment Method-specific Use Cases.
Below is a list of some general key-values applicable to many payment methods:

key (value type, functionality)

description

PaymentDescription
(string)

Information about items selected for purchase that should be displayed in the user statement, and sent as part of 3DSecure

PaymentDescriptionLanguageCode
(string)

The language code of the payment’s description

RecipientLastName
(string, Financial Services Check)

Last name of the card holder on whose behalf the payment is done
Used for payment methods: Visa Deposi

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

TransactionPlanID
(guid, Recurring Payments)

Required for Installment/Recurring payments

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

Used for payment methods: Card Deposits

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.

QuotaID
(integer)

The number of months for a payment to be due (deferred payment date). Specific for country Colombia.

Used for payment methods: Card Deposits

VatAmount
(decimal)

VAT Amount value associated with the purchase tax

Used for payment methods: Card Deposits

TaxIdentificationNumber
(string)

Company identification number

Used for payment methods: Card Deposits

TaxID
(integer)

Tax type

Used for payment methods: Card Deposits

TaxName
(string)

Tax name

Used for payment methods: Card Deposits

TaxAmount
(decimal)

Tax amount

Used for payment methods: Card Deposits

PaymentPlanID
(integer)

Instalments plan ID, can have following values:
0 - One-off payment;
1 - Installments with interest by the merchant;
2 - Installments with interest by the issuer bank.
*for “Braspag” provider

Used for payment methods: Card Deposits

PaymentCount
(integer)

Count of payments per payment plan. This value should be 1 if PaymentPlanID=0 and bigger than 0 if PaymentPlanID=1 or 2. In other case error ‘Transaction with disqualifying error’ occurred.
*for “Braspag” provider

Used for payment methods: Card Deposits

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

UserConsentForStoredAccount
(boolean)

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

DeviceType
(string)

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

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.

BrowserHeaderAccept
(string)

The exact content of the HTTP accept header as sent to the merchant from the cardholder's user agent. This field is required only if the cardholder's user agent supplied a value.
Example: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng

BrowserHeaderUserAgent
(string)

The exact content of the HTTP User-Agent header.
Example: Mozilla/5.0 (X11; Linux x86_64; rv:12.0) Gecko/20100101 Firefox/12.0

BrowserJavaEnabled
(boolean)

Ability of the cardholder's browser to execute Java. Required if JavaScriptEnabled = true

BrowserJavaScriptEnabled
(boolean)

Ability of the cardholder's browser to execute JavaScript

BrowserLanguage
(string)

The cardholder's browser language as defined in IETF BCP 47.
The field should be taken from the 'navigator.language' property.
Required if JavaScriptEnabled = true

BrowserScreenColorDepth
(integer)

Contains a value representing the bit depth of the colour palette, in bits per pixel, for displaying images
Required if JavaScriptEnabled = true

BrowserScreenHeight
(integer)

Total height of the cardholder's screen in pixels.
The field should be taken from the 'screen.height' property.
Required if JavaScriptEnabled = true

BrowserScreenWidth
(integer)

Total width of the cardholder's screen in pixels.
The field should be taken from the 'screen.width' property.
Required if JavaScriptEnabled = true

BrowserTimeZone
(string)

Difference between UTC time and the cardholder's browser local time in minutes.
This is the value returned from the getTimezoneOffset() method.
Required if JavaScriptEnabled = true

BrowserVerificationNotificationURL
(string)

The URL to which the result of fingerprinting will be posted

UserVerificationNotificationURL
(string)

The notification URL to which the challenge response is sent

CardholderEmail
(string)

Email address of the cardholder

CardholderHomePhone
(string)

Home phone number provided by the cardholder.
Expected format:
<country_code>-<telephone_number>. <country_code> must be up to 3 digits. <telephone_number> is up to 15 digits.
Example:
359-453921233

CardholderMobilePhone
(string)

Mobile phone number provided by the cardholder.
Expected format:
<country_code>-<telephone_number>. <country_code> must be up to 3 digits. <telephone_number> is up to 15 digits.
Example:
359-453921233

CardholderWorkPhone
(string)

Work phone number provided by the cardholder.
Expected format:
<country_code>-<telephone_number>. <country_code> must be up to 3 digits. <telephone_number> is up to 15 digits.
Example:
359-453921233

UserVerificationWindowSize
(integer)

Challenge window size.
This field is relevant if a Challenge flow is triggered and indicates the dimensions of the challenge window that has been displayed to the cardholder. This information will be used by the ACS, which will reply to the browser with content that is formatted to appropriately render in this window to provide the best possible user experience.
Preconfigured sizes are width x height in pixels of the window displayed in the cardholder browser. Possible values are:
1: 250 x 400 (default, if not populated)
2: 390 x 400
3: 500 x 600
4: 600 x 400
5: Full screen

ScaPolicyID
(integer)

Indicates the policy type that the merchant wants to apply for the particular transaction.
If a value is supplied, this will override what is configured against the merchant.
Possible values:
1 - Default policy (if not set)
2 - Apply SCA When 3DS 2.0 is available
3 - Apply SCA when 3DS 2.0 with fallback to 3DS 1.0
4 - Never Apply SCA

ScaChallengeIndicator
(integer)

Indicates the merchant's preference for a challenge for the particular transaction.

Possible values:
1 - noPreference - Default if not set
2 - requestNoChallenge
3 - requestChallenge
4 - requestChallengeAsMandate - A Challenge flow must take place to fulfill a mandate
5 - ChallengeRequestedWhitelistPrompt - Required when setting up a trusted beneficiary to force a challenge

ScaExemptionID
(integer)

Indicates the exemption type that the merchant wants to request for the particular transaction.

Possible values:
1- anonymousCard
2 - lowValue
3 - noExemption
4 - secureCorporate
5 - trustedBeneficiary
6 - transactionRiskAnalysis

ScaExemptionFlowID
(integer)

Indicates at which stage the merchant wishes the exemption to be applied.
Possible values:
1 - authentication - The SCA exemption will be applied during the Authentication stage of 3D Secure
2 - authorisation - The SCA exemption will be applied direct in authorisation, bypassing 3D Secure

ThreeDSecureVersion
(string)

The 3DS 2.0 protocol version.

Applicable only for payments authenticated by third-party 3DS Server and authorised by PXP Financial.

ThreeDSecureCAVV
(string)

Corresponds to the authentication value
Applicable only for payments authenticated by
third-party 3DS Server and authorised by PXP Financial.

ThreeDSecureTransactionStatus
(string)

The Transaction Status value in the ARes or CRes depending on whether the authentication was frictionless or not.
Applicable only for payments authenticated by third-party 3DS Server and authorised by PXP Financial.

ThreeDSecureECI
(string)

The Electronic Commerce Indicator in the ARes or CRes depending on whether the authentication was frictionless or not.
Applicable only for payments authenticated by third-party 3DS Server and authorised by PXP Financial.

DirectoryServerTransactionID
(string)

The unique ID assigned the Directory Server for this payment.
Applicable only for payments authenticated by third-party 3DS Server and authorised by PXP Financial.

IsThreeDSecureAppBased
(boolean)

Indicates whether the 3DS authentication is performed via native app.

"true": the authentication is performed via native app
"false" or not provided: the authentication is not performed via native app, i.e. via browser either on desktop or mobile device

IsInitialPayment
(boolean)

Indicates whether the payment is initial for setting up a series of recurring payments

Applicable for payments through Gateway

RecurringFrequencyInDays
(integer)

Indicates the minimum number of days between authorisations of recurring payments

Applicable for payments through Gateway

RecurringExpirationDate
(datetime)

Indicates the date after which no further authorisations of recurring payments shall be possible

Applicable for payments through Gateway

SchemeSettlementDate
(string)

The settlement date of the original COF or recurring payment used for storing credentials/ setting up a series of recurring payments
Applicable for MasterCard payments only

SchemeReferenceTransactionIdentifier
(string)

The Visa Transaction Identifier or MasterCard Banknet Reference Number of the original payment used for storing credentials/ setting up a series of recurring payments.

This identifier is used for dynamic linking of subsequent COF and recurring payments with the original payment.

ThreeDSecureRequestorID
(string)

Unique identifier assigned by Scheme following 3DS2 enrolment. This must be provided if you are authorising through a different Acquirer or Gateway.

IndustrySpecificMITType
(integer)

The type of Merchant Initiated Transaction. It is applicable if creationTypeID is 10

Possible values:
0 - Incremental
1 - Resubmission
2 - Delayed charge
3 - Reauthorisation
4 - No show
5 - Deferred authorisation (Visa only)

initiatePaymentRequest.paymentAccount.specificPaymentAccountData key-values

Each payment method requires certain payment account key-values to be present in the specificPaymentData collections, as described in the sections in Payment Method-specific Use Cases.
Sample list for Card key-values:

key (value type, account type, required)

value

CardNumber
(string,Cards, required)

PAN

CardVerificationCode
(string,Cards, required)

CVC, 3 or 4 digits number

HolderName
(string,Cards, required)

card holder name

ExpiryMonth
(string,Cards, required)

month number

ExpiryYear
(string,Cards, required)

year number

initiatePaymentResponse fields

field (type, required)

description

payment
(paymentWithState, required)

Represents the processed payment with state details

initiatePaymentResponse.payment.state.paymentStateDetails key-values

key (value type, functionality)

value

ProviderResponseCode
(string)

ApprovalCode
(string)

initiatePaymentResponse.payment.paymentDetails key-values

key (value type, required)

description

ThreeDSecureVersion
(string)

The 3DS 2.0 protocol version. The returned value is "2.1.0" at present.

SchemeTransactionIdentifier
(string)

The Visa Transaction Identifier or MasterCard Banknet Reference Number.

This identifier is used for dynamic linking of subsequent COF and recurring payments with the original payment used for setting up agreement with cardholder.

SchemeSettlementDate
(string)

The settlement date of a payment
Applicable for MasterCard payments only

ECIAfterAuthentication
(string)

The Electronic Commerce Indicator assigned to a payment as a result of authentication. The detail is returned when the Issuer downgrades the transaction from authenticated to unauthenticated.

SchemeAccountReference
(string)

The payment account reference as assigned by the Scheme. It can be returned in responses if provided by the Issuer. The field can be used to link transactions containing PANs or Tokens associated with the same underlying payment account.

ThreeDSecureChallengeCancelIndicator
(string)

Indicator that the authentication with challenge has been cancelled.

Possible values:
01 - Cardholder selected “Cancel”
03 - Transaction Timed Out—Decoupled Authentication
04 - Transaction Timed Out at ACS—other timeouts
05 - Transaction Timed Out at ACS—First CReq not received by ACS
06 - Transaction Error
07 - Unknown
08 - Transaction Timed Out at SDK

MerchantAdviceCode
(string)

Contains the code of recommended action for merchants when a payment authorisation has been declined by the Issuer.

Possible values (this is not an exhaustive list):
01 - Updated/additional information needed
02 - Try Again Later
03 - Do Not Try Again
04 - Token requirements not fulfilled for this token type
21 - Payment Cancellation

Language
Authentication
Basic
base64
: