Created on: 2017-04-06 15:10 by

Wirecard CEE Integration Documentation

() -

Created: 2017-04-06 15:10

Online Guides - Integration documentation 1/14

 Created on: 2017-04-06 15:10 by
-

API Reference

The Wirecard CEE REST API uses a standard REST 1) interface. Requests and responses are sent in
JSON data format and the OAuth 2.0 standard is used for authentication and authorization.

JSON

The data format used in the following cases is the open standard JSON which uses human readable
text to transmit data objects and largely replaces XML.

For most programming languages there are ready-to-use implementations as the list on
www.json.org shows.

In general, a JSON object may look like this:

{
"name1": "value1",
"subObject1": {
"subName1": "subValue1"
},
"orderedArray1": [
{"arrayName1": "arrayValue1" },
{"arrayName2": "arrayValue2" }
]
"number1": 1
}

Authorization

For all requests to our server you need to provide an authorization token. Since the OAuth 2.0
standard is an open protocol it is already implemented in most programming languages. You can
find a list on oauth.net.

Authorization Process

By sending a valid authorization request an access token will be returned. This token allows you
to access resources on our server.

An example request (HTTP header and body, separated by a line break) could be:

Online Guides - Integration documentation 2/14

 Created on: 2017-04-06 15:10 by
-

POST https://checkout.wirecard.com/oauth/token HTTP/1.1

Content-Type: application/x-www-form-urlencoded
Authorization: Basic RDIwMDQxMTpteXNlY3JldHBhc3N3b3Jk

grant_type=client_credentials

The following table explains each line more detailed. You can copy most of the lines except for the
Authorization, which contains the credentials assigned to you by Wirecard.

Line Description
POST Required request method is POST.
https://checkout.wirecard.com/oauth/token Resource for authentication is
HTTP/1.1 /oauth/token.
Content-Type: The Content-Type as defined in the
application/x-www-form-urlencoded OAuth2.0 standard.
Basic authorization via Base64 encoded
credentials in the form
<merchantId>:<clientSecret>
Merchant ID assigned to
merchantId
you by Wirecard.
Client secret assigned to
Authorization: Basic you by Wirecard. Please
RDIwMDAwMTpteXNlY3JldHBhc3N3b3Jk note that
clientSecret is NOT
clientSecret the request parameter
called secret which is
used for parameter
verification against other
Wirecard interfaces.
The grant type Wirecard uses for
grant_type=client_credentials
authorization.

The JSON object in the response body would be:

Response Property Description

Object encapsulating the
access_token
{ security identity.
"access_token": Type Bearer is used to get
"e378debf-60a3-4323-aa37-0124e3aa9ced", token_type access to the associated
"token_type": "Bearer", resources.
"expires_in": 1800, Time in seconds until the
"scope": "masterpass" expires_in
token expires.
} Specifies the resources you
scope
have access to.

The access_token allows you to access the resources on

https://checkout.wirecard.com/. You have to provide the token_type and the
access_token in the header field ”Authorization”. This access token is valid as long as specified
in the property expires_in which is also sent in the server response.

A follow-up request header example would be:

Online Guides - Integration documentation 3/14

 Created on: 2017-04-06 15:10 by
-

GET https://checkout.wirecard.com/masterpass/merchants HTTP/1.1

Authorization: Bearer e378debf-60a3-4323-aa37-0124e3aa9ced

Masterpass Shipping Profiles

You can define shipping profiles for the items you sell in your online shop. These profiles allow to
define geographic restrictions which are applied to the addresses in the Masterpass wallet of your
consumer. Thus only those shipping addresses are shown to your consumer you actually ship items to.
Please contact our support teams to create the profiles for you.

During the checkout process you can retrieve the available shipping profiles as described in the
following section. You can then select those that are applicable to the items your consumer has put in
his shopping basket and forward the possible profiles to the Wirecard Checkout Server. The addresses
which are not compatible with the shipping profiles you selected will not be available for your
consumer to choose during the checkout process in the Masterpass wallet.

Retrieving the Masterpass Shipping Profiles

You can get the list of shipping profiles assigned to your configuration by an authorized request.

GET /masterpass/merchants/<merchantId>/shipping-profiles

The request header is for example:

GET
https://checkout.wirecard.com/masterpass/merchants/D200001-masterpass/shippi
ng-profiles HTTP/1.1
Authorization: Bearer e378debf-60a3-4323-aa37-0124e3aa9ced

Response Property Description

HTTP/1.1 200 OK
Content-Type:
application/json; Unique ID of the “shipping profile” resource. Can be
charset=UTF-8 id used to limit Masterpass wallet requests to specific
shipping profiles.
[{
"id": "WDCEDACH",
"description":
"Deutschland, Description for this “shipping profile” resource.
description
Österreich, Schweiz" Contains a list of countries enabled in this resource.
}]

Masterpass Shipping Profile Details

Online Guides - Integration documentation 4/14

 Created on: 2017-04-06 15:10 by
-

Each single shipping profile can also be obtained by an authorized GET request to its resource link.

GET /masterpass/merchants/<merchantId>/shipping-profiles/<shippingProfileId>

Response example

Response Property Description

HTTP/1.1 200 OK
Content-Type:
application/json; Unique ID of the shipping profile. Can be used by the
charset=UTF-8 id merchants implementation to limit Masterpass wallet
requests to specific shipping profiles.
{
"id": "WDCEDACH",
"description":
"Deutschland, Description for this shipping profile. Contains a list of
description
Österreich, Schweiz" countries enabled in this resource.
}

Error messages

The following error messages are possible when requesting shipping profiles.

HTTP status
Error message Explanation
code
Could not retrieve shippingProfile for ID There are no shipping profiles assigned
404
'merchantId'. to the provided merchantId.

Masterpass Wallet

To start the checkout process a Masterpass wallet needs to be created. This wallet is used to
transfer information between your shop and Masterpass. In this wallet you need to store the amount
you want to bill your consumer. Since this wallet is created before your consumer can select the
shipping address, this amount must exclude shipping costs. To show the shopping basket while
your consumer is interacting with Masterpass you need to store the shopping basket in the wallet
resource.

After your consumer selected the shipping address and the credit card you can access payment
details, shipping address and billing address via this wallet.

Creating a Wallet

The following request can be used to create a wallet resource.

Online Guides - Integration documentation 5/14

 Created on: 2017-04-06 15:10 by
-

POST /masterpass/merchants/<merchantId>/wallets
Authorization: Bearer <access_token>
Content-Type: application/json;charset=UTF-8

Example of the JSON object in the request:

POST /masterpass/merchants/D200001-masterpass/wallets HTTP/1.1

Authorization: Bearer e378debf-60a3-4323-aa37-0124e3aa9ced
Content-Type: application/json;charset=UTF-8

{
"originUrl": "https://www.demoshop.at/",
"basket": {
"totalAmount": {
"amount": 99.79,
"currency": "EUR"
},
"items": [{
"articleNumber": "A1",
"name": "Item 1",
"description": "something",
"quantity": 1,
"unitGrossAmount": { "amount": 19.99, "currency": "EUR" },
"unitNetAmount": { "amount": 16.66, "currency": "EUR" },
"unitTaxAmount": { "amount": 3.33, "currency": "EUR" },
"unitTaxRate": 20,
"imageUrl": "https://www.demoshop.at/item01.jpg"
},
{
"articleNumber": "A2",
"name": "Item 2",
"description": "something else",
"quantity": 2,
"unitGrossAmount": { "amount": "39,90", "currency": "EUR" },
"unitNetAmount": { "amount": "33,25", "currency": "EUR" },
"unitTaxAmount": { "amount": "6,65", "currency": "EUR" },
"unitTaxRate": 20,
"imageUrl": null
}]
}
}

Request
Max
Name Type Description Required
length
basket Object Basket object. yes
Total amount and currency you want to bill your
totalAmount Object yes
consumer (excluding shipping costs).

Online Guides - Integration documentation 6/14

 Created on: 2017-04-06 15:10 by
-

Can contain up to 19 digits followed by a

decimal separator and the maximum digits
allowed depending on the currency, e.g. two
amount Decimal yes 19.4
digits for EUR. If comma is used as decimal
separator, the amount must be a string, i.e.
"amount": 4.20 or "amount": "4,20".
currency String Currency in 3-letter abbreviation (ISO 4217). yes
If items is
quantity Integer Quantity of each item.
used.
URL of your shop (“http://” or “https://” is
originUrl String yes
required).
items Object Array of the items your consumer ordered. no
articleNumber String Unique ID of item in shopping basket. yes 127
name String Item name in shopping basket. yes 127
description String Item description in shopping basket. no 500
quantity Integer Number of items in shopping basket. yes
imageUrl String URL to an image of each item. no
Price per unit of item in shopping basket with
unitGrossAmount Object taxes (for more info see totalAmount yes
description).
Price per unit of item in shopping basket without
unitNetAmount Object yes
taxes.
unitTaxAmount Object Tax amount per unit of item in shopping basket. yes
Percentage of tax per unit of item in shopping
unitTaxRate Decimal yes
basket.

If the request is successful, the same object as requested will be returned as response
including the wallet ID as property id.

Error messages

The following error messages are possible when creating a wallet resource.

HTTP status
Error message Explanation
code
No callback URL or function was given.
400 Bad Request. You are not allowed to add wallets using the provided
merchantId.

Reading a Wallet

After your consumer finishes the interaction with Masterpass, the information your consumer
provided is stored in the wallet resource you created. To retrieve the information, the following
request can be used.

GET /masterpass/merchants/<merchantId>/wallets/<walletId>

Online Guides - Integration documentation 7/14

 Created on: 2017-04-06 15:10 by
-

Example of the JSON object in the response:

{
"id": "0aa18d3d-bffe-44dd-bdda-34161c908a45",
"created": "2015-11-16T16:14:29.000Z",
"basket": { [ ... ] },
"card": {
"transactionId": "396105201",
"expiryMonth": 7,
"expiryYear": 2020,
"cardHolderName": "Masterpass Card Holder",
"anonymousPan": "0007",
"hashedPan": "88faba348f46294ea23ad2ac6db2761ac73a[...]",
"maskedPan": "5422******0007",
"masterpassWalletId": "101",
"created": "2015-11-16T16:15:26.000Z",
"firstName": "Joe",
"lastName": "Test",
"country": "US",
"emailAddress": "joe.test@email.com",
"phoneNumber": "1-9871111111"
},
"shippingAddress": {
"city": "Buffalo Grove",
"country": "US",
"countrySubdivision": "US-IL",
"postalCode": "60089",
"addressLine1": "681 Bernard Drive",
"addressLine2": "",
"addressLine3": "",
"recipientName": "Aaron Aardsma",
"recipientPhoneNumber": "US+1-8155370618"
},
"billingAddress": {
"city": "Buffalo Grove",
"country": "US",
"countrySubdivision": "US-IL",
"postalCode": "60089",
"addressLine1": "681 Bernard Drive",
"addressLine2": "",
"addressLine3": ""
}
}

(Min-)Max.
Name Type Description
length
id String ID of the wallet. 255
Wallet creation timestamp (format:
created DateTime 27
“YYYY-MM-DD'T'hh:mm:ss.sss'Z”).
basket Object Object containing the basket information. Same as above.

Online Guides - Integration documentation 8/14

 Created on: 2017-04-06 15:10 by
-

card Object Card data object available for the wallet.

transactionId String Masterpass transaction ID. 255
expiryMonth Integer Credit card expiry month. 2
expiryYear Integer Credit card expiry year. 4
cardHolderName String Credit card cardholder name. 100
anonymousPan String Last 4 digits of credit card PAN. 2) 4
hashedPan String Hashed credit card PAN 3). 255
maskedPan String Masked credit card PAN. 4) 20
Payment details creation timestamp (format:
created DateTime 27
“YYYY-MM-DD'T'hh:mm:ss.sss'Z”)
firstName String Contact data first name. 20
lastName String Contact data last name. 20
middleName String Contact data middle name. 20
gender String Contact data gender (M/F). 1
Contact data birth-date (format:
birthDate Date 14
“YYYY-MM-DD”).
nationalId String Contact data national identification. 150
Two-letter country code (ISO 3166-1) of
country String 2
residence.
emailAddress String Contact e-mail address. 5-512
phoneNumber String Contact phone number. 3-20
Object containing the shipping address provided by Masterpass
shippingAddress Object
wallet.
city String Shipping address city. 25
Shipping address country as two-letter country
country String 2
code (ISO 3166-1).
countrySubdivision String Shipping address country subdivision. 255
postalCode String Shipping address postal code. 20
addressLine1 String Shipping address line 1. 40
addressLine2 String Shipping address line 2. 40
addressLine3 String Shipping address line 3. 255
Name of the person specified in the shipping
recipientName String 100
address.
Phone number of person set to receive the
recipientPhoneNumber String 20
shipped order.
billingAddress Object Billing Address object corresponding to the selected credit card.
city String Billing address city. 25
Billing address country as two-letter country
country String 2
code (ISO 3166-1).
countrySubdivision String Billing address country subdivision. 255
postalCode String Billing address postal code. 20
addressLine1 String Billing address line 1. 40
addressLine2 String Billing address line 2. 40
addressLine3 String Billing address line 3. 255

Additionally if you only want to retrieve the card details or the billing address or shipping
address, the request can be confined. If such a request is made, the response will be only the

Online Guides - Integration documentation 9/14

 Created on: 2017-04-06 15:10 by
-

shipping address or the payment details object as described above.

Placeholder
Resource URI
description

Client ID
Card
/masterpass/merchants/<merchantId>/wallets/<walletId>/card assigned
details <merchantId>
to you by
Wirecard.
Shipping Wallet ID
/masterpass/merchants/<merchantId>/wallets/<walletId>/shipping-address
address you
received
in
<walletId>
Billing response
/masterpass/merchants/<merchantId>/wallets/<walletId>/billing-address of
address
creating
a wallet.

Error messages

The following error messages are possible when reading a wallet resource.

HTTP
status Error message Explanation
code
Merchant resource not found or not The merchantId is invalid.
permissible. Querying the requested resources is not allowed.
404
Wallet resource not found or not Wallet with provided walletId does not exist or
permissible. is not accessible.

Initiating the payment

If the wallet contains the expected card details, you can initiate the payment with a POST request.

POST /masterpass/merchants/<merchantId>/wallets/<walletId>/payment

Example of the JSON object in the request:

{
"orderNumber": 285703324,
"orderDescription": "John Doe - ID: 002302",
"totalAmount": {
"amount": 104.79,
"currency": "EUR"
},
"customerStatement": "Your purchase at the example store.",
"orderReference": "234092",
"notificationUrl": "https://www.demoshop.at/payment_notification.php",
"deposit": false,
"useWalletConsumerData": true

Online Guides - Integration documentation 10/14

 Created on: 2017-04-06 15:10 by
-

Max.
Name Type Description Required
length
orderNumber Integer Order number of payment. no 9
Unique description of the consumer's
orderDescription String yes 255
order in a human readable form.
Total amount and currency you want to
totalAmount Object bill your consumer (including shipping yes
costs).
Total amount (ISO 4217) you want to bill
amount Decimal yes 19.4
your consumer (including shipping costs).
Currency given as ISO 4270 three letter
currency String yes 3
currency code, e.g. EUR.
Text displayed on bank statement issued
to your consumer by the financial service
customerStatement String provider. Relevant information for your no 254
consumer to identify the payments made
to your online shop.
Unique order reference ID sent from
merchant to financial institution.
orderReference String Convenient to correlate the order no 128
numbers of your online shop with the
effected payments.
URL to which a notification will be sent
notificationUrl String when the payment is processed. Only no
http(s) with ports 80/443 are possible.
Enable automated debiting of payments.
deposit Boolean no true/false
default = false
Use Masterpass wallet's billing and
useWalletConsumerData Boolean shipping data in payment initiation. no true/false
default = true

The amount can contain up to 19 digits followed by a decimal separator and the maximum digits
allowed depending on the currency, e.g. two digits for EUR. If comma is used as decimal separator,
the amount must be a string, i.e. "amount": 4.20 or "amount": "4,20".

For a successful request the orderNumber and "processingState":"PENDING" will be returned.

{
"orderNumber": 285703324,
"processingState": "PENDING"
}

The notification URL will be requested one time only when the final payment process state is
reached. This POST request contains the parameters walletId with the ID of the wallet and state
with the final state of the payment, i.e. SUCCESS or FAILURE.

Online Guides - Integration documentation 11/14

 Created on: 2017-04-06 15:10 by
Final transaction results -

Error messages
The following table contains a summary of all data that are returned if the processing state has
changed to SUCCESS and states both always returned data and only optionally returned data.
The following error messages are possible when initiating a payment.
{
HTTP
"orderNumber": 285703324,
status Error message Explanation
"orderDescription": "John Doe - ID: 002302",
code
"customerStatement": "Your purchase at the example store.",
Value for parameter orderNumber
400"amount": { The orderNumber requires a specific format.
is invalid.
"currency": "EUR",
400 orderNumber already used. An orderNumber may only be used once.
"amount": 104.79
Wallet has already been processed or is currently
400}, Already processed.
processing.
"approvalCode":"708491",
"approveAmount": { No Masterpass wallet data available yet. Consumer
412 "currency":
No card data available
"EUR", yet. has not yet finished the interaction with the
Masterpass wallet.
"amount": 104.79
Payment related card data timed The data required for the payment was deleted due
412},
out. to time out.
"depositAmount": {
Communication error with Impaired communication with the processing
502 "currency": "EUR",
processing system. system.
"amount": 0.00
502}, Could not initiate processing. The payment process could not be started.
"gatewayReferenceNumber": "C837757147074816743447",
"gatewayContractNumber": "70031",
Receiving the final
"paymentNumber": transaction result
446758869,
"paymentState": "payment_approved",
"processingDate": "2016-08-09T13:09:27.000Z",
To receive the final result of"234092",
"orderReference": the payment process, you can request the following resource.
"processingState": "SUCCESS",
GET /masterpass/merchants/<merchantId>/wallets/<walletId>/payment
"brand": "MasterCard SecureCode/MasterPass"
}
The processingState is either still PENDING with the same result as above or has changed to
SUCCESS or FAILURE. Max.
Name Type Description Always Optional
length
orderNumber Integer Order number of payment. ✔ 9
Unique description of the consumer's
orderDescription String ✔ 255
order in a human readable form.
Text displayed on bank statement issued
customerStatement String to your consumer by the financial service ✔ 128
provider.
Approval code of financial service provider
approvalCode String ✔
(may be also an empty string).
approveAmount Object Approved amount and currency. ✔
amount Decimal Total amount (ISO 4217). ✔ 19.4
Currency given as ISO 4270 three letter
currency String ✔ 3
currency code, e.g. EUR.
depositAmount Object Deposited amount and currency. ✔
amount Decimal Total amount (ISO 4217). ✔ 5)
19.4
Currency given as ISO 4270 three letter
currency String ✔6) 3
currency code, e.g. EUR.

Online Guides - Integration documentation 12/14

 Created on: 2017-04-06 15:10 by
-

Country of the consumer which has been

detected and returned by the financial
instrumentCountry String service provider. Please be aware that this ✔ 2
feature is not provided by all financial
service providers.
Unique order reference ID sent from
merchantReference String ✔ 128
merchant to financial institution.
paymentNumber Integer Number of payment. ✔ 9
Current state of payment (
payment_approved,
paymentState String ✔ 32
payment_deposited, payment_closed
or payment_approvalexpired).
Technical reference number of the
providerReferenceNumber String ✔ 255
financial service provider or acquirer.
Date and time when order has been
processingDate Date processed ✔ 28
(Format:“yyyy-MM-dd'T'HH:mm:ss.SSS'Z”).
Unique order reference ID sent from
orderReference String ✔ 128
merchant to financial institution.
Current state of payment SUCCESS,
processingState String ✔
FAILURE, PENDING).
Brand of used credit card. Alphanumeric
brand String with a variable length of up to 255 ✔ 255
characters.
Technical reference number of the
gatewayReferenceNumber String ✔ 255
payment process.
Contract number of the processor or
gatewayContractNumber String ✔ 255
acquirer.
Result code of AVS check. Only for
avsResultCode String American Express transactions using AVS ✔ 5
(Address Verification System).
Result text of AVS check. Only for
avsResultMessage String American Express transactions using AVS ✔ 256
(Address Verification System).
Provider result code of AVS check. Only for
avsProviderResultCode String American Express transactions using AVS ✔ 5
(Address Verification System).
Provider result text of AVS check. Only for
avsProviderResultMessage String American Express transactions using AVS ✔ 256
(Address Verification System).

If the processing state has changed to FAILURE, the following data is returned:

{
"orderNumber": 285703324,
"orderDescription": "John Doe - ID: 002302",
"customerStatement": "Your purchase at the example store.",
"errorCode": "<error code>",
"errorMessage": "<error message>",
"paysysMessage": "<payment system error message>",
"orderReference": "234092",
"processingState": "FAILURE"
}

Online Guides - Integration documentation 13/14

 Created on: 2017-04-06 15:10 by
-

Error messages

The following error messages are possible when receiving the final transaction results.

HTTP status
Error message
code
200 Value for parameter orderNumber is invalid.
Parameter orderNumber has to be unique for this operation. Most likely, this
200
transaction has already been processed.
404 Wallet not yet processed.
404 Unknown wallet.
410 Payment not retrievable from processing system.

For status code 200 the property for the error message is errorMessage, otherwise it is message.
1)
Representational State Transfer
2)
, 4) Will not be returned, if hashedPan is enabled.
3)
Only if explicitly enabled by our support teams.
5)
, 6) If stated

Online Guides - Integration documentation 14/14