post https://api.test.kalixa.com/PaymentRedirectionService/PaymentService.svc/pox/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 valueApplicable 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 10Possible values: 0 - Incremental 1 - Resubmission 2 - Delayed charge 3 - Reauthorisation 4 - No show 5 - Deferred authorisation (Visa only) |
| UserDeviceFingerprint (string) | Optional detail. Used with cards for Order Insight & Compelling Evidence. Max 256 characters. |
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 |