Card Deposits

The following method IDs are covered in this section:

ID

Name

Credit/Debit State

Reversal State

1

ECMC Deposit

AuthorisedByProvider (13) CapturedByProvider (27)

Cancelled (113)

2

VISA Deposit

AuthorisedByProvider (13) CapturedByProvider (27)

Cancelled (113)

3

Diners Deposit

AuthorisedByProvider (13) CapturedByProvider (27)

Cancelled (113)

47

Postepay Deposit

AuthorisedByProvider (13) CapturedByProvider (27)

Cancelled (113)

73

Maestro Deposit

AuthorisedByProvider (13) CapturedByProvider (27)

Cancelled (113)

113

AMEX Deposit

AuthorisedByProvider (13)

Cancelled (113)

187

JCB Deposit

AuthorisedByProvider (13)

Cancelled (113)

Payment method interaction type: Synchronous Execution (see Interaction Types)

Redirect Integration

There are no specific steps for initiating Card Deposits with Redirect Integration. Refer to Initiate New Payment (Redirect) for the standard steps.

Backend2Backend Integration

To initiate a card deposit the initiatePayment web method should be invoked. The following table contains the fields to be sent in the specificPaymentAccountData xml section for card deposits:

key (value type, account type, required)

value

CardNumber (string,Cards, required)

PAN, e.g. 4111111111111111

CardVerificationCode (string,Cards, conditional)

CVC, 3 or 4-digit number, e.g. 333

HolderName (string,Cards, required)

Cardholder name, e.g. John Doe

ExpiryMonth (string,Cards, required)

Expiration month of the card, e.g. 12

ExpiryYear (string,Cards, required)

Expiration year of the card, e.g. 2019

🚧

Conditional CVC

CVC can be configured to be optional or mandatory based on the payment creation type. By default, PaymentService will treat CVC as mandatory.

🚧

Dynamic Billing Descriptor

Card Deposits can also be configured to support Dynamic Descriptors in order to display specific information on the cardholder's statement. Once this has been configured, the key-value PaymentDescription must be provided in the intiatePaymentRequest.specificPaymentData collection up to a length of no more than 25 characters.

Please contact PXP Financial Support in order to set this up.

🚧

Downgraded payments - MasterCard and Visa

Successfully authenticated payments are chargeback protected by Issuer and have ECI = 02 (fully authenticated) or 01 (attempted) for MasterCard and 05 (fully authenticated) or 06 (attempted) for Visa.

However, it is possible during authorization the Issuer to downgrade the ECI submitted in a payment from authenticated to unauthenticated and the liability is shifted back to the merchant. When this happens, we return the following two fields in the initiatePayment/executeAction response:
ElectronicCommerceIndicator = NN ECIAfterAuthentication = NN

The ECIAfterAuthentication value indicates the ECI after SCA was carried out (or the value submitted by the merchant to indicate the same. ElectronicCommerceIndicator indicates the final ECI value returned, and would be different to the authentication ECI if a downgrade occurred.

🚧

Deferred authorisations - Visa

Deferred authorisations occur when a merchant cannot complete an authorisation at the time of transaction with the cardholder because of connectivity problems, systems issues or other limitations, and then later completes the authorization when they are able. A connectivity issue may occur for example when airlines or train operators make sales in transit.
Merchants should collect the transaction information and send a deferred authorisation request at the earliest possible opportunity. IndustrySpecificMITType = 5 should be sent in initiatePayment request to indicate deferred authorisation.

ExampleinitiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
	<merchantTransactionID>Order99999</merchantTransactionID>
	<paymentMethodID>2</paymentMethodID>
	<amount currencyCode="EUR">100</amount>
	<userID>u12312312</userID>
	<userData>
		<username>johndoe</username>
		<firstname>John</firstname>
		<lastname>Doe</lastname>
		<currencyCode>EUR</currencyCode>
		<languageCode>EN</languageCode>
		<email>[email protected]</email>
		<address>
			<street>Marxergasse</street>
			<houseNumber>1b</houseNumber>
			<postalCode>1030</postalCode>
			<city>Vienna</city>
			<countryCode2>AT</countryCode2>
			<telephoneNumber>00437778889999</telephoneNumber>
		</address>
		<dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
		<gender>Male</gender>
	</userData>

	<userIP>127.0.0.1</userIP>
	<userSessionID>123</userSessionID>
	<creationTypeID>1</creationTypeID>

	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>some description</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
	</specificPaymentData>

	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>4111111111111111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>CardVerificationCode</key>
				<value>111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>John Doe</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryMonth</key>
				<value>1</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryYear</key>
				<value>2099</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>

</initiatePaymentRequest>

ExampleinitiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>2</key>
      <value>VISA Deposit</value>
    </paymentMethod>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <paymentID>47026705-e9e2-44c1-8f50-2b3676d60075</paymentID>
    <userID>u12312312</userID>
    <paymentProvider>
      <key>92</key>
      <value>CQRUK</value>
    </paymentProvider>
    <amount currencyCode="EUR">100.00</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
		<state>
			<id>462890c3-2803-4b9f-b741-484ee8f73db3</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2014-12-11T11:45:16.7360552Z</createdOn>
			<description>Approved or completed successfully</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>442653</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">100</baseAmount>
		<paymentDetails xsi:nil="true"/>
		<paymentAccount>
			<paymentAccountID>3e27c7d9-e3d5-45df-8033-a78e66ab319e</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Notifications

ExamplehandlePaymentStateChangedNotificationRequest for Visa Deposit in state AuthorisedByProvider:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest 
  xmlns="http://www.cqrpayments.com/PaymentProcessing" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xsi:type="q1:paymentWithPaymentAccount">
		<merchantID>KalixaAcceptDEMO</merchantID>
		<shopID>KalixaAcceptDEMO</shopID>
		<paymentMethod>
			<key>2</key>
			<value>VISA Deposit</value>
		</paymentMethod>
		<merchantTransactionID>20141211_1</merchantTransactionID>
		<paymentID>616129bf-3ee0-4e63-9998-2fed6e85b7b7</paymentID>
		<userID>KalxiaTestUser_3</userID>
		<paymentProvider>
			<key>92</key>
			<value>CQRUK</value>
		</paymentProvider>
		<amount currencyCode="GBP">100.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>195.72.132.1</userIP>
		<state>
			<id>3560adf3-6dd2-40f9-a6db-3a52ffa6ce90</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2014-12-11T15:06:56.66</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>452237</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">126.5300</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>206969</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>PaymentScoring</key>
				<value>711201</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingName</key>
				<value>Christiane Zepeda</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingStreet</key>
				<value>Marxergasse 1B</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingCity</key>
				<value>Vienna</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingState</key>
				<value>Vienna</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingPostalCode</key>
				<value>1030</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingCountryCode2</key>
				<value>AT</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingTelephoneNumber</key>
				<value> 123456789</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>c8650e17-89ff-4566-a4de-835d8818b3f3</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

📘

ProviderResponseCode and ApprovalCode key-values

In the above sample the handlePaymentStateChangedNotificationRequest.payment.state.paymentStateDetails key-values are:

  • ProviderResponseCode containing the issuer response code (see Card Deposit Provider Response Codes)
  • ApprovalCode generated by the issuer, serving as a proof for the authorization and used for some post-authorization operations.

ExamplehandlePaymentStateChangedNotificationRequest for Amex Deposit in state AuthorisedByProvider:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest
  xmlns="http://www.cqrpayments.com/PaymentProcessing"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
´ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xsi:type="paymentWithPaymentAccount">
    <merchantID>KalixaAcceptDEMO</merchantID>
    <shopID>KalixaAcceptDEMO</shopID>
    <paymentMethod>
      <key>113</key>
      <value>AMEXDeposit</value>
    </paymentMethod>
    <merchantTransactionID>05012015_1</merchantTransactionID>
    <paymentID>9d52f550-7316-4a40-8f94-f3648a2009a7</paymentID>
    <userID>KalixaTestUser_5</userID>
    <paymentProvider>
      <key>81</key>
      <value>AmericanExpress</value>
    </paymentProvider>
    <amount currencyCode="EUR">100.0000</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>195.72.132.1</userIP>
    <state>
      <id>0f4d6cb5-6826-431c-8936-008378435dc7</id>
      <definition>
        <key>13</key>
        <value>AuthorisedByProvider</value>
      </definition>
      <createdOn>2015-01-05T13:56:26.233</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ApprovalCode</key>
          <value>46</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">100.0000</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>724612</value>
      </detail>
      <detail xsi:type="keyIntValuePair">
        <key>PaymentScoring</key>
        <value>724612</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingName</key>
        <value>Christiane Zepeda</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingStreet</key>
        <value>Marxergasse 1B</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingCity</key>
        <value>Vienna</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingState</key>
        <value>Vienna</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingPostalCode</key>
        <value>1030</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingCountryCode2</key>
        <value>AT</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ShippingTelephoneNumber</key>
        <value> 123456789</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>906004830</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

ExamplehandlePaymentStateChangedNotificationRequest for ECMC Debit Deposit in state AuthorisedByProvider:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest
  xmlns="http://www.cqrpayments.com/PaymentProcessing"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>KalixaAcceptDEMO</merchantID>
		<shopID>KalixaAcceptDEMO</shopID>
		<paymentMethod>
			<key>168</key>
			<value>ECMC Debit Deposit</value>
		</paymentMethod>
		<merchantTransactionID>05012015_2</merchantTransactionID>
		<paymentID>fac0a901-2240-4a94-99ef-d6a36e4bcf27</paymentID>
		<userID>KalixaTestUser_5</userID>
		<paymentProvider>
			<key>92</key>
			<value>CQRUK</value>
		</paymentProvider>
		<amount currencyCode="EUR">100.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>195.72.132.1</userIP>
		<state>
			<id>bff607d3-c6d8-4a36-97ac-51b73787c0b6</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2015-01-05T14:02:41.143</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderResponseCode</key>
					<value>0</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>ApprovalCode</key>
					<value>858627</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">100.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>211609</value>
			</detail>
			<detail xsi:type="keyIntValuePair">
				<key>PaymentScoring</key>
				<value>724614</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingName</key>
				<value>Christiane Zepeda</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingStreet</key>
				<value>Marxergasse 1B</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingCity</key>
				<value>Vienna</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingState</key>
				<value>Vienna</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingPostalCode</key>
				<value>1030</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingCountryCode2</key>
				<value>AT</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ShippingTelephoneNumber</key>
				<value> 123456789</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>906004831</paymentAccountID>
			<details>
				<detail xsi:type="keyStringValuePair">
					<key>issuerCountry</key>
					<value>US</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>fundingSource</key>
					<value>Debit</value>
				</detail>
			</details>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

📘

issuerCountry and fundingSource key-values of paymentAccount

In the above sample the handlePaymentStateChangedNotificationRequest.payment.paymentAccount.details fundingSource key-value indicates the card type is a debit card.

Cancellation of Card Deposits

In order to cancel a Card Deposit you will need to make use of the Execute Payment Action API call.

See the Cancel Payment page for further instructions.

Payment States for Card Deposits

StatesDescription
RefusedByProviderRefusal state, payment was not accepted by provider
AuthorisedByProviderSuccess state, payment was authorised by provider.
RefusedByPaymentScoringRefusal state, Declined by PXP risk engine during risk checks
ValidationFailed AuthoriseErrorOccurredError state, Technical validation failed. Examples: Mandatory parameters not available / Provided parameter validation failure
UserVerificationFailedError state, user was not authenticated
AuthoriseErrorReportedByProviderError state; an error was returned by provider.
AuthoriseCommunicationErrorOccurredError state, Authorisation timed out and no response was received.
DuplicatePaymentValidationFailedUnsuccessful state; Duplication of payment.

Enhanced Authorisation Response Information

The following additional fields can be returned on request where available to supplement and enhance the information provided.

Please refer to the API documentation for details

FieldDescriptionUse
Original ISO Response CodeProvides the raw Scheme response code for a decline. See here for more informationFor determining reattempts in line with the Visa and MasterCard initiatives
Merchant Advice CodeMasterCard-only: In addition to the response code, issuers can provide specific advice on what action a merchant should take following a decline, or provide other additional information associated to a payment. See here for more informationAs above with certain decline codes. Additionally, provides further information on a payment which may require specific merchant actions e.g. use of a Virtual Card.
Scheme Account ReferenceA unique value attributed to a PAN and all tokens associated with a PAN. Also referred to as Payment Account Reference (PAR)Tracking and unifying payments across FPANs and DPANs
AVS Response Code, AVS Response MessageFor payments where AVS data is submitted, these fields carry the response code and message respectively. See AVS page for mappingAdditional card security check outcomes can inform higher approval rates
CVC Response Code, CVC ResponseFor payments where CVC checks have been carried out, these fields carry the CVC outcomes. See below for mappingAs above
Funding SourceThe type of card product being used. Can be Credit, Debit, Prepaid, Charge or Deferred Debit.Additional card information
Issuer CountryCountry of the Issuing BankAdditional card information

CVV/CVC2 Response Mapping

CVC Response CodeCVC Response Message
1Unknown
2Match
3No Match
4Not Processed
5Not Provided
6Unable