Fields

These fields are used with Wirecard Payment Gateway REST API. They are mandatory (M) or optional (O) in a request. Fields that show only in the response are marked accordingly.

Please refer to the XSD for details about the field’s value range.

Field values must not contain &, <, >.

Request and Response Fields

payment
Field M/O Datatype Size Description

merchant-account-id

M/O

String

36

Unique identifier assigned to each merchant account. Mandatory unless merchant-account-resolver-category is used.

merchant-account-resolver-category

M/O

String

36

Used to resolve the merchant account based on a number of resolving rules. Mandatory unless merchant-account-id is used.

request-id

M

String

150

The identification number of the request. It must be unique for each request.
Allowed characters: ASCII character code 32-38 and 40-126.

requested-amount

M

Decimal

18.3

The total amount that is requested in a transaction. In the case of a refund, this is what you request. In the case of a chargeback, this is the amount that is being contested.
The number of decimal places depends on the currency.
Use . (decimal point) as separator.

requested-amount/@currency

M

String

3

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

transaction-type

M

String

30

Determines a transaction’s behavior during transaction processing and merchant settlement, e.g.

  • authorization

  • capture-authorization

  • credit

  • purchase

  • refund-purchase

  • void-authorization

  • void-capture

→ Complete list of transaction types.

descriptor

O

String

64

The descriptor is the text representing an order on the consumer’s bank statement issued by their credit card company.

order-detail

O

String

65535

Merchant side order details.

order-number

O

String

32

The order number which you can provide.
Allowed characters: ASCII character code 32-38 and 40-126.

consumer-id

M/O

String

50

The ID of the consumer.
In loyalty programs consumer-id is used with VOP only. It is mandatory to Enroll Tokenized Card.
When using a credit card for the VOP, at least one of following must be present: consumer-id, account-holder.email or account-holder.phone.

parent-transaction-id

M/O

String

36

Unique identifier for a preceding transaction. This is mandatory to assign a transaction to a previous one, e.g. to capture a preceding authorization.

group-transaction-id

O

String

36

A unique ID assigned to a group of related transactions. For example, an authorization, capture, and refund will all share the same group-transaction-id.

authorization-code

O

String

36

The authorization-code can be

  • output of an authorization: Generated by the card-issuing bank as proof that the transaction request was acknowledged or declined.

  • input for a capture without reference to an authorization.

ip-address

O

String

45

The global (internet) IP address of the consumer’s device.

non-gambling-oct-type

O

Enumeration

7

A transfer type of non-gambling Original Credit Transaction (OCT).
Accepted values:

  • p2p

  • md

  • acc2acc

  • ccBill

  • fd.

processing-redirect-url

O

String

256

The URL to which the consumer is redirected during payment processing. This is normally a page on your website. Enter a value in the request if you want to send your consumer to a different page than defined in your integration.

success-redirect-url

O

String

256

The URL to which the consumer is redirected after a successful payment. This is normally a success confirmation page on your website. Enter a value in the request if you want to send your consumer to a different page than defined in your integration.

cancel-redirect-url

O

String

256

The URL to which the consumer is redirected after the payment has been canceled. This is normally a page on your website. Enter a value in the request if you want to send your consumer to a different page than defined in your integration.

fail-redirect-url

O

String

256

The URL to which the consumer is redirected after an unsuccessful payment. This is normally a page on your website notifying the consumer of a failed payment, often suggesting the option to try another payment method. Enter a value in the request if you want to send your consumer to a different page than defined in your integration.

locale

O

String

6

Code of the language the payment page is rendered in. Typically used in conjunction with Hosted Payment Page.
Format can be either language or language_country, e.g. EN or EN_US.

entry-mode

O

Enumeration

n/a

Channel through which the account holder information was collected.
Accepted values:

  • mail-order = collected via mail order

  • telephone-order = collected via telephone

  • ecommerce = collected via internet

  • mcommerce = collected via mobile devices

  • pos = collected by the primary payment instrument

  • empty: unknown source

iso-transaction-type

O

Enumeration

2

iso-transaction-type is a 3D Secure 2 field. It identifies the type of ISO transaction. The values are derived from ISO 8583.
Accepted values:

  • 01 = Goods/ Service Purchase

  • 03 = Check Acceptance

  • 10 = Account Funding

  • 11 = Quasi-Cash Transaction

  • 28 = Prepaid Activation and Load

authorization-reason

O

Enumeration

authorization-reason is an industry-specific indicator for merchant-initiated transactions (MIT). It is used to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with a single transaction.
This indicator is available for the following transaction types:

  • authorization

  • preauthorization

  • purchase

  • referenced-purchase

Accepted values:

  • resubmission = an indicator used when the original purchase took place, but the authorization was not executed at the time the goods or services were provided.

  • delayed-charges = an indicator for an additional account charge performed after the original services have been provided. It is typically used by hotels, cruise lines and vehicle rental services.

  • reauthorization = an indicator used in the event of a purchase made after the original purchase in different specific conditions. It is typically found in delayed/split shipments and extended stays/rentals scenarios.

  • no-show = an indicator enabling you to charge for services that the consumer agreed to purchase, but failed to fulfill the agreement terms.

  • deferred-authorization = an indicator for cases when an authorization is completed at a later time, after the initial authorization failed/was delayed due to connectivity, system issues or other technical limitations.

account-holder

airline-industry

browser

card

card-token

cruise-industry

custom-fields.custom-field

device

loyalty-card

notifications.notification

order-items.order-item

payment-methods.payment-method

periodic

risk-info

shipping

three-d

creditor-id

O

String

256

The merchant’s creditor ID allowing the merchant to process SEPA Direct Debit transactions.
Allowed characters: [a-zA-Z]\{2,2}[0-9]\{2,2}[a-zA-Z0-9]\{3,3}[a-zA-Z0-9]\{1,28}

redirect-url

M/O

String

256

The URL to which the consumer is redirected after completion of a payment regardless of the transaction state. This is normally a page on the merchant’s website.

redirect-url is optional if the payment method is not based on a redirect (e.g. SEPA).

transaction-id

Response only

String

36

Unique identifier assigned to each transaction.

transaction-state

Response only

Enumeration

n/a

Current status of a transaction. Typically, a transaction starts in-progress and finishes in either success or failed state.

completion-time-stamp

Response only

Timestamp

20

The date and time that a transaction state changes to either success or failed in GMT.
Format: YYYY-MM-DDThh:mm:ssZ.

avs-code

Response only

String

24

Code indicating address verification services results.

csc-code

Response only

String

12

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

consumer-id

Response only

String

50

Consumer identifier.

api-id

Response only

String

36

Unique identifier assigned for each API. Always returned in the notification.

instrument-country

Response only

String

256

Retrieves the issuer country of a certain credit card. It returns a two-digit country code, e.g.
DE (Germany),
ES (Spain),
FR (France), or
IT (Italy).

api-transaction-id

Response only

String

36

The unique identifier for a transaction submitted via a white-label API.

merchant-account-id/@ref

Response only

String

n/a

A reference URL to the merchant account. Can be used to retrieve merchant account details over a browser.

@self

Response only

String

n/a

A reference URL to the payment. Can be used to retrieve payment details over a browser.

provider-transaction-reference-id

Response only

String

36

Unique transaction reference ID assigned by the provider.
account-holder

account-holder specifies detailed information about the consumer. account-holder fields are mainly Optional. However, we recommend that you include all account-holder data in your request to facilitate fraud prevention.

Field M/O Datatype Size Description

date-of-birth

O

Date

Consumer’s birth date.
Accepted format: YYYY-MM-DD.

email

M/O

String

156

Consumer’s email address as given in your shop.
Mandatory for 3D Secure 2 payments.
When using a credit card for the loyalty program VOP, at least one of the following must be present: payment.consumer-id, email or phone.

first-name

M/O

String

32

First name of the consumer.
Mandatory for 3D Secure 2 payments.

last-name

M/O

String

32

Last name of the consumer.
Mandatory for 3D Secure 2 payments.

gender

O

Enumeration

1

Consumer’s gender.
Accepted values:

  • m

  • f

merchant-crm-id

O

String

64

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

mobile-phone

O

String

18

Mobile phone number provided by the consumer.

phone

M/O

String

18

Phone number provided by the consumer.
When using a credit card for the loyalty program VOP, at least one of the following must be present: payment.consumer-id, email or phone.

work-phone

O

String

18

Work phone number provided by the consumer.

social-security-number

O

String

14

Consumer’s social security number.

tax-number

O

String

14

This is the tax-number of the consumer.

account-info

address
account-holder.account-info

account-info fields are used with 3D Secure 2. With account-info you can provide detailed information about the consumer. Provide all the account-info data in your 3D Secure 2 request to facilitate fraud prevention.

Field M/O Datatype Size Description

authentication-method

O

Enumeration

2

Type of consumer login in your shop.
Accepted values:

  • 01 = Guest checkout (i.e. the consumer is not logged in).

  • 02 = Login to the consumer’s account in your 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.

authentication-timestamp

O

Timestamp

20

Date and time (UTC) of the consumer login to your shop.
Accepted format: YYYY-MM-DDThh:mm:ss.
For guest checkout, the timestamp is now.

card-creation-date

O

Date

10

Date that the consumer’s card was added to their account in your 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 date is now.

card-transactions-last-day

O

Numeric

9

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

challenge-indicator

O

Enumeration

2

Specifies whether this transaction shall be subject to Strong Customer Authentication (SCA).
Accepted values:

  • 01 = No preference.

  • 02 = No challenge requested (Consequence: higher conversion rate, but higher risk of fraud).

  • 03 = Merchant requests challenge (Consequence: lower conversion rate, but lower risk of fraud).

  • 04 = Challenge requested: Mandate. Must be sent in a first transaction that stores a token (e.g. for one-click checkout).

If the element is not provided, the ACS will interpret this as 01 = No preference.

creation-date

O

Date

10

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

password-change-date

O

Date

10

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

purchases-last-six-months

O

Number

9

Number of successful orders by the consumer in your shop within the past six months.

shipping-address-first-use

O

Date

10

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

suspicious-activity

O

Boolean

Indicates if you know of suspicious activities by the consumer (e.g. previous fraud).

transactions-last-day

O

Number

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

O

Number

9

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

update-date

O

Date

10

Date that the consumer last made changes to their account in your shop, e.g. 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.
address

address is a child of

It is used to specify the consumer’s address and can refer to

  • the consumer (for account-holder). The account holder’s address is used as the billing address.

  • the consumer’s shipping address (for shipping). For 3D Secure 2 transactions it is highly recommended to send shipping.address data in any case, as a complete set of shipping.address data reduces the likelihood of a challenge test.

  • the ticket issuer (for airline-industry).

Data can be provided optionally but it helps with fraud checks if address is complete.

Field M/O Data Type Size Description

street1

M/O

String

50

Line 1 of the street of the consumer’s address.

  • Mandatory for billing address.

  • Optional for shipping address.

street2

O

String

50

Line 2 of the street of the consumer’s address.

  • Optional for billing address and shipping address.

  • Recommended for 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

street3

O

String

50

Line 3 of the street of the consumer’s address.

  • Optional for billing address and shipping address.

  • Recommended for 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

city

M/O

String

50

City of the consumer’s address.

  • Optional for shipping address.

  • Recommended for billing address and shipping address in 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

country

M/O

String

2

Country of the consumer’s address.

  • Optional for shipping address.

  • Recommended for billing address and shipping address in 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

postal-code

M/O

String

16

ZIP/postal code of the consumer’s address.

  • Optional for shipping address.

  • Recommended for billing address and shipping address in 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

state

M/O

String

3

State/province of the consumer’s address.
Format: Numeric ISO 3166-2 standard.
Recommended for 3D Secure 2 transactions to reduce likelihood of an authentication challenge.

block-no

O

String

12

Block number of the consumer’s billing address.
Optional for billing address and shipping address.

level

O

String

3

Level (floor) of the consumer’s billing address.
Optional for billing address and shipping address.

unit

O

String

12

Unit of the consumer’s billing address.
Optional for billing address and shipping address.
bank-account
Field M/O Datatype Size Description

iban

O

String

34

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

bic

O

String

15

The Bank Identifier Code in bank transfer.
Allowed characters: ([a-zA-Z]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3})

account-number

O

String

34

The number designating a bank account used nationally.

bank-code

O

String

15

The national bank sorting code for national bank transfers.

bank-name

O

String

100

The name of the consumer’s bank.

branch-address

O

String

64

The address of the bank. Typically required for Chinese Bank Transfers.

branch-city

O

String

64

The city in which the bank is located. Typically required for Chinese Bank Transfers.

branch-state

O

String

64

The state in which the bank is located. Typically required for Chinese Bank Transfers.
browser
Field M/O Datatype Size Description

accept

O

String

2048

HTTP Accept Header as retrieved from the consumer’s browser in the HTTP request. If the string is longer than 2048, it must be truncated.

We strongly recommend to provide this field if you want to prevent rejection from the ACS server.

challenge-window-size

O

Enumeration

2

Dimensions of the challenge window as displayed to the consumer. The ACS replies with content that is formatted to correctly render in this window to provide the best possible user experience.
Preconfigured sizes are width x height in pixels of the window displayed in the consumer’s browser window.
This is used only to prepare the CReq request and is not part of the AReq flow. If not present, it will be omitted.
Accepted values:

  • 01 = 250 x 400

  • 02 = 390 x 400

  • 03 = 500 x 600

  • 04 = 600 x 400

  • 05 = Full screen

color-depth

O

Number

2

Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from consumer’s browser using the screen.colorDepth property. The field is limited to single and double digits.
Accepted values:

  • 1 = 1 bit

  • 4 = 4 bits

  • 8 = 8 bits

  • 15 = 15 bits

  • 16 = 16 bits

  • 24 = 24 bits

  • 32 = 32 bits

  • 48 = 48 bits

ip-address

M/O

String

45

IP address of the consumer’s browser, obtained by payment page during payment.
Accepted format: IPv4 or IPv6.
Mandatory for requests where

  1. deviceChannel = 02 (BRW) and

  2. where regionally acceptable.

java-enabled

O

Boolean

Boolean that represents the ability of the consumer’s browser to execute Java.
Value is returned by the navigator.javaEnabled property.

language

O

String

8

Value representing the browser language as defined in IETF BCP47.
The value is limited to 1-8 characters.
Value is returned by the navigator.language property.

screen-resolution

O

String

12

Total height and width of the consumer’s screen in pixels.
Value is returned by the screen.height and screen.width properties.

time-zone

O

String

5

Time difference in minutes between UTC and the local time of the consumer’s browser. Value is returned from the getTimezoneOffset() method.

user-agent

O

String

256

User agent as retrieved from the cardholder’s browser in the HTTP request.
If it is longer than 256 bytes, it must be truncated.

We strongly recommend to provide this field if you want to prevent rejection from the ACS server.
card
Field M/O Datatype Size Description

account-number

M/O

String

36

The embossed or encoded number that identifies the card issuer to which a transaction is to be routed and the account to which it is to be charged, unless specific instructions indicate otherwise. In the case of a credit card, this is the primary account number.
Mandatory for credit card transactions if card-token is not used.

account-type

O

String

2

The type of account, e.g. for a multi-account card product.
Accepted values:
01 = Not Applicable.
02 = Credit.
03 = Debit.

Include this field

  • if you want consumers to select the account type they are using before completing their purchase.

  • for certain markets, e.g. Brazil.

Otherwise, the field is optional.

card-security-code

M/O

String

4

A security feature for credit or debit card transactions, providing increased protection against credit card or debit card fraud. The card security code is located on the back of credit or debit cards and is typically a separate group of 3 digits to the right of the signature strip.
On American Express cards, the card security code is a printed, not embossed, group of four digits on the front towards the right.
Depending on your merchant account settings it may be mandatory.

card-type

M/O

String

15

Card brand, e.g. visa.
Please refer to the Payment XSD for the complete list of supported card types.

Mandatory for credit card transactions.

expiration-month

M/O

Numeric

2

The 2-digit representation of the expiration month of the account-number. Mandatory for credit card transactions if card-token is not used.

expiration-year

M/O

Numeric

4

The 4-digit representation of the expiration year of the account-number. Mandatory for credit card transactions if card-token is not used.

merchant-tokenization-flag

M/O

Boolean

This flag is set to true as soon as the consumer’s card data has been stored for future transactions.
Maps the Visa field Stored Credential.
Mandatory for one-click checkout.

track-1

O

String

79

"Track" of information on a credit card that usually contains credit card number, expiration date and consumer name.

track-2

O

String

40

"Track" of information on a credit card that usually contains credit card number and expiration date.

card-emv

card-pin

card-raw
card-emv

card-emv a child of payment.card.

It is used for card present transactions. You can find additional card-emv fields in the Response > card-emv section.

For card present transactions.

Field

M/O

Datatype

Size

Description

request-icc-data

M

String

999

The ICC System Related Data field contains information required by the acquirer to complete an EMV transaction with an issuer. The authorization request cryptogram is sent during an authorization request and contains data from the chip card presented.
Mandatory if you do not send track-1 and track-2.

request-icc-data-encoding

M

String

5

Encoding method of the request EMV data.
Allowed value: hex.
Mandatory if you do not send track-1 and track-2.

response-icc-data

Response only

String

999

The ICC System Related Data field contains information from an issuer to the acquirer to complete the EMV transaction. The authorization response cryptogram is sent in an authorization response and contains data from the issuer to be verified by the card.

response-icc-data-encoding

Response only

String

5

Encoding method of the response EMV data.
Allowed value: hex.
card-pin.

card-pin is a child of payment.card. card-pin is used for card present payments.

Consumer’s Personal Identification Number data are always encrypted.

A card present payment process can be initiated by a POS terminal (PIN pad) transaction processed online (and/or offline). The terminal accepts, encrypts and forwards the cardholder’s PIN.

All card-pin fields are mandatory for payment processes with online PIN.
Field M/O Data Type Size Description

data

M

String

24

Encrypted PIN generated by the PIN pad.

encoding

M

String

6

PIN data encoding method.
Allowed values:

  • hex

  • base64

format

M

String

5

PIN block format according to ISO 9564.
Allowed values:

  • ISO-0

  • ISO-1

  • ISO-3

encryption-context
card-raw

card-raw is a child of payment.card.

card-raw data is used, when the consumer uses a mobile device in a card present payment process.
For mobile device initiated transactions, there is typically a backend server that integrates to the Wirecard Payment Gateway for payment transactions processing. This is to ensure that the credentials connecting to the gateway are not published in mass consumer devices.

If card-raw.data is submitted, all the other card-raw fields below are mandatory.
Field M/O Data Type Size Description

data

O

String

256

Encrypted card details directly from card reader.

encoding

M/O

String

6

Raw card data encoding method.
Accepted values:

  • hex

  • base64

format

M/O

String

30

Raw data format.

encryption-context
card-token
Field M/O Datatype Size Description

masked-account-number

O

String

36

The masked version of card.account-number of the consumer, e.g. 440804******7893.

token-ext-id

O

String

36

Identifier used for the credit card in the external system which is used in mapping to token-id.

token-id

M/O

String

36

The token corresponding to the card.account-number of the consumer.
It is mandatory if card.account-number is not specified.
It is unique per instance.
cryptogram
Field M/O Datatype Size Description

cryptogram-type

M/O

String

1024

Name of payment method for which a cryptogram is created.

cryptogram-value

M/O

String

1024

Encrypted payment data. Typically used in place of an account-number or token-id.
custom-fields.custom-field
Field M/O Datatype Size Description

@field-name

O

String

36

Merchant-defined name of the custom field.

@field-value

O

String

256

Content of the merchant-defined custom field. In this field you can send additional information.
device
Field M/O Datatype Size Description

fingerprint

O

String

4096

Information collected about a remote computing device for the purpose of identification. Fingerprints can be used to fully or partially identify individual users or devices even when cookies are turned off.
encryption-context

encryption-context is a child of

payment.card.card-pin and payment.card.card-raw are used for card present payments.

All encryption-context fields are mandatory for payment processes with online PIN.
Field M/O Data Type Size Description

algorithm

M/O

String

10

Encryption context algorithm.

parameter

M/O

String

30

Encryption context parameter (hex encoded) to determine the key for decryption.
For PIN management: If dukpt is used as encryption algorithm, this contains the KSN.

padding

M/O

String

5

Encryption context padding.
Accepted value: pkcs

value

M/O

String

40

Encryption context value.

version

M/O

String

3

Encryption context version.
iso

For card present transactions.

Field M/O Datatype Size Description

merchant-id

O

String

15

Merchant identifier for card present device processing.

terminal-id

M

String

16

Terminal identifier for card present device processing.

pos-entry-mode

M

String

4

Specifies the method by which the PAN was entered, according to the first two digits of the ISO 8583:1987 POS Entry Mode.

pos-pin-input-length-capability

O

String

5

Max. terminal PIN length.
mandate
Field M/O Datatype Size Description

mandate-id

M/O

String

35

The ID of the signed mandate between you and the consumer.
The mandate ID is NOT generated by Wirecard Payment Gateway. This is solely your responsibility.
Allowed characters: [A-Za-z0-9][ + ? - : ( ) . , ']){1,35}

due-date

O

String

19

The date that the mandated transaction is due.

signed-date

M/O

String

19

The date when the above-mentioned mandate was signed by the consumer.
The date cannot be in the future, the validity is checked against the server time. You may choose to specify the UTC timezone as +/- number of hours, e.g. <signed-date>2013-09-24+03.00</signed-date>. The timezone is considered during the validation process, signed-date is stored with transaction using the server’s timezone afterwards.
The Mandate Signature Date is only required for SEPA Direct Debit and not for SEPA Credit Transfer transactions.

signed-city

O

String

128

The city in which the mandate was signed.

signature-image

O

String

n/a

The signature of the mandate transaction.
notifications.notification
Field M/O Datatype Size Description

@transaction-state

O

String

12

Status of a transaction that triggers an Instant Payment Notification.

@url

O

String

256

URL to be used for the instant payment notification. Overwrites the notification URL set during merchant configuration.
order-items.order-item
Field M/O Datatype Size Description

name

O

String

256

Name of the item in the shopping basket.

article-number

O

String

256

EAN or other merchant-side article identifier.

amount

M/O

Numeric

18.3

Item’s price per unit.
Use . (decimal point) as separator.

amount/@currency

M

String

3

Currency of this item’s price. Must match the order currency (requested amount currency).
Format: 3-character abbreviation according to ISO 4217.

quantity

O

Numeric

Total number of this item in the shopping basket.

tax-rate

O

Numeric

5,2

Item’s tax rate per unit in percent.
Mandatory if tax-amount is specified.

tax-amount

O

Numeric

5,2

Item’s tax value per unit.
Mandatory if tax-rate is specified.

description

O

String

1024

Description of the item in the shopping basket.

discount

O

Numeric

18.3

The discount value for one order item.
Use . (decimal point) as separator.

type

O

String

n/a

Order item type.
Accepted values:

  • shipment_fee

  • handling_fee

  • discount

  • physical

  • sales_tax

  • digital

  • gift_card

  • store_credit
payment-methods.payment-method
Field M/O Datatype Size Description

@name

M

String

15

Name of the payment method selected by the consumer, e.g. creditcard.

@url

O

String

256

The URL to be used for proceeding with the payment process on provider side.
periodic
Field M/O Datatype Size Description

number-of-installments

M/O

Number

3

Indicates the maximum number of authorizations permitted for installment payments.

Mandatory only for installment payments with periodic-type = installment. Sent in authentication of the first transaction.

periodic-type

M/O

Enumeration

9

Indicates the recurring payment type.
Accepted values:

  • recurring: is used for the recurring payments of a subscription.

  • installment: is used for the partial payments of an installment payment.

  • ucof: (Unscheduled Credential on File) is used to reference a regularly based transaction to an already successfully submitted transaction.

  • ci: (Consumer Initiated) identifies the consumer as the initiator of the transaction.

recurring-expire-date

M/O

Date

10

Date after which recurring payments with this card are no longer allowed. Accepted format: YYYY-MM-DD.

Mandatory only for installment payments with periodic-type = installment. Sent in authentication of the first transaction.

recurring-frequency

M/O

Number

4

Indicates the minimum number of days between individual authorizations.

Mandatory only for recurring payments (installments or subscriptions) with periodic-type = installment or periodic-type = recurring. Sent in authentication of the first transaction.

sequence-type

M/O

Enumeration

9

Indicates the phase of a recurring transaction.
Accepted values:

  • first: is used for the first payment of a recurring series.

  • recurring: is used for all the intermediate payments of a recurring series.

  • final: is used for the last payment of a recurring series.
risk-info
Field M/O Datatype Size Description

availability

O

Enumeration

2

The consumer is placing an order for merchandise that is not yet available and will be released in the future.
Accepted values:

  • 01 = Currently available

  • 02 = Future availability

delivery-mail

O

String

254

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

delivery-timeframe

O

Enumeration

2

The approximate delivery time.
Accepted values:

  • 01 = Electronic delivery

  • 02 = Same-day delivery

  • 03 = Overnight delivery

  • 04 = Two-day or more delivery

preorder-date

O

Date

10

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

reorder-items

O

Enumeration

2

Specifies whether the consumer has previously ordered the same item.
Accepted values:

  • 01 = First-time order

  • 02 = Reorder

gift-cards.gift-card
risk-info.gift-cards.gift-card
Field M/O Datatype Size Description

@id

O

Number

2

For prepaid and gift card purchase only. Identifies individual gift cards. Information about up to 10 gift cards can be sent in one request.
Accepted values:
A number that ranges from 1 to 10.

amount

O

Decimal

18.2

For prepaid and gift card purchase only. The amount paid with a specific gift card. The field allows decimal values (e.g. 10.50).

amount/@currency

O

String

3

For prepaid and gift card purchase only. The ISO 4217 three-digit currency code of the gift card.
shipping

shipping is a child of payment. For 3D Secure 2 transactions it is highly recommended to send shipping data in any case, as a complete set of shipping data reduces the likelihood of a challenge.

Field M/O Datatype Size Description

first-name

M/O

String

32

The first name given in the consumer’s shipping information.
Mandatory for credit card.

last-name

M/0

String

32

The last name given in the consumer’s shipping information.
Mandatory for credit card.

phone

O

String

32

Phone number given in the consumer’s shipping information.

email

O

String

64

Email address given in the consumer’s shipping information.

return-shipping-company

O

String

36

Company that handles the return delivery.

return-tracking-number

O

String

64

The delivery tracking number of the return.

return-tracking-url

O

String

2000

URL for tracking the delivery of the return.

shipping-company

O

String

64

Company that delivers the order to the recipient.

shipping-method

O

Enumeration

The shipping method chosen by the consumer.
Use the shipping indicator value that applies most accurately to the shipping method. If the consumer checks out two or more items, use the shipping indicator value for physical goods. If all goods are digital goods, use the shipping indicator value that matches the most expensive item.
Accepted values:

  • home_delivery: Ship to consumer’s billing address.

  • verified_address_delivery: Ship to another address which you know and have verified.

  • other_address_delivery: Ship to an address that differs from the consumer’s billing address.

  • store_pick_up: "Ship to Store" / Pick-up at local store (store address in shipping address fields).

  • digital_goods: Digital goods (includes online services, electronic gift cards, and redemption codes).

  • digital_tickets: Travel and event tickets, not shipped.

  • other_verified: Other (e.g. gaming, digital services, e-media subscriptions)

  • own_delivery: Ship directly to the consumer’s shipping address via your own delivery service.

  • registered_box: Ship to a delivery box where the consumer needs to be registered to pick them up, e.g. DHL Packstation.

  • unregistered_box: Ship to a delivery box where the consumer does not need to be registered to pick them up, e.g. Itella smartpost, Hermes PaketShop.

  • pick_up_point: Ship to a manned pick-up point by an external shipping company. External personnel hands over goods to the consumer.

tracking-number

O

String

64

The shipping tracking number.

tracking-url

O

String

2000

URL for tracking the shipping.

address
sub-merchant-info

sub-merchant-info is a child of payment. sub-merchant-info fields are required for the Payment Facilitator. If you want to use sub-merchant-info, all the fields in this table are mandatory in the first request of a transaction flow. We recommend to send sub-merchant-info with each transaction step during the payment process. Otherwise, some transactions cannot be completed successfully.
state is an exception. See state description for details.

sub-merchant-info fields may only contain standard ASCII characters.
Field M/O Data Type Size Description

id

M/O

String

36

Unique ID of the sub-merchant.

name

M/O

String

64

Sub-merchant’s name

country

M/O

String

3

Country in which the sub-merchant is located.

state

M/O

String

32

Mandatory if country = US or CA.
If country is neither US nor CA, do not send this field.

city

M/O

String

32

City in which the sub-merchant is located.

street

M/O

String

38

Street in which the sub-merchant is located.

postal-code

M/O

String

16

Postal code of the sub-merchant’s address.

payment-facilitator-id

M/O

String

8 or 11

Unique identifier of the Payment Facilitator.
From each scheme the Payment Facilitator receives a different ID.
Accepted values:

  • 8 alphanumeric characters for UPI.

  • 11 numeric characters for Mastercard and Visa.

  • For JCB no value is needed.

For details contact Merchant Support.
surcharge
Field M/O Datatype Size Description

surcharge-amount

O

Decimal

18,6

Amount added to the original transaction amount based on the respective surcharge rates. The number of decimals depends on the currency.

original-requested-amount

Response only

Decimal

18,6

Full amount that is requested/contested in the original transaction. The number of decimals depends on the currency.

original-requested-amount/@currency

Response only

String

3

Currency in which the original transaction is received and processed.
statuses.status
Field M/O Datatype Size Description

@code

Response only

String

12

The status code of a transaction. Primarily used in conjunction with the transaction state to determine the exact details of the status of the transaction.
→ Complete list of status codes.

@description

Response only

String

512

Text used to describe the transaction status.

@severity

Response only

Enumeration

20

The severity of the transaction, can be information, warning or error.
three-d
Field M/O Datatype Size Description

acs-url

M/O

String

2048

Issuer URL. You need to direct the enrollment-check request via the cardholder’s browser to this URL. It is returned only if the cardholder is enrolled in the 3D Secure program.
Mandatory for 3D Secure 2 payments.

attempt-three-d

O

String

1

Indicates that the transaction request should proceed with the 3D Secure 1 workflow if the consumer is enrolled. Otherwise, the transaction proceeds without 3D Secure 1. This field is used for transactions with the Hosted Payment Page (Wirecard Payment Page v1).

cardholder-authentication-status

M/O

String

1

Status of the 3D Secure check.
Mandatory for 3D Secure 2 payments.

cardholder-authentication-value

M/O

String

1024

A cryptographic value generated by the issuer. Used for

  • Visa’s Cardholder Authentication Verification Value (CAVV) and

  • Mastercard’s

    • Accountholder Authentication Value (AAV) and

    • Universal Cardholder Authentication Field (UCAF).

Mandatory for 3D Secure 2 payments.

ds-transaction-id

M/O

String

36

Universally unique transaction identifier assigned by the Directory Server to identify a single transaction.
Mandatory for external 3D Secure servers not provided by Wirecard.
Accepted format: see IETF RFC 4122.

eci

M/O

String

2

Indicates the status of the VERes.
Mandatory for 3D Secure 2 payments.

pareq

M/O

String

16000

A base64-encoded request message created for cards participating in the 3D Secure program. The PaReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to you.
Mandatory for 3D Secure 2 payments.

pares

M/O

String

2048

Issuer URL. You need to direct the enrollment-check request via the consumer’s browser to this URL. It is returned only if the cardholder is enrolled in the 3D Secure program.
Mandatory for 3D Secure 2 payments.

riid

O

Enumeration

2

Indicates the type of 3RI request.
Accepted values:

* 01 = Recurring transaction
* 02 = Installment transaction
* 03 = Add card
* 04 = Maintain card information
* 05 = Account

server-transaction-id

O

String

36

Universally unique transaction identifier assigned by the 3DS server to identify a single transaction.
If not specified, Netcetera 3DS server generates a UUID.

status-reason

O

String

Mapping of EMVCo error messages to Wirecard Payment Gateway messages.

version

O

Enumeration

5

Identifies the version of 3D Secure authentication used for the transaction.
Accepted values:

  • 1.0

  • 2.1

Uses default value 1.0 if the version is not provided in the request.

xid

M/O

String

36

The unique transaction identifier.
Mandatory for 3D Secure 2 payments.

liability-shift-indicator

Response only

String

2048

Liability shift can be enabled for 3D Secure consumers.
airline-industry
Field M/O Datatype Size Description

airline-code

O

String

3

The airline code assigned by IATA.

airline-name

O

String

64

Name of the airline.

passenger-code

O

String

10

The file key of the passenger name record (PNR). This information is mandatory for transactions with AirPlus UATP cards.

passenger-name

O

String

64

The name of the airline transaction passenger.

passenger-phone

O

String

32

The phone number of the airline transaction passenger.

passenger-email

O

String

64

The email address of the airline transaction passenger.

passenger-ip-address

O

String

45

The IP address of the airline transaction passenger.

ticket-issue-date

O

Date

n/a

The date the ticket was issued.

ticket-number

O

String

11

The airline ticket number, including the check digit. If no airline ticket number (IATA) is used, the element field must be populated with 99999999999.

ticket-restricted-flag

O

Token

1

Indicates that the airline transaction is restricted.
0 = No restriction
1 = Restricted (non-refundable).

pnr-file-key

O

String

10

The passenger name File id for the airline transaction.

ticket-check-digit

O

Short

2

The airline ticket check digit.

agent-code

O

String

3

The agency code assigned by IATA.

agent-name

O

String

64

The agency name.

non-taxable-net-amount

O

Decimal

7.2

This field must contain the net amount of the purchase transaction in the specified currency for which the tax is levied. Two decimal places are implied. If this field contains a value greater than zero, the indicated value must differ to the content of the transaction amount.

number-of-passengers

O

Short

3

The number of passengers on the airline transaction.

reservation-code

O

String

32

The reservation code of the airline Transaction passenger.
airline-industry.ticket-issuer
Field M/O Datatype Size Description

street1

O

String

128

The issuer address street for the airline transaction.

street2

O

String

128

The issuer address street 2 for the airline transaction.

city

O

String

32

The city of the address of the airline transaction issuer.

state

O

String

32

The state of the address of the airline transaction issuer.

country

O

Token

3

The Issuer address country Id for the airline transaction.

postal-code

O

String

16

An alphaNumber numeric code used to represent the airline transaction issuer postal code.
airline-industry.itinerary.segment
Field M/O Datatype Size Description

carrier-code

O

String

3

The 2-letter airline code (e.g. LH, BA, KL) supplied by IATA for each leg of a flight.

departure-airport-code

O

String

3

The departure airport code. IATA assigns the airport codes.

departure-city-code

O

String

32

The departure city code of the itinerary segment. IATA assigns the airport codes.

arrival-airport-code

O

String

3

The arrival airport code of the itinerary segment. IATA assigns the airport codes.

arrival-city-code

O

String

32

The arrival city code of the itinerary segment. IATA assigns the airport codes.

departure-date

O

Date

n/a

The departure date for a given leg.

arrival-date

O

Date

n/a

The arrival date of the itinerary segment. IATA assigns the airport codes.

flight-number

O

String

6

The flight number of the itinerary segment.

fare-class

O

String

3

Used to distinguish between First Class, Business Class and Economy Class, but also used to distinguish between different fares and booking codes within the same type of service.

fare-basis

O

String

6

Represents a specific fare and class of service with letters, numbers, or a combination of both.

stop-over-code

O

Token

1

0 = allowed
1 = not allowed

tax-amount

O

Decimal

18.6

The amount of the value added tax levied on the transaction amount in the specified currency.
cruise-industry
Field M/O Datatype Size Description

carrier-code

O

String

3

The airline code assigned by IATA.

agent-code

O

String

8

The agency code assigned by IATA.

travel-package-type-code

O

String

10

This indicates if the package includes car rental, airline flight, both or neither.
Accepted values:
C = Car rental reservation included
A = Airline flight reservation included
B = Both car rental and airline flight reservations included
N = Unknown

ticket-number

O

String

15

The ticket number, including the check digit.

passenger-name

O

String

100

The name of the passenger.

lodging-check-in-date

O

Date

n/a

The cruise departure date also known as the sail date.

lodging-check-out-date

O

Date

n/a

The cruise return date also known as the sail end date.

lodging-room-rate

O

Numeric

n/a

The total cost of the cruise.

number-of-nights

O

Short

3

The length of the cruise in days.

lodging-name

O

String

100

The ship name booked for the cruise.

lodging-city-name

O

String

20

The name of the city where the lodging property is located.

lodging-region-code

O

String

10

The region code where the lodging property is located.

lodging-country-code

O

String

10

The country code where the lodging property is located.
cruise-industry.itinerary.segment
Field M/O Datatype Size Description

carrier-code

O

String

3

The 2-letter airline code (e.g. LH, BA, KL) supplied by IATA for each leg of a flight.

departure-airport-code

O

String

3

The destination airport code. IATA assigns the airport codes.

departure-city-code

O

String

32

The departure city code of the itinerary segment. IATA assigns the airport codes.

arrival-airport-code

O

String

3

The arrival airport code of the itinerary segment. IATA assigns the airport codes.

arrival-city-code

O

String

32

The arrival city code of the itinerary segment. IATA assigns the airport codes.

departure-date

O

Date

n/a

The departure date for a given leg.

arrival-date

O

Date

n/a

The arrival date of the itinerary segment.

flight-number

O

String

6

The flight number of the itinerary segment.

fare-class

O

String

3

Used to distinguish between First Class, Business Class and Economy Class, but also used to distinguish between different fares and booking codes within the same type of service.

fare-basis

O

String

6

Represents a specific fare and class of service with letters, numbers, or a combination of both.

stop-over-code

O

Token

1

0 = allowed
1 = not allowed

tax-amount

O

Decimal

18.6

The amount of the value added tax levied on the transaction amount in the specified currency.
hotel-industry
Field M/O Datatype Size Description

hotel-code

O

String

20

This is the hotel code.

hotel-name

O

String

32

This is the hotel name.

hotel-segment/hotel-folio-number

O

String

25

Contains the card acceptor’s internal invoice or billing ID reference number.

reservation-confirmation-number

O

String

64

This is the guest’s booking reference.

guest-first-name

O

String

20

This is the first name of the guest.

guest-last-name

O

String

20

This is the last name of the guest.

company

O

String

20

This is the company name of the guest.

check-in-date

O

Date

10

This is the date when the guest is scheduled to check-in.

check-out-date

O

Date

10

This is the date when the guest is scheduled to check-out.

no-show

O

Token

1

Indicates whether or not the guest showed up after having made a reservation for a vehicle or lodging.
0 = guest arrived
1 = no-show (guest did not show up).
If not provided, 0 will be set as default value.

agent-code

O

String

8

This is the code of the agency that initiated the reservation.

agent-name

O

String

26

This is the name of the agency that initiated the reservation.

hotel-phone-number

O

String

32

Identifies the specific lodging property location by its local phone number.

service-phone-number

O

String

32

This is the customer service phone number.

total-room-nights

O

Short

4

Provides the total number of nights a room was contracted for a lodging stay.

daily-room-rate

O

money

13

Contains the daily room charges exclusive of taxes and fees.

total-room-tax

O

money

14

Contains tax amount information such as the daily room tax, occupancy tax, energy tax, and tourist tax.

non-room-charges

O

money

14

Contains the total amount of non-room charges, such as no-show or canceling.

telephone-fax-charges

O

money

13

Contains the total amount of charges for all phone calls.

gift-shop-purchases

O

money

13

Contains the total amount of all gift shop and specialty shop charges.

movie-charges

O

money

13

Provides the total amount charged for in-room movies.

health-club-charges

O

money

13

Provides the total amount charged for health club use and supplies.

business-center-charges

O

money

13

Provides the total amount charged for business center use and supplies.

laundry-charges

O

money

13

Contains the total amount of cleaning charges.

food-beverages-minibar-charges

O

money

13

Contains the total amount of in-room "mini-bar" service charges.

parking-valet-charges

O

money

13

Contains the total amount of charges associated with the use of valet services.

cash-advances

O

money

14

This is the total amount of advance payments received before/during the lodging.
avs

The Address Verification System (AVS) is an advanced credit card security service that is integrated in the Wirecard credit card processing network to help thwart identity theft.

Field Data Type Size Description

result-code

String

5

AVS result code.

result-message

String

256

AVS result message.

provider-result-code

String

5

AVS provider result code.

provider-result-message

String

256

AVS provider result message.

→ Complete list of Wirecard result codes and messages.

Field Definitions

Name

The field name structure is based on the hierarchical relation between individual elements.
Example: order-items.order-item.article-number

XML Structure
<payment>
    <order-items>
        <order-item>
            <article-number> </article-number>
        </order-item>
    </order-items>
</payment>

In the example, the parent element is order-items, and its child order-item.
order-item itself is also a parent element of its child article-number. The hierarchies are separated by a dot .
Attributes are indicated by an @

Cardinality

Cardinality indicates if the field is necessary for the request to work. A field can be either mandatory (M) or optional (O):

  • Mandatory: The field must be included in each request and must contain a valid value. Without this field, the request fails.

  • Optional: The field can, but does not have to be, included in a request. Including optional fields can have certain advantages which we list in the respective field description.

Some fields can be mandatory for individual requests, depending on transaction type and payment scenario. We list them as M/O. See the field description for more information on the respective field’s cardinality.

Example:merchant-account-id is listed as M/O.

Some transactions require a merchant-account-id, others a merchant-account-resolver-category. These two fields shall be used complementary, depending on the context which is explained in the description field.

Data Types

Data types define the input values that can be used for a field.

Data Type Description

String

A combination of text and numbers which is arbitrary but finite in size. A subset of String values can be defined according to a pattern value, such as api-id. The pattern is given in the Description column.

Enumeration

A subset of String. Enumeration consists of a list of predefined values, e.g. the severity of a status, which can provide the predefined values warning, error and information.

Boolean

Has one of two possible values (usually either true or false).

Date

Value taken from a calendar (e.g. the date of birth).
Format (according to ISO 8601): YYYY-MM-DD
This pattern cannot be customized.

Timestamp

A moment in time defined by a system.
Format (according to ISO 8601): YYYY-MM-DDThh:mm:ssZ
This pattern cannot be customized.

Decimal

A numeric value which has digits before and after the decimal point .
Example: the amount of money in a specific currency (e.g. 138.53 EUR).

Number

A numeric value that has no decimal places, such as the expiration month of a credit card.
Size

Size shows how many characters can be used for this field. We provide the maximum value so you can make sure the whole amount of characters is processed.

In general, the Wirecard Payment Gateway allows all characters for each field, depending on the Data Type.

If other rules apply to a field, they are stated in the Description column.

← FAQ | Status Codes and Statuses →