Wirecard Documentation

Przelewy24

REST API

Przelewy24 is a type of Online Bank Transfer.

Countries	Poland
Currencies	PLN

Communication Formats

This table illustrates how P24 notifications are encoded and which formats and methods can be used for requests and responses.

Requests/Responses	Format	XML
Methods	POST
IPN Encodement	Please follow the instructions given at Notification Examples to set up IPN.

Requests/Responses

Format

XML

Methods

POST

IPN Encodement

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

Transaction Types

This table lists all transaction types available for P24.

Some transaction types cannot be sent in your request. Refer to columns Request, Response/IPN and WEP for details where to expect involved transaction types.

Recurring mode is not available.

For transaction type details which are not given here look at Transaction Types.

Transaction Type Request Response/IPN WEP Description Link to Samples

Transaction Type	Request	Response/IPN	WEP	Description	Link to Samples
debit	Yes	Yes	Yes	Moves funds from Consumer to Merchant. `debit` requests to take funds from consumer’s bank account.	debit samples
get-url	No	No	Yes	A step in a group of transactions where the URL of P24 landing page is retrieved for the Consumer to be redirected to.
refund-request	Yes	Yes	Yes	A request to give funds to the Consumer’s account, referring to an eligible debit transaction.	refund samples
refund-debit	No	Yes	Yes	Moves funds from the Merchant to the Consumer. It follows `refund-request` as a final step of the refund flow.

debit

Yes

Moves funds from Consumer to Merchant. debit requests to take funds from consumer’s bank account.

debit samples

get-url

Yes

A step in a group of transactions where the URL of P24 landing page is retrieved for the Consumer to be redirected to.

refund-request

Yes

A request to give funds to the Consumer’s account, referring to an eligible debit transaction.

refund samples

refund-debit

Yes

Moves funds from the Merchant to the Consumer. It follows refund-request as a final step of the refund flow.

Request

Yes means the transaction type can be sent in the request.

Response/IPN

Yes means the transaction type can appear in either response or notification.

WEP

Yes means the transaction type is visible in Wirecard Enterprise Portal.

Our test environment is connected to P24 sandbox which does not require to enter any additional data. P24 landing page will skip entering consumer card data or credentials and returns to your shop immediately.

URLs (Endpoints)	REST API	For transaction type `debit`.	`https://api-test.wirecard.com/engine/rest/paymentmethods/`
For transaction types `refund-request` and `refund-debit`.	`https://api-test.wirecard.com/engine/rest/payments/`
Payment Page	`https://api-test.wirecard.com/engine/hpp/`
Merchant Account ID	86451785-3ed0-4aa1-99b2-cc32cf54ce9a
Username	16390-testing
Password	3!3013=D3fD8X7
Secret Key	fdd54ea1-cef1-449a-945c-55abc631cfdc

URLs (Endpoints)

REST API

For transaction type debit.

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

For transaction types refund-request and refund-debit.

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

Payment Page

https://api-test.wirecard.com/engine/hpp/

Merchant Account ID

86451785-3ed0-4aa1-99b2-cc32cf54ce9a

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key

fdd54ea1-cef1-449a-945c-55abc631cfdc

Workflow

debit Transaction

Prerequisites

For a successful workflow, please keep the following prerequisites in mind:

A P24 payment process is accomplished successfully only, if WPG has sent out a successful notification. The status success in the response only confirms that the payment was technically accepted.
In case the consumer closes the browser before confirming the payment, there is a redirection to shop page possible. This means, the workflow can be accomplished successfully, even when shutting down the browser.
As soon as the P24 landing page has been opened in a browser, the consumer has 15 minutes to authorize the payment. However, the validity of the received URL is not limited. Try to ensure that the URL is opened by the consumer as soon as possible. In edge cases the payment could be successfully finished even after a long time (when the merchant could have cancelled the order already).
The maximum period to receive notification is 30 days.

Payment Process Using the ReST API

The consumer initiates a transaction (currency is set to PLN).
The merchant sends a request with the consumer’s data to the endpoint of WPG.
WPG sends a response to the merchant.
The merchant redirects the consumer to the P24 landing page (The URL for redirection is in the response message, field payment-methods/payment-method/@url).
The consumer authorizes the transaction.
WPG performs two actions simultaneously:
WPG redirects the consumer (via redirect URLs) back to the shop where the information about the status of the payment is displayed. The redirect URL uses the definition in success-redirect-url and fail-redirect-url from the request (Step 2). According to success or failure during the payment process WPG sends the consumer to the corresponding URL. This is the page where the consumer is informed about his successful or failed payment.
WPG sends a notification (IPN) of the payment outcome. In order to receive server-to-server notification, the notification must use the definition in the field notifications/notification/@url in the request (Step 2)

Payment Process Using the Payment Page

Figure 23. Payment Process Using Payment Page

The consumer initiates a transaction (currency is set to PLN).
The merchant sends a request with the consumer’s data to the endpoint of WPG.
WPG analyses the consumer’s data.
1. If the request does not include the payment method P24, the WPG redirects the consumer to Payment Page
  1. The consumer selects P24.
  2. WPG redirects the consumer to the P24 landing page.
2. If the request already includes the payment method P24, WPG redirects the consumer to the P24 landing page.
The consumer selects the desired bank.
The consumer authorizes the transaction.
WPG performs two actions simultaneously:
1. WPG redirects the consumer (via redirect URLs) back to the shop where the information about the status of the payment is displayed. The redirect URL uses the definition in success-redirect-url and fail-redirect-url from the request (Step 2). According to success or failure during the payment process WPG sends the consumer to the corresponding URL. This is the page where the consumer is informed about his successful or failed payment.
2. WPG sends a notification (IPN) of the payment outcome. In order to receive a server-to-server notification, the notification must use the definition in the field notifications/notification/@url in the request (Step 2).

refund Transaction

A refund transaction is a backend process. Wirecard can only provide a process for ReST API. When using Payment Page the merchant must set up a refund process.

Prerequisites

In order to transfer funds back to the consumer you have to be aware of the following prerequisites:

The flow is asynchronous. You have to wait for a notification with the result. Usually it takes one day for refunds to be processed.
The refund must reference to a successful debit transaction. In a refund, a Transaction ID from a debit notification must be used.
The refunded amount must be less than or equal to original debit transaction
Multiple refunds to a single debit are possible as long as the sum of those individual refunds does not exceed original full amount.
In order to have a final status of the refund, you have to process a subsequent notification.

refund Process Using the ReST API

Figure 24. refund Process Using the ReST API

The merchant initiates a refund transaction.
The merchant sends a request to the endpoint of WPG. The request must contain:
1. the Request ID from a previously sent successful debit transaction. The Request ID is expected in the field parent-transaction-id
2. a payment-methods/payment-method/@name set to p24
3. a transaction-type set to refund-request
WPG sends a response to the merchant.
P24 processes the refund.

Processing a refund lasts at least one day!
WPG waits for the status "Refund Process Finished".
WPG sends a notification (IPN) of the refund outcome to the merchant. This notification has the transaction type refund-debit, instead of refund-request which was sent in the merchant’s request (Step 2).
In order to receive a server-to-server notification, the notification must use the definition in the field notifications/notification/@url in the request (Step 2). See Instant Payment Notification for details.

Banking Statement

After a successful payment process, a banking statement appears in the consumer’s transaction history. The statement consists of a Transaction-ID generated by P24 (P24-Transaction-ID) and a value provided in the field descriptor of the debit request.

The structure of the P24-Transaction-ID is P24-YXX-XXX-XXX. The _P24-Transaction-ID_ is also displayed in the Wirecard Enterprise Portal (WEP) as Provider Transaction-ID.

Fields

For full reference of allowed fields for Payment Page or REST API can be found on Fields for Payment Page or Fields for ReST API respectively.
The following tables describe only P24 specifics. The following elements are either mandatory M, optional O or conditional C.

debit

Fields for debit transaction
Field	Cardinality	Datatype	Size	Description
account-holder/email	M	Alphanumeric	64	The email address of the account holder.
account-holder/address/country	O	Alphanumeric	3	The Country ID of the account holder. It must be `PL`; if it is not provided, will be automatically set to `PL`.
order-number	O	Alphanumeric	64	This is the order number of the merchant. If provided, it is displayed on P24 landing page as "Order Information"
payment-methods/payment-method-name	M	Alphanumeric	15	This is the name of the payment method. Always use value `p24`
transaction-type	M	Alphanumeric	30	This is the type for a transaction. Always use value `debit`
requested-amount/@currency	M	Alphanumeric	3	This is the currency in which a transaction is received and processed. Always use value `PLN`
descriptor	O	Alphanumeric	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. Do not use no more than 20 characters and do not use special chars as it can be misinterpreted by a bank system.
locale	O	Alphanumeric	6	With this field you can specify language in which P24 landing page is displayed. Possible values: `pl`, `en`, `de`, `es`, `it`

The P24 landing page contains the section "Description". This section displays additional information about the payment. The text displayed comprises Order Number, Merchant Name and Request Id in the following format: [order-number], [merchant_name], [request-id] Merchant Name is taken from the configuration of the merchant’s profile.

refund request

Fields for refund request
Field	Cardinality	Datatype	Size	Description
payment-methods.payment-method-name	M	Alphanumeric	15	This is the name of the payment method. Always use value `p24`
transaction-type	M	Alphanumeric	30	This is the type for a transaction. Always use value `refund-request`
requested-amount/@currency	M	Alphanumeric	3	This is the currency in which a transaction is received and processed. Always use value `PLN`

Samples

Go to Notification Examples if you want to see corresponding notification samples.

debit

debit Request (Successful)

<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>86451785-3ed0-4aa1-99b2-cc32cf54ce9a</merchant-account-id>
   <request-id>28040771-b2e6-4b43-ab80-8f9a24164917</request-id>
   <transaction-type>debit</transaction-type>
   <payment-methods>
      <payment-method name="p24" />
   </payment-methods>
   <requested-amount currency="PLN">10</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
   </account-holder>
   <order-number>180730104557465</order-number>
   <descriptor>Eshop Order - Shoes</descriptor>
   <notifications>
      <notification url="https://merchant.com/ipn.php" />
   </notifications>
 <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
 <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
 <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
</payment>

debit Response (Successful)

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
  <merchant-account-id>86451785-3ed0-4aa1-99b2-cc32cf54ce9a</merchant-account-id>
  <transaction-id>38245a43-c7c0-43e5-bf4b-c9aca64acd41</transaction-id>
  <request-id>8a5a2813-5cd7-42ab-96b0-e70ea2d4004f</request-id>
  <transaction-type>debit</transaction-type>
  <transaction-state>success</transaction-state>
  <completion-time-stamp>2018-07-30T09:17:05.000Z</completion-time-stamp>
  <statuses>
    <status code="201.0000" description="The resource was successfully created." severity="information" />
  </statuses>
  <requested-amount currency="PLN">10</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
  </account-holder>
  <order-number>180730111704952</order-number>
  <descriptor>Eshop Order - Shoes</descriptor>
  <notifications>
    <notification url="https://merchant.com/ipn.php"></notification>
  </notifications>
  <payment-methods>
    <payment-method url="https://sandbox.przelewy24.pl/trnRequest/D7A31BCD3C-B845DB-614CA2-7BD158C3A9" name="p24" />
  </payment-methods>
  <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
  <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
  <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
</payment>

refund

refund-request Request (Successful)

<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <request-id>e90684e4-3588-4450-b1f6-42d614f4430f</request-id>
  <transaction-type>refund-request</transaction-type>
  <requested-amount currency="PLN">10</requested-amount>
  <parent-transaction-id>77e8f783-8960-45b5-8e61-5e50f9a29ba1</parent-transaction-id>
  <payment-methods>
    <payment-method name="p24" />
  </payment-methods>
</payment>

refund-request Response (Successful)

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction" self="https://api-test.wirecard.com:443/engine/rest/merchants/86451785-3ed0-4aa1-99b2-cc32cf54ce9a/payments/8c2bdc7f-d426-4008-a200-745275c6bd46">
  <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/86451785-3ed0-4aa1-99b2-cc32cf54ce9a">86451785-3ed0-4aa1-99b2-cc32cf54ce9a</merchant-account-id>
  <transaction-id>8c2bdc7f-d426-4008-a200-745275c6bd46</transaction-id>
  <request-id>e90684e4-3588-4450-b1f6-42d614f4430f-refund-request</request-id>
  <transaction-type>refund-request</transaction-type>
  <transaction-state>success</transaction-state>
  <completion-time-stamp>2018-07-30T09:27:50.000Z</completion-time-stamp>
  <statuses>
    <status code="201.0000" description="p24:The resource was successfully created." severity="information" />
  </statuses>
  <requested-amount currency="PLN">10</requested-amount>
  <parent-transaction-id>77e8f783-8960-45b5-8e61-5e50f9a29ba1</parent-transaction-id>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
  </account-holder>
  <order-number>180730111704952</order-number>
  <descriptor>Eshop Order - Shoes</descriptor>
  <notifications>
    <notification url="https://merchant.com/ipn.php" />
  </notifications>
  <payment-methods>
    <payment-method name="p24" />
  </payment-methods>
  <parent-transaction-amount currency="PLN">10.000000</parent-transaction-amount>
  <authorization-code>92749318</authorization-code>
  <api-id>elastic-api</api-id>
  <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
  <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
  <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
  <provider-account-id>16027</provider-account-id>
</payment>

Wirecard Payment Page v2

Wirecard Payment Page v1 is no longer supported. We recommend using Wirecard Payment Page v2 integration instead. If you have questions about your existing Wirecard Payment Page v1 integration, consult our REST API integration guide.

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 v2 (WPP v2)?

Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

All WPP v2 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 v2 section.

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

About Przelewy24

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

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.

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:

Create a payment session (initial request).
Redirect the consumer to the payment page (initial response URL).
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 Mandatory/Optional Size Description

Field (JSON)	Data Type	Mandatory/Optional	Size	Description
merchant-account-id	value	String	Mandatory	36	A unique identifier assigned to every merchant account (by Wirecard).
request-id	String	Mandatory	150	A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. `{{$guid}}` serves as a placeholder for a random `request-id`.
order-number	String	Mandatory	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	Mandatory	30	The requested transaction type. For P24 payments, the transaction-type must be set to `debit`.
requested-amount	value	Numeric	Mandatory	18	The full amount that is requested/contested in a transaction. 2 decimal places allowed.
currency	String	Mandatory	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	Mandatory	32	The last name of the account holder.
email	String	Mandatory	64	The email address of the account holder.
payment-method	name	String	Mandatory	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`

merchant-account-id

value

String

Mandatory

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

request-id

String

Mandatory

150

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

order-number

String

Mandatory

This is the order number of the merchant. If provided, it is displayed on the P24 landing page as "Order Information".

transaction-type

String

Mandatory

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

requested-amount

value

Numeric

Mandatory

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

currency

String

Mandatory

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

account-holder

first-name

String

Optional

The first name of the account holder.

last-name

String

Mandatory

The last name of the account holder.

email

String

Mandatory

The email address of the account holder.

payment-method

name

String

Mandatory

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

country

String

Optional

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

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

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.

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 v2 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" : "{api-id]",
    "descriptor" : "test",
    "country" : "PL"
    }
}

Field (JSON) Data Type Description

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`.

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 v2 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 ({ })

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

account-holder ({ })

payment_method

payment-method ([ ])/name

payment-methods ({ })

country

payment ({ })

locale

payment ({ })

notification-url

url

notifications ({ })

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" : "{api-id]"
    }
}

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 ({ })

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 ({ })