GuidesAPI ReferenceDiscussions

PayByInvoice Deposit (via RatePay)

Suggest Edits

The payment method PayByInvoice Deposit is provided by RatePay and is available in Germany, Austria and Switzerland.

📘

Applicability

Please note that this payment method can only be offered in Gateway Model. The Merchant has to have a contract with RatePay directly.

The following method IDs are covered in this section:

IDNameCredit/Debit StateReversal State
235PayByInvoice DepositInitiatedByProvider (3)Cancelled (113)
Refunded (125)

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

After the customer has confirmed the transaction in the Checkout (Merchant or PXP Financial Hosted Payment Pages), a request is sent from PXP Financial to the provider RatePay. The provider performs some automated risk checks and accepts or refuses the payment.
For successful payments the Merchant will receives via the PXP Financial Payment State Change Notificaiton PaymentStateChangedNotification a "Purpose of Payment", which needs to be printed on the customers invoice together with the Ratepay Bank Account details. Now, the Merchant delivers the purchased items to the customer. At this point of time, the payment needs to be captured. This can be done in three ways:

  • Automatic Capturing by PXP Financial Payment Service with a predefined delay, e.g. 1 day after the payment was created (in case shipping is done within that timeframe)
  • Using the PXP Financial Payment Service Admin Tool
  • Via a call to Execute Payment Action

After this request has been sent, RatePay will settle the money with the Merchant within the next 14 days.

For payments which were refused by the provider RatePay (usually because their risk screening was negative), the merchant is obliged to show the following error message to the customer: "Leider ist eine Bezahlung mit RatePAY nicht möglich. Diese Entscheidung ist auf
Grundlage einer automatisierten Datenverarbeitung getroffen worden. Einzelheiten finden
Sie in den zusätzlichen Allgemeinen Geschäftsbedingungen und dem Datenschutzhinweis
für RatePAY-Zahlungsarten."

The following table lists the possible state results and their meaning:

PaymentState (payment state ID)Description
ExecutedByProvider ()Successful payment. Merchant has to print the purpose of payment on the invoice and deliver the goods to the customer. Payment has to be captured.
InitiateRefusedByProvider ()Provider RatePay has refused the payment. Appropriate error message needs to be displayed to the customer.

Redirect Integration

The optional element shoppingCart is required and needs be correctly populated in the getRedirectDataRequest (see getRedirectData).

Example geRedirectDataRequest with shoppingCart element:

<?xml version="1.0" encoding="utf-8"?>
<getRedirectDataRequest 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>
  <redirectParameters xsi:type="paymentMethodSelectionWithDetailsRedirectParameters">
    <shopID>KalixaAcceptDemo</shopID>
    <httpMethod>GET</httpMethod>
    <returnUrl>http://return</returnUrl>
    <languageCode>de</languageCode>
    <currencyCode>eur</currencyCode>
    <countryCode>de</countryCode>
    <additionalDetails>
      <detail xsi:type="keyStringValuePair">
        <key>description</key>
        <value>Test description</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>skinid</key>
        <value></value>
      </detail>
    </additionalDetails>
    <shoppingCart>
      <items>
        <item>
          <product>
            <id>123</id>
            <name>Jeans</name>
            <description>stonewashed</description>
            <unitPrice>
              <grossAmount>40</grossAmount>
              <taxAmount rate="20" name="VAT">6.67</taxAmount>
            </unitPrice>
          </product>
          <quantity>1</quantity>
          <totalPrice>
            <grossAmount>30</grossAmount>
            <taxAmount rate="20" name="VAT">5</taxAmount>
          </totalPrice>
          <discount>
            <name>Jeans-Promotion</name>
            <grossAmount>-10</grossAmount>
            <taxAmount rate="20" name="VAT">-1.67</taxAmount>
          </discount>
        </item>
        <item>
          <product>
            <id>456</id>
            <name>Skirt</name>
            <description>Flowers Design</description>
            <unitPrice>
              <grossAmount>50</grossAmount>
              <taxAmount rate="10" name="VAT">4.54</taxAmount>
            </unitPrice>
          </product>
          <quantity>2</quantity>
          <totalPrice>
            <grossAmount>80</grossAmount>
            <taxAmount rate="10" name="MwSt">7.27</taxAmount>
          </totalPrice>
          <discount>
            <name>Spring-Promotion</name>
            <grossAmount>-20</grossAmount>
            <taxAmount rate="10" name="VAT">-1.82</taxAmount>
          </discount>
        </item>
       <item>
          <product>
            <id>789</id>
            <name>Tshirt</name>
            <description>red</description>
            <unitPrice>
              <grossAmount>15</grossAmount>
              <taxAmount rate="20" name="VAT">2.5</taxAmount>
            </unitPrice>
          </product>
          <quantity>1</quantity>
          <totalPrice>
            <grossAmount>15</grossAmount>
            <taxAmount rate="20" name="VAT">2.5</taxAmount>
          </totalPrice>
         </item>
      </items>
      <subTotalAmount>125</subTotalAmount>
      <shippingCost>
        <name>Express</name>
        <grossAmount>30</grossAmount>
        <taxAmount rate="20" name="VAT">5</taxAmount>
      </shippingCost>
      <discounts>
        <discount>
          <name>Sales-Discount</name>
          <grossAmount>-10</grossAmount>
          <taxAmount rate="20" name="VAT">-1.67</taxAmount>
        </discount>
      </discounts>
      <amountsByTax>
        <amountByTax taxName="VAT" taxRate="10">
          <grossAmount>80</grossAmount>
          <taxAmount>7.27</taxAmount>
        </amountByTax>
        <amountByTax taxName="VAT" taxRate="20">
          <grossAmount>45</grossAmount>
          <taxAmount>7.5</taxAmount>
        </amountByTax>
      </amountsByTax>
    </shoppingCart>
    <user>
      <id>TestUser</id>
    </user>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <grossAmount>145.00</grossAmount>
    <expirationTimeSpanInSeconds>3600</expirationTimeSpanInSeconds>
    <successUrl>http://success</successUrl>
    <pendingUrl>http://pending</pendingUrl>
    <errorUrl>http://error</errorUrl>
    <cancelUrl>http://cancel</cancelUrl>
    <refusedUrl>http://refused</refusedUrl>
    <paymentDirection>Deposit</paymentDirection>
  </redirectParameters>
</getRedirectDataRequest>

The standard getRedirectDataResponse is returned, for an example see getRedirectData.

Backend2BackendIntegration

The following parameters are mandatory for this payment method and must be provided in initiatePaymentRequest:

ParameterValue
userIPThe IP of the user in IPv4 or IPv6 format.

The following parameters must be provided in initiatePaymentRequest.userData xml section:

key (value type, account type, required)value
address
(address, required)		The address of the user
address.countryCode2
(string, required)		The country code of the user
address.telephoneNumber
(string, required)		The telephone number of the user
dateOfBirth
(datetime, required)		The date of birth of the user.
Please note that the user must be 18+ old for using this payment method!

Example initiatePaymentRequest:

<?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>235</paymentMethodID>
  <amount currencyCode="EUR">145.00</amount>
  <userID>user123</userID>
  <userdata>
    <address>
      <countryCode2>de</countryCode2>
      <telephoneNumber>+43(0)681/20306399</telephoneNumber>
    </address>
    <dateofbirth>1981-02-28t00:00:00</dateofbirth>
  </userdata>
  <userIP>10.10.10.10</userIP>
  <userSessionID>abc-9</userSessionID>
  <creationTypeID>1</creationTypeID>
	<shoppingCart>
	  <items>
		<item>
		  <product>
			<id>123</id>
			<name>Jeans</name>
			<description>stonewashed</description>
			<unitPrice>
			  <grossAmount>40</grossAmount>
			  <taxAmount rate="20" name="VAT">6.67</taxAmount>
			</unitPrice>
		  </product>
		  <quantity>1</quantity>
		  <totalPrice>
			<grossAmount>30</grossAmount>
			<taxAmount rate="20" name="VAT">5</taxAmount>
		  </totalPrice>
		  <discount>
			<name>Jeans-Promotion</name>
			<grossAmount>-10</grossAmount>
			<taxAmount rate="20" name="VAT">-1.67</taxAmount>
		  </discount>
		</item>
		<item>
		  <product>
			<id>456</id>
			<name>Skirt</name>
			<description>Flowers Design</description>
			<unitPrice>
			  <grossAmount>50</grossAmount>
			  <taxAmount rate="10" name="VAT">4.54</taxAmount>
			</unitPrice>
		  </product>
		  <quantity>2</quantity>
		  <totalPrice>
			<grossAmount>80</grossAmount>
			<taxAmount rate="10" name="MwSt">7.27</taxAmount>
		  </totalPrice>
		  <discount>
			<name>Spring-Promotion</name>
			<grossAmount>-10</grossAmount>
			<taxAmount rate="10" name="VAT">-0.91</taxAmount>
		  </discount>
		</item>
		 <item>
		  <product>
			<id>789</id>
			<name>Tshirt</name>
			<description>red</description>
			<unitPrice>
			  <grossAmount>15</grossAmount>
			  <taxAmount rate="20" name="VAT">2.5</taxAmount>
			</unitPrice>
		  </product>
		  <quantity>1</quantity>
		  <totalPrice>
			<grossAmount>15</grossAmount>
			<taxAmount rate="20" name="VAT">2.5</taxAmount>
		  </totalPrice>
		 </item>
	  </items>
	  <subTotalAmount>125</subTotalAmount>
	  <shippingCost>
		<name>Express</name>
		<grossAmount>30</grossAmount>
		<taxAmount rate="20" name="VAT">5</taxAmount>
	  </shippingCost>
	  <discounts>
		<discount>
		  <name>Sales-Discount</name>
		  <grossAmount>-10</grossAmount>
		  <taxAmount rate="20" name="VAT">-1.67</taxAmount>
		</discount>
	  </discounts>
	  <amountsByTax>
		<amountByTax taxName="VAT" taxRate="10">
		  <grossAmount>80</grossAmount>
		  <taxAmount>7.27</taxAmount>
		</amountByTax>
		<amountByTax taxName="VAT" taxRate="20">
		  <grossAmount>45</grossAmount>
		  <taxAmount>7.5</taxAmount>
		</amountByTax>
	  </amountsByTax>
	  <subTotalTaxAmount>14.77</subTotalTaxAmount>
	</shoppingCart>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing">
  <payment>
    <merchantID>KalixaAcceptDemo</merchantID>
    <shopID>KalixaAcceptDemo</shopID>
    <paymentMethod>
      <key>235</key>
      <value>PayByInvoice Deposit</value>
    </paymentMethod>
    <merchantTransactionID>Order99999</merchantTransactionID>
    <paymentID>28521cb4-d1ec-4fec-ba44-e255641cfdea</paymentID>
    <userID> user123</userID>
    <paymentProvider>
      <key>151</key>
      <value>RatePAY</value>
    </paymentProvider>
    <amount currencyCode="EUR">10</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>10.10.10.10</userIP>
    <state>
      <id>86900723-65e8-45f2-b08f-2ca5463bd51d</id>
      <definition>
        <key>142</key>
        <value>ExecutedByProvider</value>
      </definition>
      <createdOn>2017-02-21T15:04:12.7700715Z</createdOn>
      <paymentStateDetails xsi:nil="true"/>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">10</baseAmount>
    <paymentDetails xsi:nil="true"/>
    <paymentAccount>
      <paymentAccountID>0</paymentAccountID>
    </paymentAccount>
  </payment>
</initiatePaymentResponse>

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

The property ProviderTransactionVAN has to be used as Purpose of Payment and need to be printed on the customers invoice, together with the RatePay Bank Account Details (provided by RatePay directly to the Merchant).

Updated almost 3 years ago