Credit Card

REST API

Payment Mode, Countries and Currencies

Payment Mode

Online Bank Transfer, Offline Bank Transfer

Countries

Depends on the licensed area of the financial institution/acquirer. Wirecard Bank, for example, is licensed to process payments globally.

Currencies

VISA and MC support basically all currencies. For more information, go to their respective manuals. JCB and UPI require an explicit setup of transaction currencies as part of the acquirer license agreement.
Communication Formats

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

Requests

Format

XML

Methods

POST

Responses

Format

XML

Methods

POST

IPN Encodement

Please follow the instructions given at Instant Payment Notification to set up IPN.
Test Credentials

URL (Endpoint)

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

Refer to one of the following tables to complete your test credentials:

Non-3D (Manual Card Brand Recognition) Demo

Merchant Account ID (MAID)

1b3be510-a992-48aa-8af9-6ba4c368a0ac

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APIDEMO-CARD

Password to access Test Account

ohysS0-dvfMx

Secret Key

33a67608-9822-43c2-acc1-faf2947b1be5

Mobile SDK Applicable

No
Non-3D (Manual Card Brand Recognition) Test

Merchant Account ID (MAID)

9105bb4f-ae68-4768-9c3b-3eda968f57ea

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

d1efed51-4cb9-46a5-ba7b-0fdc87a66544

Mobile SDK Applicable

Yes
3D (Manual Card Brand Recognition) Test

Merchant Account ID (MAID)

33f6d473-3036-4ca5-acb5-8c64dac862d1

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

9e0130f6-2e1e-4185-b0d5-dc69079c75cc

Mobile SDK Applicable

Yes
Non-3D (Automatic Card Brand Recognition) Demo

Merchant Account ID (MAID)

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

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APIDEMO-CARD

Password to access Test Account

ohysS0-dvfMx

Secret Key

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

Mobile SDK Applicable

No
Non-3D (Automatic Card Brand Recognition) Test

Merchant Account ID (MAID)

07edc10b-d3f9-4d12-901f-0db7f4c7e75c

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

65f1d302-b2ac-4c52-8e31-5cc5351a258b

Mobile SDK Applicable

Yes
3D (Automatic Card Brand Recognition) Test

Merchant Account ID (MAID)

cad16b4a-abf2-450d-bcb8-1725a4cef443

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

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

Mobile SDK Applicable

Yes
Original Credit Transaction (OCT) Test

Merchant Account ID (MAID)

86687a11-3f9b-4f30-be54-8f22998b6177

Merchant Account Name

Merchant-Test-Accounts

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

dce5ebea-28f0-4fce-b087-85465a138a83

Mobile SDK Applicable

Yes
Non-3D Non-Gambling Original Credit Transaction (OCT) Test

Merchant Account ID (MAID)

1d08d0ea-535e-4b1a-b50b-d1591e97b8ea

Merchant Account Name

Merchant-Test-Accounts

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

1ddab375-08da-4704-83da-36610518efcf

Mobile SDK Applicable

Yes
3D Non-Gambling Original Credit Transaction (OCT) Test

Merchant Account ID (MAID)

ba90c606-5d0b-45b9-9902-9b0542bba3a4

Merchant Account Name

Merchant-Test-Accounts

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

b30bf3cc-f365-4929-89e9-d1cbde890f84

Mobile SDK Applicable

Yes
Payment Solutions

As payment solutions the Wirecard Payment Gateway provides Pay by Link via API and Invoice via Email. They both are currently only used with a Payment Page integration.

You can find

Transaction Types

This section describes Credit Card transaction types that can be used with the Wirecard Payment Gateway. For each transaction type we provide a Credit Card specific introduction. We explain the transaction type’s availability and restrictions. We look at the conditions or preconditions required to process this transaction type.

You get the best knowledge of our transaction types when you send an XML request to our endpoint. We describe the content and structure of these requests in the section "Sending Data". For reference we also provide a response that can be expected. Where applicable we set up a flow of subsequent transaction types (e.g. authorization > capture-authorization). Refer to the complete field list for credit card transactions.

In <statuses> of the response you will find a number that represents a status code.

Update of Refund Transactions for Mastercard and Visa
Advantages

  • Faster, easier refund processing.

  • No changes in the refund-request (refund-capture, refund-purchase).

  • Enhanced consumer experience: Successful refunds show up immediately in your consumers' bank statements.

We are updating refund transactions for credit card (Mastercard and Visa).

With the update, the response to a refund-request returns the authorization-code as follows:

  • If your refund-request is successful, the authorization-code contains a 6-digit value.

  • If the issuer declines the refund-request, the authorization-code does not contain a value. Please refer to statuses.status.code for more details.

In Wirecard Payment Gateways, this feature will be fully functional as of 25 May 2020 for eCommerce, POS and MOTO.

The authorization-code does not contain a value prior to that date.

For Mastercard and Visa, the online refund mandate takes effect on 17 July 2020 for all merchants except airlines. The previously scheduled date (17 April 2020) had to be postponed due to the current COVID-19 situation.
List of Transaction Types

Please read about details for the transaction types authorization, capture-authorization and purchase.

authorization

Reserves funds from the cardholder’s account. Typically, the limit ranges from three to thirty days to conduct a capture-authorization, depending on the acquirer and card brand.

authorization-only

Verifies the card’s validity without leaving an authorized amount.

authorization-supplementary

Reserves additional funds from the cardholder’s account following an authorization. Typically, the limit ranges from three to thirty days to conduct a capture-authorization, depending on the acquirer and card brand.

This transaction type is not included in default configuration.
For further information please contact: support@wirecard.com

preauthorization

Reserves funds from the cardholder’s account. Typically, the limit ranges from three to thirty days to conduct a capture-preauthorization, depending on the acquirer and card brand.

Mastercard allows up to 30 days to conduct a capture-preauthorization depending on the configuration.

capture-authorization

Takes funds from the cardholder’s account. Must follow an authorization or authorization-supplementary chain.

Typically, a capture-authorization captures either part of or the full authorized amount. If you want to capture an amount higher than initially authorized, your merchant account needs to be configured accordingly (details see overcapturing).

check-enrollment

check-enrollment consists of a single request/response communication that verifies, if the card number is eligible and participates in the 3D program.

check-payer-response

check-payer-response forwards the PARes, which is a digitally signed XML document to WPG for validation.

check-risk

Checks the risk profile of the transaction information, without submitting a payment.

This transaction type is not included in default configuration.
For further information please contact: support@wirecard.com

credit

Moves funds from the merchant account to the cardholder’s account.

enrollment

Enrolls a credit card for a loyalty program.

original-credit

Moves funds to the cardholder’s account, without referring to an eligible purchase or capture (i.e. non-referenced). This transaction type can be used for gambling and non-gambling processes.

purchase

Takes funds from the cardholder’s account. A one-step process to conduct two transaction types: authorization and capture.

referenced-authorization

Reserves funds from the cardholder’s account. Identical to a authorization except for the fact that it refers to a previous authorization in the context of recurring transactions. See details for referencing a transaction.

referenced-purchase

Takes funds from the cardholder’s account. Identical to a purchase except for the fact that it refers to a previous purchase in the context of recurring transactions.

refund-capture

Moves funds to the cardholder’s account, referring to an eligible capture.

refund-purchase

Moves funds to the cardholder’s account, referring to an eligible purchase.

void-authorization

Frees reserved funds from the cardholder’s account due to an authorization or a chain of authorization-supplementary.

void-authorization-supplementary

Voids an upwardly adjustment of an existing authorization.

void-capture

Frees reserved funds from the cardholder’s account due to a capture.

void-credit

Frees reserved funds from the cardholder’s account due to a credit.

void-original-credit

Frees reserved funds from the cardholder’s account due to an original-credit.

void-preauthorization

Frees reserved funds from the cardholder’s account due to a preauthorization.

void-purchase

Frees reserved funds from the cardholder’s account due to a purchase.

void-refund

Frees reserved funds from the cardholder’s account due to a refund.

void-refund-capture

Frees reserved funds from the cardholder’s account due to a refund-capture.

void-refund-purchase

Frees reserved funds from the cardholder’s account due to a refund-purchase.
void vs. refund

It is often the case that the merchants must withdraw an online shopping process. When the consumer wants to buy a product or service online, Wirecard Payment Gateway (WPG) initiates a payment process. When the merchants withdraw this process, they can stop the process in two ways. Either with a void or a refund.

A void is only possible as long as no money transfer has been initiated. As soon as WPG has initiated the payment flow to the acquirer the merchants must return the funds to the consumer via a refund process.

Workflow

Voiding a transaction requires a reference to the transaction that shall be voided.

The void transaction contains a <parent-transaction-id> that refers to the <transaction-id> of the transaction that shall be voided.

Here is an example how to void a capture.

void_workflow
refund
refund
Workflow

Refunding a transaction requires a reference to the transaction that shall be refunded.

The refund transaction contains a <parent-transaction-id> that refers to the <transaction-id> of the transaction that shall be refunded.

Here is an example how to refund a capture.

refund_workflow
OCT Eligibility Check

Wirecard Payment Gateway uses the transaction type authorization-only, to find out whether the card in use is eligible for original credit transactions (OCT). If you want to use this eligibility check contact merchant support for details.

authorization

authorization checks the consumer’s account for credibility and reserves a fixed amount of funds. Reservation means that Wirecard Payment Gateway informs the card holder’s issuer about the upcoming transaction. The reservation lasts from three to thirty days, depending on the acquirer and card brand. Within that time the merchants can prepare the selected products or services for shipping. Once the merchants initiate the shipping, they also initiate a capture-authorization which will transfer the authorized amount from the issuer to the acquirer.

authorization, preauthorization or final-authorization
The functionality of an authorization as described in this section can also be configured as preauthorization or final-authorization. Which one shall be your choice, strongly depends on your business case, the acquirer and the credit card brand. Please consult your sales representative for details.
Real-Life Example

Consumers order a dishwasher for 500 EUR online. authorization checks the consumers' account immediately and reserves 500 EUR. When the merchants start the shipping process, a capture-authorization will transfer the 500 EUR from the consumers' to the merchants' account.

Availability and Restrictions

authorization is generally available.

Every authorization request has a time limit depending on the card schemes. The limit refers to the period of time from sending an authorization to sending a capture-authorization. Typically, the limit ranges from three to thirty days, depending on the acquirer and card brand. It is recommended to check the card schemes for details. An authorization may be denied. Some reasons (among others) for the denial are:

  • The consumer’s credit limit is reached.

  • The card was blocked.

  • A fraud case is suspected by the issuer.

  • The card itself expired.

Sequence

An authorization reserves funds on the cardholder’s account. It may be followed by a void-authorization or a capture-authorization. As an authorization merely reserves funds there is only a void possible but no refund.

A capture-authorization may be followed by either a void-capture or a refund-capture.

authorization sequence

See details for void and refund.

Sending Data

We only list samples for requests and responses. Notifications follow the general structure described in General Platform Features.

Are you using Postman to send the requests?

  • If yes, you can use the samples as provided below (Request Header and Request Sample).

  • If no, please replace {{$guid}} with a globally unique ID in <request-id>.

Status Codes

In <statuses> of the response you will find a number that represents a status code.

authorization Using Card Data
Request

If the credit card is used for the first time, the authorization request will contain the clear card data. The first response immediately replaces the explicit card data with a token. The token will be used from then on.

Read how a token replaces the clear credit card data.

Handling clear card data requires a strong degree of PCI DSS compliance. If your PCI DSS compliance is not sufficient, you can use our Wirecard Payment Page v2.

We provide detailed descriptions of all credit card fields.

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>authorization</transaction-type>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <device>
            <fingerprint>D205933_it27sqacgghmsvge83790ocrj7_16432733</fingerprint>
        </device>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card>
        <account-number>4271149787014678</account-number>
        <expiration-month>12</expiration-month>
        <expiration-year>2020</expiration-year>
        <card-security-code>123</card-security-code>
        <card-type>visa</card-type>
    </card>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
</payment>
Response

We provide detailed descriptions of all credit card fields.

<card-token> data replaces the <card> data in the initial response when using the credit card for the first time.
XML authorization 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/3d01299c-c28b-471b-976f-18249cc9d544">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>3d01299c-c28b-471b-976f-18249cc9d544</transaction-id>
    <request-id>0a58d654-d0b0-40ca-bb19-f1eb4933d7cd</request-id>
    <transaction-type>authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-06T15:18:55.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <csc-code>P</csc-code>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <descriptor></descriptor>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>570549</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
authorization Using a Token
Request

If the credit card is already known to the merchant, the authorization request will not contain the clear card data. It will contain the token data instead.

Read how a token replaces the clear credit card data.

We provide detailed descriptions of all credit card fields.

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>authorization</transaction-type>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <device>
            <fingerprint>D205933_it27sqacgghmsvge83790ocrj7_16432733</fingerprint>
        </device>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
</payment>
Response

We provide detailed descriptions of all credit card fields.

XML authorization 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/0036ec58-3011-4b9f-acf3-2f6f8b3f9753">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>0036ec58-3011-4b9f-acf3-2f6f8b3f9753</transaction-id>
    <request-id>3aedafa7-21c7-4620-b1b1-620e81107b6d</request-id>
    <transaction-type>authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-10T11:07:05.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <descriptor></descriptor>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>967507</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>

A successful authorization response can be followed by a void-authorization (details see void).

void-authorization

A void-authorization request must reference a successful authorization response.

Request

We provide detailed descriptions of all credit card fields.

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML void-authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>void-authorization</transaction-type>
    <parent-transaction-id>0036ec58-3011-4b9f-acf3-2f6f8b3f9753</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>
Response

We provide detailed descriptions of all credit card fields.

XML void-authorization 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/242f9dc0-04ec-450c-8246-489d32e3590e">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>242f9dc0-04ec-450c-8246-489d32e3590e</transaction-id>
    <request-id>a99a9b2b-ad21-4233-bab0-d6a2c0bf3517</request-id>
    <transaction-type>void-authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-17T14:59:43.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <parent-transaction-id>878d86d2-f85e-43da-8305-4dcaa347b36f</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">2.500000</parent-transaction-amount>
    <authorization-code>106806</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
capture-authorization
Introduction

A capture-authorization transfers an authorized amount from the consumer bank account to the acquirer (merchant’s bank account).

Real-Life Example

See authorization.

Availability and Restrictions

A capture-authorization must be initiated in a defined period of time after a successful authorization (details see authorization).

Captured Amount
Typically, a capture-authorization captures either part of or the full authorized amount.
Overcapturing
There is also the option to capture an amount that is up to 40% higher than initially authorized. To enable this option, your merchant account needs to be configured accordingly. Please contact merchant support.
Sequence

A capture-authorization follows an authorization.

A void-capture or a refund-capture follows a capture-authorization.

capture-authorization_sequence

See details for void and refund.

Sending Data

We only list samples for requests and responses. Notifications follow the general structure described in General Platform Features.

Are you using Postman to send the requests?

  • If yes, you can use the samples as provided below (Request Header and Request Sample).

  • If no, please replace {{$guid}} with a globally unique ID in <request-id>.

Status Codes

In <statuses> of the response you will find a number that represents a status code.

authorization

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>authorization</transaction-type>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <device>
            <fingerprint>D205933_it27sqacgghmsvge83790ocrj7_16432733</fingerprint>
        </device>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML authorization 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/df92ce59-a39c-4e2d-a5d6-c3f952826acd">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</transaction-id>
    <request-id>127869ec-cfce-4bc8-959a-d48866e3001d</request-id>
    <transaction-type>authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-21T10:45:58.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <descriptor></descriptor>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>570271</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>

A successful authorization may be followed by a

capture-authorization

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML capture-authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>
    <requested-amount currency="USD">2.50</requested-amount>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML capture-authorization 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/76c1fcbf-860e-4793-88b8-b1eed6f22ab0">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>76c1fcbf-860e-4793-88b8-b1eed6f22ab0</transaction-id>
    <request-id>91cdfbd6-2a54-4c5c-b29c-3b4f727586a6</request-id>
    <transaction-type>capture-authorization</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-21T10:54:45.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">2.500000</parent-transaction-amount>
    <authorization-code>570271</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>

A successful capture-authorization may be followed by a

void-capture

A void-capture request must reference a successful capture-authorization response.

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML void-capture Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>void-capture</transaction-type>
    <parent-transaction-id>76c1fcbf-860e-4793-88b8-b1eed6f22ab0</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML void-capture 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/86198107-a392-4df6-92d3-6bf7a8525e71">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>86198107-a392-4df6-92d3-6bf7a8525e71</transaction-id>
    <request-id>b90d6b19-bb56-4272-b794-a6cc94148c6d</request-id>
    <transaction-type>void-capture</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-21T11:02:12.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <parent-transaction-id>76c1fcbf-860e-4793-88b8-b1eed6f22ab0</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">2.500000</parent-transaction-amount>
    <authorization-code>570271</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
refund-capture

A refund-capture request must reference a successful capture-authorization response.

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML refund-capture Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>refund-capture</transaction-type>
    <parent-transaction-id>dce8eb51-d520-48b5-8ae5-897297da6f10</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML refund-capture 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/49fc219a-4821-4e0d-8c26-d9b78c4d0a7e">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>49fc219a-4821-4e0d-8c26-d9b78c4d0a7e</transaction-id>
    <request-id>1db35de9-4414-4159-9852-ffef29d4a195</request-id>
    <transaction-type>refund-capture</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-21T11:35:50.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">2.50</requested-amount>
    <parent-transaction-id>dce8eb51-d520-48b5-8ae5-897297da6f10</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>7049</order-number>
    <order-detail>Test Product</order-detail>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="d37b0e36-d712-11e5-96d8-005056a96a54"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">2.500000</parent-transaction-amount>
    <authorization-code>080119</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
purchase
Introduction

purchase transfers the transaction amount without preceding reservation from the consumer directly to the merchant. With this transaction type merchants collect the money immediately while selling goods or providing a service to the consumers. Merchants use purchase in most of the cases to process POS transactions. It is also used for immediate online payments, such as software downloads.

Merchants can also perform recurring payments using the transaction type purchase. The first payment of a recurring payment process starts with the transaction type purchase which is followed by referenced-purchase transactions.

Real-Life Example

Single Payment

For POS payments, purchase is used when consumers hire a taxi and pay the taxi fare with their credit card. Or the consumers shop in a department store or grocery store and pay at the check out using their credit card.

In an online shopping process, purchase is used when consumers download software, a movie or audio files.

Recurring Payment

When consumers subscribe to a magazine or pay an insurance, they face periodically repeating payments for a certain period of time. When consumers want to pay online, merchants can arrange this type of payment with the transaction type referenced-purchase referencing a purchase transaction.

Availability and Restrictions

No restrictions apply to this transaction type. A purchase is generally available.

A void-purchase can stop a successfully completed purchase (merchant received a success purchase notification) as long as the funds transfer has not been initiated. The same logic applies to void a refund-purchase. That means, a void-refund-purchase can stop a refund-purchase. If merchants want to cancel the purchase after the funds transfer was initiated, they must do it with a refund-purchase.

A referenced-purchase is only possible, if there is a preceding successful purchase transaction to refer to, which contains a <periodic-type> and a <sequence-type>.

Sequence

A purchase can be a stand-alone transaction. It may be followed by a void-purchase, a referenced-purchase or a refund-purchase. A refund-purchase may be followed by a void-refund-purchase.

purchase_sequence

See details for void and refund.

Sending Data

We only list samples for requests and responses. Notifications follow the general structure described in General Platform Features.

Are you using Postman to send the requests?

  • If yes, you can use the samples as provided below (Request Header and Request Sample).

  • If no, replace {{$guid}} with a globally unique ID in <request-id>.

Status Codes

In <statuses> of the response you will find a number that represents a status code.

purchase Using Card Data

Request

If the credit card is used for the first time, the purchase request will contain the explicit card data. The first response immediately replaces the explicit card data with a token. The token will be used from then on.

Read how a token replaces the clear credit card data.

Handling explicit card data requires a strong degree of PCI DSS compliance. If your PCI DSS compliance is not sufficient, you can use our Wirecard Payment Page v2.

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML purchase Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>purchase</transaction-type>
  <requested-amount currency="USD">5.01</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
    <phone></phone>
    <address>
      <street1>123 anystreet</street1>
      <city>Brantford</city>
      <state>ON</state>
      <country>CA</country>
      <postal-code>M4P1E8</postal-code>
    </address>
  </account-holder>
  <card>
    <account-number>4271149787014678</account-number>
    <expiration-month>12</expiration-month>
    <expiration-year>2020</expiration-year>
    <card-type>visa</card-type>
    <card-security-code>123</card-security-code>
  </card>
  <order-number>44152</order-number>
  <order-detail>Test Product</order-detail>
  <ip-address>127.0.0.1</ip-address>
  <payment-methods>
    <payment-method name="creditcard"/>
  </payment-methods>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

<card-token> data replaces the <card> data in the initial response when using the credit card for the first time.

Sample

XML purchase Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/a3296ada-7d63-4131-9b5d-c6d985bb5a48">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>a3296ada-7d63-4131-9b5d-c6d985bb5a48</transaction-id>
    <request-id>8fb52775-77f1-4124-aa7c-60ba672cc7cf</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-11-26T10:11:39.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <csc-code>P</csc-code>
    <requested-amount currency="USD">5.01</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone></phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>44152</order-number>
    <order-detail>Test Product</order-detail>
    <descriptor></descriptor>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>585422</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
purchase Using a Token

Request

If the credit card is already known to the merchant, a token already exists and can be used from the beginning.

Read how a token replaces the clear credit card data.

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML purchase with token Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>purchase</transaction-type>
    <requested-amount currency="USD">1.01</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@example.com</email>
        <phone></phone>
        <address>
            <street1>Example Street 1</street1>
            <city>Example City</city>
            <country>DE</country>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML purchase with token 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/36fc8d02-4ceb-483c-a3ff-929543452df7">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>36fc8d02-4ceb-483c-a3ff-929543452df7</transaction-id>
    <request-id>c6de9490-9815-42c0-b98b-830e7067782b</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-11-28T09:04:42.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">1.01</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@example.com</email>
        <phone></phone>
        <address>
            <street1>Example Street 1</street1>
            <city>Example City</city>
            <country>DE</country>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <descriptor></descriptor>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <authorization-code>038588</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>

A successful purchase response can be followed by

Referencing purchase Transactions

Recurring transactions can be referenced using <parent-transaction-id>.

The following sample set describes a flow of recurring purchase transactions which are connected via <parent-transaction-id>.

The Initial Transaction
The initial transaction is a purchase. It contains a <periodic>: <periodic-type> = recurring and <sequence-type> = first.

The Recurring Transactions
There can be multiple recurring transactions. Each recurring transaction is a referenced-purchase. It contains a <periodic>: <periodic-type> = recurring and <sequence-type> = recurring.

The Final Transaction
The final transaction is a referenced-purchase. It contains a <periodic>: <periodic-type> = recurring and <sequence-type> = final.

The <parent-transaction-id>
<parent-transaction-id> of the referenced-purchase is always the same as <transaction-id> of the initial purchase.

Workflow

ReferencingPurchaseTransactions_Workflow

purchase Request (recurring/first)

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML (recurring/first) purchase Request (Success)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
  <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>purchase</transaction-type>
  <requested-amount currency="USD">5.01</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
    <phone></phone>
    <address>
      <street1>123 anystreet</street1>
      <city>Brantford</city>
      <state>ON</state>
      <country>CA</country>
      <postal-code>M4P1E8</postal-code>
    </address>
  </account-holder>
  <card>
    <account-number>4271149787014678</account-number>
    <expiration-month>12</expiration-month>
    <expiration-year>2020</expiration-year>
    <card-type>visa</card-type>
    <card-security-code>123</card-security-code>
  </card>
  <order-number>44152</order-number>
  <order-detail>Test Product</order-detail>
  <ip-address>127.0.0.1</ip-address>
  <periodic>
   <periodic-type>recurring</periodic-type>
    <sequence-type>first</sequence-type>
  </periodic>
 <payment-methods>
    <payment-method name="creditcard"/>
  </payment-methods>
</payment>

purchase Response (recurring/first)

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML (recurring/first) purchase Response (Success)
<?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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/cad0c8c0-867a-451e-b820-ed65f48c0c3a">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>cad0c8c0-867a-451e-b820-ed65f48c0c3a</transaction-id>
    <request-id>9ed3cebf-79f2-4055-95f3-0edbdc33752b</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-11-28T12:30:38.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <csc-code>P</csc-code>
    <requested-amount currency="USD">5.01</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone></phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>44152</order-number>
    <order-detail>Test Product</order-detail>
    <descriptor></descriptor>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>871877</authorization-code>
    <api-id>elastic-api</api-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <provider-account-id>70001</provider-account-id>
</payment>

referenced-purchase Request (recurring/recurring)

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML referenced-purchase Request (Success)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>referenced-purchase</transaction-type>
    <parent-transaction-id>cad0c8c0-867a-451e-b820-ed65f48c0c3a</parent-transaction-id>
    <requested-amount currency="USD">5.01</requested-amount>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
</payment>

referenced-purchase Response (recurring/recurring)

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML referenced-purchase Response (Success)
<?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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/e3baaaf8-3417-4650-998c-058557e5847e">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>e3baaaf8-3417-4650-998c-058557e5847e</transaction-id>
    <request-id>1f38bbc0-247a-46c2-b4b5-5b669747c93e</request-id>
    <transaction-type>referenced-purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2019-01-11T07:33:19.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">5.01</requested-amount>
    <parent-transaction-id>cad0c8c0-867a-451e-b820-ed65f48c0c3a</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone></phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>44152</order-number>
    <order-detail>Test Product</order-detail>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">5.010000</parent-transaction-amount>
    <authorization-code>384949</authorization-code>
    <api-id>elastic-api</api-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <provider-account-id>70001</provider-account-id>
</payment>

referenced-purchase Request (recurring/final)

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML referenced-purchase Request (Success)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>referenced-purchase</transaction-type>
    <parent-transaction-id>cad0c8c0-867a-451e-b820-ed65f48c0c3a</parent-transaction-id>
    <requested-amount currency="USD">5.01</requested-amount>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>final</sequence-type>
    </periodic>
</payment>

referenced-purchase Response (recurring/final)

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML referenced-purchase Response (Success)
<?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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/d9736b05-efe1-46ec-ac27-9e842d5a0785">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>d9736b05-efe1-46ec-ac27-9e842d5a0785</transaction-id>
    <request-id>0e0b9e60-8c84-42df-ae6e-cf8dfb7f907f</request-id>
    <transaction-type>referenced-purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2019-01-11T07:39:22.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">5.01</requested-amount>
    <parent-transaction-id>cad0c8c0-867a-451e-b820-ed65f48c0c3a</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@wirecard.com</email>
        <phone></phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4127352795354678</token-id>
        <masked-account-number>427114******4678</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-number>44152</order-number>
    <order-detail>Test Product</order-detail>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">5.010000</parent-transaction-amount>
    <authorization-code>167472</authorization-code>
    <api-id>elastic-api</api-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>final</sequence-type>
    </periodic>
    <provider-account-id>70001</provider-account-id>
</payment>
void-purchase

A void-purchase must reference a successful purchase response.

A void-purchase shall be used only, if the payment was processed in an online shop and not at a POS.

We only list field descriptions for requests and responses. Notifications follow the general structure described in General Platform Features.

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML void-purchase Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>void-purchase</transaction-type>
    <parent-transaction-id>36fc8d02-4ceb-483c-a3ff-929543452df7</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML void-purchase Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/baf93d19-15ec-11e5-87be-00163e5411b5">
  <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
  <transaction-id>baf93d19-15ec-11e5-87be-00163e5411b5</transaction-id>
  <request-id>{{$guid}}</request-id>
  <transaction-type>void-purchase</transaction-type>
  <transaction-state>success</transaction-state>
  <completion-time-stamp>2015-06-18T19:03:41.000Z</completion-time-stamp>
  <statuses>
    <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information" provider-transaction-id="C847532143465422040880"/>
  </statuses>
  <requested-amount currency="USD">1.01</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
    <phone></phone>
    <address>
      <street1>123 anystreet</street1>
      <city>Brantford</city>
      <state>ON</state>
      <country>CA</country>
      <postal-code>M4P1E8</postal-code>
    </address>
  </account-holder>
  <card-token>
    <token-id>4119529611183494</token-id>
    <masked-account-number>414720******3494</masked-account-number>
  </card-token>
  <ip-address>127.0.0.1</ip-address>
  <order-number>5114</order-number>
  <order-detail>Test Product</order-detail>
  <payment-methods>
    <payment-method name="creditcard"/>
  </payment-methods>
  <authorization-code>940987</authorization-code>
  <api-id>elastic-api</api-id>
</payment>
refund-purchase

Merchants use a refund-purchase to refund a purchase or parts of it after the funds transfer was initiated.

A refund-purchase must reference a successful purchase response.

We only list field descriptions for requests and responses. Notifications follow the general structure described in General Platform Features.

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML refund-purchase Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>refund-purchase</transaction-type>
    <parent-transaction-id>36fc8d02-4ceb-483c-a3ff-929543452df7</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML refund-purchase Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="https://api-test.wirecard.com:443/engine/rest/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/01a62281-15e4-11e5-87be-00163e5411b5">
  <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
  <transaction-id>01a62281-15e4-11e5-87be-00163e5411b5</transaction-id>
  <request-id>${response}</request-id>
  <transaction-type>refund-purchase</transaction-type>
  <transaction-state>success</transaction-state>
  <completion-time-stamp>2015-06-18T18:01:14.000Z</completion-time-stamp>
  <statuses>
    <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information" provider-transaction-id="C851766143465047366859"/>
  </statuses>
  <requested-amount currency="USD">1.01</requested-amount>
  <account-holder>
    <first-name>John</first-name>
    <last-name>Doe</last-name>
    <email>john.doe@wirecard.com</email>
    <phone></phone>
    <address>
      <street1>123 anystreet</street1>
      <city>Brantford</city>
      <state>ON</state>
      <country>CA</country>
      <postal-code>M4P1E8</postal-code>
    </address>
  </account-holder>
  <card-token>
    <token-id>4266575172147814</token-id>
    <masked-account-number>413496******7814</masked-account-number>
  </card-token>
  <ip-address>127.0.0.1</ip-address>
  <payment-methods>
    <payment-method name="creditcard"/>
  </payment-methods>
  <authorization-code>136208</authorization-code>
  <api-id>elastic-api</api-id>
</payment>

A successful refund-purchase response can be followed by a void-refund-purchase (details see void).

void-refund-purchase

With this transaction type you can void a successful refund-purchase until the funds transfer has been triggered.

Request

Fields

We provide detailed descriptions of all credit card fields.

Sample

Request Header
Authorization: Basic NzAwMDAtQVBJTFVITi1DQVJEOjhtaHdhdktWYjkxVA==
Content-Type: application/xml
XML void-refund-purchase Request (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
    <merchant-account-id>9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <request-id>{{$guid}}</request-id>
    <transaction-type>void-refund-purchase</transaction-type>
    <parent-transaction-id>01a62281-15e4-11e5-87be-00163e5411b5</parent-transaction-id>
    <ip-address>127.0.0.1</ip-address>
</payment>

Response

Fields

We provide detailed descriptions of all credit card fields.

Sample

XML void-refund-purchase 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/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/9ff6eb1f-d729-4b93-bad2-75300abd3168">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>9ff6eb1f-d729-4b93-bad2-75300abd3168</transaction-id>
    <request-id>5cffdb9b-91ce-4ddb-945e-961a025e6582</request-id>
    <transaction-type>void-refund-purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-12-27T12:09:51.000Z</completion-time-stamp>
    <statuses>
        <status code="201.0000" description="3d-acquirer:The resource was successfully created." severity="information"/>
    </statuses>
    <requested-amount currency="USD">1.01</requested-amount>
    <parent-transaction-id>87fffba5-0824-4bba-843f-ed7574ae2022</parent-transaction-id>
    <account-holder>
        <first-name>John</first-name>
        <last-name>Doe</last-name>
        <email>john.doe@example.com</email>
        <phone>5555555555</phone>
        <address>
            <street1>Example Street 1</street1>
            <city>Example City</city>
            <state>ON</state>
            <country>DE</country>
            <postal-code>M4P1E8</postal-code>
        </address>
    </account-holder>
    <card-token>
        <token-id>4845276539271999</token-id>
        <masked-account-number>456396******1999</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <custom-fields>
        <custom-field field-name="elastic-api.card_id" field-value="dc947622-551b-11e8-a4ae-3cfdfe334962"/>
    </custom-fields>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <parent-transaction-amount currency="USD">1.010000</parent-transaction-amount>
    <authorization-code>550452</authorization-code>
    <api-id>elastic-api</api-id>
    <provider-account-id>70001</provider-account-id>
</payment>
Fields

This is the general field reference for credit card transactions.

  • Format: XML

  • POST requests and responses

We provide the request and the response fields in two separate sections:

  • Request contains those fields sent in the request (and usually in the response).

  • Response contains those fields sent in the response only.

The fields are ordered hierarchically and in separate tables. payment is the top parent element and all fields that are part of payment are listed in the payment table.

Some fields listed in this table are complex type fields, e.g. payment.account-holder. Complex type fields are parents to further fields. We offer separate field tables for all parent elements and their respective fields.

The tables are sorted alphabetically. Use Ctrl + F if you are looking for a specific field.

For example, payment.account-holder is a parent of address. Click on the link in the table to view the fields contained in a complex type field.

Field Definitions

Each field table contains the following columns:

Field definitions may vary by transaction type. Deviations from standard field definitions are given with the respective transaction type.
XML Elements

Click the X in the respective column for request and response fields.

Please refer to our XSD for the structural relationship between these fields.

Field Request Response

payment

X

X

account-holder

X

account-info

X

address

X

airline-industry

X

audit

X

avs

X

browser

X

card

X

card-data

X

card-emv

X

X

card-pin

X

card-raw

X

card-token

X

credit-sender-data

X

cruise-industry

X

custom-fields

X

X

device

X

encryption-context

X

gift-card

X

iso

X

loyalty-card

X

X

notifications

X

order-items

X

payment-methods

X

risk-info

X

segment

X

shipping

X

status

X

sub-merchant-info

X

three-d

X

X
Request
payment.

You can find additional payment fields in the Response > payment section.

Field M/O Data Type 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

credit-sender-data

cruise-industry

custom-fields.custom-field

device

loyalty-card

notifications.notification

order-items.order-item

payment-methods.payment-method

periodic

risk-info

shipping

sub-merchant-info

three-d
account-holder.

account-holder is a child of payment.
With the account-holder you can provide detailed information about the consumer.

The cardinality of the account-holder fields can vary, depending on the use case. You can find the details below in the description of the individual fields.
Field M/O Data Type 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-info.

account-info is a child of payment.account-holder.
account-info fields are used with 3D Secure 2. With account-info you can provide detailed information about the consumer. Please provide all the account-info data in your 3D Secure 2 request to make fraud prevention easier.

Field M/O Data Type 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

Data can be provided optionally but it is strongly recommended to provide as much as possible.
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.
airline-industry.

airline-industry is a child of payment.

Field M/O Data Type Size Description

agent-code

O

String

3

Agency code assigned by IATA.

agent-name

O

String

64

The agency name.

airline-code

O

String

3

Airline code assigned by IATA.

airline-name

O

String

64

Name of the airline.

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 allowed. Use .(decimal point) as the separator.
If this field contains a value greater than zero, the indicated value must differ from the amount of the transaction.

number-of-passengers

O

String

3

The number of passengers on the airline transaction.

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-email

O

String

64

Email address of the airline transaction passenger.

passenger-ip-address

O

String

45

IP Address of the airline transaction passenger.

passenger-name

O

String

32

The name of the airline transaction passenger.

passenger-phone

O

String

32

The phone number of the airline transaction passenger.

pnr-file-key

O

String

10

Passenger name file ID for the airline transaction.

reservation-code

O

String

32

The reservation code of the Airline Transaction passenger.

ticket-check-digit

O

String

2

Airline ticket check digit.

ticket-issue-date

O

Date

Date the ticket was issued. Format: YYYY-MM-DD

ticket-number

O

String

11

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

Enumeration

1

Indicates that the airline transaction is restricted.
Accepted values:

  • 0 = No restriction

  • 1 = Restricted (non-refundable).

itinerary.segment.

ticket-issuer.address
audit.

audit is a child of payment. Audit data is displayed in WEP for each transaction it has been send with.

Field M/O Data Type Size Description

request-source

O

String

30

Optional information that references the application or Wirecard Payment Gateway a transaction is processed with.

user

O

String

128

Optional information that identifies the origin/user of the payment request. Audit user is sent by frontend applications referencing the user processing transactions or follow-up operations using the application.
browser.

browser is a child of payment.

Field M/O Data Type 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.

card is a child of payment. card details are sent only in the first transaction request when the card is used for the first time. Due to PCI DSS compliance, card details are immediately replaced by a token. Beginning with the first response, this token is used for every consecutive transaction (request and response) that is performed with this credit card. Token data is provided with the card-token element.

Only the transaction type detokenize returns expiration-month, expiration-year and card-type in a response. All the other transaction types return elements of card-token in the response.
Field M/O Data Type 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

Enumeration

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.

Field M/O Data Type Size Description

request-icc-data

M/O

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/O

String

5

Encoding method of the request EMV data.
Allowed value: hex.
Mandatory if you do not send track-1 and track-2.
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.

card-token is a child of payment and is the substitute for card. Due to PCI DSS compliance, card data must not be sent in payment transactions. The Wirecard Payment Gateway replaces card immediately with a token in the transaction response for the first use of a credit card.

Field M/O Data Type 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.
credit-sender-data.

credit-sender-data is a child of payment.

credit-sender-data is used in OCT non gambling payment processes only.

With this element you can send money to the consumer. This can be the case, if you are

  • an insurance company and have to pay out money to the consumer (insurance case).

  • the government and have to pay back taxes.

Field M/O Data Type Size Description

receiver-last-name

M/O

String

35

Mandatory for cross-border transactions.

receiver-name

M/O

String

35

Mandatory for cross-border transactions.
Maximum size for Visa: 30

reference-number

O

String

19

Maximum size for Visa: 16

sender-account-number

M/O

String

20

Mastercard: Mandatory
Visa: Mandatory if reference-number is empty. Maximum size for Visa: 34

sender-address

M/O

String

50

Mastercard: Optional
Visa: Mandatory for US domestic and cross-border transactions. Maximum size for Visa: 35

sender-city

M/O

String

25

Mastercard: Optional
Visa: Mandatory for US domestic and cross-border transactions

sender-country

M/O

String

3

Mastercard: Optional
Visa: Mandatory for US domestic and cross-border transactions. Maximum size for Visa: 2

sender-funds-source

O

String

2

Allowed characters:
Mastercard:

  • US: 01, 02, 03, 04, 05, 07

  • Non-US: 01, 02, 03, 04, 05, 06, 07

Visa:

  • US: 1, 2, 3

  • Non-US: 01, 02, 03, 04, 05, 06

sender-last-name

M/O

String

35

Mastercard: Mandatory
Visa: Optional

sender-name

M/O

String

24

Mastercard: Mandatory
Visa: Mandatory for US domestic transactions and cross-border money transfers. Maximum size for Visa: 30

sender-postal-code

O

String

10

No specific requirements for Mastercard and Visa.

sender-state

M/O

String

2

Mastercard: Mandatory if sender country is US or Canada.
Visa: Mandatory for US domestic and cross-border transactions originating from US or Canada.
cruise-industry.

cruise-industry is a child of payment.

Field M/O Data Type Size Description

agent-code

O

String

8

Agent code assigned by IATA.

carrier-code

O

String

3

Carrier code assigned by IATA.

lodging-check-in-date

O

Date

Cruise departure date also known as the sail date. Format: YYYY-MM-DD.

lodging-check-out-date

O

Date

Cruise return date also known as the sail end date. Format: YYYY-MM-DD.

lodging-city-name

O

String

20

Name of the city where the lodging property is located.

lodging-country-code

O

String

10

Country code where the lodging property is located.

lodging-name

O

String

100

Lodging name booked for the cruise.

lodging-region-code

O

String

10

Region code where the lodging property is located.

lodging-room-rate

O

Decimal

18.2

Total cost of the cruise. Use .(decimal point) as the separator.

number-of-nights

O

Number

3

Duration of the cruise in days.

passenger-name

O

String

100

Name of the passenger.

ticket-number

O

String

15

Ticket number, including the check digit.

travel-package-type-code

O

Enumeration

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.

itinerary.segment
custom-field.

custom-field is a child of payment.custom-fields.

In the response > custom-field section you can find examples for ready-to-use custom-field.

Field M/O Data Type 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.

device is a child of payment.

Field M/O Data Type 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.
gift-card.

gift-card is a child of payment.risk-info.gift-cards.

Field M/O Data Type 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.
iso.

For card present transactions.

Field M/O Data Type 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.
loyalty-card.

loyalty-card is a child of payment.

It is used with loyalty programs.

Field M/O Data Type Size Description

user-id

M/O

String

36

VOP: Unique ID which is returned in the response of Enroll Card. The user-id can be used subsequently to Add Card.
MCLS: Unique ID for a consumer’s account.

Mandatory for MCLS Enroll Card or VOP Add Card. You cannot send it in a VOP Enroll Card.

promotion-code

O

String

36

Promotional code associated with the enrollment of the consumer. Issuer sets the loyalty program promotion code to upper case upon receipt.

product-code

M/O

String

36

The issuer bank provides this code.
Mandatory for MCLS Enroll Card or Enroll Tokenized Card. Not used with VOP.
notification.

notification is a child of payment.notifications.

notification is used to set up Instant Payment Notification (IPN). It is highly recommended to use IPN. IPN informs you about the outcome of the individual payment processes. By including notification in the request you can overwrite the merchant account configuration.

Field M/O Data Type 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-item.

order-item is a child of payment.order-items. This is a field for order’s items. You fill in the content. Order item amount always includes tax. Tax can be specified either by tax-amount or by tax-rate.

Field M/O Data Type Size Description

amount

O

Number

Item’s price per unit.

article-number

O

String

EAN or other article identifier for you.

name

O

String

Name of the item in the basket.

quantity

O

Number

Total count of items in the order.

tax-rate

O

Number

Item’s tax rate per unit.
payment-method.

payment-method is a child of payment.payment-methods. The element payment-method specifies the payment method used for a transaction.

Field M/O Data Type 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.

periodic is a child of payment.
periodic references recurring transactions such as payments of a subscription or an installment.
For all recurring payments the fields periodic-type and sequence-type must be provided with a value.

Field M/O Data Type 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.

risk-info is a child of payment.

Field M/O Data Type 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
segment.

segment is a child of airline-industry.itinerary and cruise-industry.itinerary. Itinerary segment data is used e.g. within airline industry and cruise industry to specify itineraries of the flight.
Up to 99 itinerary segments can be defined.

Field M/O Data Type Size Description

arrival-airport-code

M/O

String

3

The arrival airport code of the Itinerary Segment. IATA assigns the airport codes. Mandatory if itinerary is provided.

arrival-city-code

M/O

String

32

The arrival city code of the Itinerary Segment. IATA assigns the airport codes. Mandatory if itinerary is provided.

arrival-date

M/O

String

The arrival date for a given leg. Mandatory, if itinerary is provided. Format: YYYY-MM-DD

carrier-code

M/O

String

2

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

departure-airport-code

M/O

String

3

The departure airport code. IATA assigns the airport codes. Mandatory if itinerary is provided.

departure-city-code

M/O

String

32

The departure City Code of the Itinerary Segment. IATA assigns the airport codes. Mandatory, if itinerary is provided.

departure-date

M/O

Date

The departure date for a given leg. Mandatory, if itinerary is provided. Format: YYYY-MM-DD

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.

fare-basis

O

String

6

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

flight-number

O

String

6

The flight number of the itinerary segment.

stop-over-code

O

Enumeration

1

Accepted values:

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

tax-amount/@currency

O

String

3

The currency of the value added tax (VAT) amount levied on the transaction amount.
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 Data Type 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)

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.
three-d.

three-d is a child of payment. Additional fields can be found in the response > three-d section.

Fieldname M/O Data Type 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.
Response
payment.

Here you can find the payment element fields which are sent in the response only.

Field Data Type Size Description

transaction-id

String

36

This is the unique identifier for a transaction.

transaction-state

String

12

This is the status of a transaction.

completion-time-stamp

Timestamp

20

This is the timestamp of completion of request.
Format: YYYY-MM-DDThh:mm:ssZ

avs-code

String

24

This is the result of address validation.

csc-code

String

1

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

  • M - Matched (correct) CVC-2

  • N - Not Valid CVC-2

  • P - Processing not performed

  • S - The CVV2 should be on the card but the merchant indicates it is not

  • U - Unregistered Issuer

  • Y - CVC-1 incorrect

  • Z - Unknown (Unknown CVC Status)

api-id

String

36

The API ID is always returned in the notification. api-id is a string with a pattern value.

instrument-country

String

256

The instrument country retrieves the issuer country of a certain credit card. It returns a two-digit country code, such as

  • DE (Germany),

  • ES (Spain),

  • FR (France), or

  • IT (Italy).
    Returned only if Wirecard Payment Gateway has enabled FEATURE_CARD_TYPE_SERVICE or X-WD-Toggle-EnableFeature=FEATURE_CARD_TYPE_SERVICE header is sent with request.

avs

card-data

custom-fields.custom-field.

loyalty-card

statuses.status.

three-d
avs.

avs is a child of payment.

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. When a user makes an online purchase with a credit card, their billing address is required. The house number and postal code of the billing address is compared to the billing address held on file by the card issuing bank. If the address does not match, the transaction can be declined. AVS is an on-demand service which is configured by Wirecard.

See the complete list of the Wirecard Response Codes.

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.
card-data.

card-data is a child of payment.

It is used with the issuers' loyalty programs.

card-data is a child of payment.

Field Data Type Size Description

issuer-name

String

50

Name of the card issuer.
Returned only if

  • Wirecard Payment Gateway has enabled FEATURE_CARD_TYPE_SERVICE
    OR

  • you send X-WD-Toggle-EnableFeature=FEATURE_CARD_TYPE_SERVICE in the header of the request.
custom-field.

custom-field is a child of payment.custom-fields.

Wirecard can configure custom-field for you. For possible field values see the following selected examples. If you need the values of other card products, please contact our Merchant Support.

As the fields ─ shown here ─ are already defined, Datatype and Size information is not necessary. Please refer to custom-field for details.
Field Description

CardCategoryExt

Accepted values:

  • M (Consumer)

  • C (Commercial)

CardProductID

For possible response values, see the following selected examples. If you need the values of other card products, please contact our Merchant Support.

Visa:

  • A (Visa Traditional)

  • F (Visa Classic)

  • G (Visa Business)

  • I (Visa Infinite)

Mastercard:

  • MCC (Mastercard® Consumer)

  • MCD (Debit Mastercard® Card)

  • MCS (Mastercard® Consumer - Standard)

CardCategory

Possible response values:

  • D (Debit)

  • C (Credit)

  • P (Prepaid)
card-emv.

card-emv a child of the request element payment.card.

It is used for card present transactions. Here we show the response fields of card-emv.

Field Data Type Size Description

response-icc-data

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

String

5

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

loyalty-card is a child of payment.

It is used with the issuers' loyalty programs.

loyalty-card is a child of payment.

Field Data Type Size Description

card-id

String

36

The loyalty program assigns an ID for the consumer’s card account.

user-id

String

36

The issuer bank supplies a unique ID for a consumer’s account.
VOP returns this value in the Enroll Card response.
status.

status is a child of payment.statuses.

status informs you about the result of the previously sent request. They can use this information to redirect consumers to the respective response page (success page or failure page).

Field Data Type Size Description

@code

String

12

This is the code of the status of a transaction.

@description

String

256

This is the description of the status code of a transaction.

@severity

Enumeration

20

This field gives information about the severity. It can be either warning, error or information.
three-d.

three-d is a child of payment.

Field Data Type Size Description

liability-shift-indicator

String

2048

Liability shift can be enabled for 3D Secure consumers.
Payment Features
Tokenization
Introduction

Tokenization defines a process through which sensitive data, such as credit card number, is replaced with a surrogate value known as a "token". This token serves as a reference or surrogate value for the original credit card data.

Tokenization enables the merchant to use credit card data based on PCI DSS regulations, during a payment process.

It is a service provided by Wirecard for its customers. The token, generated by Wirecard, reduces the merchant’s PCI DSS Scope. That means, merchants do not have to store sensitive primary account numbers.

There are two options of using tokenization:

  1. Sending a Credit Card Transaction with Credit Card Data:
    Wirecard Payment Gateway takes the credit card data and encrypts the data. These data are stored in a secured encrypted area inside Wirecard Data Warehouse and are for use only in the encrypted state and secured environment.
    In other words: Every card number that accompanies a transaction in Wirecard Payment Gateway is subsequently tokenized. Regardless of the outcome of the transaction, any subsequent transaction with these credit card data uses its assigned token instead of the clear card account values. This means the merchant system never needs to store the sensitive card information, helping to reduce PCI DSS compliance issues.

  2. Sending an Explicit Request with the Transaction Type Tokenize or Detokenize.
    A transaction with this transaction type encrypts or decrypts credit card data for later reuse. The sender only gets back a token-ID. This token-ID can be reused many times as unique identifier for this specific credit card without sending or storing credit card data on shop side.

What is the difference between these two options?

Sending a Credit Card Transaction with Credit Card Data Sending an Explicit Request with the Transaction Type tokenize or detokenize

always initiates a payment process and encrypts credit card data

encrypts credit card data only

does not initiate a payment process
The token-id

The merchant sends an initial request to Wirecard Payment Gateway. This could be an authorization, for example. This request contains all data concerning the goods, shipping etc, as well as the consumer’s credit card data.

After the request of an authorization transaction was processed successfully, the response will not contain the information of the Credit Card <data> tag. The <data> tag will be replaced with a token-id in the <card-token> tag. As soon as the token-id is created, the token-id represents this special credit card.

With that token-id any recurring or other follow up transaction for this special credit card can be processed. As there is no additional encryption required, the use of the token-id reduces interaction and accelerates the credit card payment process. Especially from PCI DSS perspective, it is less critical.

e.g. A capture-authorization as follow up transaction in the workflow does not need the <data> tag of the Credit Card but only the token-id.

When using credit card, Wirecard Payment Gateway offers two different options to reference transactions. It depends on the merchant’s individual business needs and business processes, which type of referencing should be used.

Look at the following table to understand the pros and cons of referencing with a token or with the parent-transaction-id.

parent-transaction-id token-id

Pro

Can be used for all alternative payment methods and credit card.

Recurring transactions can always reference to a FIRST transaction.

Once created, the token can be reused as often as needed.

Referencing is possible to a previous transaction during the life cycle of a payment process.

Credit card check is only performed once (with the first transaction). Makes the payment process faster.

Reference is possible even on older transactions.

Reference is valid ad long as the credit card is valid.

Con

Referencing only within one life cycle of a payment process.

Can only be used with credit card.

When used with credit card all card checks have to be performed with every new transaction step.

If card has expired, new token will be needed, even if the card number remains the same.
When processing credit card transactions, the merchant must be PCI DSS compliant.

If the merchant only hands through a payment process (using a token) and does not store card holder data, it reduces the merchant’s applicable controls required for PCI DSS validation.

If the merchant wants to store card holder data (using parent-transaction-id), it increases the merchant’s applicable controls required for PCI DSS validation.

The following table describes, which data can be stored and which data must not be stored to be PCI DSS compliant.

Data Element

Storage permitted?

Data needs to be unreadable (in line with PCI DSS requirements)?

Account Data

Card holder data

Primary Account Number (PAN)

YES

YES

Card holder name

YES

NO

Service code

YES

NO

Expiration date

YES

NO

Sensitive Authentication Data

Full track data

NO

Doesn’t apply

CAV2/CVC2/CVV2/CID

NO

Doesn’t apply

PIN/PIN Block

NO

Doesn’t apply

Referencing by token-id

Referencing based on a token can be performed by using the Field <token-id>.

With that feature it is possible to refer a NEW transaction to an already submitted initial transaction. In the initial transaction the cluster of the <card> tag will be summarized in a token-id. This token-id will be used in any subsequent transaction, which is based on this initial transaction. The token-id can be seen as a black box which guarantees a correct correlation of subsequent transactions without transmitting the complete card data repeatedly.

Transaction Sequence

Transaction Type

Token-ID

<card-token>

Token Definition

Value

Initial transaction (Request)

authorization

the <card>-section and all its fields
e.g.: <account-number>, <expiration-month>, etc
obtains the substitute token-id value

1234567890987654

empty

Response on initial transaction

authorization

uses token-id value generated from <card> data given in the initial transaction

1234567890987654

Any subsequent transaction of this initial transaction

purchase

uses token-id value generated from <card> data given in the initial transaction

1234567890987654

See the samples for an overview of a payment process consisting of the transaction types authorization and purchase using a token.

Tokenize a Credit Card

The transaction type tokenize converts credit card information into a token that can be used in subsequent payment transactions, instead of the actual credit card information.

Workflow

Create_TokenID_Workflow

Fields

The following fields must be sent either in the request or the response (M = Mandatory, O = Optional). For details of the affected fields see the field table.

Field Request Response
payment

merchant-account-id

M

M

transaction-id

M

request-id

M

M

transaction-type

M

ip-address

O
statuses

statuses.status

M

status@code

M

status@description

M

status@severity

M
account-holder

account-holder.first-name

O

M

account-holder.last-name

O

M

account-holder.email

O

M

account-holder.gender

O

M

account-holder.date-of-birth

O

M

account-holder.phone

O

M
card

card.account-number

M

card.expiration-month

M

card.expiration-year

O

card.card-type

M
card-token

card-token.token-id

M

card-token.token-ext-id

O

card-token.masked-account-number

O

Samples

For transaction process details see the Tokenize samples.

Detokenize a Credit Card

The transaction type detokenize is the inverse of the transaction type tokenize. With the transaction type detokenize a token-id is provided to retrieve the original credit card information.

Fields

The following fields must be sent either in the request or the response (M = Mandatory, O = Optional). For details of the affected fields see the field table.

Field Request Response
payment

merchant-account-id

M

M

transaction-id

M

request-id

M

M

transaction-type

M

ip-address

O
statuses

statuses.status

M

status@code

M

status@description

M

status@severity

M
account-holder

account-holder.first-name

M

O

account-holder.last-name

M

O

account-holder.email

M

O

account-holder.gender

M

O

account-holder.date-of-birth

M

O

account-holder.phone

M

O
card

card.account-number

M

card.expiration-month

M

card.expiration-year

O

card.card-type

M
card-token

card-token.token-id

M

M

card-token.token-ext-id

O

O

card-token.masked-account-number

O

Samples

For transaction process details see the detokenize samples.

The transaction type detokenize is not included in default configuration.
For further information please contact: support@wirecard.com
Dynamic Descriptor

With the Dynamic Descriptor, merchants can itemize sales more clearly to the benefit of their customers, back office and consumer care management.

As merchants can add sales-specific information to electronic settlement requests, consumers have a better understanding of what they purchased. This increases their level of satisfaction and reduces the number of chargebacks. Known as a dynamic descriptor, the details can be included in any settlement transaction, be it e-commerce, POS or MOTO.

Data and Structure

Merchant Name and Merchant Location are usually displayed on the cardholder’s bank statement. These fields or parts of them are used for presenting the dynamic data on the cardholder’s statement.

Apart from such static data, the merchant can add transaction information to better reference their sales. For example, the merchant may use invoice number, booking ID or transaction ID. This data is typically passed along to the merchant. As this field has a fixed length, the longer the merchant name is, the smaller the number of digits allocated to dynamic information will be.

Digits Allocation

Card Brand

Field

Digits

VISA

Name

25

Location

13

Master Card

Name

22

Location

13

JCB

Name

25

Location

13
Merchants are advised to consider all these parameters before setting a dynamic descriptor, because any text exceeding the permissible length is cut off and discarded.

Please be aware that industry-specific restrictions apply by card schemes.

Please also note that it is up to the issuer to decide which data provided in the dynamic descriptor is printed on the cardholder’s statement. Wirecard can thus not guarantee that the dynamic descriptor data submitted to the issuers via the scheme networks is fully printed on the cardholder’s statement.

Wirecard Bank (WDB) receives the transaction data from the Wirecard Payment Gateway, looks up the merchant address, consolidates static address details and dynamic sales data (including Merchant Name and Merchant Location) and routes the information along with the settlement request to the issuer. To what level the routed details will later appear on the customer’s card statement may vary from issuer to issuer.

How It Works

When a merchant sends a transaction request with a dynamic descriptor, the data provided in the reserved transaction field tag expands the address information registered in the card acquirer’s MID database.

The dynamic descriptor is created for settlement transaction types such as purchase, capture or credit. authorization is not supported.

Workflow

CreditCard DynamicDescriptor Workflow

  1. The consumer shops at the merchant’s site and enters his card details at checkout.

  2. The merchant system records the data and posts an XML request with the default identifiers including the descriptor text (entered in one of the <Transaction-ID>, <Order Number>, <Request ID> or <Descriptor> tag) to the Wirecard Payment Gateway.

  3. Wirecard Payment Gateway processes the request and forwards the transaction details to the acquirer (e.g. Wirecard Bank).

  4. The acquirer acquires the card and sales details, reads the related identifier values, looks up the merchant’s name and business details in the MID database and complements the merchant data with the data sent in one of the transaction identifier tag fields.

  5. The aquirer routes the settlement request including the dynamic text to the issuer.

  6. The issuer processes the request, debits the consumer’s account and adds a new debit item with the dynamic descriptor to the credit card statement.

Payment Facilitator

The Payment Facilitator model allows a Payment Service Provider with a Payment Facilitator license to aggregate credit card payments, collect funds resulting from credit card traffic and settle sub merchants directly.

Requests in Payment Facilitator traffic require additional sub merchant information in the sub-merchant-info tag of each first request in the transaction flow (e.g. check-enrollment, authorization-only, authorization or purchase).

The sub merchant information is mandatory for MasterCard, Visa, UPI and JCB traffic.

For each transaction flow the first request must contain sub-merchant-info. For the following steps sub-merchant-info is not mandatory. We recommend to send sub-merchant-info in every step. This avoids complexity in implementation.

For details contact Merchant Support.

How It Works
CreditCard_PaymentFacilitator_Workflow

See the corresponding samples for details.

Recurring Transaction

To submit a recurring transaction the merchant must submit a request with the transaction type authorization-only, authorization or purchase including the PERIODIC TYPE element and a SEQUENCE TYPE.

Credit Card specific Periodic Types

Aside from the standard Periodic Types, Credit Card can also be used with the Periodic Types ucof and ci.

ucof

The Unscheduled Credential on File (ucof) allows the merchant to reference a regularly based transaction (like an unlimited periodic payment or an installment payment) to an already successfully submitted transaction. ucof is a transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date, where the cardholder has provided consent for the merchant to initiate one or more future transactions. An example of such transaction is an account auto-top up transaction.

ci

The periodic type ci (Consumer Initiated) allows the merchant to identify that the cardholder himself initiated the transaction and whether this is an initial (first) or subsequent (recurring) one. As soon as this is subsequent merchant initiated transaction (e.g. the cardholder used an account on merchant side ) and the corresponding information is sent to Wirecard Payment Gateway, CVV could be omitted within the transaction and Visa will still approve it. So this will lead to higher approve rate in the future.

Restrictions

Read, which restrictions have to be met to use a recurring transaction.

Samples

See request/response samples for Recurring Transaction.

Possible Scenarios

Shopping Online/Via an App

Establish Stored Credential/First Transaction

  1. Cardholder consent is obtained: merchant-tokenization-flag set to true

  2. Cardholder provides the Credit Card data including CVV/CVC2 code (required): periodic/periodic-type = 'ci' included in the transaction and periodic/sequence-type = 'first'

  3. Merchant sends the transaction to Wirecard Payment Gateway

Example: Establishment of Stored Credential/First Transaction
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>ci</periodic-type>
    <sequence-type>first</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
   <card>
      <account-number>4147460000000002</account-number>
      <expiration-month>12</expiration-month>
      <expiration-year>2020</expiration-year>
      <card-type>visa</card-type>
      <card-security-code>123</card-security-code>
      <merchant-tokenization-flag>true</merchant-tokenization-flag>
   </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

Subsequent Cardholder Initiated Purchase

  1. Cardholder consent is obtained: merchant-tokenization-flag set to true

  2. Cardholder data is saved within a cardholder’s account (CVV is not required)

  3. Cardholder uses the account to make a purchase: periodic/periodic-type = 'ci' included in the transaction and periodic/sequence-type = 'recurring'

  4. Merchant sends the transaction to Wirecard Payment Gateway

Example: Subsequent Cardholder initiated purchase
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>ci</periodic-type>
    <sequence-type>recurring</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <parent-transaction-id>0c036ea9-3aef-41e6-82d4-d16514379bee</parent-transaction-id>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
    <card-token>
      <token-id>4628584608610002</token-id>
   </card-token>
   <card>
    <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

Guest Account/Single Transaction

  1. Since Cardholder doesn’t create a account, Cardholder data is not being saved: the default value for merchant-tokenization-flag is false

  2. Cardholder provides the Credit Card data including CVV/CVC2 code (required)

  3. Merchant sends the transaction to Wirecard Payment Gateway

Example: Guest account/single transaction
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
   <card>
      <account-number>4147460000000002</account-number>
      <expiration-month>12</expiration-month>
      <expiration-year>2020</expiration-year>
      <card-type>visa</card-type>
      <card-security-code>123</card-security-code>
   </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

Recurring (R) or Installment (I) Transaction

First Recurring or Installment

  1. Cardholder consent is obtained: merchant-tokenization-flag set to true

  2. Cardholder would like to initiate Recurring or Installment payments

  3. Cardholder provides the Credit Card data including CVV/CVC2 code: periodic/periodic-type = 'installment'/'recurring' included in the transaction and periodic/sequence-type = 'first'

  4. Merchant sends the transaction to Wirecard Payment Gateway

Example: First Recurring or Installment
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>recurring</periodic-type>
    <sequence-type>first</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <parent-transaction-id>0c036ea9-3aef-41e6-82d4-d16514379bee</parent-transaction-id>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
   <card>
      <account-number>4147460000000002</account-number>
      <expiration-month>12</expiration-month>
      <expiration-year>2020</expiration-year>
      <card-type>visa</card-type>
      <card-security-code>123</card-security-code>
      <merchant-tokenization-flag>true</merchant-tokenization-flag>
   </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

Subsequent Recurring or Installment

Merchant Initiated Transaction

  1. Merchant initiates a subsequent Recurring or Installment payment: periodic/periodic-type = 'installment'/'recurring' included in the transaction and periodic/sequence-type = 'recurring'

  2. Merchant sends the transaction to Wirecard Payment Gateway

Example: Merchant initiated transaction
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>recurring</periodic-type>
    <sequence-type>recurring</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <parent-transaction-id>0c036ea9-3aef-41e6-82d4-d16514379bee</parent-transaction-id>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
    <card-token>
      <token-id>4628584608610002</token-id>
   </card-token>
   <card>
    <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

ucof

Example: auto-top up for transit or mobile - date is irregular, i.e. not known as usage driven

  1. Cardholder consent is obtained: merchant-tokenization-flag set to true

  2. Cardholder would like to initiate ucof payments

  3. Cardholder provides the Credit Card data including CVV/CVC2 code: periodic/periodic-type = 'ucof' included in the transaction and periodic/sequence-type = 'first'

  4. Merchant sends the transaction to Wirecard Payment Gateway

Example: First UCOF (sequence-type = 'first')
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>ucof</periodic-type>
    <sequence-type>first</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
   <card>
      <account-number>4147460000000002</account-number>
      <expiration-month>12</expiration-month>
      <expiration-year>2020</expiration-year>
      <card-type>visa</card-type>
      <card-security-code>123</card-security-code>
      <merchant-tokenization-flag>true</merchant-tokenization-flag>
   </card>
   <ip-address>127.0.0.1</ip-address>
</payment>

Merchant Initiated Transaction

  1. Merchant initiates a subsequent UCOF payment: periodic/periodic-type = 'ucof' included in the transaction and periodic/sequence-type = 'recurring'

  2. Merchant sends the transaction to Wirecard Payment Gateway

Example: Subsequent UCOF (sequence-type = 'recurring')
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <periodic>
    <periodic-type>ucof</periodic-type>
    <sequence-type>recurring</sequence-type>
   </periodic>
   <merchant-account-id>32bb900b-265b-414f-9971-23f7a0542434</merchant-account-id>
   <request-id>{{$guid}}</request-id>
   <transaction-type>authorization</transaction-type>
   <requested-amount currency="USD">1.02</requested-amount>
   <parent-transaction-id>0c036ea9-3aef-41e6-82d4-d16514379bee</parent-transaction-id>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone></phone>
   </account-holder>
    <card-token>
      <token-id>4628584608610002</token-id>
   </card-token>
   <card>
    <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>
   <ip-address>127.0.0.1</ip-address>
</payment>
Non-Referenced Capture

In an offline transaction process it is possible to have a non-referenced capture authorization. The Wirecard Payment Gateway can support such a type of transaction when using a special capture-authorization Credit Card transaction.

A transaction is considered non-referenced capture when it meets all the following four conditions in the payment XML request:

  1. The transaction type is capture-authorization

  2. payment-method is Credit Card

  3. parent-transaction-id is empty (no tag present)

  4. authorization-code is present (can have empty value)

If all conditions are met, then the transaction is sent to Wirecard Payment Gateway.

The most exceptional fact in this process is, that it is missing the Parent-Transaction-ID. By default capture-authorization takes most of its properties from the parent transaction.

Even though no parent transaction is available, captures which have not been referenced by Wirecard Payment Gateway can be processed. Cases like this will be handled a non-referenced capture-authorization transaction type. In that case all fields must be supplied with the capture-authorization request.

Account Updater

Account Updater is a feature facilitating recurring credit card payments. It informs the merchant about changes of cardholders' credit card details.

It saves the cardholders the hassle of manually updating credit card details for each individual subscription. All types of recurring credit card payments can continue seamlessly even if

  • the cardholder’s credit card has expired.

  • the cardholder has a new credit card.

Furthermore, Account Updater informs the merchant when

  • a credit card account is closed.

  • the cardholder withdraws the authorization for their credit card to be charged.

  • they need to contact the cardholder for clarification.

You must have an existing commercial agreement with the cardholder to receive these updates.
Supported credit card brands:

  • Visa

  • Mastercard

Account Updater also covers brand flips between these two.

What is updated by Account Updater?

Recurring payments need a transaction-id of a preceding transaction to refer to (i.e. parent-transaction-id). If credit card details change, Account Updater updates the corresponding transaction-id and returns the updated transaction-id to the merchant.

To activate and configure Account Updater, contact merchant support.

Workflow

Updating account information requires action on the merchant side (step 1 and step 6):

Account Updater Workflow

  1. Upload request file:

    1. Log in to the SFTP server with your SFTP credentials. If you do not have the appropriate URL or credentials, contact merchant support.

    2. Open folder FLIX. If there is no FLIX folder, contact merchant support.
      The FLIX folder contains two customized subfolders: from …​ and to …​.

    3. Open subfolder from …​.

    4. Open subfolder new.

    5. Upload the request file to the SFTP server.

  2. - 4. Account Updater retrieves the request file from the SFTP server and updates it with scheme data, which are continuously updated by the issuers. This may take up to 3 days.

  1. Account Updater exports the response file to the FLIX/to …​/new subfolder and sends a notification email to the merchant.

  2. Log in to the SFTP server with your SFTP credentials. Open subfolder FLIX/to …​/new to download the response file.

Files

Both the request file and the response file are plain text files without extension. The fields within the files are seperated by ;. All fields are mandatory, unless otherwise indicated. Default encoding is UTF-8.

Request File

The request file contains original transaction-id information. The request file name must have a specific format:

Account Updater request file name

e.g. AU.REQ.ID000000317588D017.D191015.S001

Request File Syntax:

Header line syntax (line 1):

H;MAID;batch-ID;email;Merchant Proprietary Info

  • H:
    Indicates a header line.

  • MAID:
    Merchant Account ID

  • batch-ID:
    Internal merchant file ID used to match request and response files.

  • email:
    Once the response file is ready to be downloaded, or if the request file is invalid, Account Updater sends a notification email to the address entered here.
    The email address in the request file can differ from the default email address configured at Account Updater setup.

  • Merchant Proprietary Info:
    Optional field. Contains any information you want to be included in the request header. It will be mirrored in the response.

Detail lines syntax (records):

D;rfu;rfu;rfu;transacion-id;rfu;Merchant Proprietary Info Detail

  • D:
    Indicates a detail line.

  • rfu:
    Reserved for future use. Must be left blank.

  • transaction-id:
    Retrieved from an existing transaction. This transaction-id will be checked by Account Updater and supplemented with a new transaction-id if credit card details have changed.

  • Merchant Proprietary Info Detail:
    Optional field. Contains any information you want to be included in the record. It will be mirrored in the response.

F;n

  • F:
    Indicates a footer line.

  • n:
    Total number of lines (including header, details and footer).

Sample Request File (Success):

H;000000317588D017;123;notification.address@merchant.com;ProprietaryInformation for this batch
D;;;;C020929259567753216841;;proprietaryInfoa7e94047e4494f0698b4
D;;;;C057225169441625488387;;proprietaryInfodf2cfd1ce8c84b08bf25
D;;;;C073152725565823862026;;proprietaryInfo3ea5484f848f451488fc
D;;;;C081533725758083421254;;proprietaryInfo96d19d4010d14aabbc94
D;;;;C077647318514033592579;;proprietaryInfo2a5936061c984e14834c
F;7

Sample Request File (Error):

H;6787AD3256EA;1234;notification.address@merchant.com;ProprietaryInformation for this batch
D;;;;;;ProprietaryInformation for this record
D;;;;C0992801501001007160912;;ProprietaryInformation for this record
F;4
Response File

The response file has the same name as the corresponding request file, only with "REQ" replaced by "RES":

AU.RES.ID<MAID>.D<YYMMDD>.S<3-digit seq #>

It contains

  • updated transaction-id information (i.e. information on credit card details changes) in case of success.

  • response codes, describing the credit card details changes in case of success.

  • error messages, describing the error reason (e.g. missing transaction-id) in case of failure.

Response File Syntax:

Header line syntax (line 1):

H;MAID;batch-ID;email;Merchant Proprietary Info

  • H:
    Indicates a header line.

  • MAID:
    Merchant Account ID

  • batch-ID:
    Internal merchant file ID used to match request and response files.

  • email:
    Specified only in case of an error.

  • Merchant Proprietary Info:
    Optional field. Contains any information you want to be included in the request header. It will be mirrored in the response.

If a record is invalid (e.g. invalid or missing transaction-id), Account Updater creates a response error file that contains all invalid records (see error handling). In this case, the response error file header contains also the email address to which Account Updater sent the notification that an error occured.

Detail lines syntax (records):

D;rfu;rfu;rfu;rfu;transacion-id;rfu;rfu;rfu;rfu;new-transaction-id;response-code;rfu;Merchant Proprietary-Info

  • D:
    Indicates a detail line.

  • rfu:
    Reserved for future use.

  • transaction-id:
    Retrieved from an existing transaction. This transaction-id will be checked by Account Updater and supplemented with the new-transaction-id if credit card details have changed.

  • new-transaction-id:
    New transaction-id retrieved from updated credit card details. Use this transaction-id to reference to in recurring payments.

  • response-code:

    • V: Valid credit card. No changes.

    • A: Update: Match made, credit card replaced.

    • C: Contact: Match made, credit card canceled.

    • E: Expiry: Match made, expiration date updated.

    • P: Unknown VISA credit card number - participating BIN/issuer.

    • N: Unknown VISA credit card number - non-participating BIN/issuer.

    • U: Unknown Mastercard credit card number.

    • Q: Contact the cardholder for additional account information.

  • Merchant Proprietary Info:
    Optional field. Contains any information you want to be included in the record. Mirrored from request.

If a record is invalid (e.g. missing transaction-id), Account Updater does not return a response-code. Instead, an error message is appended to the end of the line.

The footer has the same syntax as in the request file.

Sample Response File (Success):

H;000000317588D017;123;ProprietaryInformation for this batch
D;;;;;C073152725565823862026;;;;C074539155801779830647;A;;proprietaryInfo3ea5484f848f451488fc
D;;;;;C020929259567753216841;;;;C074539155801779830647;A;;proprietaryInfoa7e94047e4494f0698b4
D;;;;;C081533725758083421254;;;;C074539155801779830647;E;;proprietaryInfo96d19d4010d14a