# Direct API integration

###### The following test scenarios has to be done for the connection via API.

Before Go-Live please process the following tests if you connect front- and backend through our API.

# Operations

Consider all your possible use cases of your daily operational business. Please also **consider the following special features** in the following test chains if they occur in your business:

- Percentage and absolute discounts
- Bonus points
- Different shipping methods and costs
- Additional costs such as trusted shops, handling costs, ...
- Article bundles
- Free articles


## A: Cancellations

1. Structure the order as follows:
  - 1 x Article A
  - 1 x Article B
  - Shipping costs
  - Voucher for discount (fixed amount e.g. 5,00 €)
2. Execute a partial cancellation for Article A.
3. Cancel Article B, Shipping costs and the voucher.


#### Request example

details
summary
Click to expand

```xml Payment API 1.8
 PAYMENT_REQUEST
<shopping-basket amount="30.00" currency="EUR">
	<items>
		<item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 PAYMENT_CHANGE#cancellation1
<shopping-basket amount="10.00" currency="EUR">
	<items>
		<item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>
	</items>
</shopping-basket>

 PAYMENT_CHANGE#cancellation2
<shopping-basket amount="20.00" currency="EUR">
	<items>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>
```


```json Payment API 2.0

authorization
{
    "shop_baskets": [
        {
            "partner_shop_id": "PROVIDED_BY_RATEPAY",
            "shop_transaction_id": "ordernumber-0123",
            "gross_amount": 30.00,
            "items": [
                {
                    "gross_unit_price": 10.00,
                    "name": "article A",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 20.00,
                    "name": "article B",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "special_items": [
                {
                    "gross_unit_price": -5.00,
                    "name": "voucher",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 5.00,
                    "name": "shipping",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "vats": [
                {
                    "net_amount": 25.21,
                    "tax_amount": 4.79,
                    "tax_rate": 19
                }
            ]
        }
    ]
}

cancellation1
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "cancel-id-123",
  "gross_amount": 10.0
}

cancellation2
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "cancel-id-234",
  "gross_amount": 20.0
}
```

## B: Captures

1. Structure the order as follows:
  - 2 x Article A
  - 1 x Article B
  - Shipping costs
  - Voucher for discount (percentage amount e.g. -10%)
2. Execute a partial delivery for the following items:
  - 1 x Article A
  - Shipping costs
  - Voucher for discount
3. Execute a second delivery for the remaining articles.


#### Request example

details
summary
Click to expand

```xml Payment API 1.8
 PAYMENT_REQUEST
<shopping-basket amount="32.00" currency="EUR">
	<items>
		<item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-3.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 CONFIRMATION_DELIVER1
<shopping-basket amount="12.00" currency="EUR">
	<items>
		<item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>
	</items>
	<discount unit-price-gross="-3.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

CONFIRMATION_DELIVER2
<shopping-basket amount="20.00" currency="EUR">
	<items>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
</shopping-basket>
```


```json Payment API 2.0

authorization
{
    "shop_baskets": [
        {
            "partner_shop_id": "PROVIDED_BY_RATEPAY",
            "shop_transaction_id": "ordernumber-0123",
            "gross_amount": 32.00,
            "items": [
                {
                    "gross_unit_price": 10.00,
                    "name": "article A",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 20.00,
                    "name": "article B",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "special_items": [
                {
                    "gross_unit_price": -3.00,
                    "name": "voucher",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 5.00,
                    "name": "shipping",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "vats": [
                {
                    "net_amount": 26.89,
                    "tax_amount": 5.11,
                    "tax_rate": 19
                }
            ]
        }
    ]
}

capture1
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-123",
  "gross_amount": 12.0
}

capture2
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-234",
  "gross_amount": 20.0
}
```

## C: Returns

1. The order should be structured as follows:
  - 2 x Article A
  - 1 x Article B
  - Shipping costs
  - Voucher for discount (fixed amount e.g. 5,00 €)
2. Perform a delivery for all articles.
3. Execute a partial return with the following articles:
  - 1 x Article A
4. Finally return the remaining articles:
  - 1 x Article A
  - 1 x Article B
  - Shipping costs
  - Voucher for discount (fixed amount e.g. 5,00 €)


#### Request example

details
summary
Click to expand

```xml Payment API 1.8
 PAYMENT_REQUEST
<shopping-basket amount="40.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 CONFIRMATION_DELIVER
<shopping-basket amount="40.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 PAYMENT_CHANGE#return1
<shopping-basket amount="10.00" currency="EUR">
	<items>
		<item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>
	</items>
</shopping-basket>

 PAYMENT_CHANGE#return2
<shopping-basket amount="30.00" currency="EUR">
	<items>
        <item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>		
        <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>
```


```json Payment API 2.0

authorization
{
    "shop_baskets": [
        {
            "partner_shop_id": "PROVIDED_BY_RATEPAY",
            "shop_transaction_id": "ordernumber-0123",
            "gross_amount": 40.00,
            "items": [
                {
                    "gross_unit_price": 10.00,
                    "name": "article A",
                    "quantity": 2,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 20.00,
                    "name": "article B",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "special_items": [
                {
                    "gross_unit_price": -5.00,
                    "name": "voucher",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 5.00,
                    "name": "shipping",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "vats": [
                {
                    "net_amount": 33.61,
                    "tax_amount": 6.39,
                    "tax_rate": 19
                }
            ]
        }
    ]
}

capture
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-123",
  "gross_amount": 40.0
}

return1
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "return-id-123",
  "gross_amount": 10.0
}

return2
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "return-id-234",
  "gross_amount": 30.0
}
```

## D: Refund

1. The order should be structured as follows:
  - 2 x Article A
  - 1 x Article B
  - Shipping costs
  - Voucher
2. Perform a delivery for all articles.
3. Execute a refund (fixed amount e.g. 5,00 €):


#### Request example

details
summary
Click to expand

```xml Payment API 1.8
 PAYMENT_REQUEST
<shopping-basket amount="40.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
    <discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 CONFIRMATION_DELIVER
<shopping-basket amount="40.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
    <discount unit-price-gross="-5.00" tax-rate="19">discount</discount>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 PAYMENT_CHANGE#credit
<shopping-basket amount="-5.00" currency="EUR">
    <discount tax-rate="19.00" unit-price-gross="-5.00">Refund</discount>
</shopping-basket>
```


```json Payment API 2.0

authorization
{
    "shop_baskets": [
        {
            "partner_shop_id": "PROVIDED_BY_RATEPAY",
            "shop_transaction_id": "ordernumber-0123",
            "gross_amount": 40.00,
            "items": [
                {
                    "gross_unit_price": 10.00,
                    "name": "article A",
                    "quantity": 2,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 20.00,
                    "name": "article B",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "special_items": [
                {
                    "gross_unit_price": -5.00,
                    "name": "voucher",
                    "quantity": 1,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 5.00,
                    "name": "shipping",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "vats": [
                {
                    "net_amount": 33.61,
                    "tax_amount": 6.39,
                    "tax_rate": 19
                }
            ]
        }
    ]
}

capture
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-123",
  "gross_amount": 40.0
}

refund
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "refund-id-123",
  "gross_amount": 10.0
}
```

## E: Complex test

1. The order should be structured as follows:
  - 2 x Article A
  - 2 x Article B
  - 2 x Article C
  - Shipping costs
2. Perform a partial delivery for 3 articles + shipping costs:
  - 2 x Article A
  - 1 x Article B
  - Shipping costs
3. Perform a partial cancellation for Article C.
4. Execute a partial return for the following articles:
  - 1 x Article A
  - 1 x Article B
5. Make a partial delivery for the remaining articles:
  - 1 x Article B
  - 1 x Article C
6. Complete a full return for the remaining three articles.


#### Request example

details
summary
Click to expand

```xml Payment API 1.8
 PAYMENT_REQUEST
<shopping-basket amount="125.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="2" tax-rate="19" unit-price-gross="20.00">article B</item>
        <item article-number="345" quantity="2" tax-rate="19" unit-price-gross="30.00">article C</item>
	</items>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 CONFIRMATION_DELIVER1
<shopping-basket amount="45.00" currency="EUR">
	<items>
		<item article-number="123" quantity="2" tax-rate="19" unit-price-gross="10.00">article A</item>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
	<shipping unit-price-gross="5.00" tax-rate="19">shipping costs</shipping>
</shopping-basket>

 PAYMENT_CHANGE#cancellation
<shopping-basket amount="30.00" currency="EUR">
	<items>
		<item article-number="345" quantity="1" tax-rate="19" unit-price-gross="30.00">article C</item>
	</items>
</shopping-basket>

 PAYMENT_CHANGE#return1
<shopping-basket amount="30.00" currency="EUR">
	<items>
        <item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>		
        <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
	</items>
</shopping-basket>

 CONFIRMATION_DELIVER2
<shopping-basket amount="50.00" currency="EUR">
	<items>
		<item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>
		<item article-number="345" quantity="1" tax-rate="19" unit-price-gross="30.00">article C</item>
	</items>
</shopping-basket>

 PAYMENT_CHANGE#return2
<shopping-basket amount="60.00" currency="EUR">
	<items>
        <item article-number="123" quantity="1" tax-rate="19" unit-price-gross="10.00">article A</item>	        
        <item article-number="234" quantity="1" tax-rate="19" unit-price-gross="20.00">article B</item>		
        <item article-number="345" quantity="1" tax-rate="19" unit-price-gross="30.00">article C</item>
	</items>
</shopping-basket>
```


```json Payment API 2.0

authorization
{
    "shop_baskets": [
        {
            "partner_shop_id": "PROVIDED_BY_RATEPAY",
            "shop_transaction_id": "ordernumber-0123",
            "gross_amount":125.00,
            "items": [
                {
                    "gross_unit_price": 10.00,
                    "name": "article A",
                    "quantity": 2,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 20.00,
                    "name": "article B",
                    "quantity": 2,
                    "tax_rate": 19
                },
                {
                    "gross_unit_price": 30.00,
                    "name": "article C",
                    "quantity": 2,
                    "tax_rate": 19
                }
            ],
            "special_items": [
                {
                    "gross_unit_price": 5.00,
                    "name": "shipping",
                    "quantity": 1,
                    "tax_rate": 19
                }
            ],
            "vats": [
                {
                    "net_amount": 105.04,
                    "tax_amount": 19.96,
                    "tax_rate": 19
                }
            ]
        }
    ]
}

capture1
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-123",
  "gross_amount": 45.0
}

cancellation
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "cancel-id-123",
  "gross_amount": 30.0
}

return1
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "return-id-123",
  "gross_amount": 30.0
}

capture2
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "capture-id-234",
  "gross_amount": 50.0
}

return2
{
  "partner_shop_id": "PROVIDED_BY_RATEPAY",
  "partner_operation_id": "return-id-234",
  "gross_amount": 60.0
}
```

## F: Rejection

Transmit orders with the following data to trigger specific result and reason codes.
Please check whether these transactions were successfully rejected. Further check if the transactions do not appear in your subsequent systems.

### Payment API 1.8

| Result code | Reason code | First name | Last name | City |
|  --- | --- | --- | --- | --- |
| [150](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/result/150) | [730](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/reason/730) | Buyer | Ablehnung | Testhausen |
| [401](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/result/401) | [720](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/reason/720) | Payment | Ablehnung | Testhausen |
| [401](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/result/401) | [721](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/reason/721) | Risk | Ablehnung | Testhausen |
| [401](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/result/401) | [703](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/reason/703) | Generic* | Ablehnung | Testhausen |


*: For a rejection with reason code [703: Request not successful](/docs/developer/api_integration/payment_1.8/payment_api_documentation/responses/reason/703) you can freely select a technically valid first name.

### Payment API 2.0

| Email | Decline Categories |
|  --- | --- |
| buyer_identity@ratepay.com | [422 - Buyer Identity](/docs/developer/api_integration/payment_2.0/declines/422_buyer_identity/) |
| payment_attribute@ratepay.com | [422 - Payment Attribute](/docs/developer/api_integration/payment_2.0/declines/422_payment_attribute/) |
| risk_decision@ratepay.com | [422 - Risk Decision](/docs/developer/api_integration/payment_2.0/declines/422_risk_decision/) |
| transaction_risk@ratepay.com | [422 - Transaction Risk](/docs/developer/api_integration/payment_2.0/declines/422_transaction_risk/) |


## G: One Time Passcode

### Success

Transmit orders with the following data to trigger the OTP flow.

1. Structure the order as follows:
  - 1 x Article A
  - 1 x Article B
  - Shipping costs
2. Use **otp_required@ratepay.com** as the email address
3. Enter mock OTP code of `999999`


### Failure

Transmit orders with the following data to trigger the OTP flow.

1. Structure the order as follows:
  - 1 x Article A
  - 1 x Article B
  - Shipping costs
2. Use **otp_required@ratepay.com** as the email address
3. Enter any OTP code other than `999999` for 3 times