REST API

The Payment Processing API conforms to the design principles of Representational State Transfer (REST). Wirecard Payment Gateway provides access to resources (data entities) via URL paths. To use a REST API, your application will make an HTTP request and parse the response. By default, the response format is XML. If you wish, you can request JSON instead of XML. Your methods will be the standard HTTP methods such as GET, PUT, POST and DELETE.

The API currently supports the following data formats:

  • for requests XML, JSON and NVP (for credit card only).

  • for responses XML, HTML or JSON. Some methods accept a subset of these formats, only.

Change the format extension to a request or set the HTTP accept header to get results in the format of your choice. Methods to retrieve data from the Payment Processing API require a GET request. Methods that submit data require a POST.

API methods that require a particular HTTP method will return an error if the request is not made using the correct method. The following HTTP Return Codes are helpful in analyzing the error.

Some API methods use optional or requisite parameters. Two things to keep in mind when making requests with parameters:

  • Parameter values should be UTF-8

  • All URLs for REST should be URL encoded.

Because the Payment Processing API is based on open standards, any web development language may be used to access the API.

Security

Every request sent to Wirecard Payment Gateway is authorized and authenticated. Users are authenticated using basic authentication over an SSL enabled channel. The Merchant Account configuration is used to authorize the request.

Going on Production

REST API endpoints
Test Environment Production Environment

Credit Card

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

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

Alternative Payment Methods

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

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

Mobile Payments

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

https://api.wirecard.com/engine/rest/mobile/payments
Please contact our Merchant Support for production environment credentials.

Create a Payment

Requests to the endpoints can be sent as XML, JSON or NVP (for credit card only).

  • Content-Type header MUST be specified within the request as "application/xml" or "application/json" to specify request body content.

  • Accept header specifies response body format - "application/xml" or "application/json". When Accept header is not specified in request then application/xml is used by default and XML is returned back in response regardless of request format.

Structure and fields naming convention is based on payment.xsd so there are the same field names used within JSON request/response as well as within XML request/response.

Payment requests taking longer than 30 seconds will be timed-out and returned with an error.

Simulations

Simulations can only be processed with credit cards!
Transaction

A Merchant Account can send a special message, requesting that the result echoes back a specific set of Transaction Statuses. The following characteristics apply:

  • Any merchant account can be used for test simulation, in production or any other environment.

  • Existing fields can be populated with information notifying the engine that this is a test transaction. This allows standard payment attributes to be used in a Merchant’s existing Order Management, Internet Booking Engine, Virtual Terminal, or any other client applications.

  • Test Transactions are never settled.

  • It is possible to simulate a successful transaction by sending a transaction status of "20x.xxxx". Any other requested Transaction Status Code will result in a transaction state of 'failed'.

  • It is possible to simulate a timeout scenario by delaying the response from the engine by client application’s timeout setting.

At times, it may be required to simulate one or more valid Transaction Statuses. The client application indicates that it wishes to have certain Transaction Statuses echoed back, and the Payment Service does so in the response.

Following is the behavior:

  • Any invalid/empty transaction statuses are not simulated. See the table of valid transaction statuses.

  • The simulation is valid for Credit Card only.

  • The payment being requested does not go to any acquirer/provider. The transaction status simulation is typically used to simulate the status from the acquirer/provider.

  • The engine performs basic data validation in order to store the data in the database. In case of any failure, the requested transaction statuses are NOT echoed back. The validation errors are returned instead.

  • The transaction can be searched in the reporting site.

  • All other aspects of the payment processing are respected, including Instant Payment Notification, Reconciliation Services, etc.

  • All test transactions will have the last transaction status of "100.5555 warning: Your transaction is in test mode."

  • Merchant Account must have a test token assigned to enable transaction status simulation.

If "100.5555" is not returned, the Transaction was NOT in Transaction Processing Test Mode, and was processed live. Watch for this to ensure the intended effect.

See the conditions to simulate a set of transaction status.

Conditions

  • The tag <accountholder/address/street1> must contain the valid transaction status to be simulated.

  • The tag <account-holder/last-name> must contain an issued test token to enable the simulation of transaction status. If multiple transaction status are required, you can add a comma-delimited set of transaction status.

Samples for a Transaction Simulation

See samples for transaction simulation.

Timeout

At times, it may be required to simulate the system not responding to the client application for an extended period of time. The client application must specify that a timeout value of n milliseconds by using the <last-name> field in conjunction with the Test Token. The value of n should be more than the client application’s timeout setting.

Conditions

  • The tag <accountholder/address/street1> must contain a valid transaction status and a defined timeout period in milliseconds. If multiple transaction status are required, you can add a comma-delimited set of transaction status.

  • The tag <account-holder/last-name> must contain an issued test token to enable a timeout simulation.

Samples for a Timeout Simulation

See samples for timeout simulation.

Reference Transaction

At times, it may be required to simulate a transaction followed by another one referencing the first, such as a credit card authorization followed by a capture. In the reference transactions <street1> field is not used. As such, the client application indicates the expected status of the referenced transaction in the initial transaction. E.g. excepted status code of a capture transaction must be indicated in the initial authorization. This is indicated in the <street1> field with a grammar including a short form of the transaction type. The ordering of the status codes in the tag <accountholder/address/street1> is significant. Payment Service analyses the transaction type in a payment workflow or group and applies the status code as mentioned in the original transaction and returns it to the client application.

Transaction Type Short Form

authorization-only

AO

authorization

A

capture-authorization

CA

purchase

P

void-capture

VC

void-purchase

VP

check-risk

C
Conditions

  • The status codes must be set during the first transaction request.

  • The tag <accountholder/address/street1> must contain two valid transaction status for both transactions.

Example

The client application would like to simulate a successful zero dollar authorization, followed by credit card declined during the charge:

  1. Zero Dollar Authorization: 201.0000

  2. Purchase: 500.1053

This expected status codes were set during the ZDA request as follows:

<street1>AO-201.0000,P-500.1053</street1>

Samples for a Reference Transaction Simulation

See samples for reference transaction simulation.

Samples

For All Payment Methods
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>fb78df4a-9784-4fea-bd3c-1038e031ad56</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@wirecard.com</email>
      <phone>+1(1)4161234567</phone>
      <address>
          <street1>123 anystreet</street1>
          <city>Brantford</city>
          <state>ON</state>
          <country>CA</country>
      </address>
   </account-holder>
   <card>
    <account-number>4444333322221111</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-methods>
     <payment-method name="creditcard"/>
   </payment-methods>
 </payment>
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/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/6c770e46-36a0-11e5-b074-005056a96a54">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea">9105bb4f-ae68-4768-9c3b-3eda968f57ea</merchant-account-id>
    <transaction-id>6c770e46-36a0-11e5-b074-005056a96a54</transaction-id>
    <request-id>fb78df4a-9784-4fea-bd3c-1038e031ad56</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2015-07-30T09:50:35.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@wirecard.com</email>
        <phone>+1(1)4161234567</phone>
        <address>
            <street1>123 anystreet</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
        </address>
    </account-holder>
    <card-token>
        <token-id>4672942444021111</token-id>
        <masked-account-number>444433******1111</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <descriptor/>
    <payment-methods>
        <payment-method name="creditcard"/>
    </payment-methods>
    <authorization-code>106079</authorization-code>
    <api-id>elastic-api</api-id>
</payment>
JSON
JSON Purchase Request (Successful)
{
  "payment" : {
    "merchant-account-id" : {
      "value" : "9105bb4f-ae68-4768-9c3b-3eda968f57ea"
    },
    "request-id" : "fb78df4a-9784-4fea-bd3c-1038e031ad56",
    "transaction-type" : "purchase",
    "requested-amount" : {
      "value" : 1.01,
      "currency" : "USD"
    },
    "account-holder" : {
      "first-name" : "John",
      "last-name" : "Doe",
      "email" : "john.doe@wirecard.com",
      "phone" : "+1(1)4161234567",
      "address" : {
        "street1" : "123 anystreet",
        "city" : "Brantford",
        "state" : "ON",
        "country" : "CA"
      }
    },
    "card" : {
      "account-number" : "4444333322221111",
      "expiration-month" : 12,
      "expiration-year" : 2020,
      "card-security-code" : "123",
      "card-type" : "visa"
    },
    "ip-address" : "127.0.0.1",
    "payment-methods" : {
      "payment-method" : [ {
        "name" : "creditcard"
      } ]
    }
  }
}
JSON Purchase Response (Successful)
{
  "payment" : {
    "merchant-account-id" : {
      "value" : "9105bb4f-ae68-4768-9c3b-3eda968f57ea",
      "ref" : "https://api-test.wirecard.com:443/engine/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea"
    },
    "transaction-id" : "6c770e46-36a0-11e5-b074-005056a96a54",
    "request-id" : "fb78df4a-9784-4fea-bd3c-1038e031ad56",
    "transaction-type" : "purchase",
    "transaction-state" : "success",
    "completion-time-stamp" : 1438249835000,
    "statuses" : {
      "status" : [ {
        "value" : "",
        "code" : "201.0000",
        "description" : "3d-acquirer:The resource was successfully created.",
        "severity" : "information"
      } ]
    },
    "requested-amount" : {
      "value" : 1.01,
      "currency" : "USD"
    },
    "account-holder" : {
      "first-name" : "John",
      "last-name" : "Doe",
      "email" : "john.doe@wirecard.com",
      "phone" : "+1(1)4161234567",
      "address" : {
        "street1" : "123 anystreet",
        "city" : "Brantford",
        "state" : "ON",
        "country" : "CA"
      }
    },
    "card-token" : {
      "token-id" : "4672942444021111",
      "masked-account-number" : "444433******1111"
    },
    "ip-address" : "127.0.0.1",
    "descriptor" : "",
    "payment-methods" : {
      "payment-method" : [ {
        "name" : "creditcard"
      } ]
    },
    "authorization-code" : "106079",
    "api-id" : "elastic-api",
    "self" : "https://api-test.wirecard.com:443/engine/merchants/9105bb4f-ae68-4768-9c3b-3eda968f57ea/payments/6c770e46-36a0-11e5-b074-005056a96a54"
  }
}
Credit Card Only
Transaction Simulation
XML Purchase Request (Failure)
<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>07edc10b-d3f9-4d12-901f-0db7f4c7e75c</merchant-account-id>
   <request-id>9ab09625-12cb-4deb-b856-2feea2645dcb</request-id>
   <transaction-type>purchase</transaction-type>
   <requested-amount currency="USD">1.01</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>RYKGJ123VDEYORMZS456</last-name>
      <email>john.doe@wirecard.com</email>
      <phone>+1(416)1112222</phone>
      <address>
         <street1>500.1053</street1>
         <city>Brantford</city>
         <state>ON</state>
         <country>CA</country>
      </address>
   </account-holder>
   <card>
      <account-number>4444333322221111</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-methods>
      <payment-method name="creditcard" />
   </payment-methods>
</payment>
XML Purchase Response (Failure)
<?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/07edc10b-d3f9-4d12-901f-0db7f4c7e75c/payments/ce7e0750-78c7-438f-a949-841115b7815d">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/07edc10b-d3f9-4d12-901f-0db7f4c7e75c">07edc10b-d3f9-4d12-901f-0db7f4c7e75c</merchant-account-id>
    <transaction-id>ce7e0750-78c7-438f-a949-841115b7815d</transaction-id>
    <request-id>9ab09625-12cb-4deb-b856-2feea2645dcb</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>failed</transaction-state>
    <completion-time-stamp>2018-07-10T10:23:48.000Z</completion-time-stamp>
    <statuses>
        <status code="500.1053" description="The acquirer returned Declined.  Please check with Issuer, or use different card." severity="error" />
        <status code="100.5555" description="test Transaction" severity="information" />
    </statuses>
    <requested-amount currency="USD">1.01</requested-amount>
    <account-holder>
        <first-name>John</first-name>
        <last-name>RYKGJ123VDEYORMZS456</last-name>
        <email>john.doe@wirecard.com</email>
        <phone>+1(416)1112222</phone>
        <address>
            <street1>500.1053</street1>
            <city>Brantford</city>
            <state>ON</state>
            <country>CA</country>
        </address>
    </account-holder>
    <card-token>
        <token-id>4193258203791111</token-id>
        <masked-account-number>444433******1111</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-detail>609669634369250</order-detail>
    <payment-methods>
        <payment-method name="creditcard" />
    </payment-methods>
</payment>
Timeout Simulation

The following request shows a transaction status simulation for a successful credit card transaction that responded after 60,000 milliseconds.

XML Purchase Timeout Simulation Request (Successful)
<?xml version="1.0" encoding="utf-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <payment-methods>
      <payment-method name="creditcard" />
   </payment-methods>
   <merchant-account-id>07edc10b-d3f9-4d12-901f-0db7f4c7e75c</merchant-account-id>
   <request-id>6d324e6b-0d97-43bb-8688-52aee348655d</request-id>
   <transaction-type>purchase</transaction-type>
   <requested-amount currency="USD">1.01</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>RYKGJ123VDEYORMZS456</last-name>
      <email>john.doe@wirecard.com</email>
      <phone />
      <address>
         <street1>201.0000,timeout-60000</street1>
         <city>Brantford</city>
         <state>ON</state>
         <country>CA</country>
      </address>
   </account-holder>
   <card>
      <account-number>4444333322221111</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>
XML Purchase Timeout Simulation 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/07edc10b-d3f9-4d12-901f-0db7f4c7e75c/payments/a480eb86-7e14-4654-99cd-6eeccba4c02c">
    <merchant-account-id ref="https://api-test.wirecard.com:443/engine/rest/config/merchants/07edc10b-d3f9-4d12-901f-0db7f4c7e75c">07edc10b-d3f9-4d12-901f-0db7f4c7e75c</merchant-account-id>
    <transaction-id>a480eb86-7e14-4654-99cd-6eeccba4c02c</transaction-id>
    <request-id>6d324e6b-0d97-43bb-8688-52aee348655d</request-id>
    <transaction-type>purchase</transaction-type>
    <transaction-state>success</transaction-state>
    <completion-time-stamp>2018-07-10T10:27:55.000Z</completion-time-stamp>
    <statuses>
              <status code="201.0000" description="The resource was successfully created." severity="information" />
              <status code="100.5555" description="test Transaction" severity="information" />
    </statuses>
    <requested-amount currency="USD">1.01</requested-amount>
    <account-holder>
              <first-name>John</first-name>
              <last-name>RYKGJ123VDEYORMZS456</last-name>
              <email>john.doe@wirecard.com</email>
              <phone/>
              <address>
                        <street1>201.0000,timeout-60000</street1>
                        <city>Brantford</city>
                        <state>ON</state>
                        <country>CA</country>
              </address>
    </account-holder>
    <card-token>
              <token-id>4193258203791111</token-id>
              <masked-account-number>444433******1111</masked-account-number>
    </card-token>
    <ip-address>127.0.0.1</ip-address>
    <order-detail>613464402851117</order-detail>
    <payment-methods>
              <payment-method name="creditcard" />
    </payment-methods>
</payment>
Referenced Transaction Simulation
XML Initial Zero Dollar Authorization Request (Successful)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>c3671cf9-c775-4e39-8d67-31ce24094682</merchant-account-id>
   <request-id>89c20f59-23cd-4be6-a121-d6b2499aa604</request-id>
   <transaction-type>authorization-only</transaction-type>
   <requested-amount currency="USD">0</requested-amount>
   <account-holder>
      <first-name>John</first-name>
      <last-name>qmNmRoMhhgxtlLhvETNhaKHimBbwiJRy</last-name>
      <email>john.doe@wirecard.com</email>
      <phone>+1(416)1112222</phone>
      <address>
         <street1>AO-201.0000,P-500.1053</street1>
         <city>Brantford</city>
         <state>ON</state>
         <country>CA</country>
      </address>
   </account-holder>
   <card>
      <account-number>4444333322221111</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-methods>
      <payment-method name="creditcard" />
   </payment-methods>
</payment>
XML Initial Zero Dollar Authorization Response (Successful)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="http://10.0.0.142:8080/engine/rest/merchants/c3671cf9-c775-4e39-8d67-31ce24094682/payments/30c061a8-862f-11e2-bd92-00163e6e1b2f">
   <merchant-account-id ref="http://10.0.0.142:8080/engine/rest/config/merchants/c3671cf9-c775-4e39-8d67-31ce24094682">c3671cf9-c775-4e39-8d67-31ce24094682</merchant-account-id>
   <transaction-id>30c061a8-862f-11e2-bd92-00163e6e1b2f</transaction-id>
   <request-id>89c20f59-23cd-4be6-a121-d6b2499aa604</request-id>
   <transaction-type>authorization</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2013-03-06T07:26:41.523Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="success" />
      <status code="100.5555" description="warning: Your transaction is in test mode" severity="information" />
   </statuses>
   <requested-amount currency="USD">1.01</requested-amount>
   <card-token>
      <token-id>4671168333191111</token-id>
      <masked-account-number>444433******1111</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>
</payment>
XML Following Purchase Request (Failure)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>c3671cf9-c775-4e39-8d67-31ce24094682</merchant-account-id>
   <request-id>89c20f59-23cd-4be6-a121-d6b2499aa604</request-id>
   <transaction-type>purchase</transaction-type>
   <parent-transaction-id>30c061a8-862f-11e2-bd92-00163e6e1b2f</parent-transaction-id>
   <requested-amount currency="USD">1.01</requested-amount>
   <ip-address>127.0.0.1</ip-address>
</payment>
XML Following Purchase Response (Failure)
<?xml version="1.0" encoding="UTF-8"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" self="http://10.0.0.142:8080/engine/rest/merchants/c3671cf9-c775-4e39-8d67-31ce24094682/payments/30c061a8-862f-11e2-bd92-00163e6e1b2f">
   <merchant-account-id ref="http://10.0.0.142:8080/engine/rest/config/merchants/c3671cf9-c775-4e39-8d67-31ce24094682">c3671cf9-c775-4e39-8d67-31ce24094682</merchant-account-id>
   <transaction-id>30c061a8-862f-11e2-bd92-00163e6e1b2f</transaction-id>
   <request-id>89c20f59-23cd-4be6-a121-d6b2499aa604</request-id>
   <transaction-type>purchase</transaction-type>
   <transaction-state>failed</transaction-state>
   <completion-time-stamp>2013-03-06T07:26:41.523Z</completion-time-stamp>
   <statuses>
      <status code="500.1053" description="The acquirer returned Declined. Please check with Issuer, or use different card." severity="error" />
      <status code="100.5555" description="warning: Your transaction is in test mode " severity="information" />
   </statuses>
   <requested-amount currency="USD">1.01</requested-amount>
   <card-token>
      <token-id>4671168333191111</token-id>
      <masked-account-number>444433******1111</masked-account-number>
   </card-token>
   <ip-address>127.0.0.1</ip-address>
   <payment-methods>
      <payment-method name="creditcard" />
   </payment-methods>
</payment>

← Payment Page Solutions | Mobile Payment SDK →