Payment Change

After the checkout process has been finalized, the following actions can be performed: cancellation, return, credit/debit and add items to the shopping cart.

Request Parameters

<head> Section

Parameter Condition Enumeration
system-id Mandatory
transaction-id Mandatory
​operation​ Mandatory PAYMENT_CHANGE
​operation@subtype​ Mandatory cancellation
return
credit
change-order
​credential​ Mandatory
​external​ Optional
​meta​ Optional

<content> Section

The <content> section of the PAYMENT_CHANGE request contains shopping basket data.

Parameter Condition Type
customer Optional since API version 1.7.5 customerType
shopping-basket Mandatory shoppingBasketType
payment Optional since API version 1.7.5 paymentType
attention

With Gateway API version 1.8 and higher the content of the shopping basket consists of the items that are changed (cancelled, delivered, returned) – except the PAYMENT_CHANGE change-order. This operation replaces the open basket.

Operation subtypes

cancellation

Customer/merchant cancels some or all items which are still pending for delivery.

partial cancellationfull-cancellation
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 subtype="cancellation">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="40.00" currency="EUR">
			<items>
				<item article-number="345" quantity="1" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item>
			</items>
		</shopping-basket>
	</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 subtype="cancellation">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="0.00" currency="EUR">
			<items/>
		</shopping-basket>
	</content>
</request>

return

Customer returns some or all items which were already delivered.

partial-returnfull-return
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 subtype="return">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="45.00" currency="EUR">
			<items>
				<item article-number="123" quantity="5" tax-rate="19" unit-price-gross="10.00">Artikel A</item>
			</items>
			<discount unit-price-gross="-5.00" tax-rate="19">Rabatt</discount>
		</shopping-basket>
	</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 subtype="return">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="0.00" currency="EUR">
			<items/>
		</shopping-basket>		
	</content>
</request>

change-order

Customer/merchant adds/removes one or more items.

danger

The operation completely replaces the open items. This means that all open items have to be submitted. Items that are open before and not included at the change-order will be cancelled automatically.

warning

All Items that were subsequently added to the order also have to be delivered with a succeeding CONFIRMATION_DELIVER. "Financial" items added by a credit must not be delivered.

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 subtype="change-order">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="180.00" currency="EUR">
			<items>
				<item article-number="123" quantity="6" tax-rate="19" unit-price-gross="10.00">Article a</item> <!-- difference in description frontend/ backend -->
				<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="90.00">Artikel B</item> <!-- difference in price frontend/ backend -->
				<item article-number="345a" quantity="1" tax-rate="19" unit-price-gross="50.00" discount="-10.00">Artikel C</item> <!-- difference in article-number frontend/ backend -->
			</items>
			<discount unit-price-gross="-15.00" tax-rate="19">Rabatt</discount>
			<shipping unit-price-gross="5.00" tax-rate="19">Versandkosten</shipping>
		</shopping-basket>	
	</content>
</request>

credit

Merchant adds one or more financial items representing a credit or a debit subsequently to the order after (1st) delivery.

warning

These items must not be delivered.

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 subtype="credit">PAYMENT_CHANGE</operation>
		<credential>
			<profile-id>INTEGRATION_TE_DACH</profile-id>
			<securitycode>4c0a11923fa3433fb168f9c7176429e9</securitycode>
		</credential>
	</head>
	<content>
		<shopping-basket amount="-10.00" currency="EUR">
			<discount unit-price-gross="-10.00" tax-rate="19.00">Kulanzgutschrift</discount>
		</shopping-basket>
	</content>
</request>

Learn more

More details on payment-changes including XML examples:

API: Payment-Change Logic

Response Parameters

The PAYMENT_CHANGE response only contains payment data.

<head> Section

Parameter Condition Enumeration
system-id Mandatory
transaction-id Mandatory
operation Mandatory
operation@subtype Mandatory - cancellation
- return
- credit
- change-order
response-type Mandatory - success:
PAYMENT_PERMISSION
- failure:
STATUS_ERROR
external Optional
processing Mandatory

<content> Section

Parameter Condition
payment Optional since API version 1.7.5