Fields

These tables list all the fields used with Wirecard Payment Gateway REST API. The tables cover Fieldname, Cardinality, Datatype, Size and Description.

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

The following elements are mandatory (M), optional (O) or conditional (C) for a request/response/notification. If the respective cell is empty, the field is disregarded or not sent.

Field values must not contain &, <, >.
payment
Fieldname Cardinality Datatype Size Description

merchant-account-id

M

xs:string

36

A unique identifier assigned for every Merchant Account.

merchant-account-id/@ref

M

url

n/a

A reference URL to the Merchant Account. Can be used to retrieve merchant account details over a browser. This information is returned in the response only.

transaction-id

M

uuid

36

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

entry-mode

O

xs:token

n/a

The method in which the account holder information was collected. Possible values are:

Value Meaning

empty

unknown source

ecommerce

collected over the internet

mcommerce

collected over mobile devices

mail-order

collected over mail order

telephone-order

collected over telephone

pos

collected by the primary payment instrument

transaction-type

M

xs:token

n/a

Determines a transaction’s behavior during transaction processing and merchant settlement. Examples are: authorization, capture, credit, purchase, refund, void authorization, void capture, void credit, void purchase.

transaction-state

M

xs:token

n/a

The current status of a transaction. Typically, a transaction will start from an "in-progress" state, and then finish in either the "success" or "failed" state. This information is returned in the response only.

completion-time-stamp

M

xs:datetime

n/a

The date and time that a transaction state became either "success" or "failed" in GMT. This information is returned in the response only.

requested-amount

M

xs:decimal

18.2

The only amount that accompanies the transaction when it is created and/or requested. In the case of a sale or refund, this is what the merchant requests. In the case of a chargeback, this is the amount that is being contested.

requested-amount/@currency

M

xs:token

3

This is the currency in which a transaction is received and processed.

parent-transaction-id

O

uuid

36

This references a transaction-id of a previous transaction.

ip-address

O

xs:string

45

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

order-number

O

xs:string

64

Merchant-provided string to store the 'Order Number' for the transaction.

order-detail

O

xs:string

2048

Merchant-provided string to store the 'Order Detail' for the transaction.

descriptor

O

xs:string

64

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

authorization-code

O

xs:token

24

A code generated by the card issuing bank as proof that the transaction request was acknowledged or declined.

avs-code

O

xs:string

24

Code indicating address verification services results.

csc-code

O

xs:string

12

Code indicating card verification value (CVC/CVV) verification results.

creditor-id

O

xs:string

256

The merchant’s creditor ID for the merchant allowing the merchant to process SEPA Direct Debit transactions.

consumer-id

O

xs:string

50

The identifier of the consumer.

api-id

O

xs:token

36

A unique identifier assigned for every API.

api-transaction-id

O

uuid

36

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

redirect-url

C

xs:string

256

The URL to which the account holder will be re-directed 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).

processing-redirect-url

O

xs:string

256

The URL to which the account holder will be re-directed during payment processing. This is normally a page on the merchant’s website.

cancel-redirect-url

O

xs:string

256

The URL to which the account holder will be re-directed after he has cancelled a payment. This is normally a page on the merchant’s website.

fail-redirect-url

O

xs:string

256

The URL to which the account holder will be re-directed after an unsuccessful payment. This is normally a page on the merchant's website notifying the account holder of a failed payment often with the option to try another payment method.

success-redirect-url

O

xs:string

256

The URL to which the account holder will be re-directed after a successful payment. This is normally a success confirmation page on the merchant’s website.

locale

O

xs:string

6

A set of parameters that defines the user’s language, country and any special variant preferences that the user wants to see in their user interface. Typically used in conjunction with Hosted Payment Page.

@self

M

url

n/a

A reference URL to the Payment. Can be used to retrieve payment details over a browser. This information is returned in the response only.

payment-methods

Fieldname

Cardinality

Datatype

Size

Description

payment-methods.payment-method-name

O

xs:string

256

The name of the payment method.

payment-methods.payment-method-url

O

url

256

The URL to redirect the consumer to complete the payment process. This information is returned in the response only.

account-holder
Fieldname Cardinality Datatype Size Description

account-holder/first-name

O

xs:string

32

The first name of the account holder.

account-holder/last-name

M

xs:string

32

The last name of the account holder.

account-holder/email

O

xs:string

64

The email address of the account holder.

account-holder/gender

O

xs:token

1

The gender of the account holder.

account-holder/date-of-birth

O

xs:string

n/a

The date of birth of the account holder.

account-holder/phone

O

xs:string

32

The phone number of the account holder.

account-holder/merchant-crm-id

O

xs:string

64

The merchant CRM identifier for the account holder.

account-holder/social-security-number

O

xs:string

14

The social security number of the account holder.

account-holder/tax-number

O

xs:string

14

The corporare tax number of the account holder (applicable for legal entities).

account-holder.adress
Fieldname Cardinality Datatype Size Description

account-holder/address/street1

O

xs:string

128

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

account-holder/address/street2

O

xs:string

128

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

account-holder/address/city

O

xs:string

32

The city of the address of the account holder.

account-holder/address/state

O

xs:string

32

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

account-holder/address/country

O

xs:token

3

The Country Id of the address of the account holder.

account-holder/address/postal-code

O

xs:string

16

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

shipping
Fieldname Cardinality Datatype Size Description

shipping/first-name

O

xs:string

32

The first name of the shipping address.

shipping/last-name

O

xs:string

32

The last name of the shipping address.

shipping/phone

O

xs:string

32

The phone number of the shipping address.

shipping.address
Fieldname Cardinality Datatype Size Description

shipping/address/street1

O

xs:string

128

The first line of the shipping address.

shipping/address/street2

O

xs:string

128

The second line of the shipping address.

shipping/address/city

O

xs:string

32

The city of the shipping address.

shipping/address/state

O

xs:string

32

The state or province of the shipping address.

shipping/address/country

O

xs:token

3

The Country Id of the shipping address.

shipping/address/postal-code

O

xs:string

16

The postal code or ZIP of the shipping address.

card
Fieldname Cardinality Datatype Size Description

card/account-number

M - Or Card Token

xs:token

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.

card/expiration-month

M - Or Card Token

xs:short

2

The 2-digit representation of the expiration month of the account-number

card/expiration-year

M - Or Card Token

xs:short

4

The 4-digit representation of the expiration year of the account-number

card/card-security-code

Depending on merchant account settings

xs:token

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 MasterCard, Visa and Discover 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.

card/card-type

M - for creditcard

xs:token

15

A card scheme accepted by the processing system. This includes physically issued cards.

card/track-1

O

xs:string

79

Track one is a "track" of information on a credit card that has a 79 character alphanumeric field for information. Normally a credit card number, expiration date and consumer name are contained on track 1.

card/track-2

O

xs:string

40

Track two is a "track" of information on a credit card that has a 40 character field for information. Normally a credit card number and expiration date are contained on track 2.

card-token
Fieldname Cardinality Datatype Size Description

card-token/token-id

O - Or Account Number

uuid

16

A unique identifier assigned for every card token. This is a surrogate value for the primary account number.

card-token/masked-account-number

M

xs:string

16

The masked account number. This information is returned in the response only.

bank-account
Fieldname Cardinality Datatype Size Description

bank-account/iban

O

xs:string

34

The international bank account number (IBAN) required in a bank transfer. It is an international standard for identifying bank accounts across national borders. The current standard is ISO 13616:2007, which indicates SWIFT as the formal registrar.

Allowed characters: [a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{4}[0-9]{7}([a-zA-Z0-9]?){0,16}

bank-account/bic

O

xs:string

15

The bank identifier code (BIC) in bank transfer.

Allowed characters: ([a-zA-Z]{4}[a-zA-Z]{2}[a-zA-Z0-9]{2}([a-zA-Z0-9]{3})

bank-account/account-number

O

xs:string

34

The number designating a bank account used nationally

bank-account/bank-code

O

xs:string

15

The national bank sorting code for national bank transfers

bank-account/bank-name

O

xs:string

100

The name of the consumer’s bank.

bank-account/branch-address

O

xs:string

64

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

bank-account/branch-city

O

xs:string

64

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

bank-account/branch-state

O

xs:string

64

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

order-items
Fieldname Cardinality Datatype Size Description

order-items.order-item.name

O

Alphanumeric

Name of the item in the basket.

order-items.order-item.article-number

O

Alphanumeric

EAN or other article identifier for merchant.

order-items.order-item.amount

O

Number

Item’s price per unit.

order-items.order-item.tax-rate

O

Number

Item’s tax rate per unit.

order-items.order-item.quantity

O

Number

Total count of items in the order.

mandate
Fieldname Cardinality Datatype Size Description

mandate/mandate-id

O

xs:string

35

The mandate Id for the mandate generated between the consumer and the merchant allowing the merchant to debit the consumer’s bank account.

mandate/due-date

O

xs:string

19

The date that the mandate transaction is due.

mandate/signed-date

O

xs:string

19

The date that the mandate was signed.

mandate/signed-city

O

xs:string

128

The city in which the mandate was signed in.

mandate/signature-image

O

xs:string

n/a

The signature of the mandate transaction.

notifications
Fieldname Cardinality Datatype Size Description

notifications/notification/@url

O

url

256

The URL to be used for the instant payment notification.

notifications/notification/@transaction-state

O

xs:token

12

The transaction state, for which the instant payment notification will be sent.

three-d
Fieldname Cardinality Datatype Size Description

three-d/pares

O

xs:string

16000

In a 3-D Secure transaction, this is the digitally signed, base64-encoded authentication response message received from the issuer.

three-d/eci

O

xs:string

256

In a 3-D Secure process, this indicates the status of the VERes.

three-d/xid

O

xs:string

36

In a 3-D Secure process, this is the unique transaction identifier.

three-d/cardholder-authentication-value

O

xs:string

1024

The CAVV is a a cryptographic value generated by the Issuer. For Visa transactions it is called CAVV (Cardholder Authentication Verification Value). For MasterCard it is either called Accountholder Authentication Value (AAV) or Universal Cardholder Authentication Field (UCAF).

three-d/cardholder-authentication-status

O

xs:string

32

The result of the authentication process.

three-d/pareq

O

xs:string

16000

In a 3-D Secure transaction, this is a base64-encoded request message created for cards participating in the 3-D program. The PaReq is returned by the issuer’s ACS via the VISA or MasterCard directory to the Wirecard Payment Gateway and from here passed on to the merchant.

three-d/acs-url

O

xs:string

256

The issuer URL to where the merchant must direct the enrolment check request via the cardholder’s browser. It is returned only in case the cardholder is enrolled in 3-D secure program.

three-d/attempt-three-d

O

xs:boolean

1

Indicates that the transaction request should proceed with the 3D Secure workflow if the [Card Holder] is enrolled. Otherwise, the transaction proceeds without 3D Secure. This field is used in conjunction with Hosted Payment Page (HPP).

device
Fieldname Cardinality Datatype Size Description

device/fingerprint

O

xs:string

4096

A device fingerprint is information collected about a remote computing device for the purpose of identification retrieved on merchants side. Fingerprints can be used to fully or partially identify individual users or devices even when cookies are turned off.

browser
Fieldname Cardinality Datatype Size Description

browser/accept

O

xs:string

2048

This is the HTTP Accept Header as retrieved from the card holder’s browser in the HTTP request. In case it is longer than 2048 it has to be truncated. It is strongly recommended to provide this field to prevent rejections from ACS server side.

browser/user-agent

O

xs:string

256

This is the User Agent as retrieved from the card holder’s browser in the HTTP request. In case it is longer than 256 Byte it has to be truncated. It is strongly recommended to provide this field to prevent rejections from ACS server side.

custom-fields
Fieldname Cardinality Datatype Size Description

custom-fields/custom-field/@field-name

O

xs:string

36

The merchant defined name of the custom field.

custom-fields/custom-field/@field-value

O

xs:string

36

The merchant defined name of the custom field.

periodic
Fieldname Cardinality Datatype Size Description

periodic.periodic-type

O

xs:token

n/a

Indicates how and why a payment occurs more than once. Possible values include 'installment': one in a set that completes a financial transaction and 'recurring': one in a set that occurs repeatedly, such as a subscription.

cryptogram
Fieldname Cardinality Datatype Size Description

cryptogram/cryptogram-type

M

xs:string

1024

Name of payment method for which a cryptogram is created.

cryptogram/cryptogram-value

M

xs:string

1024

Encrypted payment data. Typically used in place of an account-number or token-id.

statuses
Fieldname Cardinality Datatype Size Description

statuses/status/@code

M

xs:string

12

The status of a transaction. This is primarily used in conjunction with the transaction state to determine the exact details of the status of the transaction. This information is returned in the response only.

statuses/status/@description

M

xs:string

512

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

statuses/status/@severity

M

xs:token

20

The severity of the transaction, can be information, warning, or error. This information is returned in the response only.

airline-industry
Fieldname Cardinality Datatype Size Description

airline-industry/airline-code

O

xs:string

3

The airline code assigned by IATA.

airline-industry/airline-name

O

xs:string

64

Name of the airline.

airline-industry/passenger-code

O

xs:string

10

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

airline-industry/passenger-name

O

xs:string

64

The name of the airline transaction passenger.

airline-industry/passenger-phone

O

xs:string

32

The phone number of the airline transaction passenger.

airline-industry/passenger-email

O

xs:string

64

The email address of the airline transaction passenger.

airline-industry/passenger-ip-address

O

xs:string

45

The IP address of the airline transaction passenger.

airline-industry/ticket-issue-date

O

xs:date

n/a

The date the ticket was issued.

airline-industry/ticket-number

O

xs: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.

airline-industry/ticket-restricted-flag

O

xs:token

1

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

airline-industry/pnr-file-key

O

xs:string

10

The passenger name File id for the airline transaction.

airline-industry/ticket-check-digit

O

xs:short

2

The airline ticket check digit.

airline-industry/agent-code

O

xs:string

3

The agency code assigned by IATA.

airline-industry/agent-name

O

xs:string

64

The agency name.

airline-industry/non-taxable-net-amount

O

xs: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.

airline-industry/number-of-passengers

O

xs:short

3

The number of passengers on the airline transaction.

airline-industry/reservation-code

O

xs:string

32

The reservation code of the airline Transaction passenger.

airline-industry/ticket-issuer
Fieldname Cardinality Datatype Size Description

airline-industry/ticket-issuer/street1

O

xs:string

128

The issuer address street for the airline transaction.

airline-industry/ticket-issuer/street2

O

xs:string

128

The issuer address street 2 for the airline transaction.

airline-industry/ticket-issuer/city

O

xs:string

32

The city of the address of the airline transaction issuer.

airline-industry/ticket-issuer/state

O

xs:string

32

The state of the address of the airline transaction issuer.

airline-industry/ticket-issuer/country

O

xs:token

3

The Issuer address country Id for the airline transaction.

airline-industry/ticket-issuer/postal-code

O

xs:string

16

An alphanumeric numeric code used to represent the airline transaction issuer postal code.

airline-industry/itinerary/segment
Fieldname Cardinality Datatype Size Description

airline-industry/itinerary/segment/carrier-code

O

xs:string

3

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

airline-industry/itinerary/segment/departure-airport-code

O

xs:string

3

The departure airport code. IATA assigns the airport codes.

airline-industry/itinerary/segment/departure-city-code

O

xs:string

32

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

airline-industry/itinerary/segment/arrival-airport-code

O

xs:string

3

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

airline-industry/itinerary/segment/arrival-city-code

O

xs:string

32

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

airline-industry/itinerary/segment/departure-date

O

xs:date

n/a

The departure date for a given leg.

airline-industry/itinerary/segment/arrival-date

O

xs:date

n/a

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

airline-industry/itinerary/segment/flight-number

O

xs:string

6

The flight number of the itinerary segment.

airline-industry/itinerary/segment/fare-class

O

xs: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.

airline-industry/itinerary/segment/fare-basis

O

xs:string

6

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

airline-industry/itinerary/segment/stop-over-code

O

xs:token

1

0 = allowed, 1 = not allowed

airline-industry/itinerary/segment/tax-amount

O

xs:decimal

18.6

The amount of the value added tax levied on the transaction amount in the specified currency.

cruise-industry
Fieldname Cardinality Datatype Size Description

cruise-industry/carrier-code

O

xs:string

3

The airline code assigned by IATA.

cruise-industry/agent-code

O

xs:string

8

The agency code assigned by IATA.

cruise-industry/travel-package-type-code

O

xs:string

10

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

cruise-industry/ticket-number

O

xs:string

15

The ticket number, including the check digit.

cruise-industry/passenger-name

O

xs:string

100

The name of the passenger.

cruise-industry/lodging-check-in-date

O

xs:date

n/a

The cruise departure date also known as the sail date.

cruise-industry/lodging-check-out-date

O

xs:date

n/a

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

cruise-industry/lodging-room-rate

O

money

n/a

The total cost of the cruise.

cruise-industry/number-of-nights

O

xs:short

3

The length of the cruise in days.

cruise-industry/lodging-name

O

xs:string

100

The ship name booked for the cruise.

cruise-industry/lodging-city-name

O

xs:string

20

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

cruise-industry/lodging-region-code

O

xs:string

10

The region code where the lodging property is located.

cruise-industry/lodging-country-code

O

xs:string

10

The country code where the lodging property is located.

cruise-industry/itinerary/segment
Fieldname Cardinality Datatype Size Description

cruise-industry/itinerary/segment/carrier-code

O

xs:string

3

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

cruise-industry/itinerary/segment/departure-airport-code

O

xs:string

3

The destination airport code. IATA assigns the airport codes.

cruise-industry/itinerary/segment/departure-city-code

O

xs:string

32

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

cruise-industry/itinerary/segment/arrival-airport-code

O

xs:string

3

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

cruise-industry/itinerary/segment/arrival-city-code

O

xs:string

32

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

cruise-industry/itinerary/segment/departure-date

O

xs:date

n/a

The departure date for a given leg.

cruise-industry/itinerary/segment/arrival-date

O

xs:date

n/a

The arrival date of the itinerary segment.

cruise-industry/itinerary/segment/flight-number

O

xs:string

6

The flight number of the itinerary segment.

cruise-industry/itinerary/segment/fare-class

O

xs: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.

cruise-industry/itinerary/segment/fare-basis

O

xs:string

6

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

cruise-industry/itinerary/segment/stop-over-code

O

xs:token

1

0 = allowed, 1 = not allowed

cruise-industry/itinerary/segment/tax-amount

O

xs:decimal

18.6

The amount of the value added tax levied on the transaction amount in the specified currency.

hotel-segment
Fieldname Cardinality Datatype Size Description

hotel-segment/hotel-code

O

xs:string

20

This is the hotel code.

hotel-segment/hotel-name

O

xs:string

32

This is the hotel name.

hotel-segment/hotel-folio-number

O

xs:string

25

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

hotel-segment/reservation-confirmation-number

O

xs:string

64

This is the guest’s booking reference.

hotel-segment/guest-first-name

O

xs:string

20

This is the first name of the guest.

hotel-segment/guest-last-name

O

xs:string

20

This is the last name of the guest.

hotel-segment/company

O

xs:string

20

This is the company name of the guest.

hotel-segment/check-in-date

O

xs:date

10

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

hotel-segment/check-out-date

O

xs:date

10

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

hotel-segment/no-show

O

xs: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.

hotel-segment/agent-code

O

xs:string

8

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

hotel-segment/agent-name

O

xs:string

26

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

hotel-segment/hotel-phone-number

O

xs:string

32

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

hotel-segment/service-phone-number

O

xs:string

32

This is the customer service phone number.

hotel-segment/total-room-nights

O

xs:short

4

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

hotel-segment/daily-room-rate

O

money

13

Contains the daily room charges exclusive of taxes and fees.

hotel-segment/total-room-tax

O

money

14

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

hotel-segment/non-room-charges

O

money

14

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

hotel-segment/telephone-fax-charges

O

money

13

Contains the total amount of charges for all phone calls.

hotel-segment/gift-shop-purchases

O

money

13

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

hotel-segment/movie-charges

O

money

13

Provides the total amount charged for in-room movies.

hotel-segment/health-club-charges

O

money

13

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

hotel-segment/business-center-charges

O

money

13

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

hotel-segment/laundry-charges

O

money

13

Contains the total amount of cleaning charges.

hotel-segment/food-beverages-minibar-charges

O

money

13

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

hotel-segment/parking-valet-charges

O

money

13

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

hotel-segment/cash-advances

O

money

14

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

Custom URL: