Transactions

Referencing a Transaction

With the Wirecard Payment Gateway a payment process can reference two subsequent transactions.

This reference can be accomplished in two different ways:

  • For alternative payment methods (such as PayPal and SEPA) and credit card the merchant can reference transactions via the transaction ID.

  • For credit card payments the merchant can also use a token.

Referencing by Transaction ID

Referencing by transaction ID uses the field <parent-transaction-id>.

In that case the <transaction-id> of the preceding transaction will be referenced as the <parent-transaction-id> of the follow up transaction.

Be aware that the parent-transaction-id is also referred to as reference-transaction-id.

The following example for PayPal shows the use of <parent-transaction-id>:

Transaction No. Transaction Type <transaction-id> <parent-transaction-id>

#1

authorization

1234567

empty

#2

capture-authorization

8901235

1234567

etc

void-authorization

6789012

8901235

Recurring Transaction

A recurring transaction is a repetitive set of transactions. In general the recurrence occurs on a regular basis (e.g. paying annual fees for an insurance). A reference to such a transaction always means that the subsequent transaction has a functional dependency on the preceding transaction.

This could be, for example, a repeating transaction in a standard transaction workflow which occurs on a regular schedule.

To submit a recurring transaction, the merchant must submit a request with a specific transaction type. It depends on the payment method, which transaction types apply. Currently the Wirecard Payment Gateway supports recurring transactions with the payment methods Credit Card , PayPal, and SEPA . If the merchant wants to use recurring transactions the request must provide the corresponding PERIODIC TYPE and a SEQUENCE TYPE.

The Periodic Type

The PERIODIC TYPE element is chosen specifically by the merchant and depends on the merchant’s business model. One of the following two periodic types must be chosen:

  • installment: one in a set that completes a financial transaction and

  • recurring: one in a set that occurs repeatedly, such as a subscription.

Both transactions will be processed the same way.

The Sequence Type

Additionally, the sub-element SEQUENCE TYPE with one of the following sequences must be submitted:

  • *first*: The first transaction in a series of recurring transactions

  • *recurring*: A transaction that is part of a series of recurring transactions.

  • *final*: The final transaction in a series of recurring transactions. A payment with this sequence type completes a chain of recurring payments.

Restrictions

To ensure proper processing, please take into consideration the following restrictions:

  • Recurring and final transactions are required to be matched to the first transaction.

  • A request with sequence type first may only contain a parent-transaction ID referring to another transaction which has been submitted without a periodic type.

  • A recurring or final transaction may only be referenced to a parent first if it is on status SUCCESS.

  • Where a first transaction has been voided, a subsequent recurring or final transaction will not be accepted.

  • After a transaction with sequence type final has been submitted, it is not possible to submit another recurring or final transaction for this series.

  • Only one periodic type may be used for the complete series of recurring payments. This means that the periodic type in a subsequent transaction must match the periodic type sent in the first request.

Retrieve a Transaction

The Wirecard Payment Gateway allows the merchant to submit payment transactions, as well as search for payments and merchant data.

In the standard process, the merchant is informed via IPN about the status of a submitted transaction. Retrieve Transaction is an option for the merchant to find out the status of a transaction, if, for some reason, the IPN has not been received. Lacking an IPN can happen due to the fact that the transaction has not reached its final status or additional information from providers are not present at the point of time the Retrieve query was sent. So in case the notification was sent the status is final.

There are several reasons why Retrieve Transaction shall not be launched immediately after submitting a transaction and still waiting for the IPN.

Formats and Methods

Request Formats

XML, NVP (credit card only)

Response Formats

XML, HTML, JSON

Request Methods

GET

Retrieve Transaction by Transaction-ID

Retrieving a transaction using a Transaction-ID returns a single transaction belonging to a merchant account. The Transaction-ID attribute must match the value that was included in the transaction response sent by Wirecard. An error occurs if the Transaction-ID is not available (request must be submitted later again) or the requested user is not authorized to see the content. The desired content type can be set through the Accept-header or by specifying an extension.

The Notification file (IPN) the merchant gets (based on configuration), is the standard process to gather information about a submitted transaction. The reason for this is that it could happen that the transaction has not reached final status or additional information from providers are not present at the point of time the Retrieve query was sent. So in case the notification was sent the status is final.

Endpoint
URL https://api-test.wirecard.com/engine/rest/merchants/{merchant-account-id}/payments/{transaction-id}
Fields

Mandatory (M) or optional (O).

Field Cardinality Datatype Size

merchant-account-id

M

Alphanumeric

36

transaction-id

M

Alphanumeric

36

Sample URL to a Merchant’s Endpoint

https://api-test.wirecard.com/engine/rest/merchants/ba261be8-af94-11df-ab7800163e5eafd7/payments/048b27e0-9c31-4cab-9eab-3b72b1b4d498

Response when retrieving a transaction

The response corresponds to the transaction type of the transaction being retrieved. For example, the transaction type = 'purchase' and the transaction type = 'tokenize' have different responses when the transaction is being created and that same response will occur for this retrieval. See the sample responses as described for each transaction type.

Retrieve Transaction by Request-ID

Retrieving a transaction using a Request-ID returns a single transaction belonging to a Merchant Account. The request-id attribute must match a request-id that was submitted during the creation of a transaction. An error is returned if the request-id is not available or the user is not authorized to see the content. The desired content type can be set through the "Accept"-header with value "application/xml" or by specifying an extension.

Endpoint

URL

https://api-test.wirecard.com/engine/rest/merchants/{merchant-account-id}/payments/search?payment.request-id={request-id}

Fields

Mandatory (M) or optional (O).

Field Cardinality Datatype Size

merchant-account-id

M

Alphanumeric

36

request-id

M

Alphanumeric

150

Sample URL to a Merchant’s Endpoint

https://api-test.wirecard.com/engine/rest/merchants/ba261be8-af94-11df-ab78-00163e5eafd7/payments/search?payment.request-id=048b27e0-9c31-4cab-9eab-3b72b1b4d498

Response when retrieving a transaction

The behavior of a response is the same no matter whether you receive it for a transaction by Request-ID or Transaction-ID.

The details are described in section Retrieve Transaction by Transaction-ID.

Retrieve Transaction by Request-ID and Category

Retrieving a transaction using a Request-ID and Category returns a single transaction belonging to a Super Merchant Account with resolving category. The request-id attribute must match a request-id that was submitted during the creation of a transaction with Super Merchant. An error is returned if the request-id is not available or the user is not authorized to see the content. The desired content type can be set through the "Accept"-header with value "application/xml" or by specifying an extension.

Endpoint

URL

https://api-test.wirecard.com/engine/rest/resolver-category/{category-id}/payments/?request_id={request-id}

Fields

Mandatory (M) or optional (O).

Field Cardinality Datatype Size

request-id

M

Alphanumeric

150

resolver-category

M

Alphanumeric

32

Sample URL to a Merchant’s Endpoint

https://api-test.wirecard.com/engine/rest/resolver-category/CATEGORY_X/payments/?request_id=c1052ad7-1372-4755-b6e1-fb32e7519be1

Sample: XML Authorization Response (Successful)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payments 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/resolver-category/CATEGORY_X/payments/?request_id=c1052ad7-1372-4755-b6e1-fb32e7519be1">
    <payment
            self="https://api-test.wirecard.com:443/engine/rest/merchants/44b30ddd-6c31-4db6-8bf3-2b7cbc032373/payments/b36dcb4b-95d2-4f3e-ad4d-0f5e0e4b7d91">
        <merchant-account-id
                ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/44b30ddd-6c31-4db6-8bf3-2b7cbc032373">
            44b30ddd-6c31-4db6-8bf3-2b7cbc032373
        </merchant-account-id>
        <transaction-id>b36dcb4b-95d2-4f3e-ad4d-0f5e0e4b7d91</transaction-id>
        <request-id>c1052ad7-1372-4755-b6e1-fb32e7519be1</request-id>
        <transaction-type>authorization</transaction-type>
        <transaction-state>success</transaction-state>
        <completion-time-stamp>2017-05-19T09:54:01.000Z</completion-time-stamp>
        <statuses>
            <status code="201.0000" description="The resource was successfully created." severity="information"
                    provider-transaction-id="IctgmYHK0nX1oonIA"/>
        </statuses>
        <requested-amount currency="EUR">5.000000</requested-amount>
        <parent-transaction-id>25fd7ee2-67d7-4baf-8f6a-a7c238f0e05d</parent-transaction-id>
        <group-transaction-id>25fd7ee2-67d7-4baf-8f6a-a7c238f0e05d</group-transaction-id>
        <account-holder>
            <first-name>Test</first-name>
            <last-name>User</last-name>
            <email>b1_1247133954_pre@example.com</email>
        </account-holder>
        <shipping>
            <first-name>Peter</first-name>
            <last-name>Test</last-name>
            <phone>+49123123123</phone>
            <address>
                <street1>Einsteinring 35</street1>
                <city>Munich</city>
                <country>DE</country>
                <postal-code>81249</postal-code>
            </address>
        </shipping>
        <order-number>26647</order-number>
        <descriptor>customerStatement 18009998888</descriptor>
        <payment-methods>
            <payment-method name="creditcard"/>
        </payment-methods>
        <api-id>---</api-id>
        <wallet>
            <account-id>NrS7h1wXXpuS</account-id>
        </wallet>
        <instrument-country>SK</instrument-country>
    </payment>
    <payment
            self="https://api-test.wirecard.com:443/engine/rest/merchants/667fddb2-38f4-4982-90c5-8f37dd54a679/payments/a538f7cf-11e8-40a9-ba2a-bac0165f4e56">
        <merchant-account-id
                ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/667fddb2-38f4-4982-90c5-8f37dd54a679">
            667fddb2-38f4-4982-90c5-8f37dd54a679
        </merchant-account-id>
        <transaction-id>a538f7cf-11e8-40a9-ba2a-bac0165f4e56</transaction-id>
        <request-id>c1052ad7-1372-4755-b6e1-fb32e7519be1</request-id>
        <transaction-type>authorization</transaction-type>
        <transaction-state>success</transaction-state>
        <completion-time-stamp>2017-05-19T09:54:00.000Z</completion-time-stamp>
        <statuses>
            <status code="200.0000" description="The request completed successfully." severity="information"/>
            <status code="201.0000" description="The resource was successfully created." severity="information"/>
        </statuses>
        <requested-amount currency="EUR">1.020000</requested-amount>
        <group-transaction-id>a538f7cf-11e8-40a9-ba2a-bac0165f4e56</group-transaction-id>
        <account-holder>
            <first-name>WDCP</first-name>
            <last-name>Test</last-name>
            <email>elastic.engine@test.com</email>
            <phone></phone>
            <address>
                <street1>Einsteinring 35</street1>
                <street2></street2>
                <city>Munich</city>
                <state>ON</state>
                <country>DE</country>
            </address>
        </account-holder>
        <card>
            <expiration-month>12</expiration-month>
            <expiration-year>2020</expiration-year>
            <card-type>visa</card-type>
        </card>
        <card-token>
            <token-id>4099548076240154</token-id>
            <masked-account-number>492910******0154</masked-account-number>
        </card-token>
        <ip-address>127.0.0.1</ip-address>
        <descriptor>demo descriptor</descriptor>
        <payment-methods>
            <payment-method name="creditcard"/>
        </payment-methods>
        <authorization-code>153620</authorization-code>
        <api-id>elastic-api</api-id>
        <instrument-country>GB</instrument-country>
    </payment>
</payments>

Storing Additional Data

In addition to processing transactions, Wirecard Payment Gateway also permits the storage and later retrieval of additional information.

The use of the header "custom-field" permits the client application to store key-value pairs with each transaction.

In the following example, the client application has stored a purchase order, invoice, crm-id, customer-tier and promotional-code.

This information is also echoed back in any response querying the status of a transaction. It is also possible to see this information in the reporting system.

<custom-fields>
   <custom-field field-name="purchase-order" field-value="PO999888776655111"/>
   <custom-field field-name="crm-id" field-value="7766558" />
   <custom-field field-name="customer-tier" field-value="gold" />
   <custom-field field-name="promotional-code" field-value="2010-06-15" />
</custom-fields>

View Transactions in Browser

You can check your transactions in the browser. All you need is the following URL:

https://{hostname}/engine/rest/merchants/{merchant-account-id}/payments/search?payment.request-id={request-id}

Enter this URL in your browser and replace the following variables:

  • {hostname}:

    • if test environment: http://api-test.wirecard.com

    • if production environment: http://api.wirecard.com

  • {merchant-account-id}: Use the appropriate Test Merchant Account ID

  • {request-id}: Use the appropriate Request ID

When you login with the username and password of the test account, you can see the result of the transaction in your browser.

Transaction Types

check-signature/authorization

check-signature and its related transaction types are transaction types that are dependent on the payment method not of elementary need for processing via Wirecard Payment Gateway. Some payment methods just provide the possibility to verify if this payment method is allowed to process by this consumer account or to verify if the account data are valid. In WEP both Transaction Types are visible.

Example

For Sofort. the transaction type check-signature can be submitted to validate the digital signature.

get-url/pending-debit/pending-credit

get-url and its related transaction types are transaction types that depend on the payment method of elementary need for processing via Wirecard Payment Gateway. Because of that for some payment methods they are additionally created automatically even they were not sent via the integration option. In WEP these Transaction Types are visible.

Example

For SEPA Direct Debit the transaction type pending-credit is created in addtion to the credit that was submitted to visualize the process steps.

  • submitted credit ⇒ visible in WEP pending-credit and credit

  • submitted debit ⇒ visible in WEP pending-debit and debit

auto-sale

auto-sale is a pseudo transaction type, which has been created for the purpose of offering merchants and easier way to integrate the standard and most widely used "SALE" transactions. auto-sale does not exist as an individual transaction type. It is only a place-holder which is used by the Wirecard Payment Gateway to decide which transaction type should be used for a specific transaction. When using auto-sale, the merchant is not required to send a specific transaction-type for each credit card or alternative payment method request.

Basic Configuration

A merchant is automatically configured to use the default settings for auto-sale.

The Wirecard Payment Gateway has already configured a default transaction type for auto-sale per payment method. The default values are:

  • For credit card, auto-sale corresponds to purchase.

  • For all other alternative payment methods, auto-sale corresponds to debit.

If a merchant sends in a transaction with transaction type auto-sale, these default values will be used.

The transaction type stored in the database for a transaction request will not be stored as auto-sale, meaning the response to a payment request will include the actual transaction type and not auto-sale. It will be stored with the transaction type configured behind auto-sale. For example, a credit card transaction will be stored with transaction type purchase.

Extended Configuration

A merchant may override these default transaction types by configuring their own default transaction types. Each payment method may be configured individually for auto-sale.

This is configured in the merchant account setup. For example, a merchant may specify that for credit card, auto-sale shall correspond to authorization. This will override the automatically set correspondence of auto-sale to purchase.

Please contact Merchant Support to setup an extended configuration.

Currency Configuration

In addition to transaction type, auto-sale may also be configured for a specific currency. The merchant is able to have multi default transaction types depending on the currency.

Example

Merchant-id-1, Creditcard, EUR, authorization; Merchant-id-1, Creditcard, CZK, purchase; Merchant-id-1, Creditcard, GBP, authorization-only;

Custom URL: