Menu

User Tools

Create PDF

Site Tools


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 (“http://” 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.

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) , 4) Will not be returned, if hashedPan is enabled.
3) Only if explicitly enabled by our support teams.
5) , 6) If stated

This website uses cookies to deliver the best service to you. By continuing to browse the site, you are agreeing to our use of cookies.