Wirecard Payment Page v2

What Is Wirecard Payment Page v2?

Wirecard Payment Page v2 (WPP) is an online checkout solution which combines a highly customizable user interface with payment processing for various payment methods.

WPP allows merchants to customize the visual representation of their payment page while keeping an optimal payment flow. WPP is designed to streamline integration so merchants can accept payments quickly. Additionally, Wirecard hosts all sensitive data so merchants can focus on their business instead of worrying about data security and PCI.

Merchants can easily modify the design of WPP through Payment Page Designer, an intuitive web interface for customizing nearly every visual element the consumer would see. As an added benefit, using Designer requires no graphical design experience or coding – new payment pages can be created in minutes!

Payment Page Modes

Hosted

Embedded

Seamless

Hosted Payment Page

Embedded Payment Page

Seamless Mode

A standalone payment page hosted independently from your checkout page.

A payment form rendered over your checkout page as a modal window.

A card form seamlessly integrated into your checkout form.

Read more >

Read more >

Read more >

What Does It Do?

WPP provides an appealing user interface for Wirecard Payment Gateway (WPG), enhancing the user experience of paying customers. Payments are created through backend payment sessions which supply a live URL to the payment page.

Customers are redirected to this URL where they submit the payment and WPP handles the processing automatically, for the benefit of both the merchant & customer.

Who Is This Documentation for?

This documentation is primarily for developers integrating WPP into an online shop. Each variation of WPP has a short introduction, and a more extensive overview of integration procedures and code.

A basic understanding of REST API services, JavaScript and HTML is assumed.

Which Payment Methods Are Supported?

Merchants can accept Credit Card payments from all the major card schemes and various local providers as well as many alternative payment methods. See the list of all supported payment methods below:

Hosted Payment Page

HPP Advantages

Integrate the Hosted Payment Page (HPP) to redirect the consumer from your shop to a standalone payment page hosted by Wirecard.

Use the Payment Page Designer to customize the HPP interface: set background, colors, fonts, logos and more for a cohesive look that meets your preferences and fits your merchant branding. The redirect to the HPP will be barely noticeable, which makes consumers feel at ease.

HPP also allows you to configure expiration times for payment hyperlinks: payments can be postponed.

Wirecard hosts all sensitive data - you only need to meet the requirements of SAQ A to be fully PCI DSS compliant. With the HPP you can focus on your business and stop worrying about data security.

Hosted Payment Page Demo

Hosted Payment Page Customization Through Payment Page Designer
Hosted Payment Page Customization Through Payment Page Designer
Hosted Payment Page Customization Through Payment Page Designer
Hosted Payment Page Customization Through Payment Page Designer
HPP Integration Guide
Download the full integration demo from our GitHub

Github Java Github PHP

Overview

To integrate the Hosted Payment Page (HPP) in your shop, use a simple backend-to-backend JSON WPP Workflow for the payment process.

  1. Create a payment session: You send an initial POST request with details of the transaction to the Wirecard Payment Page (WPP). This POST request is secured by basic access authentication.

  2. Redirect the consumer to the payment page: WPP returns an initial response URL.

    • If the initial POST request is correct, use the response URL to redirect the consumer to the payment page. The consumer fills out the required fields on the payment page and submits the payment. Continue with step 3.

    • If the initial POST request is faulty, WPP returns an error code with a description of the problem in the response. Return to step 1.

  3. Parse and process the payment response: The payment is processed. Depending on the result (successful, pending, failed or canceled), the consumer is redirected to the respective page. The WPP sends a POST request containing base64 encoded payment data to the same URL. It is highly recommended that you parse and process this base64 encoded response to verify the payment.

    The payment process is complete.

 

Payment-Processing Example

This is an example of a credit card transaction to show how to process a payment with the Hosted Payment Page. For more supported payment methods and payment-method-specific integration guides, go to Payment Methods with WPP.

The payment-processing example is designed for the testing environment  and does not use real information.

Payment processing with the Wirecard Payment Page generally follows the same steps:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON samples for each step of this process. Use a tool such as Postman to test them.

 

Setup and Test Credentials

Before you can send your first request, use the following information to set up your testing tool:

Test Credentials

URI (API Endpoint)

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

Username

70000-APIDEMO-CARD

Password

ohysS0-dvfMx

MAID

7a6dd74f-06ab-4f3f-a864-adc52687270a

Secret Key

a8c3fce6-8df7-4fd6-a1fd-62fa229c5e55

Test Card  

Card number

4200000000000018

Expiration date

01/23

CVV

018

1. Create a Payment Session

  To create a payment session, send a POST request to the /api/payment/register endpoint, e.g. https://wpp-test.wirecard.com/api/payment/register.

This is an HTTP request with two headers:

Request Headers
Content-Type: application/json
Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header needs to be formatted as: "Authorization"="Basic"  + base64(“username:password”)

Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
  }
}
Field Table
Field (JSON) Data Type Required/Optional 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.

requested-amount

value

Numeric

Required

18

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

currency

String

Required

3

The currency of the requested/contested transaction amount.
Format: 3-character abbreviation according to ISO 4217.

account holder

first-name

String

Optional

32

The first name of the account holder.

last-name

String

Required

32

The last name of the account holder.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

success-redirect-url

String

Optional

256

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

fail-redirect-url

String

Optional

256

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

cancel-redirect-url

String

Optional

256

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

To create a payment session with Credit Card using 3-D Secure 2 authentication, you need to include 3-D Secure 2 fields in your initial request.
Most of these fields are optional but we recommend the implementation of optional fields, s as this creates a smoother user experience and ensures a higher level of security.
Need more information on 3-D Secure 2? Head to our general introduction to 3-D Secure 2.

Which Payment Methods Can I Choose?

Leave out the payment-methods object from the request. WPP will show a grid of all available payment methods (based on your merchant configuration).

Alternatively, check out Payment Methods with WPP for an overview of all supported payment methods.

Download the full integration demo from our GitHub

Github Java Github PHP

2. Redirect the Consumer to the Payment Page

The response to the initial authorization request contains the payment-redirect-url.

Response to Authorization Request
{
  "payment-redirect-url": "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}

Use the payment-redirect-url to redirect the consumer.

You can implement the redirection in any way that suits you best.

Redirecting Consumers to the Payment Page Using WPP.hostedPayUrl

You can use our ready-made function to handle the redirection:

  1. Add the paymentPage.js library to your checkout page HTML code

    <script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>
  2. Submit the initial payment request on the backend.

  3. Call the WPP.hostedPayUrl(payment-redirect-url) function in your HTML code to redirect the consumer to a new window:

    <script type="text/javascript">
    WPP.hostedPayUrl("https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7")
    </script>

    Make sure to pass the payment-redirect-url value from the initial response to the redirection function and call it.

The consumer is redirected to the payment form. There they enter their data and submit the form to confirm the payment. The response can

  • be successful (transaction-state: success)

  • fail (transaction-state: failed)

  • or the consumer canceled the payment before/after submission (transaction-state: failed).

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

In any case, a base64 encoded response containing payment information is sent to the corresponding redirection URL (success-redirect-urlcancel-redirect-url, or fail-redirect-url).

See  Configuring Redirects and IPNs for WPP for more information on redirection targets after payment.

3. Parse and Process the Payment Response (Highly Recommended)

Where Can I Find the Payment Response?

WPP sends the final response to the success/fail page where the consumer is redirected to at the end of the payment session. This final response contains the payment data in a base64 encoded JSON format. It is sent with a POST request as form data response-base64.

Base64

Before you are able to parse and process the payment response, you need to decode it.

To test this

  • Copy and paste the payment-redirect-url into your browser.

  • Open your browser’s console and complete the payment with the credit card information provided above.

  • In your browser’s console, find the form data response-base64 (see screenshot).

  • Copy and paste the response into a base64 decoder of your choice, e.g. Base64 Decode.

  • Decode the response to view the payment response details.

You can find a decoded payment response example below.

Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "transaction-type": "authorization",
    "transaction-id": "08649015-eb17-4c67-ab5f-d132af616e02",
    "completion-time-stamp": "2018-12-19T12:02:26",
    "card-token": {
      "token-id": "4242796444090018",
      "masked-account-number": "420000******0018"
    },
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "transaction-state": "success",
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "api-id": "wpp"
  },
  "request-id": "28285dbd-ecd3-49bd-a7e5-0239affa2448",
  "requested-amount": {
    "currency": "EUR",
    "value": 10
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "801433",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "descriptor": "demo descriptor"
}
Field Table
Field (JSON) Data Type Description

transaction-type

String

The requested transaction type.

transaction-id

String

A unique identifier to every transaction (by Wirecard). Used when searching for or referencing to it later.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

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

card token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

This is the masked card account number of the consumer.

merchant-account-id

value

String

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

transaction-state

String

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.

payment-mode

name

String

The name of the payment method used for the transaction.

cancel-redirect-url

String

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

success-redirect-url

String

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

fail-redirect-url

String

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

api-id

String

Identifier of the currently used API.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

requested-amount

currency

String

The currency of the requested/contested transaction amount.

value

Numeric

The full amount that is requested/contested in a transaction.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message. Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message

authorization-code

String

Output code for transaction type authorization.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

descriptor

String

Describes the transaction.

For more information on redirect URLs, see Configuring Redirects and IPNs for WPP.
For response verification examples, see WPP Security.
For payment-method-specific requests, head over to the Payment Methods with WPP.

Merchants Integrated with NVP (HPP)
Migrating to WPP

In addition to the new backend-to-backend JSON flow, WPP supports an updated NVP flow for merchants who already integrated one of the Payment Page solutions previously and do not want to switch.

In that case, the migration to WPP requires only a few minor changes. New features have an NVP field equivalent so you can use them in your integration. Check the  WPP Features section for specifics.

Contact merchant support for your production credentials.
  1. Find the paymentPageLoader JavaScript library in your <head> HTML code:

    <script src="https://api-test.wirecard.com/engine/hpp/paymentPageLoader.js" type="text/javascript"></script>

    Replace it with:

    <script src="https://wpp-test.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>
  2. Find the hostedPay function call at the end of your Pay button function:

    WirecardPaymentPage.hostedPay(requestData);

    Replace it with:

    WPP.hostedPay(requestData);

    The fields in requestData remain the same and no changes are needed.

Embedded Payment Page

EPP Advantages
  • Payment form as overlay (iframe) to the checkout page

  • No consumer redirection

  • Customization with Payment Page Designer

  • PCI DSS SAQ A

Integrate the Embedded Payment Page (EPP) to display the payment form as an overlay to the checkout page. The consumer stays on the same page until the payment is finished, rather than being redirected to a separate site. This creates a smooth, uninterrupted shopping experience.

Use the Payment Page Designer to customize the EPP interface: set colors, fonts, logos and more for a cohesive look that meets your preferences and fits your merchant branding.

Wirecard hosts all sensitive data - you only need to meet the requirements of SAQ A to be fully PCI DSS compliant. With the EPP you can focus on your business and stop worrying about data security.

Embedded Payment Page Demo

EPP Integration Guide
Download the full integration demo from our GitHub

Github Java Github PHP

Overview

To integrate the Embedded Payment Page (EPP) in your shop, use a simple backend-to-backend JSON workflow for the payment process.

  1. Create a payment session: You send an initial POST request with details of the transaction to the Wirecard Payment Page (WPP). This POST request is secured by basic access authentication.

  2. Render/create the payment page: WPP returns an initial response URL.

    • If the initial POST request is correct, use the response URL to render the embedded payment page as an overlay to the checkout page. The consumer fills out the required fields on the payment page and submits the payment. Continue with step 3.

    • If the initial POST request is faulty, WPP returns an error code with a description of the problem in the response. Return to step 1.

  3. Parse and process the payment response: The payment is processed. Depending on the result (successful, pending, failed or canceled), the consumer is redirected to the respective page. The WPP sends a POST request containing base64 encoded payment data to the same URL. It is highly recommended that you parse and process this base64 encoded response to verify the payment.

    The payment process is complete.

Payment-Processing Example

This is an example of a credit card transaction to show how to process a payment with the Embedded Payment Page.
For more supported payment methods and payment-method-specific integration guides, go to Payment Methods with WPP.

The payment-processing example is designed for the testing environment  and does not use real information.

Payment processing with the Wirecard Payment Page generally follows the same steps:

  1. Create a payment session (initial request).

  2. Render the embedded payment page.

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

We provide ready-made JSON samples for each step of this process. Use a tool such as Postman to test them.

Setup and Test Credentials

Before you can send your first request, use the following information to set up your testing tool:

Test Credentials

URI (API Endpoint)

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

Username

70000-APIDEMO-CARD

Password

ohysS0-dvfMx

MAID

7a6dd74f-06ab-4f3f-a864-adc52687270a

Secret Key

a8c3fce6-8df7-4fd6-a1fd-62fa229c5e55

Test Card  

Card number

4200000000000018

Expiration date

01/23

CVV

018

1. Create a Payment Session

To create a payment session, send a POST request to the /api/payment/register endpoint, e.g. https://wpp-test.wirecard.com/api/payment/register.

This is an HTTP request with two headers:

Request Headers
Content-Type: application/json
Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header must be formatted as: Authorization=Basic  + base64 (username:password)

You can try it using the authorization headers above.

Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
  },
  "options": {
    "mode": "embedded",
    "frame-ancestor": "https://example.com"
  }
}
Field Table
Field (JSON) Data Type Required/Optional 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.

requested-amount

value

Numeric

Required

18

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

currency

String

Required

3

The currency of the requested/contested transaction amount.
Format: 3-character abbreviation according to ISO 4217.

account holder

first-name

String

Required

32

The first name of the account holder.

last-name

String

Required

32

The last name of the account holder.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

success-redirect-url

String

Optional

256

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

fail-redirect-url

String

Optional

256

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

cancel-redirect-url

String

Optional

256

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

options

mode

String

Required

8

Indicates which mode of payment page is used for the payment. Currently supports seamless and embedded.

frame-ancestor

String

Required

256

The URL of the checkout page where the iframe is rendered.

To create a payment session with Credit Card using 3-D Secure 2 authentication, you need to include 3-D Secure 2 fields in your initial request.
Most of these fields are optional but we recommend the implementation of optional fields, as this creates a smoother user experience and ensures a higher level of security.
Need more information on 3-D Secure 2? Head to our general introduction to 3-D Secure 2.

Which Payment Methods Can I Choose?

Leave out the payment-methods object from the request. WPP will show a grid of all available payment methods (based on your merchant configuration).

Alternatively, check out Payment Methods with WPP for an overview of all supported payment methods.

Download the full integration demo from our GitHub

Github Java Github PHP  

2. Embed the Payment Page

The payment page is in this case an overlay window. It is created using the payment-redirect-url, contained in the response to the initial authorization request.

Response to Authorization Request
{
  "payment-redirect-url": "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}

Embedding the Payment Page in your Checkout Page Using WPP.embeddedPayUrl

You can use our predefined function to embed the payment page:

  1. Add the paymentPage.js library to your checkout page HTML code.

    <script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>

    Make sure to pass the payment-redirect-url value from the initial response to the WPP.embeddedPayUrl function and call it to render the payment page.      

  2. Submit the initial payment request on the backend.

  3. Call the WPP.embeddedPayUrl(payment-redirect-url) function in your HTML code to render the new pop-up window.

    <script type="text/javascript">WPP.embeddedPayUrl("https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7")</script>

The consumer is redirected to the payment form. There they enter their data and submit the form to confirm the payment. The response can either:

  • be successful (transaction-state: success)

  • fail (transaction-state: failed)

  • or the consumer canceled the payment before/after submission (transaction-state: failed).

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

In any case, a base64 encoded response containing payment information is sent to the corresponding redirection URL (success-redirect-urlcancel-redirect-url, or fail-redirect-url).

See  Configuring Redirects and IPNs for WPP for more information on redirection targets after payment.

Parse and Process the Payment Response (Highly Recommended)

Where Can I Find the Payment Response?

WPP sends the final response to the success/fail page where the consumer is redirected to at the end of the payment session. This final response contains the payment data in a base64 encoded JSON format. It is sent with a POST request as form data response-base64.

Base64

Before you are able to parse and process the payment response, you need to decode it. 

To test this:

  • Copy and paste the payment-redirect-url into your browser.

  • Open your browser’s console and complete the payment with the credit card information provided above.

  • In your browser’s console, find the form data response-base64 (see screenshot).

  • Copy and paste the response into a base64 decoder of your choice, e.g. Base64 Decode.

  • Decode the response to view the payment response details.

You can find a decoded payment response example below.

Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "transaction-type": "authorization",
    "transaction-id": "08649015-eb17-4c67-ab5f-d132af616e02",
    "completion-time-stamp": "2018-12-19T12:02:26",
    "card-token": {
      "token-id": "4242796444090018",
      "masked-account-number": "420000******0018"
    },
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "transaction-state": "success",
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "api-id": "wpp"
  },
  "request-id": "28285dbd-ecd3-49bd-a7e5-0239affa2448",
  "requested-amount": {
    "currency": "EUR",
    "value": 10
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "801433",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "descriptor": "demo descriptor"
}
Field Table
Field (JSON) Data Type Description

transaction-type

String

The requested transaction type.

transaction-id

String

A unique identifier to every transaction (by Wirecard). Used when searching for or referencing to it later.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

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

card token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

This is the masked card account number of the consumer.

merchant-account-id

value

String

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

transaction-state

String

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.

payment-mode

name

String

The name of the payment method used for the transaction.

cancel-redirect-url

String

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

success-redirect-url

String

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

fail-redirect-url

String

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

api-id

String

Identifier of the currently used API.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

requested-amount

currency

String

The currency of the requested/contested transaction amount.

value

Numeric

The full amount that is requested/contested in a transaction.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message. Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message

authorization-code

String

Output code for transaction type authorization.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

descriptor

String

Describes the transaction.

For more information on redirect URLs, see Configuring Redirects and IPNs for WPP.
For response verification examples, see WPP Security.
For payment-method-specific requests, head over to the Payment Methods with WPP.

Merchants Integrated with NVP (EPP)
Migrating to WPP

In addition to the new backend-to-backend JSON flow, WPP supports an updated NVP flow for merchants who already integrated one of the Payment Page solutions previously and do not want to switch.

In that case, the migration to WPP requires only a few minor changes. New features have an NVP field equivalent so you can use them in your integration. Check the WPP Features section for specifics.

Contact merchant support for your production credentials.
  1. Find the paymentPageLoader JavaScript library in your <head> HTML code:

    <script src="https://api-test.wirecard.com/engine/hpp/paymentPageLoader.js" type="text/javascript"></script>

    Replace it with:

    <script src="https://wpp-test.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>
  2. Find the embeddedPay function call at the end of your Pay button function:

    WirecardPaymentPage.embeddedPay(requestData);

    Replace it with:

    WPP.embeddedPay(requestData);

    The fields in requestData remain the same and no changes are needed.

Seamless Mode

Seamless Mode Advantages
  • Payment form integrated into the checkout page (iframe)

  • No consumer redirection, overlays, or pop-ups

  • Customization with Payment Page Designer

  • PCI DSS SAQ A

Seamless Mode

Use Seamless Mode to display the WPP payment form as a fully integrated part of your checkout page. Without redirects to external pages (except for credit card 3-D Secure verification), overlays, or pop-ups, the payment form appears native to your website but is still being hosted by Wirecard.

Use the Payment Page Designer to customize the payment form: set colors, fonts, logos and more for a cohesive look that meets your preferences and fits your merchant branding.

Wirecard hosts all sensitive data - you only need to meet the requirements of SAQ A to be fully PCI DSS compliant. With Seamless Mode you can focus on your business and stop worrying about data security.

Currently, Seamless Mode is only available for credit card payments.
Seamless Integration Guide
Download the full integration demo from our Github

JAVA PHP

Overview

To integrate the Wirecard Payment Page in Seamless Mode in your shop, get your checkout page ready in two steps:

  1. Preparing your checkout page: Add the paymentPage.js library to your checkout page’s HTML code.

  2. Changing the background color setting in Payment Page Designer: Set the background color to transparent in Payment Page Designer.

Then use a backend-to-backend JSON workflow for the payment process.

  1. Create a payment session: You send an initial POST request with details of the transaction to the Wirecard Payment Page (WPP). This POST request is secured by basic access authentication.

  2. Render the seamless payment form: WPP returns an initial response URL.

    • If the initial POST request is correct, use this response URL and the WPP.seamlessRender library call to render the payment form in a seamless iframe. Continue with step 3.

    • If the initial POST request is faulty, WPP returns an error code with a description of the problem in the response. Return to step 1.

  3. Submit the payment: The consumer fills in the payment form. Use the WPP.seamlessSubmit function to submit the payment. Ensure that the function is bound to an interactive UI element, such as a button, in your HTML code.

    • 3-D Secure credit card payment automatically redirects the consumer to the authentication page, and then to a WPP success- or fail-redirect-url. Include the success- and fail-redirect-urls in your initial request! This page includes a JSON sample for 3-D Secure credit card payment.

    • Non-3-D Secure credit card payment requires you to implement redirects to subsequent pages, such as a success-/fail-/cancel-redirect-url to let the consumer know about the payment outcome, by yourself.

  4. Parse and Process the Payment Response: The payment is processed. WPP returns base64 encoded payment data. It is highly recommended that you parse and process this base64 encoded response to verify the payment.

First Steps

Before processing payments in Seamless Mode, you need to make a small adjustment to your checkout page’s HTML code, and change a setting in the Payment Page Designer.

1. Preparing your Checkout Page

Add the paymentPage.js library to your checkout page HTML code:

<script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>

This library lets you render the payment form as an iframe in your checkout page.

The URL included here serves only as an example. Please enter the domain of the instance received during merchant configuration.
2. Changing the Background Color Setting in Payment Page Designer

Open the Payment Page Designer to set the background color to transparent. Transparency of the card form’s background ensures a seamless appearance when it is embedded in your checkout page.

  1. Select the Payment tab and click on Colors.

    Seamless Page Designer 1
  2. In Colors, go to the Content tab and open the Content Background Color window.

    Seamless Page Designer 2
  3. Set the Content Background Color alpha value (A) to 0

    Seamless Page Designer 3
Payment-Processing Example

This is an example of a credit card 3-D Secure transaction to show how to process a payment with the Wirecard Payment Page in Seamless Mode. Currently, Seamless Mode supports only credit card payments. For a more payment-method-specific integration guide, go to Credit Card with WPP.

The payment-processing example is designed for the testing environment and does not use real information.

Payment processing with Wirecard Payment Page in Seamless Mode deviates a little bit from the

HPP and EPP payment processing workflow:

Payment Processing with Wirecard Payment Page in Seamless Mode

  1. Create a payment session (initial request).

  2. Render the Seamless payment form in your checkout page (initial response URL).

  3. Submit the payment.

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

Payment Processing with HPP and EPP

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

Setup and Test Credentials

Before you can send your first request, use the following information to set up your testing tool:

Test Credentials

URI (Endpoint)

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

Username

70000-APILUHN-CARD

Password

8mhwavKVb91T

MAID

cad16b4a-abf2-450d-bcb8-1725a4cef443

Secret Key

b3b131ad-ea7e-48bc-9e71-78d0c6ea579d

Test Card  

Card Number

4012000300001003

Expiration Date

01/23

CVV

003

3-D Verification Password

wirecard

1. Create a Payment Session 

To create a payment session, send a POST request to the /api/payment/register endpoint, e.g. https://wpp-test.wirecard.com/api/payment/register.

This is an HTTP request with two headers:

Request Headers
Content-Type: application/json
Authorization: Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA==

The Authorization header needs to be formatted as: "Authorization"="Basic" + base64(“username:password”)

  .Create a Payment Session (Initial Request)

{
    "payment": {
        "merchant-account-id": {
            "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "purchase",
        "requested-amount": {
            "value": 10.1,
            "currency": "EUR"
        },
        "payment-methods": {
            "payment-method": [
                {
                    "name": "creditcard"
                }
            ]
        },
        "three-d": {
            "attempt-three-d": "true"
        },
        "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
        "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
        "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
    },
    "options": {
        "mode": "seamless",
        "frame-ancestor": "https://www.example.com"
    }
}
Field (JSON) Data Type Required/Optional 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.

requested-amount

value

Numeric

Required

18

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

currency

String

Required

3

The currency of the requested/contested transaction amount. Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

three-d

attempt-tree-d

Boolean

Conditional

N/A

Required for 3-D Secure transactions. Indicates whether 3-D Secure authentication is enabled for the transaction.

success-redirect-url

String

Optional

256

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

fail-redirect-url

String

Optional

256

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

cancel-redirect-url

String

Optional

256

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

options

mode

String

Required

8

Indicates which mode of payment page is used for the payment. Currently supports embedded and seamless. Use seamless in this example.

frame-ancestor

String

Required

256

The URL of the checkout page where the iframe is rendered.

To create a payment session with Credit Card using 3-D Secure 2 authentication, you need to include 3-D Secure 2 fields in your initial request.
Most of these fields are optional but we recommend the implementation of optional fields, as this creates a smoother user experience and ensures a higher level of security.
Need more information on 3-D Secure 2? Head to our general introduction to 3-D Secure 2.

You must include "options": {"mode":"seamless"} in your request, otherwise WPP returns a regular payment URL that cannot be used in Seamless Mode.

Seamless Mode renders the payment form into an iframe. Therefore, you need to include "options": {`"frame-ancestor": "url"} in the request with your domain as the "url" value.
If you do not send "frame-ancestor" in the request, browsers will refuse to display the payment page in the iframe due to HTTP security policy.

Download the full integration demo from our Github

JAVA PHP

2. Render the Seamless Payment Form

The response to the initial authorization request contains the payment-redirect-url.

Response to Authorization Request
{
    "payment-redirect-url": "https://wpp-test.wirecard.com/seamless?wPaymentToken=XUcGTdnxwwCWPEP-YOeDmT05_hg1bKbaibLTpcdR8cU"
}

Use the WPP.seamlessRender function to render the payment form in a seamless iframe. Include the payment-redirect-url here:

WPP.seamlessRender({
    url: paymentredirecturl, // this is the payment link returned in response to your initial request
    wrappingDivId: "seamless-form-target",
    onSuccess: function (response) { // called when seamless form is successfully rendered
    },
    onError: function (errResp) { // called if seamless form failed to render
    }
});
This function renders only the payment form! The button with which consumers confirm their payment must be part of you checkout page. Bind the function to an interactive UI element, such as a button, in your HTML code.
Seamless Payment Form
Figure 1. Seamless payment form rendered into wrappingDivId
Render the Payment Form: Example from Wirecard Demoshop
<html>
<head>
    <!-- ... -->
    <script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
    <!-- the form will render in the following div -->
    <div id="seamless-form-target"></div>

    <!-- the following javascript will render the form; make sure to set paymentredirecturl -->
    <script type="text/javascript">
          // change the next line to include YOUR TOKEN
          var paymentredirecturl = "https://wpp-test.wirecard.com/seamless?wPaymentToken=YOUR_TOKEN_HERE";

          // frame-ancestor in the initial request (Step 1) must match the domain you are using to test this
          WPP.seamlessRender({
               url: paymentredirecturl,
               wrappingDivId: "seamless-form-target",
               onSuccess: function (response) {
                 console.log(response);
               },
               onError: function (response) {
                 console.log(response);
               }
          });
    </script>
    <!-- ... -->
</body>
</html>
3. Submit the Payment

Now the payment form has been rendered and consumers can enter their payment information.

To submit that data, use the WPP.seamlessSubmit function:

WPP.seamlessSubmit({
    onSuccess: function (response) { // called when seamless form data is successfully submitted
    },
    onError: function (response) { //called when data submission fails
    }
});
Bind the function to an interactive UI element, such as a button, in your HTML code. The consumer can then click the button to submit the payment.
Submit the Payment: Example from Wirecard Demoshop
<html>
<head>
    <!-- ... -->
    <script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>
    <!-- ... -->
</head>
<body>
    <!-- ... -->
    <!-- the form will render in the following div -->
    <div id="seamless-form-target"></div>

    <!-- the following javascript will render the form; make sure to set paymentredirecturl -->
    <script type="text/javascript">
          // change the next line to include YOUR TOKEN
          var paymentredirecturl = "https://wpp-test.wirecard.com/seamless?wPaymentToken=YOUR_TOKEN_HERE";

          // frame-ancestor in the initial request must match the domain you are using to test this
          WPP.seamlessRender({
               url: paymentredirecturl,
               wrappingDivId: "seamless-form-target",
               onSuccess: function (response) {
                 console.log(response);
               },
               onError: function (response) {
                 console.log(response);
               }
          });
    </script>

    <!-- this code will generate the "Pay Now" button and enable the submission of the form -->
    <input id="wirecard_pay_btn" type="button" onclick="pay()" value="Pay Now"/>
    <script type="text/javascript">
        function pay() {
            WPP.seamlessSubmit({
                onSuccess: function (response) {
                // called when seamless form data is successfully submitted with non-3-D Secure credit card
                // see section 4 (Parse and Process the Payment Response) on how to deal with this data
                  console.log(response);
                },
                onError: function (response) {
                // called when seamless form data is successfully submitted with non-3-D Secure credit card
                // see section 4 (Parse and Process the Payment Response) on how to deal with this data
                  console.log(response);
                }
             });
        }
    </script>
    <!-- ... -->
</body>
</html>
The function only submits the payment.

3-D Secure Transaction Redirect

For 3-D Secure transactions, WPP in Seamless Mode automatically redirects the consumer to the card provider 3-D Secure authentication pages. There are no actions required from you for this process.

After 3-D Secure authentication, the payment is further processed.

Depending on the outcome, the consumer is redirected to a success-/fail-/cancel-redirect-url. As the consumer leaves your page for 3-D Secure authentication, these URLs need to be set up in the same way as those for HPP and EPP integrations.

This means that for 3-D Secure Transactions, you need to include the success-/fail-/cancel-redirect-url in the initial request!

URLs for successful, failed, and canceled transactions can also be set during the initial merchant configuration and saved in the database. If you would like to change these default values, please contact Merchant Support.

More information on success-/fail-/cancel-redirect-url configuration can be found in Configuring Redirects and IPNs for WPP.

Non 3-D Secure Transaction Redirect

For Non 3-D Secure transactions, any further steps, such as displaying success messages to your consumer, or redirecting your consumer to success-/fail-/cancel-pages, need to be implemented separately in your online shop.

4. Parse and Process the Payment Response (Highly Recommended)

Once you have submitted the payment, and it has been processed, you receive a payment response. The payment response is sent in three parts: the response-signature-base64, the response-signature-algorithm, and the response-base64.

Object {
"response-signature-base64": "9JSIJ/G4Otz6KbAJTg20LSNOcvidhgGWAPR3BMXfbxQ=",
"response-signature-algorithm": "HmacSHA256",
"response-base64": "ewogICJwYXltZW50IiA6IHsKICAgICJmYWlsLXJlZGlyZWN0LXVybCIgOiAiaHR0cHM6Ly9kZW1vc2hvcC10ZXN0LndpcmVjYXJkLmNvbS9kZW1vc2hvcC8jIS9lcnJvciIsCiAgICAidHJhbnNhY3Rpb24tc3RhdGUiIDogInN1Y2Nlc3MiLAogICAgInN1Y2Nlc3MtcmVkaXJlY3QtdXJsIiA6ICJodHRwczovL2RlbW9zaG9wLXRlc3Qud2lyZWNhcmQuY29tL2RlbW9zaG9wLyMhL3N1Y2Nlc3MiLAogICAgInBheW1lbnQtbWV0aG9kcyIgOiB7CiAgICAgICJwYXltZW50LW1ldGhvZCIgOiBbIHsKICAgICAgICAibmFtZSIgOiAiY3JlZGl0Y2FyZCIKICAgICAgfSBdCiAgICB9LAogICAgInRocmVlLWQiIDogewogICAgICAiY2FyZGhvbGRlci1hdXRoZW50aWNhdGlvbi1zdGF0dXMiIDogIkEiLAogICAgICAiYXR0ZW1wdC10aHJlZS1kIiA6IGZhbHNlCiAgICB9LAogICAgImNhbmNlbC1yZWRpcmVjdC11cmwiIDogImh0dHBzOi8vZGVtb3Nob3AtdGVzdC53aXJlY2FyZC5jb20vZGVtb3Nob3AvIyEvY2FuY2VsIiwKICAgICJtZXJjaGFudC1hY2NvdW50LWlkIiA6IHsKICAgICAgInZhbHVlIiA6ICJjYWQxNmI0YS1hYmYyLTQ1MGQtYmNiOC0xNzI1YTRjZWY0NDMiCiAgICB9LAogICAgImN1c3RvbS1maWVsZHMiIDogewogICAgICAiY3VzdG9tLWZpZWxkIiA6IFsgewogICAgICAgICJmaWVsZC1uYW1lIiA6ICJlbGFzdGljLXBhZ2UtYXBpLjNkLm9yaWdpbmFsX3R4bl90eXBlIiwKICAgICAgICAiZmllbGQtdmFsdWUiIDogInB1cmNoYXNlIgogICAgICB9IF0KICAgIH0sCiAgICAidHJhbnNhY3Rpb24taWQiIDogImFkOWY5YjEyLTY4ODgtNDkxOC04N2NkLTZmYWRjNzRkYzRjOCIsCiAgICAiY29tcGxldGlvbi10aW1lLXN0YW1wIiA6ICIyMDE5LTAyLTExVDE1OjIzOjAwIiwKICAgICJyZXF1ZXN0ZWQtYW1vdW50IiA6IHsKICAgICAgImN1cnJlbmN5IiA6ICJFVVIiLAogICAgICAidmFsdWUiIDogMTAuMQogICAgfSwKICAgICJhdXRob3JpemF0aW9uLWNvZGUiIDogIjY4NzIwNiIsCiAgICAiY3NjLWNvZGUiIDogIk4iLAogICAgImFjY291bnQtaG9sZGVyIiA6IHsKICAgICAgImxhc3QtbmFtZSIgOiAibGFzdCIsCiAgICAgICJmaXJzdC1uYW1lIiA6ICJmaXJzdCIKICAgIH0sCiAgICAiY2FyZCIgOiB7CiAgICAgICJleHBpcmF0aW9uLW1vbnRoIiA6IDEsCiAgICAgICJleHBpcmF0aW9uLXllYXIiIDogMjAyMywKICAgICAgImNhcmQtdHlwZSIgOiAidmlzYSIsCiAgICAgICJtZXJjaGFudC10b2tlbml6YXRpb24tZmxhZyIgOiBmYWxzZQogICAgfSwKICAgICJzdGF0dXNlcyIgOiB7CiAgICAgICJzdGF0dXMiIDogWyB7CiAgICAgICAgImRlc2NyaXB0aW9uIiA6ICIzZC1hY3F1aXJlcjpUaGUgcmVzb3VyY2Ugd2FzIHN1Y2Nlc3NmdWxseSBjcmVhdGVkLiIsCiAgICAgICAgInNldmVyaXR5IiA6ICJpbmZvcm1hdGlvbiIsCiAgICAgICAgImNvZGUiIDogIjIwMS4wMDAwIgogICAgICB9LCB7CiAgICAgICAgImRlc2NyaXB0aW9uIiA6ICIzZC1hY3F1aXJlcjpQcm9vZiBvZiBhdXRoZW50aWNhdGlvbiBhdHRlbXB0IHdhcyBnZW5lcmF0ZWQuIiwKICAgICAgICAic2V2ZXJpdHkiIDogImluZm9ybWF0aW9uIiwKICAgICAgICAiY29kZSIgOiAiMjAwLjEwODQiCiAgICAgIH0gXQogICAgfSwKICAgICJwYXJlbnQtdHJhbnNhY3Rpb24taWQiIDogImFiMWI0MmI2LWIwYzktNGVmMC1iYjBjLTA1N2MzMjAzOTk1NyIsCiAgICAicGFyZW50LXRyYW5zYWN0aW9uLWFtb3VudCIgOiB7CiAgICAgICJjdXJyZW5jeSIgOiAiRVVSIiwKICAgICAgInZhbHVlIiA6IDEwLjEwMDAwMAogICAgfSwKICAgICJhcGktaWQiIDogIndwcCIsCiAgICAiZGV2aWNlIiA6IHsKICAgICAgImZpbmdlcnByaW50IiA6ICIzYmFiMTI2Zi05YjEzLWEzYmYtY2YwNS0yZTA5NjVmZGIwZGQiCiAgICB9LAogICAgImNhcmQtdG9rZW4iIDogewogICAgICAibWFza2VkLWFjY291bnQtbnVtYmVyIiA6ICI0MDEyMDAqKioqKio2MDAyIiwKICAgICAgInRva2VuLWlkIiA6ICI0ODE5MjUzODg4MDk2MDAyIgogICAgfSwKICAgICJ0cmFuc2FjdGlvbi10eXBlIiA6ICJwdXJjaGFzZSIsCiAgICAicmVxdWVzdC1pZCIgOiAiNGU4MTkyNDEtYTc1OS00NWYxLThmM2ItNWM3MTJlYjkyMzNmIgogIH0KfQ=="
}
  • response-base64 contains the payment data.

  • response-signature-base64 and the response-signature-algorithm, together with the Secret Key you receive upon signing a contract with Wirecard, are required for calculating the security response signature. The security response signature is essential for verifying the payment status.
    Please consult WPP Security for details and examples of response signature verification.

In Seamless Mode, the WPP sends the final response containing the payment data to either of the following destinations, depending on the payment mode.

3-D Secure Credit Card Payment

The WPP sends the final response containing the payment data to the success-redirect-url/fail-redirect-url specified in the initial request. This is the URL where the consumer is redirected to at the end of a payment session.

To parse and process the payment response of 3-D Secure credit card payment, please consult WPP Security for details.

This is the decoded payment data contained in the example payment response provided above.

Decoded Payment Response
{
    "payment": {
        "transaction-state": "success",
        "payment-methods": {
            "payment-method": [
                {
                    "name": "creditcard"
                }
            ]
        },
        "three-d": {
            "cardholder-authentication-status": "A",
            "attempt-three-d": false
        },
        "merchant-account-id": {
            "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
        },
        "custom-fields": {
            "custom-field": [
                {
                    "field-name": "elastic-page-api.3d.original_txn_type",
                    "field-value": "purchase"
                }
            ]
        },
        "transaction-id": "ad9f9b12-6888-4918-87cd-6fadc74dc4c8",
        "completion-time-stamp": "2019-02-11T15:23:00",
        "requested-amount": {
            "currency": "EUR",
            "value": 10.1
        },
        "authorization-code": "687206",
        "csc-code": "N",
        "account-holder": {
            "last-name": "last",
            "first-name": "first"
        },
        "card": {
            "expiration-month": 1,
            "expiration-year": 2023,
            "card-type": "visa",
            "merchant-tokenization-flag": false
        },
        "statuses": {
            "status": [
                {
                    "description": "3d-acquirer:The resource was successfully created.",
                    "severity": "information",
                    "code": "201.0000"
                },
                {
                    "description": "3d-acquirer:Proof of authentication attempt was generated.",
                    "severity": "information",
                    "code": "200.1084"
                }
            ]
        },
        "parent-transaction-id": "ab1b42b6-b0c9-4ef0-bb0c-057c32039957",
        "parent-transaction-amount": {
            "currency": "EUR",
            "value": 10.1
        },
        "api-id": "wpp"
        },
        "card-token": {
            "masked-account-number": "401200******6002",
            "token-id": "4819253888096002"
        },
        "transaction-type": "purchase",
        "request-id": "4e819241-a759-45f1-8f3b-5c712eb9233f"
    }
}
Field Table
Field (JSON) Data Type Description

transaction-state

String

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.

payment-method

name

String

The name of the payment method used for the transaction.

three-d

cardholder-authentication-status

String

Result of the 3-D Secure check.

attempt-three-d

Boolean

Indicates whether the transaction should use the 3-D Secure workflow.

merchant-account-id

value

String

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

custom-field

field-name

String

Custom field.

field-value

String

Custom field.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

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

requested-amount

currency

String

The currency of the requested/contested transaction amount.
Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

authorization-code

String

Provider authorization code.

csc-code

String

Code indicating Card Verification Value (CVV/CVC) verification results.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

card

expiration-month

Numeric

The expiration month of the card used in the transaction.

expiration-year

Numeric

The expiration year of the card used in the transaction.

card-type

String

The type/provider of the card used in the transaction.

merchant-tokenization-flag

Boolean

Indicates whether Cardholder card data was stored by the Merchant for future transactions. Maps to the Visa field Stored Credential.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message. Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

parent-transaction-id

String

The unique identifier of a transaction that is being referenced (sometimes referred to as the "original transaction").

parent-transaction-amount

currency

String

The currency of the requested/contested transaction amount.  Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

api-id

String

Description of the transaction for account holder’s bank statement purposes.

card-token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

transaction-type

String

The requested transaction type.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.

Non 3-D Secure Credit Card Payment

The WPP sends the final response containing the payment data as part of the onSuccess/onError function. Use the response to redirect the consumer to a success-/fail-/cancel-redirect-url of your own choice and design to inform the consumer about the transaction status.

To parse and process the payment response of Non 3-D Secure credit card payment, please consult WPP Security for details.

Merchants Integrated with NVP (Seamless Mode)

Merchants who integrated the previous payment page using NVP can also use seamless mode, with a few changes of function names. The integration is otherwise identical to the JSON version.

1. Update the paymentPageLoader JavaScript library in your <head> HTML code with the new paymentPage.js:

<script src="https://wpp.wirecard.com/loader/paymentPage.js" type="text/javascript"></script>

2. Use the NVP version of the "render" function:

WPP.seamlessRender({
        url: {payment-redirect-url}, // this is the payment link returned in response to your initial api/payment/register request from step 1
        wrappingDivId: "seamless-form-target",
        onSuccess: function (response) {
          // called when seamless form is successfully rendered
        },
        onError: function (errResp) {
          // called if seamless form failed to render
        }
      });

3. The "submit" function is the same for both types:

WPP.seamlessSubmit({
            onSuccess: function (response) {
            // called when seamless form data is successfully submitted
            },
            onError: function (response) {
            //called when data submission fails
            }
          });

Naturally, you do not send a backend request at the beginning with NVP, instead you include all the payment information inside requestData like in your old integration.  

Payment Methods

Credit Card
General Information

This is a reference page for Credit Card. Here you find all the information necessary for integrating this payment method in your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for all available transaction types,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact our merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

WPP can be used with the Credit Card transaction types purchase, authorization and authorization-only.

Test Credentials

URL(s) Endpoints

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

Merchant Account ID (MAID)

7a6dd74f-06ab-4f3f-a864-adc52687270a

Username

70000-APIDEMO-CARD

Password

ohysS0-dvfMx

Secret Key (used for response verification)

a8c3fce6-8df7-4fd6-a1fd-62fa229c5e55

Test Card Information for Credit Card

Card number

4200000000000018 

CVV

018

Expiration date

01/23

Credit Card Payment Form

Transaction Type purchase

A purchase transaction charges the account holder’s card and immediately transfers the reserved amount.

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for Credit Card transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA== 

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Credit Card specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "purchase",
    "requested-amount": {
      "value": 10.1,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/?wPaymentToken=PLDsRjRUB-1iMG_jKHfA98VqvLSd-nrzH_SSK8ELNOo"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. Canceled payments are returned as transaction-state: 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id": "up3-wpp",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "request-id": "102d7276-edac-4144-85b3-2b62a72ac1dd",
  "merchant-account-id": {
    "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
  },
  "transaction-state": "success",
  "payment-methods": {
    "payment-method": [
      {
        "name": "creditcard"
      }
    ]
  },
  "transaction-type": "purchase",
  "card-token": {
    "token-id": "4943380955491111",
    "masked-account-number": "444433******1111"
  },
  "transaction-id": "d1ecf4f8-f2bf-44e6-a5d5-79ce3cd4fd2e",
  "completion-time-stamp": "2018-04-03T15:19:56",
  "requested-amount": {
    "currency": "EUR",
    "value": 10.1
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "153620",
  "descriptor": "demo descriptor"
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.

merchant-account-id

value

String

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

transaction-state

String

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.

payment-method

name

String

The name of the payment method used for the transaction.

transaction-type

String

The requested transaction type.

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

authorization-code

String

Provider authorization code.

descriptor

String

Description of the transaction for account holder’s bank statement purposes.

Transaction Type authorization

An authorization transaction places the account holder’s funds on hold, pending future capture, re-authorization or void transaction.

As with other referenceable transaction types, you can use WPP only to create the authorization itself. To capture or register additional transactions referencing it, you need to use our REST API

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for Credit Card transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA== 

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Credit Card specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization",
    "requested-amount": {
      "value": 10.1,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/?wPaymentToken=aiW0jSJ69abFIV1kD6F73si9BK13PLEqTNYuIaIdUdg"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

authorization (Response)
{
  "api-id": "up3-wpp",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "request-id": "59725adc-4b4e-49d0-bd75-1ca3a4226081",
  "merchant-account-id": {
    "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
  },
  "transaction-state": "success",
  "payment-methods": {
    "payment-method": [
      {
        "name": "creditcard"
      }
    ]
  },
  "transaction-type": "authorization",
  "card-token": {
    "token-id": "4943380955491111",
    "masked-account-number": "444433******1111"
  },
  "transaction-id": "d9d47240-5b52-4184-b53a-37d5f755623d",
  "completion-time-stamp": "2018-04-03T15:44:55",
  "requested-amount": {
    "currency": "EUR",
    "value": 10.1
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "153620",
  "descriptor": "demo descriptor"
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.

merchant-account-id

value

String

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

transaction-state

String

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.

payment-method

name

String

The name of the payment method used for the transaction.

transaction-type

String

The requested transaction type.

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

authorization-code

String

Provider authorization code.

descriptor

String

Description of the transaction for account holder’s bank statement purposes.

Transaction Type authorization-only

An authorization-only transaction verifies the validity of account holder’s card, but does not leave an authorized amount.

authorization-only transactions require a zero requested amount.

As with other referenceable transaction types, you can use WPP only to create the authorization itself. To capture or register additional transactions referencing it, you need to use our REST API

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for Credit Card transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJREVNTy1DQVJEOm9oeXNTMC1kdmZNeA== 

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Credit Card specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization-only",
    "requested-amount": {
      "value": 0,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed. authorization-only transactions require a zero requested amount.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/?wPaymentToken=aiW0jSJ69abFIV1kD6F73si9BK13PLEqTNYuIaIdUdg"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id": "up3-wpp",
  "payment-methods": {
    "payment-method": [
      {
        "name": "creditcard"
      }
    ]
  },
  "request-id": "7d7fee3f-5d57-444d-ada2-8e0f0017840b",
  "merchant-account-id": {
    "value": "7a6dd74f-06ab-4f3f-a864-adc52687270a"
  },
  "transaction-state": "success",
  "account-holder": {
    "first-name": "John",
    "last-name": "Doe"
  },
  "transaction-type": "authorization-only",
  "card-token": {
    "token-id": "4684930252011111",
    "masked-account-number": "444433******1111"
  },
  "transaction-id": "a19e8683-aa82-41b2-b6d0-49a9cdfdc923",
  "completion-time-stamp": "2018-04-04T22:37:21",
  "requested-amount": {
    "currency": "EUR",
    "value": 0
  },
  "statuses": {
    "status": [
      {
        "description": "3d-acquirer:The resource was successfully created.",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "authorization-code": "153620",
  "descriptor": "demo descriptor"
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.

merchant-account-id

value

String

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

transaction-state

String

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.

payment-method

name

String

The name of the payment method used for the transaction.

transaction-type

String

The requested transaction type.

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

authorization-code

String

Provider authorization code.

descriptor

String

Description of the transaction for account holder’s bank statement purposes.

Credit Card with 3-D Secure

To process 3-D Secure transactions, you need to have them enabled on your merchant account. Contact merchant support if 3-D Secure was not enabled for you during Merchant setup.

If a consumer card is not 3-D enrolled and attempt-three-d is set to true, the payment fails.

To process a card payment with 3-D Secure enabled:

Add the attempt-three-d field to the payment request and set it to true.

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Test Credentials

URL(s) Endpoints

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

Merchant Account ID (MAID)

cad16b4a-abf2-450d-bcb8-1725a4cef443

Username

70000-APILUHN-CARD

Password

8mhwavKVb91T

Secret Key (used for response verification)

b3b131ad-ea7e-48bc-9e71-78d0c6ea579d

Test Card Information for Credit Card with 3D Secure

Card number

4012000300001003

CVV

003

Expiration date

01/23

3-D verification password

wirecard

Request Headers

Authorization

Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA== 

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Credit Card specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "purchase",
    "requested-amount": {
      "value": 10.1,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "three-d": {
      "attempt-three-d": "true"
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to creditcard.

attempt-three-d

Boolean

Conditional

N/A

Required for 3-D Secure transactions. Indicates whether 3-D Secure authentication is enabled for the transaction.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/?wPaymentToken=9TbVFfOEKVQKMR5JOw921dnF3x2kr0EwErr3LIcrKAQ"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "authorization-code": "376765",
    "transaction-state": "success",
    "merchant-account-id": {
      "value": "cad16b4a-abf2-450d-bcb8-1725a4cef443"
    },
    "card-token": {
      "token-id": "4304509873471003",
      "masked-account-number": "401200******1003"
    },
    "csc-code": "P",
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "statuses": {
      "status": [
        {
          "description": "Cardholder Successfully authenticated.",
          "severity": "information",
          "code": "200.1083"
        },
        {
          "description": "The resource was successfully created.",
          "severity": "information",
          "code": "201.0000"
        }
      ]
    },
    "custom-fields": {
      "custom-field": [
        {
          "field-name": "elastic-page-api.3d.original_txn_type",
          "field-value": "purchase"
        }
      ]
    },
    "parent-transaction-id": "983c48e3-4e46-45c7-8d06-8775d7a059c0",
    "api-id": "wpp",
    "iso": {
      "approval-code": "376765"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "transaction-id": "626a672e-a4c8-4e10-a5c8-b10e2ab43634",
    "completion-time-stamp": "2018-11-30T09:07:29",
    "requested-amount": {
      "currency": "EUR",
      "value": 10.1
    },
    "card": {
      "merchant-tokenization-flag": false,
      "card-type": "visa",
      "expiration-month": 1,
      "expiration-year": 2019
    },
    "three-d": {
      "eci": "05",
      "xid": "aG9ONUhrbmFIVnUxQUIwOVBTelM=",
      "cardholder-authentication-value": "AAABD///////////////AAAAAAA=",
      "attempt-three-d": false,
      "cardholder-authentication-status": "Y"
    },
    "transaction-type": "purchase",
    "request-id": "d2eb0563-e7b5-4415-ade9-0246bcc2f6bc"
  }
}
Possible results for ECI field

These are the possible scenarios for the value of the field eci:

3-D authentication successful

The card issuing bank is 3-D ready and cardholder is enrolled. (ECI Value: 05 - VISA/JCB/American Express; 02 - Mastercard)

3-D authentication unsuccessful

Either the card issuing bank is not 3-D ready or the cardholder is not enrolled. (ECI Value: 06 - VISA/JCB/American Express; 01 - Mastercard)

3-D authentication unsuccessful or not attempted

Either a non-3D card or the card issuing bank does not handle the transaction as 3-D Secure. (ECI Value: 07 - VISA/JCB/American Express; 00 - Mastercard)

Field (JSON) Data Type Description

authorization-code

String

Provider authorization code.

transaction-state

String

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.

merchant-account-id

value

String

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

card-token

token-id

String

A unique identifier assigned to every card token.

masked-account-number

String

The masked code that represents the account (card) number used in the transaction.

csc-code

String

Code indicating Card Verification Value (CVV/CVC) verification results.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

custom-field

field-name

String

field-value

String

parent-transaction-id

String

The unique identifier of a transaction that is being referenced (sometimes referred to as the "original transaction").

api-id

String

Description of the transaction for account holder’s bank statement purposes.

iso

approval-code

String

Authentication ID of the response

payment-method

name

String

The name of the payment method used for the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

card

merchant-tokenization-flag

Boolean

Indicates whether Cardholder card data was stored by the Merchant for future transactions. Maps to the Visa field Stored Credential.

card-type

String

The type/provider of the card used in the transaction.

expiration-month

Numeric

The expiration month of the card used in the transaction.

expiration-year

Numeric

The expiration year of the card used in the transaction.

three-d

eci

String

ECI (Electronic Commerce Indicator) indicates the 3-D authentication results. This value is returned from the card provider’s directory server.

xid

String

Unique transaction identifier in the 3-D Secure process provided by MPI (merchant plug-in).

cardholder-authentication-value

String

The CAVV is a a cryptographic value generated by the issuer.

For Visa transactions, it is called CAVV (Cardholder Authentication Verification Value).

For MasterCard transactions, it is either called Account Holder Authentication Value (AAV) or Universal Cardholder Authentication Field (UCAF).

attempt-three-d

Boolean

Indicates whether the transaction should use the 3-D Secure workflow.

cardholder-authentication-status

String

Result of the 3-D Secure check.

transaction-type

String

The requested transaction type.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing to it later.

3-D Secure 2 - Additional Fields

To create a payment session with Credit Card using 3-D Secure 2 authentication, you need to include additional 3-D Secure 2 fields in your initial request.

Most of these fields are optional but we recommend the implementation of optional fields, as this creates a smoother user experience and ensures a higher level of security.

Need more information on 3-D Secure 2? Head to our general introduction to 3-D Secure 2.

Additional Fields for 3DS2
JSON Datatype Required/Optional/Conditional Size Description

account-holder

account-info

authentication-method

String

Conditional

2

Type of consumer login in the merchant’s shop.
Possible values: 01, 02, 03, 04, 05, 06
01 = Guest checkout (i.e. the consumer is not logged in).
02 = Login to the consumer’s account in merchant’s shop with shop-own authentication credentials.
03 = Login with Federated ID.
04 = Login with card issuer credentials.
05 = Login with third-party authentication.
06 = Login with FIDO authenticator.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

authentication-timestamp

DateTime

Conditional

19

Date and time (UTC) of the consumer login in the merchant’s shop. Accepted format: YYYY-MM-DDThh:mm:ss. For guest checkout, the datetime is now.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

challenge-indicator

String

Optional

2

Indicates whether a challenge is requested for this transaction.
Possible values: 01, 02, 03, 04
01 = No preference.
02 = No challenge requested.
03 = Challenge requested: Merchant Preference.
04 = Challenge requested: Mandate. Must be sent in a first transaction that stores a token (e.g. for one-click checkout).

account-creation-date

Date

Optional

10

Registration date of the consumer’s account in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

account-update-date

Date

Optional

10

Date that the consumer last made changes to their account in the merchant’s shop. For example, changes to billing and shipping address, new payment account, new email address. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

password-change-date

Date

Optional

10

Date that the consumer last changed/reset their password in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

shipping-address-first-use

Date

Optional

10

Date that the consumer first used this shipping address in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

transactions-last-day

Numeric

Optional

9

Number of transactions (successful, failed, and canceled) that the consumer has attempted in the past 24 hours. Does not include merchant-initiated transactions.

transactions-last-year

Numeric

Optional

9

Number of transactions (successful, failed, and canceled) that the consumer has attempted within the past year. Does not include merchant-initiated transactions.

card-transactions-last-day

Numeric

Optional

9

Number of cards the consumer has attempted to add to their account in the merchant’s shop for card-on-file payments (one-click checkout) in the past 24 hours.

purchases-last-six-months

Numeric

Optional

9

Number of successful orders by the consumer in the merchant’s shop within the past six months.

suspicious-activity

Boolean

Optional

Indicates if the merchant knows of suspicious activities by the consumer (e.g. previous fraud).

card-creation-date

Date

Optional

10

Date that the consumer’s card was added to their account in the merchant’s shop for card-on-file payments (one-click checkout). Accepted format: YYYY-MM-DD.
For all other types of checkout (e.g. guest checkout, regular checkout, the first transaction with one-click checkout), the datetime is now.

merchant-crm-id

String

Optional

64

Consumer identifier in the merchant’s shop. Requests that contain payment information from the same consumer in the same shop must contain the same string.

address

city

String

Conditional

50

City of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

country

String

Conditional

2

Country of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

street1

String

Conditional

50

Line 1 of the street address of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

street2

String

Conditional

50

Line 2 of the street address of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

street3

String

Conditional

50

Line 3 of the street address of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

postal-code

String

Conditional

16

ZIP/postal code of the consumer’s billing address.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

state

String

Conditional

3

State/province of the consumer’s billing address. Accepted format: numeric ISO 3166-2 standard.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

email

String

Conditional

256

The consumer’s email address as given in the merchant’s shop.
This field is conditional. If you do not include it in the request, the likelihood that the transaction will be challenged increases.

home-phone

String

Conditional

18

Home phone number provided by the consumer.
This field is required if available.

mobile-phone

String

Conditional

18

Mobile phone number provided by the consumer.
This field is required if available.

work-phone

String

Conditional

18

Work phone number provided by the consumer.
This field is required if available.

last-name

String

Conditional

50

The last name provided by the consumer as part of the credit card details.

first-name

String

Conditional

50

The first name provided by the consumer as part of the credit card details.

shipping

shipping-method

String

Optional

2

The shipping method chosen by the consumer. Merchants must use the shipping indicator value that applies most accurately to the shipping method.
Accepted values are: 01, 02, 03, 04, 05, 06, 07
01 = Ship to consumer’s billing address.
02 = Ship to another address known to and verified by the merchant.
03 = Ship to an address that differs from the consumer’s billing address.
04 = "Ship to Store" / Pick-up at local store (store address in shipping address fields).
05 = Digital goods (includes online services, electronic gift cards, and redemption codes).
06 = Travel and event tickets, not shipped.
07 = Other (e.g. gaming, digital services, e-media subscriptions)

address

city

String

Conditional

50

City of the consumer’s shipping address. Must be sent even if billing city is identical.
This field does not apply to digital goods.

country

String

Conditional

2

Country of the consumer’s shipping address. Must be sent even if billing country is identical.
This field does not apply to digital goods.

street1

String

Conditional

50

Line 1 of the street address of the consumer’s shipping address. Must be sent even if billing address is identical.
This field does not apply to digital goods.

street2

String

Conditional

50

Line 2 of the street address of the consumer’s shipping address. Must be sent even if billing address is identical.
This field does not apply to digital goods.

street3

String

Conditional

50

Line 3 of the street address of the consumer’s shipping address. Must be sent even if billing address is identical.
This field does not apply to digital goods.

postal-code

String

Conditional

16

ZIP/postal code of the consumer’s shipping address. Must be sent even if billing address is identical.
This field does not apply to digital goods.

state

String

Conditional

3

State/province of the consumer’s shipping address. Accepted format: numeric ISO 3166-2 standard. Must be sent even if billing address is identical.
This field does not apply to digital goods.

risk-info

delivery-timeframe

String

Optional

2

The approximate delivery time.
Accepted values are: 01, 02, 03, 04
01 = Electronic delivery
02 = Same-day delivery
03 = Overnight delivery
04 = Two-day or more delivery

delivery-mail

String

Optional

254

The consumer’s email address used for electronic delivery of digital goods.

reorder-items

String

Optional

2

The consumer has previously ordered the same item. Accepted values are: 01, 02
01 = First-time order
02 = Reorder

availability

String

Optional

2

The consumer is placing an order for merchandise that is not yet available and will be released in the future. Accepted values are: 01, 02
01 = Currently available
02 = Future availability

preorder-date

Date

Optional

10

Expected shipping date for pre-ordered goods. Accepted format: YYYY-MM-DD.

gift

amount

Numeric

Optional

For the purchase of prepaid and gift cards. The total amount of prepaid/gift card in major units (no decimal places allowed).

amount

currency

String

Optional

3

The currency code for prepaid and gift cards. Accepted format: ISO 4217.

card-count

Numeric

Optional

2

The total number of prepaid and gift cards that are being purchased.

periodic

recurring-expire-date

Date

Conditional

10

For recurring payments only. Date after which no further recurring payments using this card are allowed. Accepted format: YYYY-MM-DD.

recurring-frequency

Numeric

Conditional

4

For recurring payments only. The minimum number of days between individual payments.

iso-transaction-type

String

Optional

2

Identifies the transaction type. The values are derived from ISO 8583. Accepted values are: 01, 03, 10, 11, 28
01 = Goods/ Service Purchase
03 = Check Acceptance
10 = Account Funding
11 = Quasi-Cash Transaction
28 = Prepaid Activation and Load

three-d

version

String

Optional

5

Identifies the version of 3-D Secure authentication used for the transaction. Accepted values are: 1.0, or 2.1

Post-Processing Operations 

WPP is best used to deal with "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 operations — like a refund of one of your debit transactions  — use our REST API directly. Check the REST API Credit Card specification for details on Credit Card specific post processing operations.

There are multiple post processing operations available for Credit Card:

  • capture operations for both authorization and authorization-only,

  • recurring transactions,

  • void transactions,

  • refunds,

  • and more.

For examples and more information, see the REST API Credit Card specification.

JSON/NVP Field Reference

Here you can

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

  • see the structure of a full request (optional fields included).

JSON Structure for Credit Card Requests
{
  "payment": {
    "merchant-account-id": {
      "value": "string"
    },
    "request-id": "string",
    "transaction-type": "string",
    "requested-amount": {
      "currency": "string",
      "value": 0
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "creditcard"
        }
      ]
    },
    "account-holder": {
      "first-name": "string",
      "last-name": "string",
      "email": "string",
      "phone": "string",
      "address": {
        "street1": "string",
        "street2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postal-code": "string"
      }
    },
    "shipping": {
      "first-name": "string",
      "last-name": "string",
      "phone": "string",
      "address": {
        "street1": "string",
        "street2": "string",
        "city": "string",
        "state": "string",
        "country": "string",
        "postal-code": "string"
      }
    },
    "order-number": "string",
    "order-detail": "string",
    "ip-address": "string",
    "three-d": {
      "attempt-three-d": "true"
    },
    "success-redirect-url": "string",
    "fail-redirect-url": "string",
    "cancel-redirect-url": "string",
    "descriptor": "string"
  }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount_currency

currency

requested-amount ({ })

requested_amount

value

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

email

email

account-holder ({ })

phone

phone

account-holder ({ })

street1

address ({ })/ street1

account-holder ({ })

street2

address ({ })/ street2

account-holder ({ })

city

address ({ })/ city

account-holder ({ })

state

address ({ })/ state

account-holder ({ })

country

address ({ })/ country

account-holder ({ })

postal_code

address ({ })/ postal-code

account-holder ({ })

shipping_first_name

first-name

shipping ({ })

shipping_last_name

last-name

shipping ({ })

shipping_phone

phone

shipping ({ })

shipping_street1

address ({ })/ street1

shipping ({ })

shipping_street2

address ({ })/ street2

shipping ({ })

shipping_city

address ({ })/ city

shipping ({ })

shipping_state

address ({ })/ state

shipping ({ })

shipping_country

address ({ })/ country

shipping ({ })

shipping_postal_code

address ({ })/ postal-code

shipping ({ })

order_number

order-number

payment ({ })

order_detail

order-detail

payment ({ })

ip_address

ip-address

payment ({ })

attempt_three_d

attempt-three-d

payment ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

descriptor

descriptor

payment ({ })

Response-only Fields
{
  "payment": {
    "api-id": "string",
    "transaction-state": "string",
    "card-token": {
      "masked-account-number": "string"
    },
    "transaction-id": "string",
    "completion-time-stamp": "2018-03-22T16:28:46",
    "statuses": {
      "status": [
        {
          "description": "string",
          "severity": "string",
          "code": "string"
        }
      ]
    },
    "authorization-code": "string"
  }
}
Field (NVP) Field (JSON) JSON Parent

api_id

api-id

payment ({ })

transaction_state

transaction-state

payment ({ })

masked_account_number

masked-account-number

card-token ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

authorization_code

authorization-code

payment ({ })

Alipay Cross-border
General Information

This is a reference page for Alipay Cross-border. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type  debit, including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About Alipay Cross-border
Alipay Cross-border logo

Alipay is China’s leading online payment service provider. It offers a wallet system similar to PayPal and WeChat Pay.

Alipay Cross-border makes international online shopping easy for Chinese consumers: they can pay using Renminbi (RMB). Alipay Cross-border will then remit the sum to the foreign merchant in their currency.

Currently, Alipay Cross-border supports transactions with the following currencies: AUD, CAD, CHF, CNY, DKK, EUR, GBP, HKD, JPY, NOK, NZD, SEK, SGD, THB, USD.

Test Credentials

Merchant Credentials for Transaction Type debit

URI Endpoint

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

Merchant Account ID (MAID)

47cd4edf-b13c-4298-9344-53119ab8b9df

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

94fe4f40-16c5-4019-9c6c-bc33ec858b1d

Additional Test Credentials for the Alipay Cross-border Environment

Merchant Test Account

User ID

2088101122136241

Key

760bdzec6y9goq7ctyx96ezkz78287de

Consumer Test Account

Account Name

alipaytest20091@gmail.com

Password

111111

Payment Password

111111

Alipay Cross-border login form
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for Alipay Cross-border transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Alipay Cross-border specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "47cd4edf-b13c-4298-9344-53119ab8b9df"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "requested-amount": {
      "currency": "USD",
      "value": "2.22"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "180528105918955",
    "order-detail": "Test product 001",
    "ip-address": "127.0.0.1",
    "locale": "en",
    "account-holder": {
      "first-name": "Wing",
      "last-name": "Wu",
      "email": "wiwu@example.com"
    },
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
  }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

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

request-id

String

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-z0-9-_]

transaction-type

String

The requested transaction type. For Alipay Cross-border payments, transaction-type must be set to debit.

requested-amount

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

To test Alipay Cross-border, enter a small sum (double digit amount at most).

currency

String

The currency of the requested/contested transaction amount. For Alipay Cross-border payments, the currency must be one of the following: AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD. Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

The name of the payment method used. Set this value to alipay-xborder.

order-number

String

The order number provided by the merchant.

order-detail

String

Merchant-provided string to store the order details for the transaction.

ip-address

String

The internet protocol address of the consumer.

locale

String

A set of parameters defining language and country in the user interface.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

email

String

The email address of the account holder.

success-redirect-url

String

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

fail-redirect-url

String

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

cancel-redirect-url

String

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

2. Redirect the Consumer to the Payment Page (Initial Debit Response)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=qbGUDHkDzUGJ6lMePOZCGMIrM-19k61AXlUAEOaqccU"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "locale": "en",
    "ip-address": "127.0.0.1",
    "transaction-id": "93b086ec-3183-494a-83e0-fcf6f85f4273",
    "completion-time-stamp": "2019-03-12T07:24:06",
    "requested-amount": {
      "currency": "USD",
      "value": 2.22
    },
    "parent-transaction-id": "f30f82ff-86e1-47b2-aa1a-d741e9eee8cf",
    "request-id": "47987754-5852-419d-9d44-0236ea6a8780",
    "merchant-account-id": {
      "value": "47cd4edf-b13c-4298-9344-53119ab8b9df"
    },
    "transaction-state": "success",
    "transaction-type": "debit",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
    "statuses": {
      "status": [
        {
          "description": "The resource was successfully created.",
          "severity": "information",
          "code": "201.0000"
        }
      ]
    },
    "account-holder": {
      "first-name": "Wing",
      "last-name": "Wu",
      "email": "wiwu@example.com"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "180528105918955",
    "order-detail": "Test product 001",
    "api-id": "wpp"
  }
}
Field (JSON) Data Type Description

locale

String

A set of parameters defining language and country in the user interface.

ip-address

String

The internet protocol address of the consumer.

transaction-id

String

A unique identifier assigned for every transaction. This information is returned in the response only.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For Alipay Cross-border payments, the currency must be one of the following: AUD, CAD, CHF, DKK, EUR, GBP, HKD, JPY, KRW, NOK, NZD, SEK, SGD, THB, USD.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

transaction-state

String

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.

transaction-type

String

The requested transaction type. For Alipay Cross-border payments, transaction-type must be set to debit.

cancel-redirect-url

String

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

success-redirect-url

String

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

fail-redirect-url

String

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

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

account-holder

first-name

String

The first name of the consumer.

last-name

String

The last name of the consumer.

email

String

The email address of the consumer.

payment-method

name

String

The name of the payment method used. Set this value to alipay-xborder.

order-number

String

This is the order number of the merchant.

order-detail

String

Merchant-provided string to store the order details for the transaction.

api-id

String

Identifier of the currently used API.

Post-Processing Operations

WPP is best used to deal with 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 Alipay Cross-border specification for details on Alipay Cross-border specific post-processing operations.
JSON/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for Alipay Cross-Border debit Requests
{
  "payment": {
    "merchant-account-id": {
      "value": "string"
    },
    "request-id": "string",
    "transaction-type": "string",
    "requested-amount": {
      "currency": "string",
      "value": "numeric"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "alipay-xborder"
        }
      ]
    },
    "order-number": "string",
    "order-detail": "string",
    "ip-address": "string",
    "locale": "string",
    "account-holder": {
      "first-name": "string",
      "last-name": "string",
      "email": "string"
    },
    "success-redirect-url": "string",
    "fail-redirect-url": "string",
    "cancel-redirect-url": "string"
  }
}
Request-Only Fields
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

order_number

order-number

payment ({ })

order_detail

order-detail

payment ({ })

ip_address

ip-address

payment ({ })

locale

locale

payment ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

email

email

account-holder ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

JSON Structure for Alipay Cross-border debit Responses
{
  "payment": {
    "transaction-id": "string",
    "completion-time-stamp": "2019-03-12T07:24:06",
    "parent-transaction-id": "string",
    "transaction-state": "success",
    "statuses": {
      "status": [
        {
          "description": "string",
          "severity": "string",
          "code": "string"
        }
      ]
    },
    "api-id": "wpp"
  }
}
Response-Only Fields
Field (NVP) Field (JSON) JSON Parent

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

parent_transaction_id

parent-transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

api_id

api-id

payment ({ })

Bancontact
General Information

This is a reference page for Bancontact. Here you find all the information necessary for integrating this payment method in your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find an example request for the available transaction type debit, including field lists with short descriptions.

You need to complete these requests with your production credentials. You receive your credentials with your Wirecard contract. If you need your production credentials, contact merchant support.

Testing Bancontact

Bancontact does not offer a payment testing sandbox. You need to test transactions with your production credentials.

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

For response verification examples, see the WPP Security section.

About Bancontact
Bancontact logo

Bancontact is the most popular online payment method in Belgium. It is used in more than 80% of Belgian web shops. It allows consumers to pay with Belgian credit cards.

  • With the Bancontact mobile app, one can pay back friends without cash immediately after they took over a payment (e.g. at a restaurant).

  • Invoices can be paid at home using the Bancontact mobile app. The app is used in a growing number of businesses and stores to pay bills without the hassle of a card reader.

Countries and Currencies

Bancontact can be used by consumers with a bank account in Belgium. The available payment currency for consumers is EUR.  

Test Credentials

Test Credentials for Transaction Type debit.

URL (Endpoint)

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

Merchant Account ID (MAID)

86f03c98-6691-421d-94c8-232c3d5c2573

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

2341ae35-aa13-4511-95d5-acd80f0fcb52

Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for Bancontact transactions.

Initial Request

This example is an initial request which creates the payment session. If it is successful, you receive a URL as a response, which redirects to the Bancontact payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Bancontact specification.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "86f03c98-6691-421d-94c8-232c3d5c2573"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "bancontact"
        }
      ]
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "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"
  }
}
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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type. For Bancontact payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For Bancontact payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-methods

payment-method

name

String

Required

15

The name of the payment method used. Set this value to bancontact.

account-holder

first-name

String

Optional

32

The first name of the account holder.

last-name

String

Requested

32

The last name of the account holder.

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

2. Redirect the consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=UvnC2LM5QuDotVHTmfV2t4AZn9dJpZNt6dFAwxZHdvU"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "merchant-account-id": {
      "value": "your-custom-MAID-..."
    },
    "request-id": "66b62159-691f-40e3-8411-24c854bb0f8b",
    "transaction-type": "debit",
    "parent-transaction-id": "8d2ec658-d234-44cb-b557-791489e8464f",
    "payment-methods": {
      "payment-method": [
        {
          "name": "bancontact"
        }
      ]
    },
    "transaction-state": "success",
    "transaction-id": "The-transaction-id-received-here-is-the-parent-transaction-id-of-the-following-capture-authorization",
    "completion-time-stamp": "2018-09-26T05:54:20",
    "requested-amount": {
      "currency": "EUR",
      "value": 10.1
    },
    "statuses": {
      "status": [
        {
          "description": "The resource was successfully created.",
          "severity": "information",
          "code": "201.0000"
        }
      ]
    },
    "api-id": "wpp",
    "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"
  }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

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

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

transaction-type

String

The requested transaction type. For Bancontact payments, the transaction-type must be set to debit.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

payment-methods

payment-method

name

String

The name of the payment method used.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For Bancontact payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

statuses

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

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

eps
General Information

This is a reference page for eps. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type debit,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About eps
eps logo

eps-Überweisung (electronic payment standard), eps for short, is an online payment method provided to consumers of Austrian banks. eps utilizes the established popular payment methods for online shopping in Austria. eps is one of the most popular payment methods for online shopping in Austria.

The eps e-payment standard is the interface between online payment systems for irrevocable payments, adopted by online shops as well as public authorities like E-Government.

Selecting a bank in a merchant’s web store, the consumer is redirected from the merchant’s web store to their bank’s online banking window.

If no bank is selected in the merchant’s web store, the bank selection is done during redirect and the consumer is redirected to their bank’s online banking window after selecting a bank from the SO (Scheme Operator, central routing instance for eps) bank list.

Successfully logging on to their respective account using their account number and PIN, the consumer simply needs to confirm the transaction using a TAN.

After the consumer has confirmed the payment with TAN (or other commonly used approval mechanism within internet banking), eps confirms the payment-sending payment result and details to the PSP system.

The consumer clicks the "Back to shop" link in the online banking window and is redirected back to the merchant’s web shop.

giropay interoperability
giropay logo

SO-implemented interlink to eps-giropay scheme in Germany. If the merchant’s contract allows to process those interoperability transactions, all eps-giropay participating banks in Germany can also be reached with a technical eps transaction. To enable giropay interoperability, the merchant has to register giropay directly with eps. In some cases, this is a free add-on. If giropay is activated by eps, the bank selection page shows the German bank institutes next to the Austrian ones.

Test Credentials

Test Credentials for Transaction Type debit.

Merchant Credentials

URI (Endpoint)

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

Merchant Account ID (MAID)

1f629760-1a66-4f83-a6b4-6a35620b4a6d

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

20c6a95c-e39b-4e6a-971f-52cfb347d359

Test Credentials for eps sandbox

Ärzte- und Apotheker Bank

BIC

BWFBATW1XXX 

Login data

Click to continue - no input needed.

or

Stuzza Bank

BIC

STUZZATWXXX

Login data

On request available from merchant support.

Transaction Type debit

A debit transaction charges the account holder’s bank account with the specified amount and transfers it immediately.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for eps transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json

1. Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
            "value": "1f629760-1a66-4f83-a6b4-6a35620b4a6d"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "debit",
        "requested-amount": {
            "value": "62.34",
            "currency": "EUR"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "eps"
                }
            ]
        },
        "bank-account": {
            "iban": "AT123456789012345678",
            "bic": "BWFBATW1XXX"
        },
        "account-holder" : {
            "first-name" : "Iam T.",
            "last-name" : "Shopper"
        },
        "descriptor": "Here are the details to your payment. Thank you for shopping!",
        "order-number": "7171456",
        "locale": "AT",
        "notifications": {
            "notification": [
                {
                "url": "https://example.com/ipn.php"
                }
            ]
        },
        "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"
    }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

Required

36

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant-account-id for each payment method.

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-z0-9-_]

transaction-type

String

Required

n/a

The requested transaction type. For eps payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Required

18.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-methods

payment-method

name

String

Required

15

The name of the payment method used. Set this value to eps.

bank-account

bic

String

Optional

8 or 11

The bank identifier code (BIC) of the account owner (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

Optional

34

The international bank account number (IBAN) of the account owner (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}

account-holder

first-name

String

Optional

32

The first name of the account holder.

last-name

String

Required

32

The last name of the account holder.

descriptor

String

Optional

140

The descriptor is the text representing an order on the bank statement issued to your consumer by their bank. It provides information for the consumer, as it associates a specific debit on the consumer’s account to a specific purchase in your shop.

Limit of 35 characters for structured purpose or 140 characters for unstructured purpose. Applied only if not already configured during merchant setup.

Supports only limited character set:

[a-zA-Z0-9],

€ - $ § % ! = # ~ ; + / ? : ( ) . , ' & > < " * { } [ ] @ \ _ ° ^ |

Ä Ö Ü ä ö ü ß

The space key.

order-number

String

Optional

32

Merchant-side order number.

Allowed characters: [a-zA-Z0-9+]

locale

String

Optional

2

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

notification-url

String

Optional

256

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

2. Redirect the Consumer to the Payment Page (Initial Debit Response)
{
"payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=6SHxrNo6Pfwa_gLiCadCgMDmj2U9SpvzdvhG8gNQ_gA"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
   "payments": {
      "payment": {
         "merchant-account-id": "557c767b-92a6-4b74-98c0-233025ba016b",
         "transaction-id": "0635ef01-5448-4df8-8fd6-29fd8ef7a5e3",
         "request-id": "61108925-0944-40a1-b2af-1ed291e16e49",
         "transaction-type": "debit",
         "transaction-state": "success",
         "completion-time-stamp": "2018-08-29T13:06:40.000Z",
         "statuses": {
            "status": [
               {
                  "code": "201.0000",
                  "description": "The resource was successfully created.",
                  "severity": "information"
               }
            ]
         },
         "requested-amount": {
            "currency": "EUR",
            "text": "62.340000"
         },
         "parent-transaction-id": "1051f70d-941f-4e1c-ba05-eaf9a705fe8d",
         "order-number" : "7171456",
         "account-holder": {
            "first-name": "Iam T.",
            "last-name": "Shopper"
         },
         "payment-methods": {
            "payment-method": {
               "name": "eps"
            }
         },
         "bank-account": {
            "iban": "AT302099900001123488",
            "bic": "SPBAAT20XXX"
         },
         "api-id": "wpp",
         "locale": "at",
         "descriptor" : "Here are the details to your payment. Thank you for shopping!",
         "notifications": {
            "notification": [
                {
                "url": "https://example.com/ipn.php"
                }
            ]
         },
         "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"
      }
   }
}
Field (JSON) Data Type Description

merchant-account-id

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

transaction-id

String

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

request-id

String

A unique identifier assigned by the merchant to each request. Used when searching for or referencing it later.

transaction-type

String

The requested transaction type. Must be debit for eps payments.

transaction-state

String

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

DateTime

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

status

code

String

Status code of the status message.

description

String

The description of the transaction status message. Click here for a complete list of status descriptions.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

requested-amount

currency

String

The currency of the requested/contested transaction amount.

value

Numeric

The full amount that was requested/contested in the transaction.

parent-transaction-id

String

The ID of the transaction being referenced as a parent. As a debit transaction is internally split into sub-transactions, the parent-transaction-id serves to link these sub-transactions.

order-number

String

Merchant-side order number as set in the request.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

ip-address

String

The internet protocol address of the account holder as recorded by the entity receiving the transaction attempt from the account holder. Supported IP versions: IPv4 and IPv6.

payment-methods

payment-method

name

String

The name of the payment method used.

bank-account

iban

String

The international bank account number (IBAN) of the account holder.

bic

String

The bank identifier code (BIC) of the account holder.

api-id

String

Identifier of the currently used API.

locale

String

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

descriptor

String

The descriptor is the text representing an order on the bank statement issued to your consumer by their bank. It provides information for the consumer, as it associates a specific debit on the consumer’s account to a specific purchase in your shop.

notification-url

String

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

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

fail-redirect-url

String

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

cancel-redirect-url

String

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

Transaction Type refund

Basically, eps with WPP supports debit only. For refunds, use SEPA Credit Transfer (if SEPA Credit Transfer is activated for your merchant account) through our REST API.

You must provide the necessary data:

  • parent-transaction-id: This is the transaction ID of the preceding debit. You can gather it from the response to a successful debit.

  • amount (can be either the total amount for refunding the full amount, or a partial amount for a partial refund).

If the parent-transaction-id is not available, the following fields are mandatory:

  • iban

  • bic (only required by some acquirers)

  • amount (can be either the total amount for refunding the full amount, or a partial amount for a partial refund)

JSON/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for eps Requests
{
    "payment": {
        "merchant-account-id": {
        "value": "string"
        },
        "request-id": "string",
        "transaction-type": "string",
        "requested-amount": {
            "currency": "string",
            "value": "0"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "string"
                }
            ]
        },
        "bank-account": {
            "iban": "string",
            "bic": "string"
        },
        "account-holder" : {
            "first-name" : "string",
            "last-name" : "string"
        },
        "descriptor": "string",
        "order-number": "string",
        "locale": "string",
        "success-redirect-url": "string",
        "fail-redirect-url": "string",
        "cancel-redirect-url": "string"
    }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id

request_id

request-id

payment

transaction_type

transaction-type

payment

requested_amount_currency

currency

requested-amount

requested_amount

value

requested-amount

payment_method

payment-method ([ ])/name

payment-methods

bank_account_bic

bic

bank-account

bank_account_iban

iban

bank-account

first_name

first-name

account-holder

last_name

last-name

account-holder

descriptor

descriptor

payment

order_number

order-number

payment

locale

locale

payment

success_redirect_url

success-redirect-url

payment

fail_redirect_url

fail-redirect-url

payment

cancel_redirect_url

cancel-redirect-url

payment

ip_address

ip-address

ip-address

Response-Only Fields
{
    "api-id" : "string",
    "parent-transaction-id" : "string",
    "transaction-state" : "string",
    "transaction-id" : "string",
    "completion-time-stamp" : "2018-03-23T10:41:34",
    "statuses" : {
        "status" : [ {
        "severity" : "string",
        "code" : "string",
        "description" : "string"
        } ]
    }
}
Field (NVP) Field (JSON) JSON Parent

api_id

api-id

payment

parent_transaction_id

parent-transaction-id

payment

transaction_state

transaction-state

payment

transaction_id

transaction-id

payment

completion_time_stamp

completion-time-stamp

payment

status_severity_n

status ([ {} ])/ severity

statuses

status_code_n

status ([ {} ])/ code

statuses

status_description_n

status ([ {} ])/ description

statuses

iDEAL
General Information

This is a reference page for iDEAL. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type debit,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About iDEAL
iDEAL logo

iDEAL is an e-commerce payment method widely used in the Netherlands. Introduced in 2005, this payment method allows consumers to buy on the Internet using direct online transfers from their bank account. iDEAL works together with leading Dutch banks using their online banking systems to carry out payment transactions.

Participating Banks
BIC Name

ABNANL2A

ABN Amro Bank

ASNBNL21

ASN Bank

BUNQNL2A

bunq

HANDNL2A

Handelsbanken

INGBNL2A

ING

KNABNL2H

Knab

MOYONL21

Moneyou

RABONL2U

Rabobank

RGGINL21

Regio Bank

SNSBNL2A

SNS Bank

TRIONL2U

Triodos Bank

FVLBNL22

Van Lanschot Bankiers

Test Credentials

Test Credentials for Transaction Type debit.

URLI (Endpoint)

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

Merchant Account ID (MAID)

adb45327-170a-460b-9810-9008e9772f5f

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

1b9e63b4-c132-42c3-bcbd-2d2e47ae7154

Test banks for iDEAL Sandbox
Bank BIC

Rabobank 

RABONL2U

ING

INGBNL2A

At the moment, only Rabobank (RABONL2U) and ING (INGBNL2A) are available for testing purposes. Choosing any other bank from the selection on the payment or sending its BIC in the request triggers payment failure.

image
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for iDEAL payments.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API iDEAL specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
        "value": "adb45327-170a-460b-9810-9008e9772f5f"
        },
        "request-id": "{{$guid}}",
        "transaction-type": "debit",
        "requested-amount": {
            "currency": "EUR",
            "value": "1.23"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "ideal"
                }
            ]
        }
    }
}
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-z0-9-_]

transaction-type

String

Required

n/a

The requested transaction type. For iDEAL payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Required

18.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For iDEAL payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-methods

payment-method

name

String

Required

15

The name of the payment method used. Set this value to iDEAL.

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
"payment-redirect-url" : "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id" : "up3-wpp",
  "parent-transaction-id" : "335da412-98ba-446d-a936-52b53f195e6c",
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "ideal"
    } ]
  },
  "request-id" : "edcdefd8-ba6b-4987-a02c-112ecb3c67a5",
  "merchant-account-id" : {
    "value" : "adb45327-170a-460b-9810-9008e9772f5f"
  },
  "transaction-state" : "success",
  "account-holder" : {
    "first-name" : "Hr",
    "last-name" : "E G H Küppers en/of MW M.J. Küpp"
  },
  "bank-account" : {
    "iban" : "NL53INGB0654422370",
    "bic" : "INGBNL2A"
  },
  "transaction-type" : "debit",
  "transaction-id" : "cac570c9-d2a3-4b43-ac14-ca9e72b60c8c",
  "completion-time-stamp" : "2018-03-23T10:41:34",
  "requested-amount" : {
    "currency" : "EUR",
    "value" : 1.230000
  },
  "statuses" : {
    "status" : [ {
      "severity" : "information",
      "code" : "201.1126",
      "description" : "Successful confirmation received from the bank."
    } ]
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

payment-method

name

String

The name of the payment method used.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

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

transaction-state

String

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.

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

bank-account

iban

String

The international bank account number (IBAN) of the account holder.

bic

String

The bank identifier code (BIC) of the account holder.

transaction-type

String

The requested transaction type.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For iDEAL payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

description

String

The description of the transaction status message.

Post-Processing Operations

WPP is best used to deal with 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.

A direct refund through WPP is not possible for iDEAL so you have to obtain your consumer’s banking information and send the refund using SEPA Credit Transfer.
Check the REST API SEPA Credit Transfer specification for details on iDEAL specific post-processing operations.
JSON/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for iDEAL Requests
{
    "payment": {
        "merchant-account-id": {
        "value": "string"
        },
        "request-id": "string",
        "transaction-type": "string",
        "requested-amount": {
            "currency": "string",
            "value": "0"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "string"
                }
            ]
        },
        "bank-account": {
            "iban": "string",
            "bic": "string"
        },
        "account-holder" : {
            "first-name" : "string",
            "last-name" : "string"
        },
        "descriptor": "string",
        "order-number": "string",
        "locale": "string",
        "success-redirect-url": "string",
        "fail-redirect-url": "string",
        "cancel-redirect-url": "string"
    }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request-id

request-id

payment ({ })

transaction-type

transaction-type

payment ({ })

requested_amount_currency

currency

requested-amount ({ })

requested_amount

value

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

bank_account_bic

bic

bank-account ({ })

bank_account_iban

iban

bank-account ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

descriptor

descriptor

payment ({ })

order_number

order-number

payment ({ })

locale

locale

payment ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

Response-Only Fields
{
  "api-id" : "string",
  "parent-transaction-id" : "string",
  "transaction-state" : "string",
  "transaction-id" : "string",
  "completion-time-stamp" : "2018-03-23T10:41:34",
  "statuses" : {
    "status" : [ {
      "severity" : "string",
      "code" : "string",
      "description" : "string"
    } ]
  }
}
Field (NVP) Field (JSON) JSON Parent

api_id

api-id

payment ({ })

parent_transaction_id

parent-transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

status_description_n

status ([ {} ])/ severity

statuses ({ })

status_severity_n

status ([ {} ])/ code

statuses ({ })

status_code_n

status ([ {} ])/ description

statuses ({ })

paybox
General Information

This is a reference page for paybox. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find an example request for the available transaction types purchase and authorization, including field lists with short descriptions.

You need to complete these requests with your production credentials. You receive your credentials with your Wirecard contract. If you need your production credentials, contact merchant support.

Testing paybox

paybox does not offer a payment testing sandbox. You need to test transactions with your production credentials.

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

For response verification examples, see the WPP Security section.

About paybox
paybox logo

paybox is an Austrian mobile payment provider for mobile payments in Austria. Consumers with a bank account in Austria, Switzerland or the European Economic Area and a valid contract with an Austrian mobile phone provider can set up a direct debit agreement with paybox. Using their mobile phone, they can pay in (online) shops, at (ticket) vending machines, for mobile parking, …​

Countries and Currencies

paybox can be used by consumers with a bank account in Austria, Switzerland or the European Economic Area and a valid contract with an Austrian mobile phone provider.

As paybox is an Austrian payment method, the only available payment currency for consumers is EUR.

Two transaction types are available for paybox:

Transaction Type purchase

A purchase transaction immediately transfers the order amount from the consumer’s account to the merchant’s account.

For a successful purchase transaction:

  1. Create a payment session (initial purchase request).

  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. You need to adapt the field values to your system.

API Endpoint Production/Live

Please contact merchant support for your production credentials. You must use these credentials for test purposes.

Request Headers

Authorization

needs to be formatted as: "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)
{
    "payment":{
        "merchant-account-id":{
            "value":"your-custom-MAID-..."
        },
        "request-id":"{{$guid}}",
        "transaction-type":"purchase",
        "requested-amount":{
            "value":10.1,
            "currency":"EUR"
        },
        "account-holder":{
            "phone":"+436641234567"
        },
        "payment-methods":{
            "payment-method":[
               {
               "name":"paybox"
                }
            ]
        },
        "order-number": "7171456",
        "descriptor": "Here are the details to your payment. Thank you for shopping!",
        "notifications": {
            "notification": [
                {
                "url":"https://example.com/ipn.php"
                }
            ]
        },
        "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"
    }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

required

36

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

required

64

A unique identifier assigned by the merchant to each request. Used when searching for or referencing it later.

You may enter any request ID that has never been used before.

As the request ID must be unique, {{$guid}} serves as a placeholder; e.g. Postman uses it to generate a random request-id for testing.

Allowed characters: [a-zA-Z0-9-_]

transaction-type

String

required

n/a

The requested transaction type.

Available transaction types for paybox:

  • authorization

  • purchase

requested-amount

value

Numeric

required

9.2

The full amount that is requested/contested in a transaction. 2 decimals digits allowed.

currency

String

required

3

The currency of the requested/contested transaction amount. For paybox payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

account-holder

phone

String

required

24

The phone number of the account holder (= consumer). Has to be a valid Austrian mobile phone number starting with +43.

payment-methods

payment-method

name

String

required

256

The name of the payment method used for the transaction, i.e. paybox.

order-number

String

optional

40

Merchant-side order number.

descriptor

String

optional

60

The descriptor is the text representing an order on the bank statement issued to your consumer by their bank. It provides information for the consumer, as it associates a specific debit on the consumer’s account to a specific purchase in your shop.

notification

url

String

optional

256

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

required

2000

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

2000

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

2000

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

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

payment-redirect-url

String

The URL which redirects to the payment form (hosted by paybox). 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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
    "payment" : {
        "merchant-account-id" : {
            "value" : "your-custom-MAID-..."
        },
        "request-id" : "66b62159-691f-40e3-8411-24c854bb0f8b",
        "account-holder" : {
            "phone" : "+436641234567"
        },
        "transaction-type" : "purchase",
        "parent-transaction-id" : "8d2ec658-d234-44cb-b557-791489e8464f",
        "payment-methods" : {
            "payment-method" : [ {
                "name" : "paybox"
            } ]
        },
        "transaction-state" : "success",
        "transaction-id" : "1f806091-5ab1-4832-8ccf-64232f1a7677",
        "completion-time-stamp" : "2018-09-26T05:54:20",
        "requested-amount" : {
            "currency" : "EUR",
            "value" : 10.100000
        },
        "statuses" : {
            "status" : [ {
                "description" : "The resource was successfully created.",
                "severity" : "information",
                "code" : "201.0000"
            } ]
        },
        "api-id" : "wpp",
        "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"
    }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

account-holder

phone

String

The phone number of the account holder (= consumer).

transaction-type

String

The requested transaction type, i.e. purchase.

parent-transaction-id

String

The ID of the transaction being referenced as a parent. As a purchase transaction is internally split into sub-transactions, the parent transaction ID serves to link these sub-transactions.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction, i.e. paybox.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

Date

The UTC/ISO time-stamp documenting the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

requested-amount

value

Numeric

The full amount that was requested/contested in the transaction.

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

statuses

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

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

Transaction Type authorization

For a successful authorization transaction:

  1. Create an authorization session (initial authorization request).

  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. You need to adapt the field values to your system.

API Endpoint Production/Live

Please contact merchant support for your production credentials. You must use these credentials for test purposes.

Request Headers

Authorization

needs to be formatted as: "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 an authorization Request
{
    "payment":{
        "merchant-account-id":{
            "value":"your-custom-MAID-..."
        },
        "request-id":"{{$guid}}",
        "transaction-type":"authorization",
        "requested-amount":{
            "value":10.1,
            "currency":"EUR"
        },
        "account-holder":{
            "phone":"+436641234567"
        },
        "payment-methods":{
            "payment-method":[
               {
               "name":"paybox"
                }
            ]
        },
        "order-number": "7171456",
        "descriptor": "Here are the details to your payment. Thank you for shopping!",
        "notifications": {
            "notification": [
                {
                "url": "https://example.com/ipn.php"
                }
            ]
        },
        "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"
    }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

required

36

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

required

64

A unique identifier assigned by the merchant to each request. Used when searching for or referencing it later.

You may enter any request ID that has never been used before.

As the request ID must be unique, {{$guid}} serves as a placeholder; e.g. Postman uses it to generate a random request-id for testing.

Allowed characters: [a-zA-Z0-9-_]

transaction-type

String

required

n/a

The requested transaction type.

Available transaction types for paybox:

  • authorization

  • purchase

requested-amount

value

Numeric

required

9.2

The full amount that is requested/contested in a transaction. 2 decimals digits allowed.

currency

String

required

3

The currency of the requested/contested transaction amount. For paybox payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

account-holder

phone

String

required

24

The phone number of the account holder (= consumer). Has to be a valid Austrian mobile phone number starting with +43.

payment-methods

payment-method

name

String

required

256

The name of the payment method used for the transaction, i.e. paybox.

order-number

String

optional

40

Merchant-side order number.

descriptor

String

optional

60

The descriptor is the text representing an order on the bank statement issued to your consumer by their bank. It provides information for the consumer, as it associates a specific debit on the consumer’s account to a specific purchase in your shop.

notification

url

String

optional

256

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

required

2000

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

2000

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

2000

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

2. Redirect the Consumer to the Payment Page (Sample Response URL)

The response to this initial authorization request is the  payment-redirect-url. Proceed with step 2 in a similar way as described for purchase.

3. Parse and Process the authorization Response (Decoded Payment Response)
{
    "payment" : {
        "merchant-account-id" : {
            "value" : "your-custom-MAID-..."
        },
        "request-id" : "66b62159-691f-40e3-8411-24c854bb0f8b",
        "account-holder":{
            "phone":"+436641234567"
        },
        "transaction-type" : "authorization",
        "parent-transaction-id" : "8d2ec658-d234-44cb-b557-791489e8464f",
        "payment-methods" : {
            "payment-method" : [ {
                "name" : "paybox"
            } ]
        },
        "transaction-state" : "success",
        "transaction-id" : "The-transaction-id-received-here-is-the-parent-transaction-id-of-the-following-capture-authorization",
        "completion-time-stamp" : "2018-09-26T05:54:20",
        "requested-amount" : {
            "currency" : "EUR",
            "value" : 10.100000
        },
        "statuses" : {
            "status" : [ {
                "description" : "The resource was successfully created.",
                "severity" : "information",
                "code" : "201.0000"
            } ]
        },
        "api-id" : "wpp",
        "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"
    }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

account-holder

phone

String

The phone number of the account holder (= consumer).

transaction-type

String

The requested transaction type authorization.

parent-transaction-id

String

The ID of the transaction being referenced as a parent. As a purchase transaction is internally split into sub-transactions, the parent transaction ID serves to link these sub-transactions.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction: paybox.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

DateTime

The UTC/ISO time-stamp documenting the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

requested-amount

value

Numeric

The full amount that was requested/contested in the transaction.

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

statuses

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

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

How to proceed after an authorization

To transfer money, the authorized amount has to be captured. WPP does not support capturing. However, you can capture an authorization using the REST API,

if

  • the authorization was successful AND has not yet been captured AND has not been voided (which can also be done using the REST API).

  • you provide the parent-transaction-id: This is the transaction-id of the preceding authorization. You can gather it from the response to a successful authorization.

Click the REST API paybox specification for details.

Transaction Type refund

Basically, paybox with WPP supports purchase and authorization only. For refunds, use the REST API.

You must provide the necessary data:

  • parent-transaction-id: This is the transaction ID of the preceding debit. You can gather it from the response to a successful debit.

  • amount (can be either the total amount for refunding the full amount, or a partial amount for a partial refund).

Click the REST API paybox specification for details.

JSON/NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for paybox Requests
{
    "payment" : {
          "merchant-account-id" : {
                "value" : "string"
          },
          "request-id" : "string",
          "transaction-type" : "string",
          "requested-amount" : {
                "value" : 0,
                "currency" : "string"
          },
          "account-holder" : {
                "phone" : "string"
          },
          "payment-methods" : {
                "payment-method" : [
                   {
                   "name" : "string"
                   }
                ]
          },
          "order-number": "string",
          "descriptor": "string",
          "success-redirect-url" : "string",
          "cancel-redirect-url" : "string",
          "fail-redirect-url" : "string"
     }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

phone

phone

account-holder ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

order_number

order-number

payment ({ })

descriptor

descriptor

payment ({ })

success_redirect_url

success-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

Response-Only Fields
{
    "payment" : {
        "transaction-state" : "string",
        "transaction-id" : "string",
        "completion-time-stamp" : "date",
        "api-id" : "string",
        "statuses" : {
            "status" : [ {
                "description" : "string",
                "severity" : "string",
                "code" : "string"
            } ]
        }
    }
}
Field (NVP) Field (JSON) JSON Parent

transaction_id

transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

api_id

api-id

payment ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

PayPal
General Information

This is a reference page for PayPal. Here you’ll find all the information necessary for integrating this payment method in your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for debit, authorization, authorization-only and order,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact our merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About PayPal
PayPal Logo

PayPal is a world wide online payment system which supports online money transfers and allows consumers to make and accept payments without having to share their financial information with each specific merchant (PayPal handles the transfer).

Test Credentials

Test credentials for transaction types debit, authorization, authorization-only and order

URL(s) Endpoints

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

Merchant Account ID (MAID)

9abf05c1-c266-46ae-8eac-7f87ca97af28

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

5fca2a83-89ca-4f9e-8cf7-4ca74a02773f

PayPal Login Credentials

Email

buyer@wirecard.com

Password

Einstein35

Merchant’s Test Store Screenshot
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the customer to the payment page (initial response URL).

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

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

Endpoint for PayPal transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the PayPal payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API PayPal specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "requested-amount": {
      "currency": "EUR",
      "value": "1.00"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "paypal"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to paypal.

2. Redirect the Customer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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 customer to payment-redirect-url (or render it in an iframe depending on your integration method).

The customers are redirected to the payment form. There they enter their data and submit the form to confirm the payment. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The customer canceled the payment before/after submission (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 payment response in the statuses object. Canceled payments are returned as failed, but the status description indicates it was canceled.

In any case (unless the customer 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)*
{
  "api-id": "up3-wpp",
  "parent-transaction-id": "3f792a90-3331-45fe-96ce-3961ff69edc1",
  "shipping": {
    "last-name": "Puente",
    "first-name": "Tito",
    "address": {
      "street1": "C/ La Cochibamba 3",
      "city": "Madrid",
      "postal-code": "28001",
      "country": "ES"
    }
  },
  "wallet": {
    "account-id": "ZNKTXUBNSQE2Y"
  },
  "payment-methods": {
    "payment-method": [
      {
        "name": "paypal"
      }
    ]
  },
  "transaction-id": "b026a9bc-618f-4750-9a00-4fb475c27ce1",
  "completion-time-stamp": "2018-03-21T17:22:25",
  "requested-amount": {
    "currency": "EUR",
    "value": 1
  },
  "statuses": {
    "status": [
      {
        "description": "The resource was successfully created.",
        "provider-transaction-id": "1PK89494VW075423R",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "instrument-country": "DE",
  "request-id": "12eb44db-4d75-4cf4-bd52-9c047e024eee",
  "merchant-account-id": {
    "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
  },
  "transaction-state": "success",
  "transaction-type": "debit",
  "account-holder": {
    "last-name": "Puente",
    "email": "tito.puente@example.com",
    "first-name": "Tito"
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

shipping

last-name

String

The last name of the shipping address.

first-name

String

The first name of the shipping address.

address

street1

String

The first line of the shipping address street.

city

String

The city of the shipping address.

postal-code

String

The postal code/ZIP of the shipping address.

country

String

The country ID part of the shipping address.

account-id

String

Account holder’s PayPal Wallet identifier.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

description

String

The description of the transaction status message.

provider-transaction-id

String

A unique transaction identifier generated by the provider.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

instrument-country

String

Payment origin country.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

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

transaction-state

String

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.

transaction-type

String

The requested transaction type.

account-holder

last-name

String

The last name of the account holder.

email

String

Account holder’s email address.

first-name

String

The first name of the account holder.

Transaction Type authorization

An authorization transaction places the account holder’s funds on hold, pending future capture, re-authorization or void transaction.

As with other referenceable transaction types, you can use WPP only to create the authorization itself. To capture or register additional transactions referencing it, you need to use our REST API

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the customer to the payment page (initial response URL).

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

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

Endpoint for PayPal transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the PayPal payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API PayPal specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization",
    "requested-amount": {
      "value": 10.1,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "paypal"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to paypal.

2. Redirect the Customer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id": "up3-wpp",
  "parent-transaction-id": "b675f63c-2df0-420f-a081-7c6b4967c992",
  "shipping": {
    "last-name": "Puente",
    "first-name": "Tito",
    "address": {
      "street1": "C/ La Cochibamba 3",
      "city": "Madrid",
      "postal-code": "28001",
      "country": "ES"
    }
  },
  "wallet": {
    "account-id": "ZNKTXUBNSQE2Y"
  },
  "payment-methods": {
    "payment-method": [
      {
        "name": "paypal"
      }
    ]
  },
  "transaction-id": "ff0b8cf4-6fd3-4318-9e54-e8c035add938",
  "completion-time-stamp": "2018-03-21T16:49:30",
  "requested-amount": {
    "currency": "EUR",
    "value": 10.1
  },
  "statuses": {
    "status": [
      {
        "description": "The resource was successfully created.",
        "provider-transaction-id": "86M17436478175249",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "instrument-country": "DE",
  "request-id": "2502cae8-91b6-4dac-8f60-6e9c6ef0cbe6",
  "merchant-account-id": {
    "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
  },
  "transaction-state": "success",
  "transaction-type": "authorization",
  "account-holder": {
    "last-name": "Puente",
    "email": "tito.puente@example.com",
    "first-name": "Tito"
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

shipping

last-name

String

The last name of the shipping address.

first-name

String

The first name of the shipping address.

address

street1

String

The first line of the shipping address street.

city

String

The city of the shipping address.

postal-code

String

The postal code/ZIP of the shipping address.

country

String

The country ID part of the shipping address.

account-id

String

Account holder’s PayPal Wallet identifier.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

description

String

The description of the transaction status message.

provider-transaction-id

String

A unique transaction identifier generated by the provider.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

instrument-country

String

Payment origin country.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

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

transaction-state

String

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.

transaction-type

String

The requested transaction type.

account-holder

last-name

String

The last name of the account holder.

email

String

Account holder’s email address.

first-name

String

The first name of the account holder.

Transaction Type authorization-only

An authorization-only transaction creates a PayPal billing agreement between the merchant and account holder, obtaining authorization for pre-approved payments. 

This transaction type requires specific fields in the request:

  • periodic-type, set to value recurring or installment.

  • sequence-type, set to value first.

  • The value field of requested-amount set to zero.

The periodic and sequence information indicates that this is the first transaction in a series. The zero transaction amount is required because this is only an agreement for future transactions, not a charge. The provider-transaction-reference-id field returned in the response contains the ID used to reference the billing agreement.

As with other referenceable transactions, you can use WPP only to create this initial billing agreement. For all following transactions (i.e. capturing the authorization), you need to use our REST API.

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the customer to the payment page (initial response URL).

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

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

Endpoint for PayPal transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the PayPal payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API PayPal specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "authorization-only",
    "requested-amount": {
      "currency": "EUR",
      "value": "0"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "paypal"
        }
      ]
    },
    "periodic": {
      "periodic-type": "recurring",
      "sequence-type": "first"
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimals allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used for the transaction. Set this value to paypal.

periodic

periodic-type

String

Conditional

9

Required for recurring transactions. Indicates if (and how) payment occurs more than once.

sequence-type

String

Conditional

9

Required for recurring transactions. Indicates the phase of a recurring transaction.

2. Redirect the Customer to the Payment Page (Initial Response URL)
{
"payment-redirect-url" : "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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.

3. Parse and Process the Payment Response (Decoded Payment Response)
 {
  "api-id" : "up3-wpp",
  "parent-transaction-id" : "40760e14-e3d4-4ceb-92a5-747258589cc6",
  "shipping" : {
    "last-name" : "Puente",
    "first-name" : "Tito",
    "address" : {
      "street1" : "C/ La Cochibamba 3",
      "city" : "Madrid",
      "postal-code" : "28001",
      "country" : "ES"
    }
  },
  "wallet" : {
    "account-id" : "ZNKTXUBNSQE2Y"
  },
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "paypal"
    } ]
  },
  "periodic" : {
    "periodic-type" : "recurring",
    "sequence-type" : "first"
  },
  "transaction-id" : "e3a29b72-9bb4-41de-ac57-438e4eff6c6b",
  "completion-time-stamp" : "2018-03-21T17:16:52",
  "requested-amount" : {
    "currency" : "EUR",
    "value" : 0.000000
  },
  "statuses" : {
    "status" : [ {
      "description" : "The resource was successfully created.",
      "severity" : "information",
      "code" : "201.0000"
    } ]
  },
  "provider-transaction-reference-id" : "B-9W832714HC860770E",
  "instrument-country" : "DE",
  "request-id" : "d6958186-8572-4795-863b-95b2337277de",
  "merchant-account-id" : {
    "value" : "9abf05c1-c266-46ae-8eac-7f87ca97af28"
  },
  "transaction-state" : "success",
  "transaction-type" : "authorization-only",
  "account-holder" : {
    "last-name" : "Puente",
    "email" : "tito.puente@example.com",
    "first-name" : "Tito"
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

shipping

last-name

String

The last name of the shipping address.

first-name

String

The first name of the shipping address.

address

street1

String

The first line of the shipping address street.

city

String

The city of the shipping address.

postal-code

String

The postal code/ZIP of the shipping address.

country

String

The country ID part of the shipping address.

account-id

String

Account holder’s PayPal wallet identifier.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction.

periodic

periodic-type

String

Indicates if (and how) payment occurs more than once.

sequence-type

String

Indicates the phase of a recurring transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

description

String

The description of the transaction status message.

provider-transaction-id

String

A unique transaction identifier generated by the provider.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

instrument-country

String

Payment origin country.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

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

transaction-state

String

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.

transaction-type

String

The requested transaction type.

account-holder

last-name

String

The last name of the account holder.

email

String

Account holder’s email address.

first-name

String

The first name of the account holder.

Transaction Type order

order is a PayPal-specific transaction type, which indicates that the buyer has consented to the purchase but does not place the funds on hold. For detailed information on how it works, see its  REST API specification.

After merchant creates an order, they can place multiple authorizations upon it to place funds on hold until ready to capture. This transaction is primarily for situations where items are not available for shipment immediately after the order is placed, e.g.:

  • when a merchant ships items from multiple distribution centers and needs separate authorizations for each shipment,

  • delayed shipping on items that are not in stock.

As with other referenceable transaction types, you can use WPP only to create an order transaction. To register an additional authorization to capture it, you need to use our REST API.

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the customer to the payment page (initial response URL).

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

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

Endpoint for PayPal transactions.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the PayPal payment form.

After the merchant creates an order, they can place multiple authorizations upon it to place funds on hold until ready to capture.

Merchants often use this technique to accept orders for items that are not available for shipment when the order is placed. For example, when a merchant ships items from multiple distribution centers and needs separate authorizations for each shipment. Another example would be delayed shipping on items that are not in stock.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API PayPal specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "order",
    "requested-amount": {
      "currency": "EUR",
      "value": "1.00"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "paypal"
        }
      ]
    }
  }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to paypal.

2. Redirect the Customer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "api-id": "up3-wpp",
  "parent-transaction-id": "6998700b-a573-4a39-b8e0-c0da1008c468",
  "shipping": {
    "last-name": "Puente",
    "first-name": "Tito",
    "address": {
      "street1": "C/ La Cochibamba 3",
      "city": "Madrid",
      "postal-code": "28001",
      "country": "ES"
    }
  },
  "wallet": {
    "account-id": "ZNKTXUBNSQE2Y"
  },
  "payment-methods": {
    "payment-method": [
      {
        "name": "paypal"
      }
    ]
  },
  "transaction-id": "59b94534-edd3-4668-9c9d-567be60e4622",
  "completion-time-stamp": "2018-03-21T17:24:00",
  "requested-amount": {
    "currency": "EUR",
    "value": 1
  },
  "statuses": {
    "status": [
      {
        "description": "The resource was successfully created.",
        "provider-transaction-id": "O-70W17875FY9058845",
        "severity": "information",
        "code": "201.0000"
      }
    ]
  },
  "custom-fields": {},
  "instrument-country": "DE",
  "request-id": "649e2792-5af4-45c8-909c-7333b0a8f43c",
  "merchant-account-id": {
    "value": "9abf05c1-c266-46ae-8eac-7f87ca97af28"
  },
  "transaction-state": "success",
  "transaction-type": "order",
  "account-holder": {
    "last-name": "Puente",
    "email": "tito.puente@example.com",
    "first-name": "Tito"
  }
}
Field (JSON) Data Type Description

api-id

String

Identifier of the currently used API.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

shipping

last-name

String

The last name of the shipping address.

first-name

String

The first name of the shipping address.

address

street1

String

The first line of the shipping address street.

city

String

The city of the shipping address.

postal-code

String

The postal code/ZIP of the shipping address.

country

String

The country ID part of the shipping address.

wallet

account-id

String

Account holder’s PayPal wallet identifier.

payment-methods

payment-method

name

String

The name of the payment method used for the transaction.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

statuses

status

description

String

The description of the transaction status message.

provider-transaction-id

String

A unique transaction identifier generated by the provider.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

instrument-country

String

Payment origin country.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

merchant-account-id

value

String

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

transaction-state

String

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.

transaction-type

String

The requested transaction type.

account-holder

last-name

String

The last name of the account holder.

email

String

Account holder’s email address.

first-name

String

The first name of the account holder.

Post-Processing Operations

WPP is best used to deal with 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 PayPal specification for details on PayPal specific post processing operations.

There are multiple post processing operations available for PayPal:

  • capture operations for both authorization and authorization-only

  • recurring transactions

  • void transactions

  • refunds

For examples and more information, see the REST API PayPal specification.

JSON/NVP Field Reference

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure of a PayPal Request
{
  "payment": {
    "merchant-account-id": {
      "value": "string"
    },
    "request-id": "string",
    "transaction-type": "string",
    "requested-amount": {
      "currency": "string",
      "value": 0
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "string"
        }
      ]
    },
    "account-holder": {
      "address": {
        "city": "string",
        "country": "string",
        "postal-code": "string",
        "state": "string",
        "street1": "string",
        "street2": "string"
      },
      "email": "string",
      "first-name": "string",
      "last-name": "string",
      "phone": "string"
    },
    "shipping": {
      "address": {
        "city": "string",
        "country": "string",
        "postal-code": "string",
        "state": "string",
        "street1": "string",
        "street2": "string"
      },
      "first-name": "string",
      "last-name": "string",
      "phone": "string"
    },
    "descriptor": "string",
    "order-number": "string",
    "periodic": {
      "periodic-type": "string",
      "sequence-type": "string"
    },
    "success-redirect-url": "string",
    "fail-redirect-url": "string",
    "cancel-redirect-url": "string"
  }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount_currency

currency

requested-amount ({ })

requested_amount

value

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

city

address ({ })/ city

account-holder ({ })

country

address ({ })/ country

account-holder ({ })

postal_code

address ({ })/ postal-code

account-holder ({ })

state

address ({ })/ state

account-holder ({ })

street1

address ({ })/ street1

account-holder ({ })

street2

address ({ })/ street2

account-holder ({ })

email

email

account-holder ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

phone

phone

account-holder ({ })

shipping_city

address ({ })/ city

shipping ({ })

shipping_country

address ({ })/ country

shipping ({ })

shipping_postal_code

address ({ })/ postal-code

shipping ({ })

shipping_state

address ({ })/ state

shipping ({ })

shipping_street1

address ({ })/ street1

shipping ({ })

shipping_street2

address ({ })/ street2

shipping ({ })

shipping_first_name

first-name

shipping ({ })

shipping_last_name

last-name

shipping ({ })

shipping_phone

phone

shipping ({ })

descriptor

descriptor

payment ({ })

order_number

order-number

payment ({ })

periodic_type

periodic-type

periodic ({ })

sequence_type

sequence-type

periodic ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

JSON Structure of a PayPal Response
{
  "payment": {
    "api-id": "string",
    "wallet": {
      "account-id": "string"
    },
    "transaction-id": "string",
    "completion-time-stamp": "2019-02-21T09:38:57.645Z",
    "statuses": {
      "status": [
        {
          "code": "string",
          "description": "string",
          "severity": "string"
        }
      ]
    },
    "provider-transaction-reference-id": "string",
    "instrument-country": "string",
    "transaction-state": "string"
  }
}
Field (NVP) Field (JSON) JSON Parent

api_id

api-id

payment ({ })

wallet_account_id

account-id

wallet ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

status_code_n

status ([ { } ])/ code

statuses ({ })

provider_transaction_id_n

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

statuses ({ })

status_description_n

status ([ { } ])/ description

statuses ({ })

status_severity_n

status ([ { } ])/ severity

statuses ({ })

provider_transaction_reference_id

provider-transaction-reference-id

payment ({ })

instrument_country

instrument-country

payment ({ })

transaction_state

transaction-state

payment ({ })

paysafecard
General Information

This is a reference page for paysafecard. Here you find all the information necessary for integrating this payment method in your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for debit, authorization and capture-authorization including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact our merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About paysafecard
paysafecard logo

paysafecard is a well-known prepaid electronic payment method for mainly online shopping e.g. in gaming, social media & communities and music, film & entertainment industries. paysafecard is currently available in many countries and languages all over the world. It offers a broad selection of currencies to choose from.

Consumers either purchase a paysafecard voucher which contains a 16-digit PIN from sales outlets or from authorized online PIN shops, or alternatively, create a my paysafecard account defining their personal username and password.

paysafecard PINs can be used multiple times for paying in online shops or for topping up the my paysafecard account.

Using my paysafecard during the payment process in an online shop, you do not have to reenter the PIN again, only username and password are required.

Paying with paysafecard, the consumer enters the 16 digit number and the amount tendered is deducted from the paysafecard balance. Thus, the same PIN code can be used multiple times. For larger sums, it is possible to combine various paysafecard PINs. Combining PINs also allows consumers to use up any remaining credit on a paysafecard PIN. The current balance of each paysafecard as well as its transaction history and production date can be viewed at the official paysafecard site by entering the respective 16 digit PIN code.

Payments for goods or services other than EUR are converted into EUR at the conversion rate at the time of purchase. The conversion fee varies depending on the original currency and end currency and it varies from country to country. The currency conversion rates for foreign currencies are always available on the paysafecard web site.

Test Credentials

Test credentials for transaction types debit, authorization and capture-authorization.

URI (Endpoint)

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

Merchant Account ID (MAID)

4c0de18e-4c20-40a7-a5d8-5178f0fe95bd

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

bb1f2975-827b-4aa8-bec6-405191d85fa5

Test Credentials for paysafecard Sandbox

16-digit PIN

3105 6626 4830 5874

Countries and Currencies

paysafecard can be used in the following countries and with the listed currencies:

Countries

Europe

Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Finland, France, Georgia, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Montenegro, The Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden, Switzerland, Turkey, UK

North & South America

Argentina, Brazil, Canada, Mexico, Peru, Uruguay, USA

Middle East

Kuwait, Saudi Arabia, UAE

Oceania

Australia, New Zealand

Africa

Egypt

Currencies

AED, ARS, AUD, BRL, CAD, CHF, CZK, DKK, EGP, EUR, GBP, GEL, HRK, HUF, KWD, MXN, NOK, NZD, PEN, PLN, RON, SAR, SEK, TRY, USD, UYU

Transaction Type debit

A debit transaction charges the consumer’s paysafecard account with the specified amount and transfers it immediately.

For a successful debit transaction:

  1. Create a payment session (initial debit request).

  2. Redirect the consumer to the payment page (initial response URL).

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

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

Endpoint for paysafecard payments.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

1. Create a Payment Session (Initial Request)
{
    "payment":{
        "merchant-account-id":{
            "value":"4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id":"{{$guid}}",
        "transaction-type":"debit",
        "requested-amount":{
            "value":10.1,
            "currency":"EUR"
        },
        "account-holder":{
            "merchant-crm-id":"A123456789"
        },
        "payment-methods":{
            "payment-method":[
               {
               "name":"paysafecard"
                }
            ]
        },
        "notifications": {
            "notification": [
                {
                "url": "https://yourdomain.com/ipn.php"
                }
            ]
        },
        "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"
    }
}
Field (JSON) Data Type Required/Optional 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 by the merchant to each request. Used when searching for or referencing it later.

You may enter any request-id that has never been used before.

As the request ID must be unique, {{$guid}} serves as a placeholder; Postman uses it to generate a random request-id for testing.

Allowed characters: [a-z0-9-_]

transaction-type

String

Required

n/a

The requested transaction type, i.e. debit.

Available transaction types for paysafecard:

  • authorization

  • capture-authorization

  • debit

requested-amount

value

Numeric

Required

9.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For paysafecard payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

account-holder

merchant-crm-id

String

Required

64

Unique ID identifying the consumer of your online shop, e.g. from your CRM system.
The parameter must not be a human readable email address. However, if an email address is used, you have to hash it beforehand.

payment-method

name

String

required

256

The name of the payment method used for the transaction, i.e. paysafecard

notification-url

String

Optional

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

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

payment-redirect-url

String

The URL which redirects to the payment form (hosted by paysafecard). 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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
    "payment" : {
        "merchant-account-id" : {
            "value" : "4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id" : "66b62159-691f-40e3-8411-24c854bb0f8b",
        "account-holder" : {
            "merchant-crm-id" : "A123456789"
        },
        "transaction-type" : "debit",
        "parent-transaction-id" : "8d2ec658-d234-44cb-b557-791489e8464f",
        "payment-methods" : {
            "payment-method" : [ {
                "name" : "paysafecard"
            } ]
        },
        "transaction-state" : "success",
        "transaction-id" : "1f806091-5ab1-4832-8ccf-64232f1a7677",
        "completion-time-stamp" : "2018-09-26T05:54:20",
        "requested-amount" : {
            "currency" : "EUR",
            "value" : 10.100000
        },
        "statuses" : {
            "status" : [ {
                "description" : "The resource was successfully created.",
                "severity" : "information",
                "code" : "201.0000"
            } ]
        },
        "api-id" : "wpp",
        "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"
    }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

account-holder

merchant-crm-id

String

Unique ID identifying the consumer of your online shop, e.g. from your CRM system.

transaction-type

String

The requested transaction type, here: debit.

parent-transaction-id

String

The ID of the transaction being referenced as a parent. As a debit transaction is internally split into sub-transactions, the parent-transaction-id serves to link these sub-transactions.

payment-method

name

String

The name of the payment method used for the transaction, here: paysafecard.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

Date

The UTC/ISO time-stamp documenting the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

requested-amount

value

Numeric

The full amount that was requested/contested in the transaction.

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.
See the complete list of status codes and descriptions.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

fail-redirect-url

String

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

Transaction Type authorization

An authorization

  • reserves funds on a consumer’s paysafecard account (e.g. until the merchant ships/delivers the goods/services).

  • does not trigger money transfer.  

To transfer money, the amount has to be captured with the transaction type capture-authorization.

For a successful authorization transaction

  1. Create an authorization session (initial authorization request).

  2. Redirect the consumer to the payment page (initial response URL).

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

Endpoint for paysafecard payments.

Initial Request

The initial request creates the payment session. If it’s successful, you receive a URL as a response which redirects to the paysafecard payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

1. Create a Payment Session (Initial Request)
{
    "payment":{
        "merchant-account-id":{
            "value":"4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id":"{{$guid}}",
        "transaction-type":"authorization",
        "requested-amount":{
            "value":10.1,
            "currency":"EUR"
        },
        "account-holder":{
            "merchant-crm-id":"A123456789"
        },
        "payment-methods":{
            "payment-method":[
               {
               "name":"paysafecard"
                }
            ]
        },
        "notifications": {
            "notification": [
                {
                "url": "https://yourdomain.com/ipn.php"
                }
            ]
        },
        "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"
    }
}
Field (JSON) Data Type Required/Optional 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 by the merchant to each request. Used when searching for or referencing it later.

You may enter any request-id that has never been used before.

As the request ID must be unique, {{$guid}} serves as a placeholder; Postman uses it to generate a random request-id for testing.

Allowed characters: [a-z0-9-_]

transaction-type

String

Required

n/a

The requested transaction type, i.e. authorization.

Available transaction types for paysafecard:

  • authorization

  • capture-authorization

  • debit

requested-amount

value

Numeric

Required

9.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For paysafecard payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

account-holder

merchant-crm-id

String

Required

64

Unique ID identifying the consumer of your online shop, e.g. from your CRM system.
The parameter must not be a human readable email address. However, if an email address is used, you have to hash it beforehand.

payment-method

name

String

required

256

The name of the payment method used for the transaction, i.e. paysafecard

notification-url

String

Optional

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

2. Redirect the Consumer to the Payment Page (Sample Response URL)

The response to this initial authorization request is the  payment-redirect-url. Proceed with step 2 in a similar way as described for debit.

3. Parse and Process the authorization Response (Decoded Payment Response)
{
    "payment" : {
        "merchant-account-id" : {
            "value" : "4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id" : "66b62159-691f-40e3-8411-24c854bb0f8b",
        "account-holder" : {
            "merchant-crm-id" : "A123456789"
        },
        "transaction-type" : "authorization",
        "parent-transaction-id" : "8d2ec658-d234-44cb-b557-791489e8464f",
        "payment-methods" : {
            "payment-method" : [ {
                "name" : "paysafecard"
            } ]
        },
        "transaction-state" : "success",
        "transaction-id" : "The-transaction-id-received-here-is-the-parent-transaction-id-of-the-following-capture-authorization",
        "completion-time-stamp" : "2018-09-26T05:54:20",
        "requested-amount" : {
            "currency" : "EUR",
            "value" : 10.100000
        },
        "statuses" : {
            "status" : [ {
                "description" : "The resource was successfully created.",
                "severity" : "information",
                "code" : "201.0000"
            } ]
        },
        "api-id" : "wpp",
        "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"
    }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

account-holder

merchant-crm-id

String

Unique ID identifying the consumer of your online shop, e.g. from your CRM system. The parameter must not be a human readable email address. However, if an email address is used, you have to hash it beforehand.

transaction-type

String

The requested transaction type, i.e. authorization.

parent-transaction-id

String

The ID of the transaction being referenced as a parent (e.g. the transaction ID of a previous internal get-url).

payment-method

name

String

The name of the payment method used for the transaction, here: paysafecard.

transaction-state

String

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.

transaction-id

String

A unique identifier assigned to every transaction. Used when searching for or referencing it later.
The transaction ID of an authorization is the parent transaction ID of the following capture-authorization request.

completion-time-stamp

Date

The UTC/ISO time-stamp documenting the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

requested-amount

value

Numeric

The full amount that was requested/contested in the transaction.

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

status

description

String

The description of the transaction status message. See the complete list of status codes and descriptions.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.
See the complete list of status codes and descriptions.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

fail-redirect-url

String

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

Transaction Type capture-authorization

A capture-authorization transfers funds reserved by a prior authorization  request from the consumer’s account. You can refer to a preceding authorization with the field parent-transaction-id. The transaction-id from an authorization response is the parent-transaction-id of the following capture-authorization request.

Endpoint for paysafecard payments.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the paysafecard payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

capture-authorization (request)
{
    "payment": {
        "merchant-account-id":{
            "value":"4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id":"{{$guid}}",
        "transaction-type":"capture-authorization",
        "parent-transaction-id": "enter-the-transaction-id-of-the-preceding-authorization",
        "requested-amount":{
            "value":10.1,
            "currency":"EUR"
        },
        "payment-methods":{
            "payment-method":[
                {
                   "name":"paysafecard"
                }
            ]
        },
        "account-holder":{
            "merchant-crm-id":"A123456789"
        },
        "notifications": {
            "notification": [
                {
                "url": "https://yourdomain.com/ipn.php"
                }
            ]
        },
        "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"
   }
}
Field (JSON) Data Type Required/Optional 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 by the merchant to each request. Used when searching for or referencing it later.

You may enter any request-id that has never been used before.

As the request ID must be unique, {{$guid}} serves as a placeholder; Postman uses it to generate a random request-id for testing.

Allowed characters: [a-z0-9-_]

transaction-type

String

Required

n/a

The requested transaction type, i.e. authorization.

Available transaction types for paysafecard:

  • authorization

  • capture-authorization

  • debit

parent-transaction-id

String

Required

36

The ID of the transaction being referenced as a parent (e.g. the transaction ID of a previous internal get-url).

requested-amount

value

Numeric

Required

9.2

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For paysafecard payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

account-holder

merchant-crm-id

String

Required

64

Unique ID identifying the consumer of your online shop, e.g. from your CRM system.
The parameter must not be a human readable email address. However, if an email address is used, you have to hash it beforehand.

payment-method

name

String

required

256

The name of the payment method used for the transaction, i.e. paysafecard

notification-url

String

Optional

The URL to which Wirecard Payment Gateway sends the transaction outcome.

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

capture-authorization (response)
{
    "payment": {
        "merchant-account-id": {
            "value": "4c0de18e-4c20-40a7-a5d8-5178f0fe95bd"
        },
        "request-id": "37f26cbf-f4aa-429e-9966-82d2b3cbad46",
        "account-holder": {
            "merchant-crm-id": "A123456789"
        },
        "transaction-type": "capture-authorization",
        "parent-transaction-id": "6dadad3d-3cbd-4789-8165-ffdf15752bca",
        "payment-methods": {
            "payment-method": [
                {
                    "name": "paysafecard"
                }
            ]
        },
        "transaction-state": "success",
        "transaction-id": "2a1baa9d-d29f-408c-8bed-ec38194e4e16",
        "completion-time-stamp": "2018-10-01T13:17:58",
        "requested-amount": {
            "value": 10.1,
            "currency": "EUR"
        },
        "statuses": {
            "status": [
                {
                    "code": "201.0000",
                    "description": "paysafecard:The resource was successfully created.",
                    "severity": "information"
                }
            ]
        },
        "api-id": "wpp",
        "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",
        }
    }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

account-holder

merchant-crm-id

String

Unique ID identifying the consumer of your online shop, e.g. from your CRM system. The parameter must not be a human readable email address. However, if an email address is used, you have to hash it beforehand.

transaction-type

String

The requested transaction type, i.e. capture-authorization.

parent-transaction-id

String

The ID of the transaction being referenced as a parent, i.e. the transaction ID of the preceding authorization.

payment-method

name

String

The name of the payment method used for the transaction, i.e. paysafecard.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

Date

The UTC/ISO time-stamp documenting the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss.sssZ (ISO).

requested-amount

value

Numeric

The full amount that was requested/contested in the transaction.

currency

String

The currency of the requested/contested transaction amount.

Format: 3-character abbreviation according to ISO 4217.

status

description

String

The description of the transaction status message. See the complete list of status codes and descriptions.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.
See the complete list of status codes and descriptions.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

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

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

fail-redirect-url

String

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

void-authorization

You may cancel an authorization using the REST API, if the authorization was successful and has neither been captured nor voided before.

Only the whole authorized amount may be voided.

For a void process you must provide a parent-transaction-id. This is the transaction-id of the preceding authorization. You can gather it from the response to a successful authorization.

NVP Field Reference

NVP equivalents for JSON fields (for migrating merchants).

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for paybox Requests
{    "payment":{
        "merchant-account-id":{
            "value":"string"
        },
        "request-id":"string",
        "transaction-type":"string",
        "requested-amount":{
            "value":0,
            "currency":"string"
        },
        "account-holder":{
            "merchant-crm-id":"string"
        },
        "payment-methods":{
            "payment-method":[
               {
               "name":"paysafecard"
                }
            ]
        },
        "success-redirect-url": "string",
        "cancel-redirect-url": "string",
        "fail-redirect-url": "string"
    }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

merchant_crm_id

merchant-crm-id

account-holder ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

ip_address

ip-address

payment ({ })

Response-Only Fields
{
    "payment" : {
        "transaction-state" : "string",
        "transaction-id" : "string",
        "completion-time-stamp" : "date",
        "api-id" : "string",
        "statuses" : {
            "status" : [ {
                "description" : "string",
                "severity" : "string",
                "code" : "string"
            } ]
        }
    }
}
Field (NVP) Field (JSON) JSON Parent

transaction_id

transaction-id

payment ({ })

transaction_state

transaction-state

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

api_id

api-id

payment ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

Przelewy24
General Information

This is a reference page for Przelewy24. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type debit,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About Przelewy24
Przelewy24 logo

Przelewy24 (P24) offers bank transfers and other payment methods for the Polish e-commerce sector. 80-90% of online payments in Poland happen via bank transfer, making P24 the most popular payment service in this region.

Currently, Przelewy24 cooperates with 165 banks.

Consumers select the bank of their choice. P24 redirects them to that bank’s login page. There, consumers use their bank credentials to log in, and then initialize the transaction. Upon payment confirmation, merchants and consumers receive a notification of the transaction outcome.

 

Test Credentials

Test credentials for the transaction type debit.

URI (Endpoint)

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

Merchant Account ID (MAID)

86451785-3ed0-4aa1-99b2-cc32cf54ce9a

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

fdd54ea1-cef1-449a-945c-55abc631cfdc

P24 Sandbox Credentials

Our test environment is connected to the P24 sandbox which does not require you to enter any additional data. The P24 landing page will ask you to select a bank. You will be redirected to a page that asks for payment confirmation. Upon confirmation of your test payment, P24 immediately returns you to your shop.

P24 Demoshop

 

Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for P24 transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json

1. Create a Payment Session (Initial Request)
{
    "payment": {
        "merchant-account-id": {
            "value": "86451785-3ed0-4aa1-99b2-cc32cf54ce9a"
        },
        "request-id": "{{$guid}}",
        "order-number": "123456789",
        "transaction-type": "debit",
        "requested-amount": {
            "value": "10.00",
            "currency": "PLN"
        },
        "account-holder": {
            "first-name": "Paul",
            "last-name": "Atreides",
            "email": "paul.atreides@example.com"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "p24"
                }
            ]
        },
        "country": "PL",
        "locale": "en",
        "notifications": {
            "notification": [
                {
                "url": "https://example.com/"
                }
            ]
        },
        "descriptor": "test",
        "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"
    }
}
Field (JSON) Data Type Required/Optional 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.

order-number

String

Required

64

This is the order number of the merchant. If provided, it is displayed on the P24 landing page as "Order Information".

transaction-type

String

Required

30

The requested transaction type. For P24 payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

currency

String

Required

3

The currency of the requested/contested transaction amount. For P24 payments, the currency must be set to PLN.

account-holder

first-name

String

Optional

32

The first name of the account holder.

last-name

String

Required

32

The last name of the account holder.

email

String

Required

64

The email address of the account holder.

payment-method

name

String

Required

15

The name of the payment method used. Set this value to p24.

country

String

Optional

3

The country ID of the account holder. It must be set to PL; if it is not provided, it will automatically be set to PL.

locale

String

Optional

6

With this field you can specify the language in which the P24 landing page is displayed.

Possible values:

  • pl

  • en

  • de

  • es

  • it

notification-url

String

Optional

256

The URL with which the merchant is notified about the transaction outcome.

descriptor

String

Optional

64

Describes the transaction. It is shown on the account holder’s statement along with the P24-Transaction-ID. See section Banking Statement for details on the P24-Transaction-ID.

Length and allowed characters depend on the respective consumer’s bank system and can vary. 

success-redirect-url

String

Optional

256

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

fail-redirect-url

String

Optional

256

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

cancel-redirect-url

String

Optional

256

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

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
    "payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=x_APEDQWk8g55wmeAyagobjTt5_p-pyHof8w6zJiTGI"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
    "payment" : {
        "notifications" : {
        "notification" : [
            {
            "url" : "https://example.com/"
            }
        ]
    },
    "locale" : "en",
    "parent-transaction-id" : "dc189b09-3cd9-4984-9df3-0984b5218b6c",
    "statuses" : {
        "status" : [
            {
            "description" : "The resource was successfully created.",
            "severity" : "information",
            "code" : "201.0000"
            }
        ]
    },
    "cancel-redirect-url" : "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "success-redirect-url" : "https://demoshop-test.wirecard.com/demoshop/#/success",
    "fail-redirect-url" : "https://demoshop-test.wirecard.com/demoshop/#/error",
    "account-holder" : {
        "first-name" : "Paul",
        "last-name" : "Atreides",
        "email" : "paul.atreides@example.com"
    },
    "request-id" : "85ac92ca-2f18-4af0-961c-1995cf494002",
    "transaction-id" : "2cd6a138-5dde-4efc-b196-7a75d930a1e2",
    "completion-time-stamp" : "2018-10-15T08:13:37",
    "requested-amount" : {
        "currency" : "PLN",
        "value" : 10.000000
    },
    "merchant-account-id" : {
        "value" : "86451785-3ed0-4aa1-99b2-cc32cf54ce9a"
    },
    "transaction-state" : "success",
    "transaction-type" : "debit",
    "payment-methods" : {
        "payment-method" : [
            {
            "name" : "p24"
            }
        ]
    },
    "order-number" : "123456789",
    "api-id" : "wpp",
    "descriptor" : "test",
    "country" : "PL"
    }
}
Field (JSON) Data Type Description

notification-url

String

The URL with which the merchant is notified about the transaction outcome.

locale

String

With this field you can specify the language in which the P24 landing page is displayed.

Possible values:

  • pl

  • en

  • de

  • es

  • it

parent-transaction-id

String

The ID of the transaction being referenced as a parent. As a debit transaction is internally split into sub-transactions, the parent-transaction-id serves to link these sub-transactions.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

cancel-redirect-url

String

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

success-redirect-url

String

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

fail-redirect-url

String

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

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

email

String

The email address of the account holder.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.

value

Numeric

The full amount that is requested/contested in a transaction.

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard). You receive a unique merchant account ID for each payment method.

transaction-state

String

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.

transaction-type

String

The requested transaction type. Must be debit for P24 payments.

payment-method

name

String

The name of the payment method used.

order-number

String

This is the order number of the merchant. If provided, it is displayed on the P24 landing page as "Order Information".

api-id

String

Identifier of the currently used API.

descriptor

String

Describes the transaction. It is shown on the account holder’s statement along with the P24-Transaction-ID. See section Banking Statement for details on the P24-Transaction-ID.

Length and allowed characters depend on the respective consumer’s bank system and can vary. 

country

String

The country ID of the account holder. It must be PL; if it is not provided, it will be automatically set to PL.

Transaction Type refund

Basically, P24 with WPP supports debit only. You can integrate a refund process for P24 via our REST API.

You must provide the necessary data:

  • parent-transaction-id: This is the transaction ID of the preceding debit. You can gather it from the response to a successful debit.

  • amount (can be either the total amount for refunding the full amount, or a partial amount for a partial refund).

JSON/NVP Field Reference

Here you can find the NVP equivalents for JSON fields (for migrating merchants).

JSON Structure for P24 Requests
{
    "payment": {
        "merchant-account-id": {
            "value": "string"
        },
        "request-id": "string",
        "order-number": "string",
        "transaction-type": "string",
        "requested-amount": {
            "value": "0",
            "currency": "string"
        },
        "account-holder": {
            "first-name": "string",
            "last-name": "string",
            "email": "string"
        },
        "payment-methods": {
            "payment-method": [
                {
                "name": "string"
                }
            ]
        },
        "country": "string",
        "locale": "string",
        "notifications": {
            "notification": [
                {
                "url": "string"
                }
            ]
        },
        "descriptor": "string",
        "success-redirect-url": "string",
        "cancel-redirect-url": "string",
        "fail-redirect-url": "string"
    }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

order_number

order-number

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

email

email

account-holder ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

country

country

payment ({ })

locale

locale

payment ({ })

notification-url

url

notifications ({ })

descriptor

descriptor

payment ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

Response-Only Fields
{
    "payment" : {
    "parent-transaction-id" : "string",
    "statuses" : {
        "status" : [
            {
            "description" : "string",
            "severity" : "string",
            "code" : "string"
            }
        ]
    },
    "transaction-id" : "2cd6a138-5dde-4efc-b196-7a75d930a1e2",
    "completion-time-stamp" : "2018-10-15T08:13:37"
    },
    "transaction-state" : "string",
    "api-id" : "wpp"
    }
}
Field (NVP) Field (JSON) JSON Parent

parent_transaction_id

parent-transaction-id

payment ({ })

status_description_n

status ([ {} ])/ severity

statuses ({ })

status_severity_n

status ([ {} ])/ code

statuses ({ })

status_code_n

status ([ {} ])/ description

statuses ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

transaction_state

transaction-state

payment ({ })

api_id

api-id

payment ({ })

SEPA Direct Debit
General Information

This is a reference page for SEPA Direct Debit. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type  debit, including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About SEPA Direct Debit
SEPA Direct Debit logo

The Single Euro Payments Area (SEPA) is an initiative of the European banking industry that makes electronic payments across the euro area as easy as domestic payments within one country. The payments are processed under the same basic conditions, rights, and obligations regardless of their location.

SEPA Direct Debit is a payment method which authorizes a transaction before it transfers money from the consumer account to the merchant.

Test Credentials

Test credentials for the transaction type  debit.

URI (Endpoint)

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

Merchant Account ID (MAID)

4c901196-eff7-411e-82a3-5ef6b6860d64

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

ecdf5990-0372-47cd-a55d-037dccfe9d25

SEPA-specific Request Values

Creditor ID

DE98ZZZ09999999999

SEPA Direct Debit testing
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for SEPA Direct Debit transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API SEPA Direct Debit specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
"payment":{
      "merchant-account-id":{
         "value":"4c901196-eff7-411e-82a3-5ef6b6860d64"
      },
      "request-id":"{{$guid}}",
      "transaction-type":"pending-debit",
      "requested-amount":{
         "value":10.1,
         "currency":"EUR"
      },
      "payment-methods":{
         "payment-method":[
            {
               "name":"sepadirectdebit"
            }
         ]
      },
      "mandate": {
            "mandate-id":"12345678"
        },
    "creditor-id":"DE98ZZZ09999999999"
}
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

11

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For SEPA Direct Debit payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used for the transaction. Set this value to sepadirectdebit.

mandate-id

String

Required

35

The ID of the Direct Debit mandate. You must generate this value yourself.

creditor-id

String

Required

35

The Creditor ID of the merchant.

2. Redirect the Customer to the Payment Page (Initial Response URL)

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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "bank-account" : {
    "iban" : "DE42512308000000060004"
  },
  "request-id" : "4c901196-eff7-411e-82a3-5ef6b6860d64",
  "account-holder" : {
    "first-name" : "John",
    "last-name" : "Doe"
  },
  "due-date" : "2018-04-11",
  "transaction-type" : "pending-debit",
  "provider-transaction-reference-id" : "DB76A00B1A",
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "sepadirectdebit"
    } ]
  },
  "transaction-state" : "success",
  "transaction-id" : "4f325b1d-f713-4ce5-9c5f-cdf0831de874",
  "completion-time-stamp" : "2018-04-02T22:13:57",
  "requested-amount" : {
    "currency" : "EUR",
    "value" : 10.1
  },
  "statuses" : {
    "status" : [ {
      "description" : "The resource was successfully created.",
      "severity" : "information",
      "code" : "201.0000"
    } ]
  },
  "merchant-account-id" : {
    "value" : "db9041cd-acb0-4433-8dd7-b0c1c93ac797"
  },
  "api-id" : "up3-wpp",
  "mandate" : {
    "mandate-id" : "12345678",
    "signed-date" : "2018-04-02"
  },
  "creditor-id" : "DE98ZZZ09999999999"
}
Field (JSON) Data Type Description

iban

String

The International Bank Account Number (IBAN).

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

due-date

YYYY-MM-DD

The date on which the mandated transaction is due.

transaction-type

String

The requested transaction type.

provider-transaction-reference-id

String

An identifier used to match and reference all transactions belonging to a single Direct Debit payment lifecycle.

payment-method

name

String

The name of the payment method used for the transaction.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.  For SEPA Direct Debit payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

merchant-account-id

value

String

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

api-id

String

Identifier of the currently used API.

mandate-id

String

The ID of the Direct Debit mandate. You must generate this value yourself.

signed-date

YYYY-MM-DD

The date the Direct Debit mandate was signed.

creditor-id

String

The Creditor ID of the merchant.

Recurring Transactions

Use WPP to create the first transaction in a series of recurring transactions. Then use our REST API for all the following transactions (these need to reference the first one).

To register an initial (first) recurring transaction, use a normal debit request (like the one in the example above) and add these two fields: 

  • periodic-type , set to value recurring or installment.

  • sequence-type , set to value first.

The periodic and sequence information indicates that this is the first transaction in a series. There are no other requirements for the request.

The provider-transaction-reference-id returned in the response contains the ID used to reference all transactions belonging to a specific recurring group.

For a successful transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for SEPA Direct Debit transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API SEPA Direct Debit specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
{
"payment":{
      "merchant-account-id":{
         "value":"4c901196-eff7-411e-82a3-5ef6b6860d64"
      },
      "request-id":"{{$guid}}",
      "transaction-type":"debit",
      "requested-amount":{
         "value":10.1,
         "currency":"EUR"
      },
      "payment-methods":{
         "payment-method":[
            {
               "name":"sepadirectdebit"
            }
         ]
      },
        "mandate": {
            "mandate-id":"12345678"
        },
        "creditor-id":"DE98ZZZ09999999999",
        "periodic":{
            "periodic-type":"recurring",
            "sequence-type":"first"
        }
}
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

11

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For SEPA Direct Debit payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to sepadirectdebit.

mandate-id

String

Required

35

The ID of the Direct Debit mandate. You must generate this value yourself.

creditor-id

String

Required

35

The Creditor ID of the merchant.

periodic-type

String

Conditional

9

Required for recurring transactions. Indicates if (and how) payment occurs more than once.

sequence-type

String

Conditional

9

Required for recurring transactions. Indicates the phase of a recurring transaction. 

2. Redirect the Customer to the Payment Page (Initial Response URL)
{
"payment-redirect-url" : "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
 {
  "bank-account" : {
    "iban" : "DE42512308000000060004"
  },
  "request-id" : "4c901196-eff7-411e-82a3-5ef6b6860d64",
  "account-holder" : {
    "first-name" : "John",
    "last-name" : "Doe"
  },
  "due-date" : "2018-04-11",
  "transaction-type" : "debit",
  "periodic" : {
    "periodic-type" : "recurring",
    "sequence-type" : "first"
  },
  "provider-transaction-reference-id" : "843B5B45DB",
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "sepadirectdebit"
    } ]
  },
  "transaction-state" : "success",
  "transaction-id" : "1a8dc1ca-952f-4582-a602-dab070df5d3b",
  "completion-time-stamp" : "2018-04-02T22:10:10",
  "requested-amount" : {
    "currency" : "EUR",
    "value" : 10.1
  },
  "statuses" : {
    "status" : [ {
      "description" : "The resource was successfully created.",
      "severity" : "information",
      "code" : "201.0000"
    } ]
  },
  "merchant-account-id" : {
    "value" : "db9041cd-acb0-4433-8dd7-b0c1c93ac797"
  },
  "api-id" : "up3-wpp",
  "mandate" : {
    "mandate-id" : "12345678",
    "signed-date" : "2018-04-02"
  },
  "creditor-id" : "DE98ZZZ09999999999"
}
Field (JSON) Data Type Description

iban

String

The International Bank Account Number (IBAN).

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

due-date

YYYY-MM-DD

The date on which the mandated transaction is due.

transaction-type

String

The requested transaction type.

periodic

periodic-type

String

Indicates if (and how) payment occurs more than once.

sequence-type

String

Indicates the phase of a recurring transaction.

provider-transaction-reference-id

String

An identifier used to match and reference all transactions belonging to a single Direct Debit payment lifecycle.

payment-method

name

String

The name of the payment method used for the transaction.

transaction-state

String

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.

transaction-id

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount.  For SEPA Direct Debit payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction. 2 decimals allowed.

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

merchant-account-id

value

String

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

api-id

String

Identifier of the currently used API.

mandate-id

String

The ID of the Direct Debit mandate. You must generate this value yourself.

signed-date

YYYY-MM-DD

The date the Direct Debit mandate was signed.

creditor-id

String

The Creditor ID of the merchant.

B2B Scheme

To use the SEPA B2B scheme for Direct Debit, add the b2-b field to the request and set its value to true.

The default value is false so unless you send this field in the request as true, the payment proceeds with the default scheme.

For more information on SEPA schemes, click here.
SEPA Direct Debit Example Request with B2B Scheme Enabled
{
"payment":{
      "merchant-account-id":{
         "value":"4c901196-eff7-411e-82a3-5ef6b6860d64"
      },
      "request-id":"{{$guid}}",
      "transaction-type":"pending-debit",
      "requested-amount":{
         "value":10.1,
         "currency":"EUR"
      },
      "payment-methods":{
         "payment-method":[
            {
               "name":"sepadirectdebit"
            }
         ]
      },
      "mandate": {
            "mandate-id":"12345678"
        },
    "creditor-id":"DE98ZZZ09999999999",
    "b2-b":true
}
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type.

requested-amount

value

Numeric

Required

11

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For SEPA Direct Debit payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Optional

15

The name of the payment method used. Set this value to sepadirectdebit.

mandate-id

String

Required

35

The ID of the Direct Debit mandate. You must generate this value yourself.

creditor-id

String

Required

35

The Creditor ID of the merchant.

b2-b

Boolean

Conditional

N/A

Required for B2B payments. Indicates whether the B2B scheme is used for the payment.

 

Post-Processing Operations 

  WPP is best used to deal with 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.

A direct refund through WPP is not possible for SEPA Direct Debit so you have to obtain your consumer’s banking information and send the refund using SEPA Credit Transfer.
Check the REST API SEPA Credit Transfer specification for details on SEPA Direct Debit specific post-processing operations.
JSON/NVP Field Reference

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for SEPA Direct Debit Requests
{
"payment":{
      "merchant-account-id":{
         "value":"string"
      },
      "request-id":"string",
      "transaction-type":"string",
      "requested-amount":{
         "value":0,
         "currency":"string"
      },
      "parent-transaction-id":"string",
      "account-holder":{
         "first-name":"string",
         "last-name":"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"
        },
      "success-redirect-url": "string",
      "fail-redirect-url": "string",
      "cancel-redirect-url": "string",
      "b2-b":true
}
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount (\{ })

requested_amount_currency

currency

requested-amount ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holder ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

bank_account_iban

iban

bank-account ({ })

mandate_mandate_id

mandate-id

mandate ({ })

mandate_signed_date

signed-date

mandate ({ })

creditor_id

creditor-id

payment ({ })

periodic_type

periodic-type

periodic ({ })

sequence_type

sequence-type

periodic ({ })

success_redirect_url

success-redirect-url

payment ({ })

fail_redirect_url

fail-redirect-url

payment ({ })

cancel_redirect_url

cancel-redirect-url

payment ({ })

b2b

b2-b

payment ({ })

Response-Only Fields
{
"payment": {
 "provider-transaction-reference-id": "string",
 "transaction-state": "string",
 "transaction-id": "string",
 "completion-time-stamp": "2017-11-21T09:38:57.645Z",
 "statuses": {
      "status": [
        {
          "code": "string",
          "description": "string",
          "severity": "string"
        }
      ]
    },
 "api-id": "string"
}
}
Field (NVP) Field (JSON) JSON Parent

provider_transaction_reference_id

provider-transaction-reference-id

payment ({ })

transaction_state

transaction-state

payment ({ })

transaction_id

transaction-id

payment ({ })

completion_time_stamp

completion-time-stamp

payment ({ })

status_code_n

status ([ {} ])/ code

statuses ({ })

status_description_n

status ([ {} ])/ description

statuses ({ })

status_severity_n

status ([ {} ])/ severity

statuses ({ })

api_id

api-id

payment ({ })

Sofort.
General Information

This is a reference page for Sofort. Here you find all the information necessary for integrating this payment method into your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page (WPP)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

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

Below, you find example requests for the available transaction type debit,  including field lists with short descriptions.

These requests are designed for the testing environment and do not use real information. 

For production, you need to use production credentials. For details contact merchant support.

All given requests return successful responses.

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

For response verification examples, see the WPP Security section.

About Sofort.
Sofort logo

Sofort GmbH is a payment service provider which has been part of the Klarna Group since 2014. Sofort (also known as Pay now with Klarna) allows consumers to make online purchases using their online banking details. Merchants get a real-time transfer confirmation, and can dispatch their goods straight away.

Test Credentials

Test credentials for the transaction type debit.

URI (Endpoint)

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

Merchant Account ID (MAID)

f19d17a2-01ae-11e2-9085-005056a96a54

Username

70000-APITEST-AP

Password

qD2wzQ_hrc!8

Secret Key (used for response verification)

ad39d9d9-2712-4abd-9016-cdeb60dc3c8f

Testing Credentials for Sofort. Sandbox

Bank (Sort Code)

Demo Bank (00000)

User ID/password/TAN/other

Arbitrary (4 characters minimum)

On Sofort testing environment, use the sort code 00000 or the name "Demo Bank" when prompted. For other credentials (User ID, password, TAN) any number/text will do as long as it is at least 4 characters long.
Sofort testing
Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

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

We provide ready-made JSON examples for each step of this process. You find them below.

Endpoint for Sofort transactions.

Initial Request

The initial request creates the payment session. If it is successful, you receive a URL as a response which redirects to the payment form.

Request Headers

Authorization

Basic NzAwMDAtQVBJVEVTVC1BUDpxRDJ3elFfaHJjITg=

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Sofort specification.

For a full structure of a request (optional fields included), see the JSON/NVP Field Reference section at the bottom.

1. Create a Payment Session (Initial Request)
 {
    "payment": {
        "merchant-account-id": {
            "value":"f19d17a2-01ae-11e2-9085-005056a96a54"
        },
        "request-id":"{{$guid}}",
        "transaction-type": "debit",
        "requested-amount": {
            "value": "10.1",
            "currency": "EUR"
        },
        "payment-methods": {
            "payment-method":[
            {
                "name": "sofortbanking"
            }
            ]
        },
        "descriptor": "test",
        "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
        "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
        "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel"
    }
}
Field (JSON) Data Type Required/Optional 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-z0-9-_]

transaction-type

String

Required

36

The requested transaction type. For Sofort payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Required

18

The full amount that is requested/contested in a transaction. 2 decimal places allowed.

Use . (decimal point) as the separator.

currency

String

Required

3

The currency of the requested/contested transaction amount. For Sofort payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-method

name

String

Required

15

The name of the payment method used. Set this value to sofortbanking.

descriptor

String

Optional

100

Description of the transaction for account holder’s bank statement purposes. 

success-redirect-url

String

Required

2000

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

fail-redirect-url

String

Required

2000

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

cancel-redirect-url

String

Required

2000

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

2. Redirect the Consumer to the Payment Page (Initial Response URL)
{
"payment-redirect-url" : "https://wpp.wirecard.com/?wPaymentToken=f0c0e5b3-23ad-4cb4-abca-ed80a0e770e7"
}
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. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (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 payment response in the statuses object. 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 for more details on redirection targets after payment and transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
 {
  "descriptor" : "test",
  "payment-methods" : {
    "payment-method" : [ {
      "name" : "sofortbanking"
    } ]
  },
  "parent-transaction-id" : "e9a8b4ad-161b-4721-a799-e512141f1512",
  "api-id" : "up3-wpp",
  "transaction-id" : "974d9b1e-5381-4813-b09c-5f755da43840",
  "statuses" : {
    "status" : [ {
      "description" : "Successful confirmation received from the bank.",
      "severity" : "information",
      "code" : "201.1126"
    } ]
  },
  "account-holder" : {
    "first-name" : "Max",
    "last-name" : "Mustermann"
  },
  "request-id" : "e2234c45-84ab-44a2-b299-56cab4fcc927",
  "requested-amount" : {
    "value" : 10.100000,
    "currency" : "EUR"
  },
  "transaction-state" : "success",
  "success-redirect-url" : "https://demoshop-test.wirecard.com/demoshop/#/success",
  "merchant-account-id" : {
    "value" : "f19d17a2-01ae-11e2-9085-005056a96a54"
  },
  "completion-time-stamp" : "2018-04-13T10:47:10",
  "cancel-redirect-url" : "https://demoshop-test.wirecard.com/demoshop/#/cancel",
  "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error",
  "transaction-type" : "debit"
}
Field (JSON) Data Type Description

descriptor

String

Description of the transaction for account holder’s bank statement purposes.

payment-method

name

String

The name of the payment method used.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

api-id

String

Identifier of the currently used API.

transaction-id

String

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

status

code

String

Status code of the status message.

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

account-holder

first-name

String

The first name of the account holder.

last-name

String

The last name of the account holder.

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

requested-amount

currency

String

The currency of the requested/contested transaction amount. For Sofort payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

transaction-state

String

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.

success-redirect-url

String

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

merchant-account-id

value

String

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

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time and date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

cancel-redirect-url

String

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

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

transaction-type

String

The requested transaction type. For Sofort payments, the transaction-type must be set to debit.

Post-Processing Operations 

WPP is best used to deal with 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.

A direct refund through WPP is not possible for Sofort so you have to obtain your consumer’s banking information and send the refund using SEPA Credit Transfer.
Check the REST API SEPA Credit Transfer specification for details on Sofort specific post-processing operations.
JSON/NVP Field Reference

Here you can:

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

  • see the structure of a full request (optional fields included).

JSON Structure for Sofort. Requests
 {
    "payment": {
        "merchant-account-id": {
            "value":"string"
        },
        "request-id":"string",
        "transaction-type": "string",
        "requested-amount": {
            "value": 0,
            "currency": "string"
        },
        "payment-methods": {
            "payment-method":[
            {
                "name": "string"
            }
            ]
        },
        "account-holder" : {
            "first-name" : "string",
            "last-name" : "string"
        },
        "descriptor": "string",
        "success-redirect-url": "string",
        "fail-redirect-url": "string",
        "cancel-redirect-url": "string"
    }
}
Field (NVP) Field (JSON) JSON Parent

merchant_account_id

value

merchant-account-id ({ })

request_id

request-id

payment ({ })

transaction_type

transaction-type

payment ({ })

requested_amount

value

requested-amount ({ })

requested_amount_currency

currency

requested-amount ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

first_name

first-name

account-holder ({ })

last_name

last-name

account-holde