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.
| Parameter | Condition | Restriction |
|---|---|---|
system-id | Mandatory | |
transaction-id | Mandatory | |
operation | Mandatory | PAYMENT_REQUEST |
credential | Mandatory | |
customer-device | Optional | |
external | Optional | |
meta | Optional |
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 |
Open Invoice B2C
<?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>Open Invoice B2B
<?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>Direct Debit
<?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>Pay in 3 with Direct Debit
<?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>230.00</amount> <!-- <total-amount> from response -->
<installment-details>
<installment-number>3</installment-number> <!-- <number-of-rates> from response -->
<installment-amount>76.67</installment-amount> <!-- <rate> from response -->
<last-installment-amount>76.66</last-installment-amount> <!-- <last-rate> from response -->
<interest-rate>0</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>Open Invoice B2C with Packstation as delivery address
<?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>
<address type="DELIVERY" delivery-type="PICK_UP_BOX">
<street>PACKSTATION 123</street> <!-- Number of the packstation -->
<zip-code>12345</zip-code>
<city>Berlin</city>
<country-code>DE</country-code>
<street-additional>12345678</street-additional> <!-- Account id of the packstation customer (needed for DHL) -->
</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>If the Payment Request is successfully processed, the response will contain the customer data including normalized addresses.
| 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 |
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 |
<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>230.00</amount>
<installment-details>
<installment-number>3</installment-number>
<installment-amount>76.67</installment-amount>
<last-installment-amount>76.66</last-installment-amount>
<interest-rate>0</interest-rate>
<payment-firstday>2</payment-firstday>
</installment-details>
<debit-pay-type>DIRECT-DEBIT</debit-pay-type>
<descriptor>DG0479414D0</descriptor> <!-- identify the transaction on documents and bank transfers ("Verwendungszweck"). -->
</payment>
</content>
</response>