Payment Request

The Payment Request is the centerpiece of the Ratepay payment workflow during the checkout process.

With the Payment Request, the merchant asks Ratepay to approve Ratepay payment for one specific customer, one specific shopping basket and one specific set of payment data.

Request Parameters

<head> Section

Parameter Condition Restriction
​system-id Mandatory
​transaction-id​ Mandatory
​operation​ Mandatory PAYMENT_REQUEST
​credential​ Mandatory
​customer-device​ Optional
​external Optional
​meta​ Optional

​<content> Section

The <content> section of the PAYMENT_REQUEST request contains customer, shopping-basket and payment data.

Parameter Condition Type Restriction
​customer​ Mandatory customerType
​shopping-basket​ Mandatory shoppingBasketType Contains one or more item child elements
​payment​ Mandatory paymentType

XML Examples

Open Invoice B2COpen Invoice B2BDirect DebitInstallments with Direct Debit
Copy
Copied
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
    <head>
        <system-id>MyTestsystem</system-id>
        <transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
        <operation>PAYMENT_REQUEST</operation>
        <credential>
            <profile-id>INTEGRATION_TE_DACH</profile-id>
            <securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
        </credential>
        <external>
            <order-id>O-1234-HDZ</order-id> 
            <merchant-consumer-id>12345</merchant-consumer-id> <!-- important for regular customer identification (German: Stammkundenkonzept) -->
        </external>
        <customer-device>
            <device-token>xxxxxxxxxxxxxxxxxxxxxxxx</device-token>
        </customer-device>
    </head>
    <content>
        <customer>
            <first-name>Max</first-name>
            <last-name>Mustermann</last-name>
            <gender>M</gender> <!-- M=Male, F=Female, U=Unknown -->
            <date-of-birth>1982-10-31</date-of-birth>
            <ip-address>127.0.0.1</ip-address> <!-- ip-adress of customer -->
            <contacts>
                <email>test@test.de</email>
                <phone>
                    <direct-dial>030123456</direct-dial>
                </phone>
            </contacts>
            <addresses>
                <address type="BILLING">
                    <street>Nicht-Versenden-Straße 1</street>
                    <street-number>2</street-number> <!-- optional, street-number can also be part of street -->
                    <zip-code>12345</zip-code>
                    <city>Testhausen</city>
                    <country-code>DE</country-code>
                </address>
            </addresses>
            <nationality>DE</nationality>
            <customer-allow-credit-inquiry>yes</customer-allow-credit-inquiry>
        </customer>
        <shopping-basket amount="230.00" currency="EUR">
            <items>
                <item article-number="123" quantity="6" tax-rate="19" unit-price-gross="10.00">Artikel A</item>
                <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="100.00">Artikel B</item>
                <item article-number="345" quantity="2" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item> <!-- discount@item may be used for percent vouchers/discounts -->
            </items>
            <discount unit-price-gross="-15.00" tax-rate="19">Rabatt</discount> <!-- discount@shopping-basket may be used for value vouchers/discounts -->
            <shipping unit-price-gross="5.00" tax-rate="19">Versandkosten</shipping>
        </shopping-basket>		
        <payment currency="EUR" method="INVOICE">
            <amount>230.00</amount> <!-- equals shopping-basket amount for payment method INVOICE -->
        </payment>
    </content>
 </request>
Copy
Copied
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
	<head>
		<system-id>MyTestsystem</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
		<operation>PAYMENT_REQUEST</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
		<external>
			<order-id>O-1234-HDZ</order-id> 
			<merchant-consumer-id>12345</merchant-consumer-id> <!-- important for regular customer idetification (German: Stammkundenkonzept) -->
		</external>
		<customer-device>
			<device-token>xxxxxxxxxxxxxxxxxxxxxxxx</device-token> <!-- further information in Appendix5_DeviceFingerprint -->
		</customer-device>
	</head>
	<content>
		<customer>
			<first-name>Max</first-name>  <!-- optional for B2B-->
			<last-name>Mustermann</last-name>  <!-- optional for B2B-->
			<company-name>Test GmbH</company-name>  <!-- mandatory for B2B, date-of-birth optional for B2B -->
			<gender>U</gender> <!-- U=Unknown, M=Male, F=Female -->
			<ip-address>127.0.0.1</ip-address> <!-- ip-adress of customer -->
			<contacts>
				<email>test@test.de</email>
				<phone>
					<direct-dial>030123456</direct-dial>
				</phone>
			</contacts>
			<addresses>
				<address type="BILLING">
				    <company>Test GmbH</company>
					<street>Nicht-Versenden-Straße 1</street>
					<street-number>2</street-number> <!-- optional, street-number can also be part of street -->
					<zip-code>12345</zip-code>
					<city>Testhausen</city>
					<country-code>DE</country-code>
				</address>
				<address type="DELIVERY">  <!-- only if it is contractually agreed -->
					<company>Test GmbH</company>
					<street>Straße der Lieferadresse</street>
					<street-number>2</street-number> <!-- optional, street-number can also be part of street -->
					<zip-code>54321</zip-code>
					<city>Testhausen</city>
					<country-code>DE</country-code>
				</address>
			</addresses>
			<nationality>DE</nationality>
			<customer-allow-credit-inquiry>yes</customer-allow-credit-inquiry>
			<vat-id>DE123456789</vat-id> <!-- optional, German: Umsatzsteueridentifikationsnummer -->
			<company-id>HRB 124156B</company-id> <!-- optional, German: Handelsregisternummer -->
			<registry-location>Hamburg</registry-location> <!-- optional, German: Sitz Registergericht -->
			<company-type>GMBH</company-type> <!-- optional, German: Firmierung -->
			<homepage>http://www.test-gmbh.testtld</homepage>
		</customer>
		<shopping-basket amount="230.00" currency="EUR">
			<items>
				<item article-number="123" quantity="6" tax-rate="19" unit-price-gross="10.00">Artikel A</item>
				<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="100.00">Artikel B</item>
				<item article-number="345" quantity="2" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item> <!-- discount@item may be used for percent vouchers/discounts -->
			</items>
			<discount unit-price-gross="-15.00" tax-rate="19">Rabatt</discount> <!-- discount@shopping-basket may be used for value vouchers/discounts -->
			<shipping unit-price-gross="5.00" tax-rate="19">Versandkosten</shipping>
		</shopping-basket>		
		<payment currency="EUR" method="INVOICE">
			<amount>230.00</amount> <!-- equals shopping-basket amount for payment method INVOICE -->
		</payment>
	</content>
</request>
Copy
Copied
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
    <head>
        <system-id>MyTestsystem</system-id>
        <transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
        <operation>PAYMENT_REQUEST</operation>
        <credential>
            <profile-id>INTEGRATION_TE_DACH</profile-id>
            <securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
        </credential>
        <external>
            <order-id>O-1234-HDZ</order-id> 
            <merchant-consumer-id>12345</merchant-consumer-id> <!-- important for regular customer idetification (German: Stammkundenkonzept) -->
        </external>
        <customer-device>
            <device-token>xxxxxxxxxxxxxxxxxxxxxxxx</device-token>
        </customer-device>
    </head>
    <content>
        <customer>
            <first-name>Max</first-name>
            <last-name>Mustermann</last-name>
            <gender>M</gender> <!-- M=Male, F=Female, U=Unknown -->
            <date-of-birth>1982-10-31</date-of-birth>
            <ip-address>127.0.0.1</ip-address> <!-- ip-adress of customer -->
            <contacts>
                <email>test@test.de</email>
                <phone>
                    <direct-dial>030123456</direct-dial>
                </phone>
            </contacts>
            <addresses>
                <address type="BILLING">
                    <street>Nicht-Versenden-Straße 1</street>
                    <street-number>2</street-number> <!-- optional, street-number can also be part of street -->
                    <zip-code>12345</zip-code>
                    <city>Testhausen</city>
                    <country-code>DE</country-code>
                </address>
                <address type="DELIVERY"> <!-- only if it is contractually agreed -->
                    <street>Straße der Lieferadresse</street>
                    <street-number>2</street-number> <!-- optional, street-number can also be part of street -->
                    <zip-code>54321</zip-code>
                    <city>Testhausen</city>
                    <country-code>DE</country-code>
                </address>
            </addresses>
            <bank-account>
                <owner>Max Mustermann</owner> <!-- has to be same as customer name -->
                <iban>DE44100500001654698497</iban>
                <bic-swift>BELADEBEXXX</bic-swift> <!-- optional for German & Austrian bank accounts -->
            </bank-account>
            <nationality>DE</nationality>
            <customer-allow-credit-inquiry>yes</customer-allow-credit-inquiry>
        </customer>
        <shopping-basket amount="230.00" currency="EUR">
            <items>
                <item article-number="123" quantity="6" tax-rate="19" unit-price-gross="10.00">Artikel A</item>
                <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="100.00">Artikel B</item>
                <item article-number="345" quantity="2" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item> <!-- discount@item may be used for percent vouchers/discounts -->
            </items>
            <discount unit-price-gross="-15.00" tax-rate="19">Rabatt</discount> <!-- discount@shopping-basket may be used for value vouchers/discounts -->
            <shipping unit-price-gross="5.00" tax-rate="19">Versandkosten</shipping>
        </shopping-basket>		
        <payment currency="EUR" method="ELV">
            <amount>230.00</amount> <!-- equals shopping-basket amount for payment method ELV -->
        </payment>
    </content>
</request>
Copy
Copied
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
    <head>
        <system-id>MyTestsystem</system-id>
        <transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
        <operation>PAYMENT_REQUEST</operation>
        <credential>
            <profile-id>INTEGRATION_TE_DACH</profile-id>
            <securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
        </credential>
        <external>
            <order-id>O-1234-HDZ</order-id> 
            <merchant-consumer-id>12345</merchant-consumer-id> <!-- important for regular customer idetification (German: Stammkundenkonzept) -->
        </external>
        <customer-device>
            <device-token>xxxxxxxxxxxxxxxxxxxxxxxx</device-token> <!-- further information in Appendix5_DeviceFingerprint -->
        </customer-device>
    </head>
    <content>
        <customer>
            <first-name>Max</first-name>
            <last-name>Mustermann</last-name>
            <gender>M</gender> <!-- M=Male, F=Female, U=Unknown -->
            <date-of-birth>1982-10-31</date-of-birth>
            <ip-address>127.0.0.1</ip-address> <!-- ip-adress of customer -->
            <contacts>
                <email>test@test.de</email>
                <phone>
                    <direct-dial>030123456</direct-dial>
                </phone>
            </contacts>
            <addresses>
                <address type="BILLING">
                    <street>Nicht-Versenden-Straße 1</street>
                    <street-number>2</street-number> <!-- optional, street-number can also be part of street -->
                    <zip-code>12345</zip-code>
                    <city>Testhausen</city>
                    <country-code>DE</country-code>
                </address>
                <address type="DELIVERY"> <!-- only if it is contractually agreed -->
                    <street>Straße der Lieferadresse</street>
                    <street-number>2</street-number> <!-- optional, street-number can also be part of street -->
                    <zip-code>54321</zip-code>
                    <city>Testhausen</city>
                    <country-code>DE</country-code>
                </address>
            </addresses>
            <bank-account>
                <owner>Max Mustermann</owner> <!-- has to be same as customer name -->
                <iban>DE44100500001654698497</iban>
                <bic-swift>BELADEBEXXX</bic-swift> <!-- optional for German & Austrian bank accounts -->
            </bank-account>
            <nationality>DE</nationality>
            <customer-allow-credit-inquiry>yes</customer-allow-credit-inquiry>
        </customer>
        <shopping-basket amount="230.00" currency="EUR">
            <items>
                <item article-number="123" quantity="6" tax-rate="19" unit-price-gross="10.00">Artikel A</item>
                <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="100.00">Artikel B</item>
                <item article-number="345" quantity="2" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item> <!-- discount@item may be used for percent vouchers/discounts -->
            </items>
            <discount unit-price-gross="-15.00" tax-rate="19">Rabatt</discount> <!-- discount@shopping-basket may be used for value vouchers/discounts -->
            <shipping unit-price-gross="5.00" tax-rate="19">Versandkosten</shipping>
        </shopping-basket>		
        <payment currency="EUR" method="INSTALLMENT">
            <amount>244.67</amount>	<!-- <total-amount> from response -->
            <installment-details>
                <installment-number>6</installment-number> <!-- <number-of-rates> from response -->
                <installment-amount>40.79</installment-amount> <!-- <rate> from response -->
                <last-installment-amount>40.72</last-installment-amount> <!-- <last-rate> from response -->
                <interest-rate>13.7</interest-rate> <!-- <interest-rate> from response -->
                <payment-firstday>2</payment-firstday> <!-- <payment-firstday> from response -->
            </installment-details>
            <debit-pay-type>DIRECT-DEBIT</debit-pay-type>
        </payment>
    </content>
 </request>

Response Parameters

success

If the Payment Request is successfully processed, the response will contain the customer data including normalized addresses.

<head> Section

Parameter Condition Enumeration
system-id Mandatory
transaction-id Mandatory
operation Mandatory PAYMENT_REQUEST
response-type Mandatory - success:
PAYMENT_PERMISSION
- failure:
STATUS_ERROR
external Optional
processing Mandatory

<content> Section

The <content> section of the PAYMENT_REQUEST response contains customer and payment data.

Parameter Condition Type
customer Mandatory for
- response-type:
PAYMENT_PERMISSION
-N/A for:
- all other cases		 customerType
payment Mandatory for
- response-type:
PAYMENT_PERMISSION
-N/A for:
- all other cases		 paymentType

XML Example

Copy
Copied
<response xmlns="urn://www.ratepay.com/payment/1_0" version="1.0">
	<head>
		<system-id>MyTestsystem</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
		<operation>PAYMENT_REQUEST</operation>
		<response-type>PAYMENT_PERMISSION</response-type>
		<external>
			<merchant-consumer-id>12345</merchant-consumer-id>
		</external>
		<processing>
			<timestamp>2016-01-06T16:30:20.000</timestamp>
			<status code="OK">Successfully</status>
			<reason code="700">Request successful</reason>
			<result code="402">Transaction result pending</result>
		</processing>
	</head>
	<content>
		<customer>
			<addresses>
				<address>
					<street>Nicht-Versenden-Straße 1</street>
					<street-number>2</street-number>
					<zip-code>12345</zip-code>
					<city>Testhausen</city>
					<country-code>DE</country-code>
				</address>
			</addresses>
		</customer>
		<payment method="INSTALLMENT">
			<amount>244.67</amount>
			<installment-details>
				<installment-number>6</installment-number>
				<installment-amount>40.79</installment-amount>
				<last-installment-amount>40.72</last-installment-amount>
				<interest-rate>13.7</interest-rate>
				<payment-firstday>28</payment-firstday>
			</installment-details>
			<debit-pay-type>BANK-TRANSFER</debit-pay-type>
			<descriptor>DG0479414D0</descriptor> <!-- identify the transaction on documents and bank transfers ("Verwendungszweck"). -->
		</payment>
	</content>
</response>