Payment Query

The Payment Query is an optional step in the workflow in which merchants can allow their customers to select the desired payment method dynamically.

The Ratepay risk management system detects the appropriate payment methods for the given context and returns a list of the permitted Ratepay payment products. The used subtype influences the RMS in constructing the list of permitted products. This list can be empty if no Ratepay product is available for this customer.

warning

Please contact your Ratepay representative for contractual terms for using this feature.

Request Parameters

<head> Section

Parameter Condition Enumeration
system-id Mandatory
transaction-id Mandatory
operation Mandatory PAYMENT_QUERY
operation@subtype Mandatory full
credential Mandatory
customer-device Optional
external Optional
meta Optional

<content> Section

The <content> section of the PAYMENT_QUERY request contains customer and shopping basket data.

Parameter Condition Restriction
customer Mandatory
shopping-basket Mandatory Contains one or more item elements

XML Example

Copy
Copied
<?xml version="1.0" encoding="UTF-8"?>
<request version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
	<head>
		<system-id>myshop</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
		<operation subtype="full">PAYMENT_QUERY</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
		<external>
			<merchant-consumer-id>12345</merchant-consumer-id>
			<merchant-consumer-classification>vip</merchant-consumer-classification>
		</external>
		<meta>
			<systems>
				<system name="Shopmodul XY" version="1.2.2"></system>
			</systems>
		</meta>
	</head>
	<content>
		<customer>
			<first-name>Max</first-name>
			<last-name>Mustermann</last-name>
			<title>Dr.</title>
			<gender>M</gender>
			<date-of-birth>1982-10-31</date-of-birth>
			<ip-address>127.0.0.1</ip-address>
			<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>
					<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="52.20" currency="EUR">
			<items>
				<item article-number="1" quantity="2" unit-price-gross="17.40" tax-rate="19" category="1">Article 1</item>
				<item article-number="2" quantity="3" unit-price-gross="5.80" tax-rate="19" category="5" description-addition="customized printing">Article 2</item>
			</items>
		</shopping-basket>
	</content>
</request>

Response Parameters

<head> Section

Parameter Condition Enumeration
system-id Mandatory
transaction-id Mandatory
operation Mandatory PAYMENT_QUERY
operation@subtype Mandatory full
response-type Mandatory - success:
PAYMENT_PERMISSION
- failure:
STATUS_ERROR
external Optional
processing Mandatory

<content> Section

The <content> section of the PAYMENT_QUERY response contains a list of allowed Ratepay products.

Parameter Condition Restriction
products Mandatory for:
- response-type
PAYMENT_PRODUCTS
N/A for:
- other response-types		 Contains zero, one or more product elements.

XML Examples

All allowed

Copy
Copied
<?xml version="1.0"?>
<response version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
	<head>
		<system-id>myshop</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
		<operation subtype="full">PAYMENT_QUERY</operation>
		<response-type>PAYMENT_PRODUCTS</response-type>
		<external>
			<merchant-consumer-id>12345</merchant-consumer-id>
			<merchant-consumer-classification>vip</merchant-consumer-classification>
		</external>
		<processing>
			<timestamp>2012-04-30T12:27:39.234</timestamp>
			<status code="OK">Successfully</status>
			<reason code="700">Request successful</reason>
			<result code="402">Transaction result pending</result>
		</processing>
	</head>
	<content>
		<products>
			<product method="INVOICE" />
			<product method="INSTALLMENT" />
			<product method="ELV" />
			<product method="PREPAYMENT" />
		</products>
	</content>
</response>

None allowed

Copy
Copied
<?xml version="1.0"?>
<response version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
	<head>
		<system-id>myshop</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
		<operation subtype="full">PAYMENT_QUERY</operation>
		<response-type>PAYMENT_PRODUCTS</response-type>
		<external>
			<merchant-consumer-id>12345</merchant-consumer-id>
			<merchant-consumer-classification>vip</merchant-consumer-classification>
		</external>
		<processing>
			<timestamp>2012-04-30T12:27:39.234</timestamp>
			<status code="OK">Successfully</status>
			<reason code="700">Request successful</reason>
			<result code="402">Transaction result pending</result>
		</processing>
	</head>
	<content>
		<products/>
	</content>
</response>

Tech error

Copy
Copied
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<response version="1.0" xmlns="urn://www.ratepay.com/payment/1_0">
    <head>
		<system-id>myshop</system-id>
		<transaction-id>xx-xxxxxxxxxxxxxx</transaction-id>
        <operation subtype="full">PAYMENT_QUERY</operation>
        <response-type>STATUS_ERROR</response-type>
        <external>
            <merchant-consumer-id>12345</merchant-consumer-id>
            <merchant-consumer-classification>vip</merchant-consumer-classification>
        </external>
        <processing>
            <timestamp>2016-12-22T14:21:07.000</timestamp>
            <status code="ERROR">Error</status>
            <reason code="2100">billing address not valid</reason>
            <result code="150">Processing failed</result>
        </processing>
    </head>
    <content>
        <products/>
    </content>
</response>