Guaranteed Installment by Wirecard

Wirecard Payment Page v2

Guaranteed Installment by Wirecard 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. Guaranteed Installment by Wirecard ensures that merchants receive the payment amount from Wirecard prior to settlement with consumers.

Guaranteed Installment by Wirecard is a type of Offline Bank Transfer.

Countries and Currencies

Countries

Germany

Currencies

EUR

General Information

Here you find all the information for integrating Guaranteed Installment by Wirecard 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 Guaranteed Installment by Wirecard 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

Required

36

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

request-id

String

Required

64

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

Required

36

The requested transaction type. Available transaction type for Guaranteed Installment by Wirecard:

  • authorization

requested-amount

currency

String

Required

3

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

value

Numeric

Required

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

Required

32

The first name of the consumer.

last-name

String

Required

32

The last name of the consumer.

email

String

Required

64

The email address of the consumer.

phone

String

Required

32

The phone number of the consumer.

date-of-birth

String

Required

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

Required

64

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

order-items

order-item

name

Alphanumeric

Required

Name of the item in the basket.

description

String

Required

Description of the item in the basket.

article-number

String

Required

EAN or other article identifier for merchant.

amount

value

Numeric

Required

The item price per unit.

currency

String

Required

3

The currency of the item price per unit.

tax-rate

Numeric

Required

The item tax rate per unit.

quantity

Numeric

Required

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

Required

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

Required

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

Required

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 Guaranteed Installment by Wirecard, 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 Guaranteed Installment by Wirecard.
    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 Guaranteed Installment by Wirecard.

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 Guaranteed Installment by Wirecard specification for details on Guaranteed Installment by Wirecard-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 Guaranteed Installment by Wirecard 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 Guaranteed Installment by Wirecard 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 Guaranteed Installment by Wirecard
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 ({ })

Custom URL: