Wirecard Payment in Installments

REST API

Wirecard Payment in Installments is a type of Offline Bank Transfer.

General Information
Countries and Currencies

Countries

DE, AT

Currencies

EUR

Communication Formats

This table illustrates how Wirecard Payment in Installments notifications are encoded and which formats and methods can be used for requests and responses.

Requests/Responses

Format

XML

Methods

POST

IPN Encodement

Please follow the instructions given at Instant Payment Notification to set up IPN.

Transaction Types

For transaction type details which are not given here, go to API Reference: Transaction Types.

Transaction Type Description Link to samples

authorization

Performs a creditworthiness check at the moment when the consumer makes an order. All order items must be listed for the shopping basket. The authorization amount must match the value of the items in the basket.

authorization samples

capture-authorization

Used to capture the reserved funds at the moment when some or all goods are physically delivered to the consumer. Available only on successful authorization response which wasn’t voided nor fully captured. Partial (and multiple) capture is allowed, as long as the authorization limit is not exceeded. Basket items only list the items that were delivered to the consumer in this delivery, not the ones that were delivered before or are waiting to be delivered. The total amount of the capture must be the value of the items in the basket.

capture-authorization samples

void-authorization

Used when the consumer wishes to cancel some or all (not yet shipped) items from the order. Available only for a successful authorization response which was not yet voided or captured. Partial and multiple void are allowed, until all items from the order are canceled or shipped. Basket items only list those items which are canceled from the order.

void-authorization samples

refund-capture

Used when the consumer wishes to return some or all delivered goods. Available on a successful capture-authorization. Partial and multiple refunds are allowed, until all delivered items have been returned. Basket items list only those items which are returned to the merchant.

refund-capture samples

credit

Used when the merchant wishes to grant a discount on an existing order. Items from this order may already be delivered to the consumer. Available on a successful capture-authorization. Multiple credits are allowed, but the overall sum of credits must not exceed the value of the goods delivered to the consumer. The credit transaction must include a basket item representing the discount. The credit transaction must refer to the successful authorization transaction-id.

credit samples

  1. Basket items must be specified in every request.

  2. The response for each authorization request returns an individual string (an alphanumerical code) in the descriptor field.

  3. The descriptor must be printed on all invoice documents and saved by the shop (used by consumers in bank transfers; German: "Verwendungszweck").­­

  4. capture-authorization transactions must follow a successful authorization on the same day the goods are dispatched.

  5. The period between authorization and the first capture-authorization must be at least 4 hours.

  6. Merchants can request several partial capture-authorization transactions if the goods are shipped in separate shipments.

Test Credentials

You can use these credentials for payment tests as well as testing the installment configuration service and the installment calculator.

URLs (Endpoint)

authorization

https://api-test.wirecard.com/engine/rest/paymentmethods/

capture-authorization
credit
refund-capture
void-authorization

https://api-test.wirecard.com/engine/rest/payments/

Merchant Account ID (MAID)

9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e

Username

16390-testing

Password

3!3013=D3fD8X7

Banking Credentials

IBAN

DE42512308000000060004

BIC

WIREDEMMXXX

Workflow
  1. Consumer adds items to shopping basket.

  2. Consumer selects the payment method Wirecard Payment in Installments, the duration and rate of payment.

  3. Consumer proceeds to checkout.

  4. You send an authorization request including basket items to WPG.

  5. WPG generates a descriptor (an alphanumerical code, starting with DG).

  6. WPG sends you an authorization response (the authorization response includes the descriptor).

  7. You send a capture request to WPG when the basket items are ready for delivery.

  8. After a successful capture request, WPG generates the invoice, including the descriptor.

    1. Alternatively, you can generate the invoice.

  9. Invoice generator informs Wirecard Bank.

  10. Wirecard Bank collects the transaction amount from consumer’s bank account.

  11. If any payment changes are necessary, the following transaction types are available: credit, refund-capture or void-authorization.

Fields

The following elements are mandatory M or optional O in sending a request for Wirecard Payment in Installments (complete field list available in REST API field list):

Field Cardinality Datatype Size Description

payment.

merchant-account-id

M

String

36

Unique identifier for a merchant account

request-id

M

String

150

This is the identification number of the request. It has to be unique for each request.

transaction-type

M

String

30

This is the type for a transaction: authorization, capture, void-authorization, refund-capture and credit are supported for Wirecard Payment in Installments.

requested-amount

M

Numeric

18.3

This is the amount of the transaction. The amount of the decimal place depends on the currency. The amount must be between a defined minimum value and a defined maximum value.

requested-amount/@currency

M

String

3

This is the currency of the transaction. For Germany and Austria, only EUR is allowed. Switzerland additionally accepts CHF.

order-detail

O

String

65535

Details of the order filled by the merchant.

order-number

M

String

64

The order number from the merchant.

consumer-id

O

String

50

Merchant’s identifier for the consumer.

locale

O

String

5

It is used to control the language of the consumer message and the correspondence to the consumer. Allowed values:
fr (French)
en (English)
nl (Dutch)
de (German)
If empty or sent with an incorrect value, de is used by default.

payment.invoice.

invoice-number

O

String

32

Merchant’s invoice identifier, optional for capture-authorization request.

payment.payment-methods.payment-method

@name

M

String

15

The name of the Payment Method is ratepay-install.

payment.account-holder.

first-name

M

String

32

Account holder’s first name.

last-name

M

String

32

Account holder’s last name.

email

M

String

64

Account holder’s email address.

phone

M

String

32

Account holder’s phone number.

date-of-birth

M

String

10

Account holder’s date of birth. Format (according to ISO 8601): YYYY-MM-DD
This format cannot be customized.

gender

O

Enumeration

1

Account holder’s gender.

payment.account-holder.address.

street1

M

String

128

The first line of the street address of the account holder. Must include house number.

street2

O

String

128

The second line of the street address of the account holder.

city

M

String

32

The city of the address of the account holder.

state

O

String

32

The state or province of the address of the account holder.

country

M

String

2

The country id of the address of the account holder. The two-letter country code follows ISO 3166-1 alpha-2.

postal-code

M

String

16

The postal code or ZIP of the address of the account holder.

payment.bank-account.

Consumer’s bank account details.

bank-name

M

String

100

The name of the consumer’s bank.

iban

M/O

String

34

The international bank account number (IBAN) required in a bank transfer. It is an international standard for identifying bank accounts across national borders. The current standard is ISO 13616:2007, which indicates SWIFT as the formal registrar.
Allowed characters: [a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[0-9]{7}([a-zA-Z0-9]?){0,16}.
Mandatory if account-number is not used.

bic

M/O

String

15

The bank identifier code (BIC) in bank transfer.
Allowed characters: ([a-zA-Z]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3}).
Mandatory if iban is used

account-number

M/O

String

34

The number designating a bank account used nationally.
Mandatory if iban is not used.

bank-code

M/O

String

15

The national bank sorting code for national bank transfers.
Mandatory if account-number is used.

payment.order-items.order-item.

name

M

String

256

Name of the item in the basket.

article-number

M

String

256

EAN or other article identifier for merchant.

amount

M

Decimal

18.3

Item price per unit.

tax-rate

M

Decimal

18.3

Item tax rate per unit.

quantity

M

Number

5

Total count of items in the order.

payment.shipping.

Shipping fields have to match the billing address (specified as account-holder).

first-name

O

String

32

The first name of the account holder.

last-name

O

String

32

The last name of the account holder.

phone

O

String

32

The phone number of the account holder.

payment.shipping.address.

shipping.address fields have to match the billing address (specified as account-holder.address).

street1

O

String

128

The first line of the shipping address.

street2

O

String

128

The second line of the shipping address.

city

O

String

32

The city of the shipping address.

state

O

String

32

The state or province of the shipping address.

country

O

String

2

The country ID of the address of the shipping address. The two-letter country code follows ISO 3166-1 alpha-2.

postal-code

O

String

16

The postal code or ZIP of the shipping address.

payment.device.

fingerprint

M/O

String

4096

Device fingerprinting token that was used in merchant’s online shop to track this transaction. Fingerprints can be used to fully or partially identify individual users or devices even when cookies are turned off.
It is mandatory for authorization.

payment.custom-fields.

All custom fields are needed for mapping the authorization. Therefore they all are mandatory for authorization.

custom-field@name="total-amount"

M/O

Decimal

18.3

custom-field@value=installment-calculator-response.installments.installment.details.total-amount

custom-field@name="interest-rate"

M/O

Decimal

18.3

custom-field@value=installment-calculator-response.installments.installment.details.interest-rate

custom-field@name="number-of-rates"

M/O

Number

5

custom-field@value=installment-calculator-response.installments.installment.details.number-of-rates

custom-field@name="rate"

M/O

Number

5

custom-field@value=installment-calculator-response.installments.installment.details.rate

custom-field@name="last-rate"

M/O

Number

5

custom-field@value=installment-calculator-response.installments.installment.details.last-rate

custom-field@name="payment-firstday"

M/O

Number

5

custom-field@value=installment-calculator-response.installments.installment.details.payment-first-day

Installment Configuration Service

You can use the installment configuration service to configure installment plan parameters tailored for your profile.

Communication Formats

This table illustrates in which formats and methods the installment configuration service can be used for requests and responses.

Requests/Responses

Format

XML, JSON

Methods

POST

Test Credentials

URL (Endpoint)

https://api-test.wirecard.com/engine/rest/utils/installmentconfiguration

Please use these test credentials.

Fields
Request
Field Cardinality Datatype Size Description

installment-configuration-request.

payment-method

M

String

15

The name of the payment method is ratepay-install.

merchant-account-id

M

String

36

Merchant account ID.

Response
Field Datatype Description
We show this table without the Size values as you receive the response directly from Wirecard Payment in Installments and we cannot provide this information.

installment-configuration-response.statuses.status

These fields describe the structure of the response statuses.

@code

String

The status code of the response (Example: 200.0000).

@description

String

The description of the response status code (Example: Successful Response).

@severity

String

This field indicates if a status is an error or information. Values can be:
information
warning.

installment-configuration-response.configuration.

These fields send the configuration available with Wirecard Payment in Installments. They contain the installment options available to your consumers.

interest-rate-default

Decimal

The default interest rate is used if the interest rate in the calculation request deviates from the range of your supported rates. (Example: 13.7).

interest-rate-min

Decimal

Minimum interest rate (Example: 5.00).

interest-rate-max

Decimal

Maximum interest rate (Example: 10.50).

interest-rate-merchant2bank

Decimal

The interest rate defined contractually between the merchant and the factoring entity (Example: 15.00).

month-number-min

Number

Minimum duration of installment plan (Example: 2).

month-number-max

Number

Maximum duration of installment plan (Example: 2).

month-longrun

Number

Minimum duration of a long run installment plan (Example: 24).

amount-min-longrun

Decimal

Minimum amount for long run installment plan.

month-allowed

String

Comma separated list of allowed durations, stated in months (Example: 3,6,7,8,9,10,11,12,24,36).

valid-payment-firstdays

String

Comma separated list of calendar days which are allowed as starting days of the installment plan (Example: 1,15,28).

payment-firstday

Number

Default calendar day of the first payment (Example: 28).

payment-amount

Decimal

Minimum payment amount (Example: 200.55).

payment-lastrate

Decimal

Minimum amount of last payment rate. Otherwise this amount is added to the last but one rate (Example: 89.24).

rate-min-normal

Decimal

Minimum rate of a normal installment plan (Example: 5.00).

rate-min-longrun

Decimal

Minimum rate of a long running installment plan (Example: 4.00).

service-charge

Decimal

Additional costs of financing (Example: 1.95).

min-difference-dueday

Number

Minimum difference in days until due date (Example: 20).

name

String

Name of installment calculation (Example: DEFAULT).

type

String

Type of installment calculation (Example: profileId).

Installment Calculator

The installment calculator service provides the list of available installment plans.

Wirecard Payment in Installments supports two types of installment plan:

  • calculation by rate

  • calculation by time.

The consumer can choose the type of plan best suited to the payment of the purchased amount.

Communication Formats

This table illustrates in which formats and methods the installment calculator service can be used for requests and responses.

Requests/Responses

Format

XML, JSON

Methods

POST

Test Credentials

URL (Endpoint)

https://api-test.wirecard.com/engine/rest/utils/installmentcalculator

Please use these test credentials.

Fields
Request
Field Cardinality Datatype Size Description

installment-calculator-request.

payment-method

M

String

15

The name of the payment method is ratepay-install.

merchant-account-id

M

String

36

Merchant account ID. It must have the following format: 815c32ab-486d-4e4c-baf8-f412e2e4e9b8.

amount

M

Decimal

18.3

Full amount of the purchase. It must have the format of Money (Example: 100.00)

amount/@currency

M

String

3

The currency of the purchase. Wirecard Payment in Installments requires EUR.

rate

M/O

Decimal

3.2

Monthly rate which the consumer wants to pay. It must have the format of Money (Example: 25.00). It is mandatory for calculation by rate. It must not be used when calculating the installment plan by time.

rate/@currency

M

String

3

The currency of the rate. Wirecard Payment in Installments requires EUR.

months

M/O

Number

3

Number of months to cover the duration of the installment plan. It is mandatory for calculation by time. It must not be used when calculating the installment plan by rate.

Response
Field Datatype Description
We show this table without Size values as you receive the response directly from Wirecard Payment in Installments and we cannot provide this information.

installment-calculator-response.

amount

Decimal

Full amount of the purchase. It must have the format of Money (Example: 100.00)

amount/@currency

String

The currency of the purchase. Wirecard Payment in Installments requires EUR.

rate

Decimal

Monthly rate which the consumer wants to pay. It must be in the format of Money (Example: 25.00).

rate/@currency

String

The currency of the rate. Wirecard Payment in Installments requires EUR.

state

String

The state of the response. Values can be:
success
failed.

installment-calculator-response.statuses.status.

These fields describe the structure of the response statuses.

@code

String

The status code of the response (Example: 200.0000).

@description

String

The description of the response status code (Example: Successful Response).

@severity

String

This field indicates the status of the transaction. Values can be:
information
error.

installment-calculator-response.installments.installment.details.

These fields describe the structure of the available installment plans which are sent in the response. It is a breakdown of fees and other information about the corresponding installment plan.

interest-rate

Decimal

Interest rate used to calculate the annual percentage rate (Example: 12.9).

monthly-debit-interest

Decimal

Monthly interest rates based on interest-rate (Example: 1.02).

service-charge

Decimal

Additional costs of financing (Example: 1.95).

rate

Decimal

Monthly rate the consumer has to pay (Example: 89.35).

annual-percentage-rate

Decimal

The annual percentage rate is based on service-charge and interest-rate (Example: 12.25).

number-of-rates

Number

Number of months to cover the duration of the installment plan.

amount

Decimal

Price that has to be financed (Example: 1000.00).

interest-amount

Decimal

Total of all monthly paid interests (Example: 72.09).

total-amount

Decimal

Total of amount, adding up interest-amount and service-charge (Example: 1074.04).

last-rate

Decimal

Last rate which the consumer has to pay (Example: 89.24).

payment-first-day

Number

Calendar day of the first payment.

Features
Basket Items Details

Basket items details must be sent with every request. Content of the shopping basket depends on the location of the items. There can be 3 different locations:

  • the (distribution) storage of the merchant

  • the delivery (items are „on their way")

  • home of the consumer.

The shopping basket always contains the items that are being authorized (ordered), captured (delivered), voided (canceled), refunded (returned) or credited depending to the transaction type.

The detailed items of the shopping basket are stored as a part of payment details on provider and they can be obtained from Wirecard Payment Gateway later as part of transaction details.

Samples
Installment Configuration
XML Configuration
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-configuration-request xmlns="http://www.elastic-payments.com/schema/utils">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <payment-method>ratepay-install</payment-method>
</installment-configuration-request>
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-configuration-response xmlns="http://www.elastic-payments.com/schema/utils">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <payment-method>ratepay-install</payment-method>
    <state>success</state>
    <statuses>
        <status code="201.0000" description="Calculation configuration read successful" severity="information"/>
        <status code="200.0000" description="Successful Response" severity="information"/>
    </statuses>
    <configuration>
        <interest-rate-default>13.7</interest-rate-default>
        <interest-rate-min>5</interest-rate-min>
        <interest-rate-max>15</interest-rate-max>
        <interest-rate-merchant2bank>9.8</interest-rate-merchant2bank>
        <month-number-min>3</month-number-min>
        <month-number-max>36</month-number-max>
        <month-longrun>25</month-longrun>
        <amount-min-longrun>1000</amount-min-longrun>
        <month-allowed>3,6,7,8,9,10,11,12,24,36</month-allowed>
        <valid-payment-firstdays>2,28</valid-payment-firstdays>
        <payment-firstday>28</payment-firstday>
        <payment-amount>60</payment-amount>
        <payment-lastrate>0</payment-lastrate>
        <rate-min-normal>20</rate-min-normal>
        <rate-min-longrun>10</rate-min-longrun>
        <service-charge>1.95</service-charge>
        <min-difference-dueday>28</min-difference-dueday>
        <name>WIRECARD_TE_DEU_ECOM_RATEPAY</name>
        <type>DEFAULT</type>
    </configuration>
</installment-configuration-response>
JSON Configuration
Request
{
  "installment-configuration-request": {
    "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
    "payment-method": "ratepay-install"
  }
}
Response
{
  "installment-configuration-response": {
      "configuration": {
          "interest-rate-default": {
              "value": "13.7"
          },
          "interest-rate-min": {
              "value": "5"
          },
          "interest-rate-max": {
              "value": "15"
          },
          "interest-rate-merchant2bank": {
              "value": "9.8"
          },
          "month-number-min": {
              "value": "3"
          },
          "month-number-max": {
              "value": "36"
          },
          "month-longrun": {
              "value": "25"
          },
          "amount-min-longrun": {
              "value": "1000"
          },
          "month-allowed": {
              "value": "3,6,7,8,9,10,11,12,24,36"
          },
          "valid-payment-firstdays": {
              "value": "2,28"
          },
          "payment-firstday": {
              "value": "28"
          },
          "payment-amount": {
              "value": "60"
          },
          "payment-lastrate": {
              "value": "0"
          },
          "rate-min-normal": {
              "value": "20"
          },
          "rate-min-longrun": {
              "value": "10"
          },
          "service-charge": {
              "value": "1.95"
          },
          "min-difference-dueday": {
              "value": "28"
          },
          "name": {
              "value": "WIRECARD_TE_DEU_ECOM_RATEPAY"
          },
          "type": {
              "value": "DEFAULT"
          }
      },
      "state": "success",
      "statuses": {
          "status": [
              {
                  "code": "201.0000",
                  "description": "Calculation configuration read successful",
                  "severity": "information"
              },
              {
                  "code": "200.0000",
                  "description": "Successful Response",
                  "severity": "information"
              }
          ]
      },
      "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
      "payment-method": "ratepay-install"
  }
}
Installment Calculator
XML Calculation by Rate
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-calculator-request xmlns="http://www.elastic-payments.com/schema/utils">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <payment-method>ratepay-install</payment-method>
  <rate currency="EUR">100.00</rate>
  <amount currency="EUR">1000.00</amount>
</installment-calculator-request>
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-calculator-response xmlns="http://www.elastic-payments.com/schema/utils">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <payment-method>ratepay-install</payment-method>
    <state>success</state>
    <statuses>
        <status code="201.0000" description="The payment plan fulfilled the conditions." severity="information"/>
        <status code="200.0000" description="Successful Response" severity="information"/>
    </statuses>
    <amount currency="EUR">1000.00</amount>
    <installments>
        <installment>
            <details>
                <interest-rate>13.7</interest-rate>
                <annual-percentage-rate>14.28</annual-percentage-rate>
                <total-amount>1065.18</total-amount>
                <amount>1000</amount>
                <interest-amount>63.23</interest-amount>
                <service-charge>1.95</service-charge>
                <monthly-debit-interest>1.08</monthly-debit-interest>
                <number-of-rates>11</number-of-rates>
                <rate>100.18</rate>
                <last-rate>63.38</last-rate>
                <payment-first-day>28</payment-first-day>
            </details>
        </installment>
    </installments>
    <rate currency="EUR">100.00</rate>
</installment-calculator-response>
XML Calculation by Time
Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-calculator-request xmlns="http://www.elastic-payments.com/schema/utils">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <payment-method>ratepay-install</payment-method>
  <months>10</months>
  <amount currency="EUR">502.603</amount>
</installment-calculator-request>
Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<installment-calculator-response xmlns="http://www.elastic-payments.com/schema/utils">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <payment-method>ratepay-install</payment-method>
    <state>success</state>
    <statuses>
        <status code="201.0000" description="The payment plan fulfilled the conditions." severity="information"/>
        <status code="200.0000" description="Successful Response" severity="information"/>
    </statuses>
    <amount currency="EUR">502.603</amount>
    <installments>
        <installment>
            <details>
                <interest-rate>13.7</interest-rate>
                <annual-percentage-rate>14.79</annual-percentage-rate>
                <total-amount>534.5</total-amount>
                <amount>502.603</amount>
                <interest-amount>29.94</interest-amount>
                <service-charge>1.95</service-charge>
                <monthly-debit-interest>1.08</monthly-debit-interest>
                <number-of-rates>10</number-of-rates>
                <rate>53.46</rate>
                <last-rate>53.36</last-rate>
                <payment-first-day>28</payment-first-day>
            </details>
        </installment>
    </installments>
</installment-calculator-response>
JSON Calculation by Rate
Request
{
  "installment-calculator-request": {
    "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
    "payment-method": "ratepay-install",
    "amount": {
      "currency": "EUR",
      "value": "502.603"
    },
    "rate": {
      "currency": "EUR",
      "value": "20.85"
    }
  }
}
Response
{
    "installment-calculator-response": {
        "amount": {
            "value": 502.603,
            "currency": "EUR"
        },
        "installments": {
            "installment": [
                {
                    "details": {
                        "interest-rate": {
                            "value": "13.7"
                        },
                        "annual-percentage-rate": {
                            "value": "14.15"
                        },
                        "total-amount": {
                            "value": "574.59"
                        },
                        "amount": {
                            "value": "502.603"
                        },
                        "interest-amount": {
                            "value": "70.04"
                        },
                        "service-charge": {
                            "value": "1.95"
                        },
                        "monthly-debit-interest": {
                            "value": "1.08"
                        },
                        "number-of-rates": {
                            "value": "24"
                        },
                        "rate": {
                            "value": "23.95"
                        },
                        "last-rate": {
                            "value": "23.74"
                        },
                        "payment-first-day": {
                            "value": "28"
                        }
                    }
                }
            ]
        },
        "rate": {
            "value": 20.85,
            "currency": "EUR"
        },
        "state": "success",
        "statuses": {
            "status": [
                {
                    "code": "201.0000",
                    "description": "Runtime was too long to match maximum allowed installment runtime. Run time has been decreased",
                    "severity": "information"
                },
                {
                    "code": "200.0000",
                    "description": "Successful Response",
                    "severity": "information"
                }
            ]
        },
        "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
        "payment-method": "ratepay-install"
    }
}
JSON Calculation by Time
Request
{
  "installment-calculator-request": {
    "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
    "payment-method": "ratepay-install",
    "amount": {
      "currency": "EUR",
      "value": "502.603"
    },
    "months": "10"
  }
}
Response
{
    "installment-calculator-response": {
        "amount": {
            "value": 502.603,
            "currency": "EUR"
        },
        "installments": {
            "installment": [
                {
                    "details": {
                        "interest-rate": {
                            "value": "13.7"
                        },
                        "annual-percentage-rate": {
                            "value": "14.79"
                        },
                        "total-amount": {
                            "value": "534.5"
                        },
                        "amount": {
                            "value": "502.603"
                        },
                        "interest-amount": {
                            "value": "29.94"
                        },
                        "service-charge": {
                            "value": "1.95"
                        },
                        "monthly-debit-interest": {
                            "value": "1.08"
                        },
                        "number-of-rates": {
                            "value": "10"
                        },
                        "rate": {
                            "value": "53.46"
                        },
                        "last-rate": {
                            "value": "53.36"
                        },
                        "payment-first-day": {
                            "value": "28"
                        }
                    }
                }
            ]
        },
        "state": "success",
        "statuses": {
            "status": [
                {
                    "code": "201.0000",
                    "description": "The payment plan fulfilled the conditions.",
                    "severity": "information"
                },
                {
                    "code": "200.0000",
                    "description": "Successful Response",
                    "severity": "information"
                }
            ]
        },
        "merchant-account-id": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e",
        "payment-method": "ratepay-install"
    }
}
Wirecard Payment in Installments payment

Click here for corresponding notification samples.

authorization
XML authorization Request (Successful)
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>authorization</transaction-type>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <requested-amount currency="EUR">1000</requested-amount>
    <order-number>45073</order-number>
    <account-holder>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <email>john.doe@test.com</email>
        <phone>03018425165</phone>
        <date-of-birth>1973-12-27</date-of-birth>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
    <shipping>
      <first-name>Hans-Jürgen</first-name>
      <last-name>Wischnewski</last-name>
      <phone>+49123123123</phone>
      <address>
        <street1>Müllerstraße 137</street1>
        <city>Berlin</city>
        <country>DE</country>
        <state>Berlin</state>
        <postal-code>13353</postal-code>
      </address>
   </shipping>
    <bank-account>
        <bank-name>Danske Bank Hamburg</bank-name>
        <iban>AL35202111090000000001234567</iban>
    </bank-account>
    <custom-fields>
        <custom-field field-name="total-amount"     field-value="1222.99"/>
        <custom-field field-name="interest-rate"    field-value="13.7"/>
        <custom-field field-name="number-of-rates"  field-value="36"/>
        <custom-field field-name="rate"             field-value="33.97"/>
        <custom-field field-name="last-rate"        field-value="34.04"/>
        <custom-field field-name="payment-firstday" field-value="28"/>
    </custom-fields>
</payment>
XML authorization Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <transaction-id>f935f610-6c55-4d9e-93ac-2889e5898d0f</transaction-id>
    <request-id>58a8ff0d-40dc-4306-a930-fcf052d6bdc2</request-id>
    <transaction-type>authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2020-01-23T14:46:29.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="The resource was successfully created." severity="information" provider-transaction-id="64-20200123158026"/>
    </statuses>
    <requested-amount currency="EUR">1000</requested-amount>
    <account-holder>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <email>john.doe@test.com</email>
        <phone>03018425165</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <shipping>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <phone>+49123123123</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </shipping>
    <order-number>45073</order-number>
    <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
    <descriptor>AA0016823L8</descriptor>
    <custom-fields>
        <custom-field field-name="total-amount" field-value="1222.99"></custom-field>
        <custom-field field-name="interest-rate" field-value="13.7"></custom-field>
        <custom-field field-name="number-of-rates" field-value="36"></custom-field>
        <custom-field field-name="rate" field-value="33.97"></custom-field>
        <custom-field field-name="last-rate" field-value="34.04"></custom-field>
        <custom-field field-name="payment-firstday" field-value="28"></custom-field>
    </custom-fields>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <bank-account>
        <bank-name>Danske Bank Hamburg</bank-name>
        <iban>AL35202111090000000001234567</iban>
    </bank-account>
</payment>
capture-authorization
XML capture-authorization Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>capture-authorization</transaction-type>
  <payment-methods>
    <payment-method name="ratepay-install" />
  </payment-methods>
  <requested-amount currency="EUR">1000</requested-amount>
  <parent-transaction-id>{transaction_id_AUTHORIZATION}</parent-transaction-id>
  <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
</payment>
XML capture-authorization Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e/payments/e836eef3-fa12-4e80-956f-63895fd79dae">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e">9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <transaction-id>e836eef3-fa12-4e80-956f-63895fd79dae</transaction-id>
    <request-id>a49f90a1-ce35-4492-9a67-4b05f550b46a</request-id>
    <transaction-type>capture-authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2020-01-23T14:50:22.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="ratepay:The resource was successfully created." severity="information" provider-transaction-id="64-20200123158026"/>
    </statuses>
    <requested-amount currency="EUR">1000</requested-amount>
    <parent-transaction-id>f935f610-6c55-4d9e-93ac-2889e5898d0f</parent-transaction-id>
    <account-holder>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <email>john.doe@test.com</email>
        <phone>03018425165</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <shipping>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <phone>+49123123123</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </shipping>
    <order-number>45073</order-number>
    <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
    <descriptor>AA0016823L8</descriptor>
    <custom-fields>
        <custom-field field-name="total-amount" field-value="1222.99"/>
        <custom-field field-name="interest-rate" field-value="13.7"/>
        <custom-field field-name="number-of-rates" field-value="36"/>
        <custom-field field-name="rate" field-value="33.97"/>
        <custom-field field-name="last-rate" field-value="34.04"/>
        <custom-field field-name="payment-firstday" field-value="28"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <parent-transaction-amount currency="EUR">1000.000000</parent-transaction-amount>
    <bank-account>
        <bank-name>Danske Bank Hamburg</bank-name>
        <iban>AL35202111090000000001234567</iban>
    </bank-account>
    <api-id>elastic-api</api-id>
    <provider-account-id>0000003175B6BC3F</provider-account-id>
</payment>
credit
XML credit Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>credit</transaction-type>
  <payment-methods>
    <payment-method name="ratepay-install" />
  </payment-methods>
  <parent-transaction-id>{transaction_id_AUTHORIZATION}</parent-transaction-id>
  <requested-amount currency="EUR">10</requested-amount>
  <order-items>
    <order-item>
      <name>Nachlass über € 10,00</name>
      <article-number>1</article-number>
      <amount currency="EUR">10</amount>
      <tax-rate>19</tax-rate>
      <quantity>1</quantity>
    </order-item>
  </order-items>
</payment>
XML credit Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e/payments/fecca05c-fa8b-4d55-8a00-cba1bd5a65a7">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e">9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <transaction-id>fecca05c-fa8b-4d55-8a00-cba1bd5a65a7</transaction-id>
    <request-id>dbeecb32-0e13-4d20-9108-fad0947e6e9c</request-id>
    <transaction-type>credit</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2020-01-23T15:03:51.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="ratepay:The resource was successfully created." severity="information" provider-transaction-id="64-20200123158026"/>
    </statuses>
    <requested-amount currency="EUR">10</requested-amount>
    <parent-transaction-id>f935f610-6c55-4d9e-93ac-2889e5898d0f</parent-transaction-id>
    <account-holder>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <email>john.doe@test.com</email>
        <phone>03018425165</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <shipping>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <phone>+49123123123</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </shipping>
    <order-number>45073</order-number>
    <order-items>
        <order-item>
            <name>Nachlass über € 10,00</name>
            <article-number>1</article-number>
            <amount currency="EUR">10</amount>
            <tax-rate>19</tax-rate>
            <quantity>1</quantity>
        </order-item>
    </order-items>
    <descriptor>AA0016823L8</descriptor>
    <custom-fields>
        <custom-field field-name="total-amount" field-value="1222.99"/>
        <custom-field field-name="interest-rate" field-value="13.7"/>
        <custom-field field-name="number-of-rates" field-value="36"/>
        <custom-field field-name="rate" field-value="33.97"/>
        <custom-field field-name="last-rate" field-value="34.04"/>
        <custom-field field-name="payment-firstday" field-value="28"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <parent-transaction-amount currency="EUR">1000.000000</parent-transaction-amount>
    <bank-account>
        <bank-name>Danske Bank Hamburg</bank-name>
        <iban>AL35202111090000000001234567</iban>
    </bank-account>
    <api-id>elastic-api</api-id>
    <provider-account-id>0000003175B6BC3F</provider-account-id>
</payment>
refund-capture
XML refund-capture Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>refund-capture</transaction-type>
    <payment-methods>
        <payment-method name="ratepay-install" />
    </payment-methods>
    <requested-amount currency="EUR">1000</requested-amount>
    <parent-transaction-id>{transaction_id_CAPTURE_AUTHORIZATION}</parent-transaction-id>
     <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
</payment>
XML refund-capture Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e/payments/5886f701-2256-4512-b3bd-dbeae91db5cd">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e">9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <transaction-id>5886f701-2256-4512-b3bd-dbeae91db5cd</transaction-id>
    <request-id>31a0ff7a-21f5-42cd-b8cd-fd59221612ef</request-id>
    <transaction-type>refund-capture</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2020-01-23T15:26:18.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="ratepay:The resource was successfully created." severity="information" provider-transaction-id="58-20200123158222"/>
    </statuses>
    <requested-amount currency="EUR">1000</requested-amount>
    <parent-transaction-id>e15cb617-52a2-4d86-926d-97d9074bbda3</parent-transaction-id>
    <account-holder>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <email>john.doe@test.com</email>
        <phone>03018425165</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <shipping>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <phone>+49123123123</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </shipping>
    <order-number>45073</order-number>
    <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
    <descriptor>AA0016842N7</descriptor>
    <custom-fields>
        <custom-field field-name="total-amount" field-value="1222.99"/>
        <custom-field field-name="interest-rate" field-value="13.7"/>
        <custom-field field-name="number-of-rates" field-value="36"/>
        <custom-field field-name="rate" field-value="33.97"/>
        <custom-field field-name="last-rate" field-value="34.04"/>
        <custom-field field-name="payment-firstday" field-value="28"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <parent-transaction-amount currency="EUR">1000.000000</parent-transaction-amount>
    <api-id>elastic-api</api-id>
    <provider-account-id>0000003175B6BC3F</provider-account-id>
</payment>
void-authorization
XML void-authorization Request (Successful)
<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
  <request-id>bf90010c-ba53-4cc6-a742-f3913096615e</request-id>
  <transaction-type>void-authorization</transaction-type>
  <payment-methods>
    <payment-method name="ratepay-install" />
  </payment-methods>
  <parent-transaction-id>{transaction_id_AUTHORIZATION}</parent-transaction-id>
  <requested-amount currency="EUR">1000</requested-amount>
  <account-holder>
    <first-name> John</first-name>
    <last-name>Doe</last-name>
    <email>John@doe.de</email>
    <phone>03018425165</phone>
    <date-of-birth>27-12-1973</date-of-birth>
    <address>
      <street1> Nicht versenden Weg 12</street1>
      <city>Berlin</city>
      <state>Berlin</state>
      <country>DE</country>
      <postal-code>13353</postal-code>
    </address>
  </account-holder>
   <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
  </order-items>
</payment>
XML void-authorization Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e/payments/183897a3-9762-4b24-9e7b-e9b6adbb1191">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e">9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e</merchant-account-id>
    <transaction-id>183897a3-9762-4b24-9e7b-e9b6adbb1191</transaction-id>
    <request-id>bf90010c-ba53-4cc6-a742-f3913096615e</request-id>
    <transaction-type>void-authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2020-01-23T15:17:17.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="ratepay:The resource was successfully created." severity="information" provider-transaction-id="38-20200123158164"/>
    </statuses>
    <requested-amount currency="EUR">1000</requested-amount>
    <parent-transaction-id>fded6b90-4c09-4ad1-a8d7-eba16d430db5</parent-transaction-id>
    <account-holder>
        <first-name> John</first-name>
        <last-name>Doe</last-name>
        <email>John@doe.de</email>
        <phone>03018425165</phone>
        <address>
            <street1> Nicht versenden Weg 12</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </account-holder>
    <shipping>
        <first-name>Hans-Jürgen</first-name>
        <last-name>Wischnewski</last-name>
        <phone>+49123123123</phone>
        <address>
            <street1>Müllerstraße 137</street1>
            <city>Berlin</city>
            <state>Berlin</state>
            <country>DE</country>
            <postal-code>13353</postal-code>
        </address>
    </shipping>
    <order-number>45073</order-number>
    <order-items>
        <order-item>
            <name>Item 1</name>
            <article-number>123</article-number>
            <amount currency="EUR">100</amount>
            <tax-rate>0.2</tax-rate>
            <quantity>10</quantity>
        </order-item>
    </order-items>
    <descriptor>AA0016837Z9</descriptor>
    <custom-fields>
        <custom-field field-name="total-amount" field-value="1222.99"/>
        <custom-field field-name="interest-rate" field-value="13.7"/>
        <custom-field field-name="number-of-rates" field-value="36"/>
        <custom-field field-name="rate" field-value="33.97"/>
        <custom-field field-name="last-rate" field-value="34.04"/>
        <custom-field field-name="payment-firstday" field-value="28"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="ratepay-install"/>
    </payment-methods>
    <parent-transaction-amount currency="EUR">1000.000000</parent-transaction-amount>
    <bank-account>
        <bank-name>Danske Bank Hamburg</bank-name>
        <iban>AL35202111090000000001234567</iban>
    </bank-account>
    <api-id>elastic-api</api-id>
    <provider-account-id>0000003175B6BC3F</provider-account-id>
</payment>

Wirecard Payment Page v2

Wirecard Payment in Installments allows the consumer to pay directly from their bank account while providing the option for payment in a customized number of installments. The invoicing, direct debit, collection process (dunning), as well as the calculation of possible installments, is handled by Wirecard. Wirecard Payment in Installments ensures that merchants receive the payment amount from Wirecard prior to settlement with consumers.

Wirecard Payment in Installments is a type of Offline Bank Transfer.

Countries and Currencies

Countries

Germany

Currencies

EUR

General Information

Here you find all the information for integrating Wirecard Payment in Installments into your Hosted and Embedded Payment Page.

Want to know more about Wirecard Payment Page v2 (WPP v2)?
Visit one of our integration guides (Hosted Payment Page, Embedded Payment Page) for a quick explanation and a step-by-step guide.

All WPP v2 integrations share a common process flow for creating payments.

Below, we provide samples for the available transaction type authorization, including field lists with short descriptions.

The samples provided below are designed for the testing environment and do not use real information. Please contact Merchant Support for production credentials.

For more details on the redirect-url, see the Configuring Redirects and IPNs for WPP v2 section.

For response verification examples, see the WPP v2 Security section.

Transaction Type authorization

An authorization reserves the specified amount from the account holder’s bank account for a later transfer.

Test Credentials

URL (Endpoint)

https://wpp-test.wirecard.com/api/payment/register

Merchant Account ID (MAID)

9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

09df96e0-6364-472c-a26a-4be32bfe1902

Additional Test Credentials

IBAN

DE42512308000000060004

BIC

WIREDEMMXXX

Sample Workflow

For a successful transaction:

  1. Create a payment session (initial request).

    Set the country field to DE, as Wirecard Payment in Installments is currently available for Germany only.
  2. Redirect the consumer to the payment page (initial response URL).

  3. Highly recommended: Parse and process the payment response.

We provide JSON examples for each step of this process. You can find them below.

Request Headers

Authorization

"Authorization"="Basic" + base64 (“username:password”). Use username and password as given in your Wirecard contract to base64-encode the authorization.

Content-Type

application/json

1. Create a Payment Session (Initial Request)

You can use the following sample for transaction type authorization. Please enter authorization for transaction-type.

{
    "payment": {
        "merchant-account-id": {
            "value": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "authorization",
        "requested-amount": {
            "currency": "EUR",
            "value": "1900.50"
        },
        "account-holder": {
            "address": {
                "street1": "Mullerstrasse 137",
                "state": "Berlin",
                "country": "DE",
                "city": "Berlin",
                "postal-code": "13353"
            },
            "first-name": "John",
            "last-name": "Doe",
            "email": "john@doe.com",
            "phone": "+421123456789",
            "date-of-birth": "01-01-1980"
        },
        "ip-address": "127.0.0.1",
        "order-number": "12345",
        "order-items": {
            "order-item": [
                {
                    "name": "Notebook",
                    "description": "Simple Notebook",
                    "article-number": "123",
                    "amount": {
                        "value": 1900.5,
                        "currency": "EUR"
                    },
                    "tax-rate": 0,
                    "quantity": 1
                }
            ]
        },
        "locale": "de",
        "country": "DE",
        "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
        "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
        "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
        "payment-methods": {
            "payment-method": [
                {
                    "name": "ratepay-install"
                }
            ]
        },
        "mandate": {
            "mandate-id": "Wird nach dem Kauf uebermittelt",
            "signed-date": "2019-06-01"
        },
        "creditor-id": "DE98ZZZ09999999999"
    }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

Mandatory

36

A unique identifier assigned to every merchant account (by Wirecard).

request-id

String

Mandatory

150

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id.
Allowed characters:
a - z
0 - 9
-_

transaction-type

String

Mandatory

36

The requested transaction type. Available transaction type for Wirecard Payment in Installments:

  • authorization

requested-amount

currency

String

Mandatory

3

The currency of the requested/contested transaction amount. For Wirecard Payment in Installments payments, the currency must be set to EUR.
Format: 3-character abbreviation according to ISO 4217.

value

Numeric

Mandatory

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.
Use . (decimal point) as the separator.

account-holder

address

street1

String

Optional

128

The first line of the street address of the consumer.

state

String

Optional

32

The state or province of the address of the consumer.

country

Token

Optional

3

The country ID of the address of the consumer.

city

String

Optional

32

The city of the address of the consumer.

postal-code

String

Optional

16

The postal code or ZIP of the address of the consumer.

first-name

String

Mandatory

32

The first name of the consumer.

last-name

String

Mandatory

32

The last name of the consumer.

email

String

Mandatory

64

The email address of the consumer.

phone

String

Mandatory

32

The phone number of the consumer.

date-of-birth

String

Mandatory

n/a

The date of birth of the consumer.

ip-address

String

Optional

45

The internet protocol address of the consumer as recorded by the entity receiving the transaction attempt from the consumer.

order-number

String

Mandatory

64

Merchant-side order number.
Allowed characters: [a-zA-Z0-9+]

order-items

order-item

name

Alphanumeric

Mandatory

Name of the item in the basket.

description

String

Mandatory

Description of the item in the basket.

article-number

String

Mandatory

EAN or other article identifier for merchant.

amount

value

Numeric

Mandatory

The item price per unit.

currency

String

Mandatory

3

The currency of the item price per unit.

tax-rate

Numeric

Mandatory

The item tax rate per unit.

quantity

Numeric

Mandatory

The total count of items in the order.

locale

String

Optional

6

A 2-letter code which indicates what language the payment page is rendered in (ISO 639-1).

country

String

Optional

3

The country ID of the consumer. This field must be set to DE. If no value is entered, the field defaults to DE.

success-redirect-url

String

Mandatory

256

The URL to which the consumer is redirected after a successful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/success.

cancel-redirect-url

String

Mandatory

256

The URL to which the consumer is redirected after having canceled a payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/cancel.

fail-redirect-url

String

Mandatory

256

The URL to which the consumer is redirected after an unsuccessful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/error.

payment-methods

payment-method

name

String

Optional

15

The name of the payment method used.

mandate

mandate-id

String

Optional

35

Mandate ID is generated by Wirecard. Please use the following statement as placeholder: "Wird nach Kaufabschluss übermittelt".

signed-date

String

Optional

19

The date the mandate was signed.

creditor-id

String

Optional

256

The creditor ID of the merchant.

2. Redirect the Consumer to the Payment Page (Sample Response URL)
{
"payment-redirect-url": "https://wpp-test.wirecard.com/?wPaymentToken=rhNg8LV9jfUk1Xtq7NEGU1QI2em4YuA-zyPrxmHNdY0"
}
Field (JSON) Data Type Description

payment-redirect-url

String

The URL which redirects to the payment form. Sent as a response to the initial request.

At this point, you need to redirect your consumer to payment-redirect-url (or render it in an iframe depending on your integration method).

Consumers are redirected to the payment form. There they enter their data and submit the form to confirm the payment.
Possible transaction results:

  • Successful (transaction-state: success)

  • Failed (transaction-state: failed)

  • Canceled (transaction-state: failed)

The transaction result is the value of transaction-state in the payment response. More details (including the status code) can also be found in the statuses object of the payment response. Canceled payments are returned as failed, but the status description indicates it was canceled.

In any case (unless the consumer cancels the transaction on a 3rd party provider page), a base64-encoded response containing payment information is sent to the configured redirection URL. See Configuring Redirects and IPNs for WPP v2 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

For Wirecard Payment in Installments, the payment page displays a form where the consumer can select the preferred installment plan.
  1. The consumer clicks Pay Now on the payment page.
    The payment form opens.

  2. The consumer selects Wirecard Payment in Installments.
    An installment calculator is displayed.

  3. The consumer selects one of the available installment plans (number of installments (monthly rates) and the preferred payment day). The installment plan is automatically calculated according to the total sum.

    The minimum amount required for a payment in installments is 60 EUR.
  4. After selecting the installment plan, the consumer needs to enter their personal data, shipping and bank information (IBAN and BIC), and send the payment.
    The payment is confirmed.

    You are not required to create a request for this step as the installment calculation is performed automatically.
3. Parse and Process the Payment Response (Decoded Payment Response)
{
    "payment": {
        "country": "DE",
        "locale": "de",
        "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
        "bank-account": {
            "bic": "WIREDEMMXXX",
            "iban": "DE42512308000000060004"
        },
        "order-number": "12345",
        "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
        "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
        "merchant-account-id": {
            "value": "9df7b8a6-546a-4e01-9fe5-ccc3ae54b23e"
        },
        "custom-fields": {
            "custom-field": [
                {
                    "field-name": "terms-consent-checked",
                    "field-value": "true"
                },
                {
                    "field-name": "payment-firstday",
                    "field-value": "2"
                },
                {
                    "field-name": "rate",
                    "field-value": "652.08"
                },
                {
                    "field-name": "amount",
                    "field-value": "1900.5"
                },
                {
                    "field-name": "annual-percentage-rate",
                    "field-value": "14.37"
                },
                {
                    "field-name": "interest-amount",
                    "field-value": "53.77"
                },
                {
                    "field-name": "interest-rate",
                    "field-value": "13.7"
                },
                {
                    "field-name": "last-rate",
                    "field-value": "652.06"
                },
                {
                    "field-name": "monthly-debit-interest",
                    "field-value": "1.08"
                },
                {
                    "field-name": "number-of-rates",
                    "field-value": "3"
                },
                {
                    "field-name": "service-charge",
                    "field-value": "1.95"
                },
                {
                    "field-name": "total-amount",
                    "field-value": "1956.22"
                }
            ]
        },
        "transaction-id": "a4114030-9894-4fe2-ac10-c39d3e4db3e7",
        "request-id": "fabd297b-e53a-4b7b-80b9-a79d4eb192fa",
        "transaction-state": "success",
        "completion-time-stamp": "2019-09-10T12:56:01",
        "requested-amount": {
            "currency": "EUR",
            "value": 1900.5
        },
        "statuses": {
            "status": [
                {
                    "description": "The resource was successfully created.",
                    "severity": "information",
                    "code": "201.0000",
                    "provider-transaction-id": "46-2019091014525190"
                }
            ]
        },
        "ip-address": "127.0.0.1",
        "account-holder": {
            "account-info": {},
            "first-name": "John",
            "email": "john@doe.com",
            "last-name": "Doe",
            "phone": "+421123456789",
            "address": {
                "country": "DE",
                "street1": "Mullerstrasse 137",
                "city": "Berlin",
                "postal-code": "13353",
                "state": "Berlin"
            }
        },
        "payment-methods": {
            "payment-method": [
                {
                    "payload": {},
                    "name": "ratepay-install"
                }
            ]
        },
        "transaction-type": "authorization",
        "order-items": {
            "order-item": [
                {
                    "description": "Simple Notebook",
                    "article-number": "123",
                    "tax-rate": 0,
                    "quantity": 1,
                    "amount": {
                        "currency": "EUR",
                        "value": 1900.5
                    },
                    "name": "Notebook"
                }
            ]
        },
        "mandate": {
            "mandate-id": "Wird nach dem Kauf uebermittelt",
            "signed-date": "2019-06-01"
        },
        "creditor-id": "DE98ZZZ09999999999",
        "api-id": "wpp",
        "device": {
            "fingerprint": "d0f23d65-d4cb-2282-38c3-2503645dfdf7"
        },
        "descriptor": "DK0292989D6"
    }
}
Field (JSON) Data Type Description

bank-account

bic

String

The bank identifier code (BIC) of the account holder (consumer). Allowed characters and format: ([a-zA-Z]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3}).

iban

String

The international bank account number (IBAN) of the account holder (consumer). Allowed characters and format: [a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[0-9]{7}([a-zA-Z0-9]?){0,16}.

custom-fields

custom-field

field-name

String

The merchant-defined name of the custom field.

field-value

String

The merchant-defined name of the custom field.

transaction-id

String

A unique identifier assigned to every transaction. Used when searching for or referencing it later.

transaction-state

Token

The current transaction state.
Possible values:

  • in-progress

  • success

  • failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

completion-time-stamp

Timestamp

The UTC/ISO time-stamp documents the time & date when the transaction was executed. Format: YYYY-MM-DDThh:mm:ssZ (ISO).

statuses

status

description

String

Text used to describe the transaction status. This information is returned in the response only.

severity

Token

The definition of the status message.
Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

provider-transaction-id

String

A unique transaction identifier generated by the provider.

account-holder

account-info

The value of account-info depends on the payment method. Empty when the account-info field is not used in the request.

payment-methods

payment-method

payload

String

The value of payload depends on the payment method. Always empty for Wirecard Payment in Installments.

api-id

Token

Identifier of the currently used API.

device

fingerprint

String

A device fingerprint is information about a remote computing device, collected by the merchant for identification purposes. Fingerprints can be used to fully or partially identify individual users or devices even when cookies are turned off.

descriptor

String

The description of the transaction displayed on the account holder’s statement. In the case of a credit card statement, it can be dynamically set per transaction. It is only supported by some acquirers.

Post-Processing Operations

WPP v2 is best used for one-off payments (e.g. regular, independent debit transactions) or the initial transaction in a chain of them (e.g. a first authorization in a chain of recurring transactions). However, when it comes to referencing a transaction for any kind of post-processing operation - such as a refund of one of your debit transactions - use our REST API directly.

Check the REST API Wirecard Payment in Installments specification for details on Wirecard Payment in Installments-specific post-processing operations.
JSON/NVP Field Reference

Here you can:

  • see the structure of an extended JSON request (XML-JSON mapping reference)

  • find the NVP equivalents for JSON fields (for migrating merchants)

JSON Structure of a Wirecard Payment in Installments Request
{
    "payment": {
        "merchant-account-id": {
            "value": "String"
        },
        "request-id": "String",
        "transaction-type": "String",
        "requested-amount": {
            "value": "Numeric",
            "currency": "String"
        },
        "parent-transaction-id": "String",
        "account-holder": {
            "first-name": "String",
            "last-name": "String",
            "email": "String",
            "phone": "String",
            "address": {
                "city": "String",
                "country": "String",
                "postal-code": "String",
                "state": "String",
                "street1": "String",
                "street2": "String",
                "street3": "String"
            }
        },
        "shipping": {
            "first-name": "String",
            "last-name": "String",
            "phone": "String",
            "address": {
                "city": "String",
                "country": "String",
                "postal-code": "String",
                "state": "String",
                "street1": "String",
                "street2": "String",
                "street3": "String"
            }
        },
        "payment-methods": {
            "payment-method": [
                {
                    "name": "String"
                }
            ]
        },
        "bank-account": {
            "iban": "String"
        },
        "mandate": {
            "mandate-id": "String",
            "signed-date": "String"
        },
        "creditor-id": "String",
        "periodic": {
            "periodic-type": "String",
            "sequence-type": "String"
        },
        "descriptor": "String",
        "order-number": "String",
        "success-redirect-url": "String",
        "fail-redirect-url": "String",
        "cancel-redirect-url": "String"
    }
}
Optional Fields in a Wirecard Payment in Installments Request
Field (NVP) Field (JSON) JSON Parent

bank_account_iban

iban

bank-account ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

city

address ({ })/ city

account-holder ({ })

country

address ({ })/ country

account-holder ({ })

creditor_id

creditor-id

payment ({ })

descriptor

descriptor

payment ({ })

email

email

account-holder ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

mandate_mandate_id

mandate-id

mandate ({ })

mandate_signed_date

signed-date

mandate ({ })

merchant_account_id

value

merchant-account-id ({ })

order_number

order-number

payment ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

periodic_type

periodic-type

periodic ({ })

phone

phone

account-holder ({ })

postal_code

address ({ })/ postal-code

account-holder ({ })

request_id

request-id

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

sequence_type

sequence-type

periodic ({ })

shipping_city

address ({ })/ city

shipping ({ })

shipping_country

address ({ })/ country

shipping ({ })

shipping_first_name

first-name

shipping ({ })

shipping_last_name

last-name

shipping ({ })

shipping_phone

phone

shipping ({ })

shipping_postal_code

address ({ })/ postal-code

shipping ({ })

shipping_state

address ({ })/ state

shipping ({ })

shipping_street1

address ({ })/ street1

shipping ({ })

shipping_street2

address ({ })/ street2

shipping ({ })

shipping_street3

address ({ })/ street3

shipping ({ })

state

address ({ })/ state

account-holder ({ })

street1

address ({ })/ street1

account-holder ({ })

street2

address ({ })/ street2

account-holder ({ })

street3

address ({ })/ street3

account-holder ({ })

success_redirect_url

success-redirect-url

payment ({ })

transaction_type

transaction-type

payment ({ })

Response-Only Fields for Wirecard Payment in Installments
Field (NVP) Field (JSON) JSON Parent

api_id

api-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

instrument_country

instrument-country

payment ({ })

provider_transaction_id_n

status ([ { } ])/ provider-transaction-id

statuses ({ })

provider_transaction_reference_id

provider-transaction-reference-id

payment ({ })

status_code_n

status ([ { } ])/ code

statuses ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ { } ])/ severity

statuses ({ })

transaction_id

transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })