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 DebitOpen 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>
</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><?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><?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><?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><?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>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
<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>