API Reference

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:

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 https://checkout.wirecard.com/oauth/token HTTP/1.1

Required request method is POST. Resource for authentication is /oauth/token.

Content-Type: application/x-www-form-urlencoded

The Content-Type as defined in the OAuth2.0 standard.

Authorization: Basic RDIwMDAwMTpteXNlY3JldHBhc3N3b3Jk

Basic authorization via Base64 encoded credentials in the form
<merchantId>:<clientSecret>

:::

merchantId

Merchant ID assigned to you by Wirecard.

:::

clientSecret

Client secret assigned to you by Wirecard. Please note that clientSecret is NOT the request parameter called secret which is used for parameter verification against other Wirecard interfaces.

grant_type=client_credentials

The grant type Wirecard uses for authorization.

The JSON object in the response body would be:

Response Property Description

+{ "access_token": "e378debf-60a3-4323-aa37-0124e3aa9ced", "token_type": "Bearer", "expires_in": 1800, "scope": "masterpass" } +

access_token

Object encapsulating the security identity.

:::

token_type

Type Bearer is used to get access to the associated resources.

:::

expires_in

Time in seconds until the token expires.

:::

scope

Specifies the resources you 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:

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/shipping-profiles HTTP/1.1
Authorization: Bearer e378debf-60a3-4323-aa37-0124e3aa9ced
Response Property Description

+HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8

[{ "id": "Shipping profile ID", "description": "Shipping profile countries" }] +

id

Unique ID of the "shipping profile" resource. Can be used to limit Masterpass wallet requests to specific shipping profiles.

:::

description

Description for this shipping profile resource. Contains a list of countries enabled in this resource.

Masterpass Shipping Profile Details

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;charset=UTF-8

{ "id": "Shipping profile ID", "description": "Shipping profile countries" } +

id

Unique ID of the shipping profiles. Can be used by the merchants implementation to limit Masterpass wallet requests to specific shipping profiles.

:::

:::

description

Description for this shipping profile resource. Contains a list of countries enabled in this resource.

Error messages

The following error messages are possible when requesting shipping profiles.

HTTP status code Error message Explanation

404

Could not retrieve shippingProfile for ID ‘merchantId’.

There are no shipping profiles assigned 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.

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

Name

Type

Description

Required

Max length

basket

Object

Basket object.

yes

totalAmount

Object

Total amount and currency you want to bill your consumer (excluding shipping costs).

yes

amount

Decimal

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

yes

19.4

currency

String

Currency in 3-letter abbreviation (ISO 4217).

yes

3

quantity

Integer

Quantity of each item.

If items is used.

originUrl

String

URL of your shop ("https://" or "https://" is required).

yes

255

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

500

unitGrossAmount

Object

Price per unit of item in shopping basket with taxes (for more info see totalAmount description).

yes

unitNetAmount

Object

Price per unit of item in shopping basket without taxes.

yes

unitTaxAmount

Object

Tax amount per unit of item in shopping basket.

yes

unitTaxRate

Decimal

Percentage of tax per unit of item in shopping basket.

yes

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 code Error message Explanation

400

Bad Request.

No callback URL or function was given.

:::

:::

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>

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": ""
  }
}
Name Type Description (Min-)Max. length

id

String

ID of the wallet.

255

created

DateTime

Wallet creation timestamp (format: "YYYY-MM-DD’T’hh:mm:ss.sss’Z").

27

basket

Object

Object containing the basket information. Same as above.

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

created

DateTime

Payment details creation timestamp (format: "YYYY-MM-DD’T’hh:mm:ss.sss’Z")

27

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

birthDate

Date

Contact data birth-date (format: "YYYY-MM-DD").

14

nationalId

String

Contact data national identification.

150

country

String

Two-letter country code (ISO 3166-1) of residence.

2

emailAddress

String

Contact e-mail address.

5-512

phoneNumber

String

Contact phone number.

3-20

shippingAddress

Object

Object containing the shipping address provided by Masterpass wallet.

city

String

Shipping address city.

25

country

String

Shipping address country as two-letter country code (ISO 3166-1).

2

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

recipientName

String

Name of the person specified in the shipping address.

100

recipientPhoneNumber

String

Phone number of person set to receive the shipped order.

20

billingAddress

Object

Billing Address object corresponding to the selected credit card.

city

String

Billing address city.

25

country

String

Billing address country as two-letter country code (ISO 3166-1).

2

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 shipping address or the payment details object as described above.

Resource URI Placeholder description

Card details

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

<merchantId>

Client ID assigned to you by Wirecard.

Shipping address

/masterpass/merchants/<merchantId>/wallets/<walletId>/shipping-address

:::

:::

:::

:::

<walletId>

Wallet ID you received in response of creating a wallet.

Billing address

/masterpass/merchants/<merchantId>/wallets/<walletId>/billing-address

:::

:::

Error messages

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

HTTP status code Error message Explanation

404

Merchant resource not found or not permissible.

The merchantId is invalid.

:::

:::

Querying the requested resources is not allowed.

:::

Wallet resource not found or not permissible.

Wallet with provided walletId does not exist or 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
}
Name Type Description Required Max. length

orderNumber

Integer

Order number of payment.

no

9

orderDescription

String

Unique description of the consumer’s order in a human readable form.

yes

255

totalAmount

Object

Total amount and currency you want to bill your consumer (including shipping costs).

yes

amount

Decimal

Total amount (ISO 4217) you want to bill your consumer (including shipping costs).

yes

19.4

currency

String

Currency given as ISO 4270 three letter currency code, e.g. EUR.

yes

3

customerStatement

String

Text displayed on bank statement issued to your consumer by the financial service provider. Relevant information for your consumer to identify the payments made to your online shop.

no

254

orderReference

String

Unique order reference ID sent from merchant to financial institution. Convenient to correlate the order numbers of your online shop with the effected payments.

no

128

notificationUrl

String

URL to which a notification will be sent when the payment is processed. Only http(s) with ports 80/443 are possible.

no

deposit

Boolean

Enable automated debiting of payments. default = false

no

true/false

useWalletConsumerData

Boolean

Use Masterpass wallet’s billing and shipping data in payment initiation. default = true

no

true/false
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.

Error messages

The following error messages are possible when initiating a payment.

HTTP status code Error message Explanation

400

Value for parameter orderNumber is invalid.

The orderNumber requires a specific format.

400

orderNumber already used.

An orderNumber may only be used once.

400

Already processed.

Wallet has already been processed or is currently processing.

412

No card data available yet.

No Masterpass wallet data available yet. Consumer has not yet finished the interaction with the Masterpass wallet.

412

Payment related card data timed out.

The data required for the payment was deleted due to time out.

502

Communication error with processing system.

Impaired communication with the processing system.

502

Could not initiate processing.

The payment process could not be started.

Receiving the final transaction result

To receive the final result of the payment process, you can request the following resource.

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

The processingState is either still PENDING with the same result as above or has changed to SUCCESS or FAILURE.

| +{ "orderNumber":446758869, "orderDescription": "John Doe - ID: 002302", "customerStatement": "Your purchase at the example store.", "amount": { "currency": "EUR", "amount": 4.00}, "approvalCode": "708491", "approveAmount": { "currency": "EUR", "amount": 4.00 }, "depositAmount": { "currency": "EUR", "amount": 0.00 }, "gatewayReferenceNumber": "C837757147074816743447", "gatewayContractNumber": "70031", "paymentNumber": 446758869, "paymentState": "payment_approved", "processingDate": "2016-08-09T13:09:27.000Z", "orderReference": "234092", "processingState": "SUCCESS" } +

Final transaction results

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.

{
  "orderNumber": 285703324,
  "orderDescription": "John Doe - ID: 002302",
  "customerStatement": "Your purchase at the example store.",
  "amount": {
      "currency": "EUR",
      "amount": 104.79
  },
  "approvalCode":"708491",
  "approveAmount": {
    "currency": "EUR",
    "amount": 104.79
  },
  "depositAmount": {
    "currency": "EUR",
    "amount": 0.00
  },
  "gatewayReferenceNumber": "C837757147074816743447",
  "gatewayContractNumber": "70031",
  "paymentNumber": 446758869,
  "paymentState": "payment_approved",
  "processingDate": "2016-08-09T13:09:27.000Z",
  "orderReference": "234092",
  "processingState": "SUCCESS",
  "brand": "MasterCard SecureCode/MasterPass"
}
Name Type Description Always Optional Max. length

orderNumber

Integer

Order number of payment.

✔

9

orderDescription

String

Unique description of the consumer’s order in a human readable form.

✔

255

''customerStatement ''

String

Text displayed on bank statement issued to your consumer by the financial service provider.

✔

128

approvalCode

String

Approval code of financial service provider (may be also an empty string).

✔

approveAmount

Object

Approved amount and currency.

✔

amount

Decimal

Total amount (ISO 4217).

✔

19.4

currency

String

Currency given as ISO 4270 three letter currency code, e.g. EUR.

✔

3

depositAmount

Object

Deposited amount and currency.

✔

amount

Decimal

Total amount (ISO 4217).

✔[5]

19.4

currency

String

Currency given as ISO 4270 three letter currency code, e.g. EUR.

✔[6]

3

''instrumentCountry ''

String

Country of the consumer which has been detected and returned by the financial service provider. Please be aware that this feature is not provided by all financial service providers.

✔

2

merchantReference

String

Unique order reference ID sent from merchant to financial institution.

✔

128

paymentNumber

Integer

Number of payment.

✔

9

paymentState

String

Current state of payment (payment_approved, payment_deposited, payment_closed or payment_approvalexpired).

✔

32

providerReferenceNumber

String

Technical reference number of the financial service provider or acquirer.

✔

255

processingDate

Date

Date and time when order has been processed (Format:"yyyy-MM-dd’T’HH:mm:ss.SSS’Z").

✔

28

orderReference

String

Unique order reference ID sent from merchant to financial institution.

✔

128

processingState

String

Current state of payment SUCCESS, FAILURE, PENDING).

✔

brand

String

Brand of used credit card. Alphanumeric with a variable length of up to 255 characters.

✔

255

gatewayReferenceNumber

String

Technical reference number of the payment process.

✔

255

gatewayContractNumber

String

Contract number of the processor or acquirer.

✔

255

avsResultCode

String

Result code of AVS check. Only for American Express transactions using AVS (Address Verification System).

✔

5

avsResultMessage

String

Result text of AVS check. Only for American Express transactions using AVS (Address Verification System).

✔

256

avsProviderResultCode

String

Provider result code of AVS check. Only for American Express transactions using AVS (Address Verification System).

✔

5

avsProviderResultMessage

String

Provider result text of AVS check. Only for American Express transactions using AVS (Address Verification System).

✔

256

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"
}

Error messages

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

HTTP status code Error message

200

Value for parameter orderNumber is invalid.

200

Parameter orderNumber has to be unique for this operation. Most likely, this 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. Will not be returned, if hashedPan is enabled.
3. Only if explicitly enabled by our xref:support.adoc[support teams
4. Will not be returned, if hashedPan is enabled.
5. If stated
6. If stated