GuidesAPI ReferenceDiscussions

Initiate New Payment (Backend2Backend)

Suggest Edits

The Backend2Backend Integration can be used for initiating payments for all payment methods, including Card On File (Tokenization) and MOTO (Mail Order and Telephone Order) payments and installment payments.

The following diagram describes the process:

534

Step 1: Merchant calls initiatePayment

<?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>
    <data xsi:type="keyStringValuePair">
			<key>CountryCode2</key>
			<value>AT</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>

Payment methods usually differ in the data provided in the initiatePaymentRequest.specificPaymentData and specificPaymentAccountData collections of key-value fields.

📘

Dynamically populate the specific xxxData collections

For a completely configurable approach allowing new payment methods to be activated without coding a so-called “Dynamic Mapper” could be implemented which dynamically generates form fields, gathers the data from the customer and then fills initiatePaymentRequest.specificPaymentData and specificPaymentAccountData collections.

🚧

Payment country is a mandatory parameter for certain types of merchant activity

For certain types of merchant activities which may fall under some country-specific restrictions, we have to know the country from which this payment is triggered.

In such cases, please be sure to pass the 'CountryCode2' specificPayment detail.

If this detail is not passed, we will try to infer the country from the address of the user.
if neither is passed, PXP Financial will not be able to process this payment.

<?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>
		<paymentAccount>
			<paymentAccountID>3e27c7d9-e3d5-45df-8033-a78e66ab319e</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

The following fields in the initiatePaymentResponse should be parsed:

  • The payment state definition ID can be retrieved from payment.state.definition.key
  • The payment method ID can be retrieved from payment.paymentMethod.key

The values should be matched against the Payment Methods and one of the 3 possible routes should be followed:

  1. If the payment state indicates that a redirection should be performed then extract value for key RedirectionUrl from the payment.state.paymentStateDetails collection and redirect the user to this URL
  2. If the payment state indicates that the transaction was successfully processed then display or redirect the user to a success page
  3. If the payment state + method pair could not be matched against the list of payment methods then match the specific error state with the corresponding error description. If such is found then display the corresponding error message or page. If the payment state + method pair could not be matched then display a general/default error message or page.

📘

isExecuted vs. paymentMethod.key + state.definition.key

Whether a payment was processed successfully can be identified by looking in initiatePaymentRequest for either isExecuted=true flag or for a combination of 'paymentMethod.key' + 'state.definition.key' which indicates credit/debit as per Payment Methods. The difference is that once set, isExecuted=true remains true also in subsequent request to get the current state of the payment (by calling getPayments), whereas the state can change (e.g. to SettledWithProvider)

Step 2: PaymentService calls handlePaymentStateChangedNotification

Refer to PaymentStateChangedNotification for instructions on how to handle the notification.

Updated over 4 years ago