This document has been created by the Wirecard Technologies GmbH. Its contents may be changed without prior notice. External web links are provided for information only. Wirecard does not claim liability for access to and correctness of the referenced content.

Copyright © 2008-2019 Wirecard Issuing Technologies GmbH

All rights reserved.

Printed in Germany / European Union

1.2. Trademarks

The Wirecard logo is a registered trademark of Wirecard Technologies GmbH. Other trademarks and service marks in this document are the sole property of Wirecard Technologies GmbH or their respective owners.

The information contained in this document is intended only for the person or entity to which it is addressed and contains confidential and/or privileged material. Any review, retransmission, dissemination or other use of, or taking of any action in reliance upon, this information by persons or entities other than the intended recipient is prohibited. If you received this in error, please contact Wirecard Technologies GmbH and delete the material from any computer.

1.3. Contact Information

For questions relating to this document please contact:

Wirecard Technologies GmbH

Einsteinring 35

D-85609 Aschheim

Germany

Phone: +49 89 4424 1235

Note: This document may describe features and/or functionality that are not present in your software or your service agreement. Contact your account representative to learn more about available Wirecard Technologies GmbH products.

2. Introduction

2.1. Purpose

This document introduces and explains the REST interface of the Consumer Cards Platform (CCP). It is organized into two main chapters: Authenticated Web Services and Unauthenticated Web Services, where each service is described in detail including example requests and responses where appropriate.

The document provides information about every service available on the REST interface for CCP.

2.2. Audience

This document is intended for Consumer Cards Platform Client Software Providers.

2.3. Document Conventions

This document uses the following conventions:

A name put in curly brackets in an URL identifies a variable; its value should be provided by the client.

A URL part closed in square brackets identifies an optional parameter. Client requests to CCP are not obliged to specify it.

3. General information

3.1. General Request Information

Consumer Cards Platform (CCP) REST services can only be accessed via a secure channel (https), by means of HTTP requests to a given URL. In general, all REST services start with the following URL:

3.2. Base URL

The base URL pattern for all services provided within the CCP REST API looks as the following:

Placeholder Value

<base-URL>

https://<ccp-horus-url>/rest-api

Here is a list of externally visible CCP endpoints

Environment Known URLs

TEST

sps2c-test.wirecard.com

PROD

sps2c.wirecard.com

Generally, a CCP REST service can be accessed under <base-URL>/{brandName}/{service}

For versioned REST services, a {version} parameter is added to the URL:

<base-URL>/{version}/{brandName}/{service}

This parameter only exists for versioned services which represent a newer version of an already existing original version without {version}. The version part in the URL is a concatenation of the letter v with a natural number, e.g. "v2".

{brandName} identifies a business name used by Wirecard and its cooperating partners. This URL is then followed by the name of the {service}, like user, stations, potentially followed by additionally required parameters and values.

Requests should use UTF-8 encoding; all URLs must be URL-encoded. The namespace is: http://wirecardbank.com/rest-api

The whole rest communication is stateless, so no session handling or similar is required. As a result, for authenticated rest services, authentication is required for each request (See Chapter 6.1 Secured Rest Services).

To call any REST service, client can use either XML or JSON transmission protocol. To send requests in JSON format, {Content-Type: application/json} needs to be set in request’s header. To get responses in JSON format, {Accept: application/json} header needs to be set. The structure of both XML and JSON message is equivalent (with respect to format differences).

Following is an example of XML request (mobile-info service):

<?xml version="1.0"?>
<mobile-info-request xmlns='http://wirecardbank.com/rest-api'>
 <device-id>mydeviceid</device-id>
 <operating-system>ANDROID</operating-system>
</mobile-info-request>

and corresponding JSON request:

{"device-id":"mydeviceid", "operating-system":"ANDROID"}

3.3. General Error Response

An appropriate HTTP status code will be sent in case of an error. Additionally, an XML response might be sent in the case of HTTP code is 403. For technical validation of error codes, please refer to the http status codes. The optional XML error response is meant for debugging purposes. Check the error code tables if it is allowed to be displayed to the user.

The HTTP response codes specific to a service, are explained in the appropriate chapters of this manual.

The HTTP response codes common to all services, are summarized in the following table:

Method Status Technical Description

GET, PUT

200

OK

GET, PUT

403

Handled Business Error with XML Error Response.

GET, POST, PUT, DELETE

404

Not Found. The server has not found anything matching the Request-URI.

GET, PUT

500

Internal server error – please contact support. The client is encouraged to retry in this case.

GET, POST, PUT, DELETE

503

Service Unavailable. The server is currently unable to handle the request due to a temporary overloading or maintenance of the server, or due to a concurrency problem. The client is encouraged to retry in this case.

GET, POST, PUT, DELETE

504

Gateway Timeout. The server, while acting as a gateway or proxy, did not receive a timely response from the upstream server specified by the URI. The client is encouraged to retry in this case.

Elements Description

error-code

The general error code. In most cases it’s equal to the http error code.

error-key

The more specific alphanumeric code to an error.

error-message

A human readable error message.

required-token-scope

This field is only present when token authentication fails. It contains the required token scope for the service call and can be used by clients to determine whether they need to request a new appropriate token.

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
    <error-code>401</error-code>
    <error-key>UNAUTHORIZED</error-key>
    <error-message>invalid loginAlias/password</error-message>
</error-response>

In addition to Common error structure some services can also throw following multi-error response.

Sample Multi-Error Response

An example from update user address service.

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <errors>
    <error>
      <error-key>
        VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED
      </error-key>
      <error-message>
        countryOfResidence - The country is invalid for this brand
      </error-message>
    </error>
    <error>
      <error-key>VALIDATION_ERROR_MAX_LENGTH</error-key>
      <error-message>
        street - Max number of characters exceeded
      </error-message>
    </error>
  </errors>
</error-response>

The individual services indicate if they return one or both error response.

Common HTTP Codes for authenticated web services.

Error-code Error-key Description

401

401

Missing authentication credentials.

403

LOGIN_LOCKED

User can not authenticate because the user is locked.

403

LOGIN_IN_REGISTRATION

User can not authenticate because the user is still in registration.

403

LOGIN_CLOSED

User can not authenticate because the user is closed.

403

NO_PERMISSION_TO_ACCESS

Authenticated user has no permission to access the target user resource.

4. Authentication

4.1. Authentication Description

Authenticated REST services provide personal, user related data like accounting details. All URLs of secured services start with the following format:

<base-URL>/[{version}/]{brandName}/user/{loginAlias}[?aliasType={aliasType}]

The {loginAlias} parameter identifies the CCP user for whom the information is requested. The {aliasType} parameter specifies the type of the login alias, as shown in the examples below. The {aliasType} is optional. If it is omitted, a brand-specific default type is assumed.

Example

Each of the URLs in the following table can be used to call the User-Info Service

Alias type Login Alias URL

loginName

demouser

<base-URL>/{brandName}/user/demouser?aliasType=loginName

msisdn

+49176123456

<base-URL>/{brandName}/user/%2B49176123456?aliasType=msisdn

email

demo@user.com

<base-URL>/{brandName}/user/demo%40user.com?aliasType=email

loginIdentifier

a1b2c3d4e5

<base-URL>/{brandName}/user/a1b2c3d4e5?aliasType=loginIdentifier

loadingNumber

20408115555

<base-URL>/{brandName}/user/20408115555?aliasType=loadingNumber

cplcid

4750002B823123213334300802A08720023B

<base-URL>/{brandName}/user/4750002B823123213334300802A08720023B?aliasType=cplcid

bankAccountId

123123124erwr

<base-URL>/{brandName}/user/123123124erwr?aliasType=bankAccountId

creditCardId

DFAD0A5E2E3511E2

<base-URL>/{brandName}/user/DFAD0A5E2E3511E2?aliasType=creditCardId

accountNumber

4610500031

<base-URL>/{brandName}/user/4610500031?aliasType=accountNumber

cardPan

5100000000000015

<base-URL>/{brandName}/user/5100000000000015?aliasType=cardPan

globalUserName

uePsOIpeAFgWxR0E

<base-URL>/{brandName}/user/uePsOIpeAFgWxR0E?aliasType=globalUserName

externalLoadingNumber

1234567890123456

<base-URL>/{brandName}/user/1234567890123456?aliasType=externalLoadingNumber

externalUserId

a1b2c3d4e5f6h7g8

<base-URL>/{brandName}/user/a1b2c3d4e5f6h7g8?aliasType=externalUserId

The alias types are defined as follows:

  • loginName: Some brands allow their users to choose a login name. This login name can be used as an alias to identify the user.

  • msisdn: The user’s mobile phone number. The mobile phone number must be verified before it can be used as a login alias.

  • email: The user’s email address.

  • loginIdentifier: Identifier that is automatically generated for each user in the CCP backend. In contrast to the other login alias types, the login identifier ist always present and can be used independent of the brand.

  • loadingNumber: Some brands use this at the point-of-sales to identify an account.

  • cplcid: Card Production Lifecycle ID, used by some mobile apps.

  • bankAccountId: When a bank account is associated with a user in CCP, an internal ID is generated referencing the bank account. This ID can be used as the user’s login alias. The bank account IDs can be retrieved using the Bank Accounts List Service.

  • creditCardId: When a credit card is associated with a user in CCP, an internal ID is generated referencing the credit card. This ID can be used as the user’s login alias. The credit card IDs can be retrieved using the Credit Cards List Service.

  • accountNumber: Customer’s primary account number.

  • globalUserName: Identifier that is globally unique, and it can be used to identify the user without brand name.

  • externalLoadingNumber: The brand-unique external loading-number.

  • externalUserId: The brand-unique user id originating from an external system.

For the general request, see General Request Information.

For the general response, see General Error Response.

4.2. Basic Authentication

CCP supports HTTP Basic authentication relying on the client’s login alias and password to be added in the request. The login alias can be one of the login aliases described in Authentication Description chapter.

In order to access secured REST services with HTTP Basic authentication, client applications have to set the HTTP Authorization header’s value to: Basic <base64_encoded_login_alias_password>. UTF-8 is the default decoding charset; therefore, the value must also have been encoded with the same charset.

Example

Assuming, a user wants to login with login name demouser and password demopassword, the client application has to specify the following HTTP Basic authentication header

Authorization: Basic ZGVtb3VzZXI6ZGVtb3Bhc3N3b3Jk

The login alias in the URL must match the credentials given in the authentication header, otherwise, a 400 HTTP status code "Bad Request" will be returned.

Error response codes caused by invalid basic authentication are summarized in the table below. Please, note these are common to all secured services.

Status Error-Key Description

400

403

Bad Request, possible reasons: 1) the {loginAlias} value provided in the URL doesn’t match with login alias provided in the authentication header, 2) invalid basic authentication token, 3) unsupported authentication header format, 4) unsupported encoding used

401

INVALID_CREDENTIALS

Unauthorized – wrong login alias, password or brand; note that three consecutive attempts to login with wrong password will lock the user

403

LOGIN_LOCKED

Forbidden - user is locked

403

LOGIN_IN_REGISTRATION

Forbidden - user has not finished the registration process

403

LOGIN_NOT_UNIQUE

Forbidden - If returned, then the users login alias conflicts with another users login alias. This is very rare and could mean someone’s username is someone else’s e-mail.

403

TERMS_AND_CONDITIONS_NOT_ACCEPTED

The user has not accepted the terms and conditions yet

500

500

Internal server error

4.3. Token Authentication

CCP also supports token authentication to secure REST services. Token authentication is considered to be a superior authentication scheme and should be implemented by the majority of CCP clients. Leveraging token authentication improves security by:

  • Reducing the need to store sensitive credentials on the client side

  • Limiting the set of possible operations which can be done with a particular token

  • Defining fine-grained access rules for critical services (for example: a token is only valid for one service invocation within the next 5 minutes).

In order to access secured REST services with a token, client applications have to change the HTTP Authorization header’s value to: Bearer <access_token>.

In addition, if the token has been previously requested by specifying a {client_id} in the request parameters, the request to access a secure REST service must also include an additional header: X-Authorization-Client-Id which must match the {client_id} value provided upon access token request. If the token was requested without specifying a {client_id} parameters, the header will be ignored and no security check will be done in the subsequent authentication process.

Example

Authorization: Bearer 88ed9c88214a24ac1be75860ffa6c2b7d1fe035b842b6df778a315e955f6c77c

X-Authorization-Client-Id: mobile_app_v1

4.3.1. Token Authentication Errors

This section provides a list with all token authentication errors.

HTTP Response Codes

Status Error-Key Description

400

403

Bad Request, possible reasons: 1) the {loginAlias} value provided in the URL doesn’t match with login alias provided in the authentication header, 2) invalid basic authentication token, 3) unsupported authentication header format, 4) unsupported encoding used.

403

INVALID_TOKEN

Token is not valid (e.g.: token not found, expired, max-usages reached, token bound to different service-url).

403

invalid_scope

When the token’s scope did not match the requested resource.

403

ACCESS_DENIED

User credentials are invalid (e.g.: user not found, user from request differs from token’s owner)

403

LOGIN_LOCKED

Forbidden - user is locked

403

LOGIN_IN_REGISTRATION

Forbidden - user has not finished the registration process

403

LOGIN_NOT_UNIQUE

Forbidden - If returned, then the users login alias conflicts with another users login alias. This is very rare and could mean someone’s username is someone else’s e-mail.

409

INTERNAL_PROCESSING_FAILED

Unable to process due to conflict in requests (this usually happens when there are 2 concurrent requests using tokens that define a level2 scope).

500

500

Internal server error – please contact support.

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
    <error-code>403</error-code>
    <error-key>invalid_scope</error-key>
    <error-message>invalid token scope</error-message>
    <required-token-scope>level1</required-token-scope>
</error-response>

4.4. RCA Authentication (token service request only)

Token service requests support one additional authentication method - RCA (Remote Chip Authentication). Currently, RCA has two implementations:

  • DPA (Dynamic Passcode Authentication) – Visa specific

  • CAP (Chip Authentication Program) – Mastercard specific

In order to use RCA instead of Basic Authentication requests must contain a valid login alias and a RCA cryptogram generated by a NFC-capable mobile phone.

Example / Usage

<login-alias>:<cryptogram> (encode it base64)

<> are placeholders

Put the base64 encoded <login-alias>:<cryptogram> to the HTTP-header

Authorization: Remote-Chip <base64Encoded>

As with basic authentication, the encoded string should be UTF-8. If the validation of the cryptogram fails, the user associated with the login alias in the request will be automatically locked.

HTTP Response Codes

Status Error-Key Description

401

INVALID_CREDENTIALS

login credentials are missing

403

INVALID_CARD

This user does not have a valid mobile card in CCP

403

TERMS_AND_CONDITIONS_NOT_ACCEPTED

The user has not accepted the terms and conditions yet

500

500

Internal error

4.5. Application-PIN Authentication (token service request only)

In addition to basic and RCA authentication, access tokens can also be requested and granted by the use of an Application PIN. Application PIN can be specified by end-users via one of CCP’s REST services.

In order to use Application PIN authentication, a request must have:

  • A valid access token (A) previously obtained by using other means of authentication (e.g.: basic authentication).

  • Application PIN previously set by the end-user.

Upon successful authentication, the token end-point will provide a newly generated access token ©.

The described authentication mechanism enforces the following constraints:

  1. It can only be used to obtain access tokens (e.g.: cannot be used to authenticate against REST services).

  2. Access tokens generated for a specific URL (see Token Service for more info) are not valid for Application-PIN authentication requests.

  3. If the access token (A) was generated for a specific client (e.g.: by setting the {client_id} URL parameter), then the request must also specify the same client identification in the URL.

Please, note that if the validation of the Application-PIN fails 3 times, the authentication mechanism gets blocked for the requesting user and can only be re-enabled by setting a new PIN using the Application-PIN Service. Furthermore, all valid access tokens previously generated for the user and the {client_id} in the request will be revoked.

On the other hand, if the access token sent in the request is wrong 3 times, the user specified in the request gets automatically locked.

Application PIN authentication requests do not increase the usage counter of the access token sent in the request.

Example / Usage

Authorization: Application-PIN <login-alias>:<PIN>:<token>

<> are placeholders

The header value must be Base64 encoded and UTF-8 compliant.

HTTP Response Codes

Status Error-Key Description

400

INVALID_PARAMETER

Bad Request: the provided access token is bound to a specific URL, or invalid client_id in request (e.g.: stored client_id does not match request)

401

APPLICATION_PIN_INVALID

invalid login credentials

403

APPLICATION_PIN_BLOCKED

Application PIN login is blocked due to too many failed login attempts

403

INVALID_TOKEN

Token sent in request is invalid (not valid, non existent, etc.)

403

TERMS_AND_CONDITIONS_NOT_ACCEPTED

The user has not accepted the terms and conditions yet

500

500

INTERNAL_EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

Note

The Application PIN error response contains two extra elements than the one described in General Error Response. It contains extra information in order to handle the remaining login attempts properly.

An example error response looks like this:

<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <error-key>APPLICATION_PIN_INVALID</error-key>
  <error-message>invalid login credentials</error-message>
  <failed-attempts>1</failed-attempts>
  <remaining-attempts>3</remaining-attempts>
</error-response>

4.6. Tele-PIN Authentication

Tele-pin is a authentication mechanism for consuming CCP REST api, which allows users to use Interactive voice response (IVR) systems in order to perform specific activities on their user account without involving call center or using any specific mobile application or user interface.

With a valid Tele-pin a client is able to access account data using S2C services, same as standard password. If the user enters wrong Tele-pin, separate counter is maintained to count the number of failed attempts. Number of Tele-pin failed attempts is given to customer classifier script. As a default behavior, user is locked after the third failed attempt. In order to use Tele-pin, it should be enabled in brand.xml. The Tele-pin length is configurable and could be from 6 to 10 digits.

Tele-pin should have the following formats:

  • n-1 unique digits for tpin length n.

  • sequence of digits in ascending or descending orders like 123456, 234567, 987654, 876543, etc are not allowed.

Tele-pin authentication supports the following login alias types : loadingNumber, msisdn, cardPan.

Example / Usage

Authorization: Tele-PIN <login-alias>:<login-alias-type>:<Tele-PIN>

<> are placeholders

The header value must be Base64 encoded and UTF-8 compliant.

HTTP Response Codes

Status Error-Key Description

401

INVALID_CREDENTIALS

Unauthorized – wrong login alias, password, brand or login alias type; note that three consecutive attempts to login with wrong password will lock the user

403

INVALID_AUTHENTICATION_METHOD

Unsupported authentication header format.

403

LOGIN_LOCKED

Forbidden - user is locked

403

LOGIN_IN_REGISTRATION

Forbidden - user has not finished the registration process

403

LOGIN_NOT_UNIQUE

Forbidden - If returned, then the users login alias conflicts with another users login alias. This is very rare and could mean someone’s username is someone else’s e-mail.

403

TERMS_AND_CONDITIONS_NOT_ACCEPTED

The user has not accepted the terms and conditions yet

500

500

Internal server error

4.7. Parent-Child Authentication

CCP supports parent-child accounts. This is a special linkage between CCP customer accounts which represents simple structure: one parent and several related children. Main point of this concept is that parent account can control his children accounts.

Therefore CCP need to provide such mechanism that parent account can invoke REST calls on children’s account. This can be done just by invoking children’s URL using parent’s account credentials.

Example

HTTP Method: GET

URL: <base-URL>/v9/{brandName}/user/lukeSkywalker

Basic authentication header: login:vader; password:deathstar123

In this example parent can get user profile for his child account. This mechanism works also with other types of authentication.

Access by parent

List of accessible services for parent can be configured in brand using blacklist/whitelist mechanism. Also there is globally restricted REST services which could never be accessed by parent:

/{brandName}/register-user

/{brandName}/user/{loginAlias}/register-user (parent should invoke this rest service on himself, not on child)

Parent generally can access child account even if it’s business status is locked. Parent himself should be in status ACTIVE to call any of the services.

Child user status Child business status Parent access allowed

ANY

IN_REGISTRATION

YES

ANY

ACTIVE

YES

ANY

LOCKED

YES (if locked by parent himself)

CLOSED

CLOSED

NO

4.8. Token Service

Each service is recommended to be used with a particular Token level. Wirecard IT-security has recommendations regarding which token level/ mtan to be used with each service. The recommendations can be found on CCP API-Token Authentication Baseline page on our server.

The token service provides a way to generate authentication tokens. If the access token being requested (A) is bound to the same scope, client_id, http method and service url as an already existing token (B) for the same user, then B will be invalidated and be replaced by A.

Client_id is needed in order to prevent cancellation of previously issued tokens. For example client have two devices (clients) and wants to use them both simultaneously. Without client_id we will immediately cancel all old tokens, and issue new one. So the customer then should again enter his credential on second device. Specifying client_id will help to resolve this problem, so several tokens can exist in parallel. This also can be applicable for simultaneously opened tabs.

4.8.1. Token Service Request

HTTP Method: GET

The above URL is deprecated and will not be supported in future releases

URL <base-URL>/{brandName}/token?scope={scope}[&client_id={client_id}[&service_url={service_url}&http_method={http_method}]]

V2 - URL <base-URL>/v2/{brandName}/token?scope={scope}[&client_id={client_id}[&service_url={service_url}&http_method={http_method}]]

The request must also include a valid authentication header (seeBasic Authentication, RCA Authentication, Application-PIN Authentication, Tele-pin Authentication.)

URL Parameters

Parameter Required Description

scope

Yes

The scope determines the type of token to request. Certain secured REST services require a different scope than others. A scope determines the token expiration time and its max usages. Scopes can vary from brand to brand.

client_id

No

An unique identifier for the client device. The client_id value should be difficult to guess in order to increase the security of the communication between the client and the CCP backend. The maximum length is 64 bytes.

service_url

only if http_method is specified

Limit future token usages to the specified URL only. The parameter value does not include the server protocol, hostname and port. Should be encoded by HTTP URL Encoder.

http_method

only if service_url is specified

Limits the HTTP methods that can be invoked with the token. Only works in conjunction with service_url. Possible values are: get, put, post, delete, all (enable the token for all HTTP methods)

Example

<base-URL>/whitelabel/token?client_id=mobile_app_v1&scope=level2&service_url=/rest-api/whitelabel/user/demouser&http_method=all

4.8.2. Token Service Response

Element: token-response

Elements Version Description

token

all

contains

Element: token

Elements Version Description

value

all

The token value.

expires-in

all

The number of seconds left before the token expires.

remaining-usages

all

The times this token can be used before it gets revoked. Please note this value does not decrease with every request since a new token is generated every time. Thus, remaining-usages becomes the max usages value defined for a specific brand. If this element is not present, there is no usage limit.

scope

all

The token scope.

service-url

all

The service url for which the token is valid.

http-method

all

The HTTP method to which the token usage is limited.

Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<token-response xmlns="http://wirecardbank.com/rest-api">
  <token>
  <value>
    88ed9c88214a24ac1be75860ffa6c2b7d1fe035b842b6df778a315e955f6c77c
  </value>
  <expires-in>41999</expires-in>
  <remaining-usages>3</remaining-usages>
  <scope>level2</scope>
  <service-url>/rest-api/whitelabel/user/demouser</service-url>
  <http-method>all</http-method>
  </token>
</token-response>

HTTP Response Codes

In addition to the standard authentication errors (e.g. invalid username/password, login locked etc.) the following specific errors can be returned:

Status Error-Key Description

400

400

Bad Request. This can occur when: the specified url and http method do not match any configured url, no scope is specified or only one of the service_url and http_method parameters are specified

400

invalid_scope

invalid/unknown scope

HTTP Response Codes - V2

For this version the following error was removed - 403 | FORBIDDEN ("user in registration", "login locked")

The following specific errors can be returned:

Status Error-Key Description

400

400

Bad Request. This can occur when: the specified url and http method do not match any configured url, no scope is specified or only one of the service_url and http_method parameters are specified

400

invalid_scope

invalid/unknown scope

401

UNAUTHORIZED

invalid login credentials

4.9. Knowledge-based Authentication

CCP supports HTTP knowledge-based authentication (KBA). With knowledge-based authentication, the client provides personal information about the user ("shared secrets") in the request to prove the identity of the user.

Given that KBA is a weak form of authentication (personal information might be public), KBA is only used in the registration service.

In order to access secured REST services with KBA authentication, client applications have to set the HTTP Authorization header’s value to: KBA <base64-encoded-kba-value>. The KBA value has the form of <login-alias-type>:<login-alias>:<list-of-shared-secrets>.

Allowed login alias types for KBA are CARD_PAN_AND_EXPIRY_DATE and LOGIN_IDENTIFIER. CARD_PAN_AND_EXPIRY_DATE has the following format: CARD_PAN&yyyy-MM

The <list-of-shared-secrets> is a list of key-value pairs in the form of <secret-type>=<url-encoded-secret>, separated by &. Allowed secret types are:

Secret Type Description

EXTERNAL_USER_ID

The external user Id

FOUR_DIGIT_SSN

Last four digits of social security number

EMAIL_ADDRESS

The email address of the user

DOB

Date of birth, in format yyyy-MM-dd

ZIP_CODE

Zip code, five digits

MOBILE_NUMBER

The mobile number of the user

The brand configuration specifies which secret(s) need to be provided to authenticate. Zero secrets is a valid configuration.

Example

Assuming, a client wants to login with login alias type CARD_PAN_AND_EXPIRY_DATE having card pan 5100000000000015 and expiry date as 2021-07, while providing the user’s zip code as a shared secret for authentication, the KBA value is CARD_PAN_AND_EXPIRY_DATE:5100000000000015&2021-07:ZIP_CODE=80331. Thus, the HTTP header needs to be set to:

Authorization: KBA Q0FSRF9QQU5fQU5EX0VYUElSWV9EQVRFOjUxMDAwMDAwMDAwMDAwMTUmMjAyMS0wNzpaSVBfQ09ERT04MDMzMQ==

5. Authorization

5.1. M-TAN Authorization

Authenticated REST services can be additionally secured my MTAN authorization. For this, the customer needs to be active, and have a mobile number to receive the MTAN via SMS.

The number of MTANs requested without being used is limited. The limit is configurable and as of writing, it is set to 10 MTANs. After applying the MTAN correctly, counter is reset and additional MTANs can be requested.

Requesting MTANs over configurable limit or calling API with wrong MTAN three times will cause the user account to be locked.

For unlocking the user, reset counters and successive unlock calls of the API are required.

If MTAN authorization is required for a particular REST service, you will notice the following additional response codes - especially the first one when the MTAN is missing in the HTTP request header:

HTTP Response Codes

Status Error-Key Scenario Description

403

SERVICE_NOT_SECURED_BY_MTAN

Generate

Service not secured by MTAN

403

NO_MOBILE_NUMBER

Generate

Customer has no valid mobile number

403

EXISTS_MTAN

Generate

MTAN already exists for service

403

CUSTOMER_NOT_ACTIVE

all

Customer is not active

403

SECURED_BY_MTAN

Authorize

Secured by MTAN. The new MTAN has been generated. Seconds to live: <seconds>

403

NO_MTAN

Authorize

No valid MTAN for service

403

EXPIRED_MTAN

Authorize

MTAN has expired

403

INVALID_MTAN

Authorize

MTAN is invalid

403

LOGIN_LOCKED

all

login locked

403

MTAN_COUNT_EXCEED

Authorize

MTAN generation impossible: too many MTANs requested. Ask callcenter to reset.

To authorize with MTAN, you will need to add following header to the HTTP request to the authenticated REST service:

X-Wirecard-MTAN: <value of MTAN>

How to reset an MTAN?

Even if you have an MTAN for a customer and forgot it, you can reset by not sending the required header value. However, you will have to wait for 60 seconds after the first MTAN was generated to re-generate.

How many MTAN can be used in parallel per customer?

Only one. If you request an MTAN for another service, it will invalidate all existing MTAN’s of the customer. So a customer can only have one valid MTAN at a time.

Error Code Mapping

MTAN in header Stored MTAN Additional Condition Resulting Error Code

irrelevant

irrelevant

customer has no mobile number

NO_MOBILE_NUMBER

irrelevant

irrelevant

customer is not active

CUSTOMER_NOT_ACTIVE

none

some value

⇐ min(60 seconds, expiration time) after 1st MTAN generate

EXISTS_MTAN

none

some value

> min(60 seconds, expiration time) after 1st MTAN generate

SECURED_BY_MTAN

some value

none

none

NO_MTAN

some value

some value

stored MTAN exired

EXPIRED_MTAN

different value

some value

not expired

INVALID_MTAN

6. User Data

6.1. Update User Personal Data Service

The service is used to update a user’s personal data, e.g. name and birthdate.

Only the values which are provided in the request will be used to update the corresponding user’s property. The same validation rules which are used in the user-registration will be applied. Sending an empty value (e.g. <tag />) will result in deleting the stored value.

6.1.1. Update User Profile Personal Data Request

HTTP Method: PUT

URL: <base-URL>/{brandName}/user/{loginAlias}/update-personal-data[?aliasType={aliasType}]

URL v2: <base-URL>/v2/{brandName}/user/{loginAlias}/update-personal-data[?aliasType={aliasType}]

Client implementations must send the brandName and loginAlias as a url parameter.

Parameter Required Description

brandName

Yes

The brand name for this request

loginAlias

Yes

a login alias (username, login identifier, reference number, email address, or MSISDN of an existing user)

Element: update-user-profile-personal-data-request

Elements Description Required Restrictions

salutation

The salutation of the user.

No

only one of MR, MRS, MS

first-name

The user’s first/given name.

No

String - 50

middle-name

The user’s middle name

No

String - 50

last-name

The user’s last/family name

No

String - 50

maiden-name

The user’s maiden name

No

String - 50

nationality

nationality / citizenship

No

ISO 3166-1 Alpha-2 Country code , ( two letter uppercase )

birth-date

date of birth

No

date formatted as YYYY-MM-DD

city-of-birth

the city where the user is born

No

String 100

login-name

changes the login-name, same rules as for registration a user are applied

No

String - 30

locale

Language preference. Select from the 8 provided language codes

No

DE,EN,IT,TR,FR,ES,NL,PL

Sample Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<update-user-profile-personal-data-request
        xmlns="http://wirecardbank.com/rest-api">
  <salutation>MR</salutation>
  <first-name>Hans</first-name>
  <nationality>GB</nationality>
</update-user-profile-personal-data-request>

Sample Request - JSON

{
    "salutation":"MR",
    "first-name":"Hans",
    "nationality":"GB"
}

6.1.2. Update User Profile Personal Data Response

Apart from the common error structure this service can also throw the multi-error response. For more details about the error handling please refer to General Error Response section.

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>400</error-code>
  <error-key>400</error-key>
  <error-message>
    error unmarshalling message: cvc-pattern-valid:
    Value 'asdasd' is not facet-valid with respect
    to pattern '[A-Z]{2}' for type 'CountryCodeType'.
  </error-message>
</error-response>

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <error-key>LOGIN_NAME_NOT_UNIQUE</error-key>
  <error-message>The login name must be unique</error-message>
</error-response>

Sample Error Response

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <errors>
    <error>
      <error-key>VALIDATION_ERROR_UNKNOWN_COUNTRY</error-key>
      <error-message>
        nationality - The country is invalid for this brand
      </error-message>
    </error>
    <error>
      <error-key>VALIDATION_ERROR_INVALID_LOCALE</error-key>
      <error-message>
        locale - The locale is invalid
      </error-message>
    </error>
  </errors>
</error-response>

HTTP Response Codes

Status Error-Key Version Description

200

N/A

all

OK

400

400

all

Bad Request, possible reasons: common BadRequest problems, xml request not conform to the specification

401

INVALID_CREDENTIALS

all

The user is not authenticated

403

VALIDATION_ERROR_UNKNOWN_COUNTRY

all

The country is invalid for this brand.

403

VALIDATION_ERROR_LOGINNAME_CAN_NOT_BE_CHANGED

v2

The user can’t change his login name.

403

VALIDATION_ERROR_LOGINNAME_IS_ALREADY_IN_USE

all

the login name is already used by another user.

403

VALIDATION_FAILED

all

Validation of the incoming data failed. Contains a list of descriptions, which are expected to be handled by the client. At the end of the error-message, it contains a list in the format of: keys:#reasonKey1#reasonKey2

500

500

all

INTERNAL_EXCEPTION

6.2. User Profile Service

This service retrieves information from the user’s profile. The table below contains the list of possible elements. All fields are optional and might not be filled.

6.2.1. User Profile Service Request

HTTP Method: GET

URL version 1: <base-URL>/{brandName}/user/{loginAlias}/profile[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/profile[?aliasType={aliasType}]

URL version 3: <base-URL>/v3/{brandName}/user/{loginAlias}/profile[?aliasType={aliasType}]

URL version 4: <base-URL>/v4/{brandName}/user/{loginAlias}/profile[?aliasType={aliasType}]

URL version 5: <base-URL>/v5/{brandName}/user/{loginAlias}/profile[?aliasType={aliasType}]

6.2.2. User Profile Service Response

Element: user-profile-response

Elements Version Description

marketing-opt-ins

all

The set of current marketing opt-ins.

security-question

all

The security question for this user

login-name

>=v2

Login name

salutation

>=v2

Salutation (MS,MRS,MR)

first-name

>=v2

First name

middle-name

>=v2

Middle name

last-name

>=v2

Last name

maiden-name

>=v2

Maiden name

birth-date

>=v2

Birth date

city-of-birth

>=v2

City of birth

mobile-number

>=v2

Mobile number

mobile-number-status

>=v5

Mobile number status

pending-mobile-numbers

>=v2

Pending mobile numbers

landline-number

>=v2

Landline number

email

>=v2

EMail address

address

>=v2

Address

language

>=v3

ISO 639-1 two-letter language code (lower case)

citizenship

>=v3

ISO-3166 Country Codes (upper case)

locale

>=v3

User’s locale.

referrer-merchant-id

>=v4

Merchant ID

brand-membership-id

>=v4

Membership ID of the user of the brand

title

>=v4

Title (Dr., Phd.)

job

>=v4

The user’s job title

date-of-creation

>=v4

User’s creation date

Element: marketing-opt-ins

Elements Version Description

opt-in-topic

all

The set of channels (modes) for a given topic name.

Element: opt-in-topic

Attributes Version Description

name

all

Topic name.

Elements Version Description

opt-in-mode

all

A channel (mode) for the given topic name.

Element: security-question

Attributes Version Description

question

all

The set of channels (modes) for a given topic name.

Attribute: question

Values Version

MOTHER_PLACE_OF_BIRTH

all

BEST_CHILDHOOD_FRIEND_NAME

all

FIRST_PET_NAME

all

FAVOURITE_TEACHER_NAME

all

FAVOURITE_HISTORIC_CHARACTER

all

GRANDFATHER_PROFESSION

all

Element: address

Elements Version Description

street

>=v2

Street

house-number

>=v2

House number

house-details

>=v2

Extra location details

line-two

>=v2

Additional address information

zipcode

>=v2

ZIP or postal code

city

>=v2

City

region

>=v2

Region or state

country

>=v2

Country code (2 characters)

Element: pending-mobile-numbers

Elements Version Description

pending-mobile-number

>=v2

pending mobile number

Element: pending-mobile-number

Elements Version Description

mobile-number

>=v2

mobile number

date

>=v2

last update of pending mobile phone entry

status

>=v2

one of the following status: NOT_VERIFIED, PENDING, MAX_REQUESTS

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<user-profile-response xmlns="http://wirecardbank.com/rest-api">
  <marketing-opt-ins>
    <opt-in-topic name="basic_info"/>
    <opt-in-topic name="extra_info">
        <opt-in-mode>PHONE</opt-in-mode>
        <opt-in-mode>EMAIL</opt-in-mode>
    </opt-in-topic>
  </marketing-opt-ins>
  <security-question question="BEST_CHILDHOOD_FRIEND_NAME"/>
  <login-name>rfeynman</login-name>
  <salutation>MR</salutation>
  <title>Dr.</title>
  <job>Magician</job>
  <first-name>Richard</first-name>
  <last-name>Feynman</last-name>
  <middle-name>Phillips</middle-name>
  <maiden-name>Duda</maiden-name>
  <birth-date>1918-05-11</birth-date>
  <city-of-birth>Acapulco</city-of-birth>
  <mobile-number>+132235464</mobile-number>
  <mobile-number-status>COMPLETED</mobile-number-status>
  <pending-mobile-numbers>
    <pending-mobile-number>
        <mobile-number>+49123456789</mobile-number>
        <date>2014-02-14T08:20:53Z</date>
        <status>PENDING</status>
    </pending-mobile-number>
  </pending-mobile-numbers>
  <landline-number>+4989123456</landline-number>
  <email>feynman@caltech.edu</email>
  <address>
    <street>Elm Street</street>
    <house-number>13</house-number>
    <house-details>backyard</house-details>
    <zipcode>45056</zipcode>
    <city>Springwood</city>
    <region>Ohio</region>
    <country>US</country>
  </address>
  <language>en</language>
  <citizenship>US</citizenship>
  <locale>en</locale>
  <referrer-merchant-id>Oppenheimer</referrer-merchant-id>
  <brand-membership-id>Alamo</brand-membership-id>
  <date-of-creation>2015-12-28T17:05:18Z</date-of-creation>
</user-profile-response>

Sample Response - JSON

{
    "email":"feynman@caltech.edu",
    "address":{
        "street":"Bretonischer Ring",
        "city":"Grasbrunn",
        "house-number":"8",
        "house-details":"house details",
        "zipcode":"85630",
        "country":"DE"
     },
     "marketing-opt-ins":{
        "opt-in-topic":[{
            "name":"extra_info",
            "opt-in-mode":["PHONE","EMAIL"]
        },{
            "name":"basic_info",
            "opt-in-mode":[]
        }]
     },
     "security-question":{
       "question":"MOTHER_PLACE_OF_BIRTH"
     },
     "login-name":"rfeynman",
     "birth-date":"1994-03-11",
     "mobile-number":"+49178518625473"
}

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

500

500

INTERNAL_EXCEPTION

6.3. Update Mobile Info Service

The service updates information about user’s mobile device (device id and mobile operating system type).

6.3.1. Update Mobile Info Service Request

HTTP Method: PUT

URL version 1 (Deprecated): <base-URL>/{brandName}/user/{loginAlias}/mobile-info[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/mobile-info[?aliasType={aliasType}]

Element: mobile-info-request

Elements Version Description

device-id

v1

An identifier of mobile device used by the notification service (GCM or APNs). See remarks below for further information.

push-token

v2

The device registration token generated by Firebase Cloud Messaging (FCM). See remarks below for further information.

operating-system

all

The type of operating system

Element: operating-system

Values Version

ANDROID

all

IOS

all

WINDOWS

v1

BLACKBERRY

v1

LINUX

v1

Remarks

This service is used to enable push notification services for the user’s mobile phone. The client (app) should call this service: to initialize its push token and operating system type whenever its push token or operating system has changed. Failing to do so will not allow user to receive notifications on his phone.

Version 2 only supports Android and IOS apps.

Sample Request V2 - JSON

{
    "push-token":"fcp7m5kuHIc:APA91bGH2XJTA7XH_snqXhM0yhr9h58twN5_qcSOSdrNkgo65-WLq9gR17nv1vs-fJnc97N7e5UAXH8oMuDFtldEJaYqMZBqc7gEn-DFnXJdg6rUMTZKFU0pk0bAV6OZ5RcVVSDPUAAA",
    "operating-system":"ANDROID"
}

Sample Request V1 - JSON

{
    "device-id":"mydeviceid",
    "operating-system":"IOS"
}

6.3.2. Update Mobile Info Service Service Response

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request, possible reasons: common BadRequest problems, xml request not conform to the specification

6.4. Update User Address Service

Use this service to update a user’s address. In version 2 users can also update their shipping address.

Only the values which are provided in the request will be used to update the corresponding user’s property. Sending an empty value (e.g. <tag />) will result in deleting the stored value.

6.4.1. Update User Address Request

HTTP Method: PUT

URL

Version 1:

<base-URL>/{brandName}/user/{loginAlias}/update-address[?aliasType={aliasType}]

Version 2:

<base-URL>/v2/{brandName}/user/{loginAlias}/update-address[?aliasType={aliasType}]

Client implementations must send the brandName and loginAlias as a url parameter.

Parameter Required Description

brandName

Yes

The brand name for this request

loginAlias

Yes

a login alias (username, login identifier, reference number, email address, or MSISDN of an existing user)

Element: update-user-profile-address-request used in version 1

Type UserAddressType

Element: update-address-request used in version 2

Elements Description Required Restrictions

shipping-address

UserAddressType

Optional

user-address

UserAddressType

Optional

Type: UserAddressType

Elements Description Required Restrictions

street

Street name

No

String - 80

house-number

House number

No

String - 20

house-details

Building or house details. Typically should be used above/before the street-name field, and should be used essentially for FR, ES and UK customers.

No

String - 100

line-two

Optional field allowing the user to submit any additional address details.

No

String - 100

zipcode

The zip or postal code of the user’s address.

No

String - 20

city

The city in which the user resides.

No

String - 100

region

Optional field allowing the user to enter the state / region / district

No

String - 100

country

country where this address belongs to

No

ISO 3166-1 Alpha-2 Country code , (two letter uppercase)

XML Sample Request V1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<update-user-profile-address-request xmlns="http://wirecardbank.com/rest-api">
  <street>Examplestreet</street>
  <house-number>12</house-number>
  <house-details>Read house</house-details>
  <line-two>Second floor</line-two>
  <zipcode>45678</zipcode>
  <city>Examplecity</city>
  <region>Example region</region>
  <country>DE</country>
</update-user-profile-address-request>

JSON Sample Request V1

{
  "street": "Examplestreet",
  "house-number": 12,
  "house-details": "Read house",
  "line-two": "Second floor",
  "zipcode": 45678,
  "city": "Examplecity",
  "region": "Example region",
  "country": "DE"
}

XML Sample Request V2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<update-address-request xmlns="http://wirecardbank.com/rest-api">
  <shipping-address>
    <street>Examplshippingestreet</street>
    <house-number>34</house-number>
    <house-details>Blue house</house-details>
    <line-two>First floor</line-two>
    <zipcode>45678</zipcode>
    <city>Exampleshippingcity</city>
    <region>Example region</region>
    <country>DE</country>
  </shipping-address>
  <user-address>
    <street>Examplestreet</street>
    <house-number>12</house-number>
    <house-details>Read house</house-details>
    <line-two>Second floor</line-two>
    <zipcode>45678</zipcode>
    <city>Examplecity</city>
    <region>Example region</region>
    <country>DE</country>
  </user-address>
</update-address-request>

JSON Sample Request V2

{
  "shippingAddress": {
    "street": "Examplshippingestreet",
    "house-number": 34,
    "house-details": "Blue house",
    "line-two": "First floor",
    "zipcode": 45678,
    "city": "NewShippingCity",
    "region": "Example region",
    "country": "DE"
  },
  "userAddress": {
    "street": "Examplestreet",
    "house-number": 12,
    "house-details": "Read house",
    "line-two": "Second floor",
    "zipcode": 45678,
    "city": "Examplecity",
    "region": "Example region",
    "country": "DE"
  }
}

6.4.2. Update User Address Response

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request, possible reasons: common BadRequest problems, xml request not conform to the specification.

403

VALIDATION_ERROR_*

Validation error occurred (e.g.: VALIDATION_ERROR__MAXLENGTH means a field contains more than the allowed number of characters). Used in version 1.

403

SHIPPINGADDRESS -VALIDATION_ERROR_*

Validation error occurred (e.g.: VALIDATION_ERROR__MAXLENGTH means a field contains more than the allowed number of characters). Used in version 2.

403

USERADDRESS - VALIDATION_ERROR_*

Validation error occurred (e.g.: VALIDATION_ERROR__MAXLENGTH means a field contains more than the allowed number of characters). Used in version 2.

403

VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED

The country code sent in the request is not configured for this brand. Used in version 1.

403

SHIPPINGADDRESS - VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED

The country code sent in the request is not configured for this brand. Used in version 2.

403

USERADDRESS - VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED

The country code sent in the request is not configured for this brand. Used in version 2.

403

USER_ADDRESS_INCOMPLETE

The customer for which this request was sent has a card program that contains a physical card. A complete address is needed for shipment. Used in version 1.

403

SHIPPINGADDRESS - USER_ADDRESS_INCOMPLETE

The customer for which this request was sent has a card program that contains a physical card. A complete address is needed for shipment. Used in version 2.

403

USERADDRESS - USER_ADDRESS_INCOMPLETE

The customer for which this request was sent has a card program that contains a physical card. A complete address is needed for shipment. Used in version 2.

500

500

INTERNAL_EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

XML Sample Error Response Version 1

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <errors>
    <error>
      <error-key>
        VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED
      </error-key>
      <error-message>
        countryOfResidence - The country is invalid for this brand
      </error-message>
    </error>
    <error>
      <error-key>VALIDATION_ERROR_MAX_LENGTH</error-key>
      <error-message>
        street - Max number of characters exceeded
      </error-message>
    </error>
  </errors>
</error-response>

JSON Sample Error Response Version 1

{
    "errors": [
        {
            "error-key": "VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED",
            "error-message": "countryOfResidence - ???en.validation_error_countryOfResidence_not_allowed???"
        }
    ],
    "error-code": 403
}

XML Sample Error Response Version 2

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <errors>
    <error>
      <error-key>
        SHIPPINGADDRESS - VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED
      </error-key>
      <error-message>
        countryOfResidence - The country is invalid for this brand
      </error-message>
    </error>
    <error>
      <error-key>USERADDRESS - VALIDATION_ERROR_MAX_LENGTH</error-key>
      <error-message>
        street - Max number of characters exceeded
      </error-message>
    </error>
  </errors>
</error-response>

JSON Sample Error Response Version 2

{
    "errors": [
        {
            "error-key": "USERADDRESS - VALIDATION_ERROR_COUNTRYOFRESIDENCE_NOT_ALLOWED",
            "error-message": "countryOfResidence - ???en.validation_error_countryOfResidence_not_allowed???"
        }
    ],
    "error-code": 403
}

6.5. Email address change service

This service is used to change the user’s email address

6.5.1. Email address change request

HTTP Method: PUT

URL: <base-URL>/{brandName}/user/{loginAlias}/email-address-change[?aliasType={aliasType}]

Client implementations must send the brandName and loginAlias as a url parameter.

Parameter Required Description

brandName

Yes

The brand name for this request

loginAlias

Yes

a login alias (username, login identifier, reference number, email address, or MSISDN of an existing user)

Element: email-address-change-request

Elements Version Description

new-email

all

The valid new email for this user.

Sample Request - XML

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<email-address-change-request xmlns="http://wirecardbank.com/rest-api">
    <new-email>updated@email.com</new-email>
</email-address-change-request>

Sample Request - JSON

{ "new-email":"updated@email.com" }

6.5.2. Email address change response

HTTP Response Codes

Status Error-Key Description

200

N/A

OK - email has been changed

400

UNMARSHALLING_EXCEPTION

Email address was in an invalid format (simple validation against schema)

403

VALIDATION_FAILED

Email address was in an invalid format (business logic validation)

403

EMAIL_ADDRESS_EXISTS

Email address already being used for an active customer

403

EMAIL_ADDRESS_BLACKLISTED_CUSTOMER_LOCKED

An user with this email is in the black list

409

CONFLICT

Two requests for the same email address at the same time

500

500

INTERNAL_EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

7. Balance and Transaction

7.1. User-Info Service

7.1.1. User-Info Service Request

The service provides user details (like first name, last name etc), account and balance information. All versions of the service listed below are supported simultaneously.

HTTP Method: GET

URL version 1: <base-URL>/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 3: <base-URL>/v3/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 4: <base-URL>/v4/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 5: <base-URL>/v5/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 6: <base-URL>/v5/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 7: <base-URL>/v7/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 8: <base-URL>/v8/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 9: <base-URL>/v9/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 10: <base-URL>/v10/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 11: <base-URL>/v11/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 12: <base-URL>/v12/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

URL version 13: <base-URL>/v13/{brandName}/user/{loginAlias}[?aliasType={aliasType}]

7.1.2. User-Info Service Response

Element: user-response

Elements Version Description

username

all

The login name (if it exists) or the loading number of the user. This can be displayed on the user’s client, analogously to the Consumer Cards Platform web app.

firstname

all

The user’s first name, to be displayed on the user’s client, analogously to the Consumer Cards Platform web app.

lastname

all

The user’s last name, to be displayed on the user’s client, analogously to the Consumer Cards Platform web app.

brand

all

The name of the brand the user is associated with. This could result in a different UI appearance on the client.

kyc-level

all

The user’s "know-your-customer’s" – level – ANONYMOUS, REGISTERED or LEGITIMATED. When a user is legitimated, he is eligible for send-money p2p.

person-verification-submitted-at

>=v9

The timestamp when customer uploaded his/her KYC documents for verification.

person-verification-status

>=v5

The status of the person verification. Can be one of NOT_VERIFIED, PENDING, VERIFIED or REJECTED. From Version 6 on is extended with TIMED_OUT and REFUSED status

address-verification-status

>=v5

The status of the address verification. Can be one of NOT_VERIFIED, PENDING, VERIFIED or REJECTED.

account

all

Details of the user’s account.

passthrough

>=v2

Current pass-through settings of the user, if the user is allowed to use it.

application-pin

>=v4

Information about application pin.

trust-class

>=v5

User’s trust class. NOTE: This should not be used to infer any information about the business logic for the user, because this can be easily changed by new brand deployment.

creation-date

>=v7

Account creation date for a user

middle-name

>=v8

Middle name

title

>=v8

Title (Dr., Phd.)

referrer-merchant-id

>=v8

Merchant ID

parental-status

>=v8

PARENT if the customer if only parent, CHILD_PARENT if the customer is both child and parent, CHILD for customers which are only child. If the customer has no family this field is not returned.

terms-of-use-accepted

>=v8

Whether all the terms and conditions have been accepted (true or false)

global-user-name

>=v11

A globally unique user name

business-status

>=v13

The status of customer - user

Element: account

Elements Version Description

account-number

all

The Consumer Cards Platform user’s account number. The user may use it to load money on his prepaid card.

routing-number

all

The bank routing number the user may use to load money on his prepaid card.

loading-number

all

The loading number may be represented as a barcode and may then be used at a point of sale to load the card.

iban

>=v3

The International Bank Account Number (IBAN) of the virtual account.

physical-iban

>=v10

The International Bank Account Number (IBAN) of the customer’s physical bank account.

balance

all

The user’s current card balance.

Element: balance

Elements Version Description

total-amount

all

The current total amount, in a given currency, on the card.

available-amount

all

The current available amount, in a given currency, on the card. This might be less than the total-amount. The available amount is calculated as available-amount = total-amount – reserved-amount + current-overdraft-limit

reserved-amount

all

The currently reserved amount, in a given currency.

total-debit-reservations-amount

>=v12

The total amount of all pending reservations for debit transfer methods.

total-credit-reservations-amount

>=v12

The total amount of all pending reservations for credit transfer methods.

monthly-overdraft-limit

>=v2

The monthly available overdraft limit in a given currency.

current-overdraft-limit

all

The current available overdraft limit in a given currency. It is equal to or less than the monthly overdraft limit.

Element: passthrough

Attributes Version Description

enabled

>=v2

True or false, indicates if pass-through is enabled.

bank-account

>=v2

Identifies the pass-through bank account. Must be present if pass-through is enabled.

Element: bank-account

Elements Version Description

account-number

>=v2

Account number at the bank.

routing-number

>=v2

Routing number of the bank.

identifier

>=v2

Identifier of this bank account as understood by the CCP system. This is not to be displayed to the user.

display-name

>=v2

Name given to the bank account.

Element: application-pin

Attributes Version Description

initialized

>=v4

True if the user has set the application pin, otherwise false. Attribute is to enable mobile app to prompt the user to set application pin only if it’s not already set.

Element: trust-class

Attributes Version Description

name

>=v5

The name of the trust class

description

>=v5

A description of the trust class

Header: Date

Every response contains a header with the date(at the server) at which the response was generated Date: Mon, 23 Mar 2015 15:53:47 GMT

Sample Response for version 4:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <firstname>Muster</firstname>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <physical-iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
</user-response>

Sample Response for version 4 - JSON:

{
    "username":"a1394200299865",
    "brand":"earthcard",
    "account":{
        "balance":{
            "total-amount":{
                "currency":"EUR",
                "value":0.00
            },
            "available-amount":{
                "currency":"EUR",
                "value":0.00
            },
            "reserved-amount":{
                "currency":"EUR",
                "value":0.00
            }
        },
        "account-number":"4610522616",
        "routing-number":"51230800",
        "loading-number":"2040811964991"
    },
    "firstname":"A1394200299868",
    "lastname":"A1394200299869",
    "kyc-level":"REGISTERED"
}

Sample Response for version 5:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <firstname>Muster</firstname>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>NOT_VERIFIED</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
</user-response>

Sample Response for version 6:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <firstname>Muster</firstname>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>TIMED_OUT</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
</user-response>

Sample Response for version 7:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <firstname>Muster</firstname>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>TIMED_OUT</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
  <creation-date>2015-05-07T11:53:49Z</creation-date>
</user-response>

Sample Response for version 8:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <title>Phd.</title>
  <firstname>Muster</firstname>
  <middle-name>Phillips</middle-name>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>TIMED_OUT</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
  <referrer-merchant-id>Oppenheimer</referrer-merchant-id>
  <parental-status>PARENT</parental-status>
  <terms-of-use-accepted>true</terms-of-use-accepted>
  <creation-date>2015-05-07T11:53:49Z</creation-date>
</user-response>

Sample Response for version 9 - JSON:

{
    "username": "mustermann",
    "title": "Phd.",
    "brand": "Consumer Cards Platform",
    "account": {
        "iban": "DE12416000000005120124",
        "balance": {
            "total-amount": {
                "currency": "EUR",
                "value": 0
            },
            "available-amount": {
                "currency": "EUR",
                "value": 0
            },
            "reserved-amount": {
                "currency": "EUR",
                "value": 0
            },
            "monthly-overdraft-limit": {
                "currency": "EUR",
                "value": 150
            }
        },
        "account-number": "4610501449",
        "routing-number": "51230800",
        "loading-number": "2040811254757"
    },
    "firstname": "Muster",
    "middle-name": "Phillips",
    "lastname": "Mann",
    "kyc-level": "REGISTERED",
    "person-verification-submitted-at": "2016-05-09T12:03:27Z",
    "person-verification-status": "PENDING",
    "address-verification-status": "PENDING",
    "application-pin": {
        "initialized": false
    },
    "trust-class": {
        "name": "TrustClass_1",
        "description": "First level trust class"
    },
    "referrer-merchant-id": "Oppenheimer",
    "parental-status": "PARENT",
    "terms-of-use-accepted": true,
    "creation-date": "2015-09-15T11:51:16Z"
}

Sample Response for version 11:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <title>Phd.</title>
  <firstname>Muster</firstname>
  <middle-name>Phillips</middle-name>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>TIMED_OUT</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <monthly-overdraft-limit currency="EUR">
        20.00
      </monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">
        15.00
      </current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
  <referrer-merchant-id>Oppenheimer</referrer-merchant-id>
  <parental-status>PARENT</parental-status>
  <terms-of-use-accepted>true</terms-of-use-accepted>
  <creation-date>2015-05-07T11:53:49Z</creation-date>
  <global-user-name>uePsOIpeAFgWxR0E</global-user-name>
</user-response>

Sample Response for version 12:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
  <username>mustermann</username>
  <title>Phd.</title>
  <firstname>Muster</firstname>
  <middle-name>Phillips</middle-name>
  <lastname>Mann</lastname>
  <brand>Consumer Cards Platform</brand>
  <kyc-level>LEGITIMATED</kyc-level>
  <person-verification-status>TIMED_OUT</person-verification-status>
  <address-verification-status>NOT_VERIFIED</address-verification-status>

  <account>
    <account-number>41600000000</account-number>
    <routing-number>5120124</routing-number>
    <loading-number>20408125412</loading-number>
    <iban>DE12416000000005120124</iban>
    <physical-iban>DE84160032000051201345</physical-iban>
    <balance>
      <total-amount currency="EUR">50.00</total-amount>
      <available-amount currency="EUR">60.00</available-amount>
      <reserved-amount currency="EUR">5.00</reserved-amount>
      <total-debit-reservations-amount currency="EUR">50.00</total-debit-reservations-amount>
      <total-credit-reservations-amount currency="EUR">15.00</total-credit-reservations-amount>
      <monthly-overdraft-limit currency="EUR">20.00</monthly-overdraft-limit>
      <current-overdraft-limit currency="EUR">15.00</current-overdraft-limit>
    </balance>
  </account>

  <passthrough enabled="true">
    <bank-account>
    <account-number>1234567890</account-number>
      <routing-number>40020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>house bank account</display-name>
    </bank-account>
  </passthrough>

  <application-pin initialized="true"/>
  <trust-class>
    <name>TrustClass_1</name>
    <description>First level trust class</description>
  </trust-class>
  <referrer-merchant-id>Oppenheimer</referrer-merchant-id>
  <parental-status>PARENT</parental-status>
  <terms-of-use-accepted>true</terms-of-use-accepted>
  <creation-date>2015-05-07T11:53:49Z</creation-date>
  <global-user-name>uePsOIpeAFgWxR0E</global-user-name>
</user-response>

Sample Response for version 13:

<?xml version="1.0" encoding="UTF-8"?>
<user-response xmlns="http://wirecardbank.com/rest-api">
    <username>Ottttt_vvfrrrdf</username>
    <title>Dr.</title>
    <firstname>Muster</firstname>
    <middle-name>Philips</middle-name>
    <lastname>Mann</lastname>
    <brand>Consumer Cards Platform</brand>
    <kyc-level>LEGITIMATED</kyc-level>
    <person-verification-status>VERIFIED</person-verification-status>
    <address-verification-status>VERIFIED</address-verification-status>
    <account>
        <account-number>5620500277</account-number>
        <routing-number>096001013</routing-number>
        <loading-number>2040883456035</loading-number>
        <iban>DE12416000000005120124</iban>
        <physical-iban>DE84160032000051201345</physical-iban>
        <balance>
            <total-amount currency="USD">93.86</total-amount>
            <available-amount currency="USD">93.86</available-amount>
            <reserved-amount currency="USD">0.00</reserved-amount>
            <total-debit-reservations-amount currency="USD">0.00</total-debit-reservations-amount>
            <total-credit-reservations-amount currency="USD">0.00</total-credit-reservations-amount>
        </balance>
    </account>
    <application-pin initialized="false"/>
    <trust-class>
        <name>TrustClass_1</name>
        <description>TrustClass_1</description>
    </trust-class>
    <terms-of-use-accepted>true</terms-of-use-accepted>
    <creation-date>2018-10-12T15:14:34Z</creation-date>
    <business-status>ACTIVE</business-status>
</user-response>

7.2. Transactions Lite List Service

7.2.1. Transactions Lite List Request

This service can be used to retrieve a list of transactions in a lightweight service.

HTTP Method: GET

URL:

Version 1 (Deprecated) <base-URL>/{brandName}/user/{loginAlias}/transactions-lite-list

Version 2 <base-URL>/v2/{brandName}/user/{loginAlias}/transactions-lite-list

Client implementations must send the brandName and loginAlias as URL parameters.

Parameter Required Description

brandName

Yes

The brand name for this request.

loginAlias

Yes

A login alias (username, login identifier, reference number, email address, or MSISDN of an existing user).

URL Parameters

Parameter Required Version Description

from

Yes

all

Limits the transaction list returned to those starting from the specified point in time (inclusive).

to

Yes

all

Limits the transaction list returned to those ending until the specified point in time (inclusive).

view-type

No

all

Lists the authorizations and clearings separated (SEPARATED) or grouped (MERGED)

reference-types

No

all

Filter the results by reference type.

booking-statuses

No

all

Filter the results by booking status (PROCESSED, PENDING).

start

Yes

all

Limits the transaction list returned to those starting on that number (used for pagination).

end

Yes

all

Limits the transaction list returned to those ending on that number (used for pagination).

selectBy

Yes

all

The selectBy criteria used in the request. Can be one transaction_date or booking_date

is-credit

No

v2

Filter the results by credit type (CREDIT if true, DEBIT otherwise).

Date Format: Time is optional in the date, and can be added after a T character, following the date. These dates are given in UTC.

Date Format Examples:

  • 2012-06-23T14:20:05

  • 2012-06-23T14:20:05Z

7.2.2. Transactions Lite List Response

Element: transactions-lite-list-response

Elements Version Description

pagination

all

Pagination information for this request.

transactions

all

transaction The list of transactions.

Element: pagination

Elements Version Description

start

all

The start of the subset

end

all

The end of the subset

total

all

The total number of transactions for the given period (from-date/to-date)

Element: transaction

Elements Version Description

reference-id

all

The identifier of this transaction.

reference-type

all

The type of this transaction.

is-credit

all

Returns true if credit, false if debit

amount

all

The amount, in account currency.

booking-date

all

The booking date in UTC (YYYY-MM-ddThh:mm:ssZ).

transaction-date

all

The transaction date in UTC (YYYY-MM-ddThh:mm:ssZ).

details

all

Transaction details in JSON format

booking-status

all

WIP synchronization status. (PROCESSED, PENDING)

source-event-type

v2

The source event type.

Reference Type Values

Below you can find a list of currently possible reference-types. Please note that the reference-type field definition is String256. It is not an enumeration, thus new values added in the reference-type list will not result into a new version of the service. Consumer layer should be able to handle this in a graceful manner.

Value

POS

CREDIT_CARD

VOUCHER

WIRETRANSFER_TOPUP

SEND_WIRETRANSFER

SOFORTUEBERWEISUNG

DIREKTUEBERWEISUNG

IDEAL

DIRECT_DEBIT

DIRECT_DEBIT_PASSTHROUGH

MANUAL_LOAD_CHILD_ACCOUNT_SEND

MANUAL_LOAD_CHILD_ACCOUNT_RECEIVE

MANUAL_UNLOAD_CHILD_ACCOUNT_SEND

MANUAL_UNLOAD_CHILD_ACCOUNT_RECEIVE

AUTO_LOAD_CHILD_ACCOUNT_SEND

AUTO_LOAD_CHILD_ACCOUNT_RECEIVE

SEND_MONEY_TO_ACCOUNT

RECEIVE_MONEY_FROM_ACCOUNT

P2P_SEND

P2P_RECEIVE

DIRECT_DEBIT_SEPA

MICRO_DEPOSIT

WIRE_TRANSFER_TOPUP

CREDIT_CARD_TOPUP

CASH_TOPUP

DIRECT_DEBIT_TOPUP

DIRECT_DEBIT_AUTOMATIC_TOPUP

DIRECT_DEBIT_MANUAL_TOPUP

VOUCHER_TOPUP

DIRECT_TRANSFER

SOFORT_TRANSFER

IDEAL_TRANSFER

DIRECT_DEBIT_RETURN

DIRECT_DEBIT_REVERSAL

SEPA_CREDIT_RETURN

COUPON

CANCEL_COUPON

ROLLBACK_COUPON

ROLLBACK_CANCEL_COUPON

CARD_USAGE

ATM

ADJUSTMENT_POSTING

ADJUSTMENT_BOOKBACK

EXTERNAL_CARD_CREDIT

ADJUSTMENT_PURCHASE

EXTERNAL_CARD_CHARGE

TRANSFER_TO_BANK_ACCOUNT

BALANCE_TRANSFER

REQUEST_MONEY

CANCEL_REQUEST_MONEY

ROLLBACK_REQUEST_MONEY

ROLLBACK_CANCEL_REQUEST_MONEY

MANUAL_LOAD

CANCEL_MANUAL_LOAD

ROLLBACK_MANUAL_LOAD

ROLLBACK_CANCEL_MANUAL_LOAD

CONTRACT_SUBSCRIPTION_FEE

CONTRACT_RENEWAL_FEE

CARD_ISSUING_FEE

CARD_REPLACEMENT_FEE

CARD_PURCHASE_FEE

BALANCE_NOTIFICATION_FEE

DORMANCY_FEE

TOPUP_NOTIFICATION_FEE

ACCOUNT_STATEMENT_NOTIFICATION_FEE

TRANSFER_TO_BANK_ACCOUNT_REVERSAL

INACTIVITY_FEE

DISPUTE_CLEARING

MICRO_CREDIT_LOAD

MICRO_CREDIT_UNLOAD

SEPA_DIRECT_DEBIT_ORDER

SEPA_DIRECT_DEBIT_RETURN

SEPA_WIRETRANSFER_CANCEL

AUTH_FORWARDING_DEBIT

AUTH_FORWARDING_CREDIT

LOAD_MONEY_COMMON

REVERSE_LOAD_MONEY_COMMON

SEND_MONEY_COMMON

CANCEL_SEND_MONEY_COMMON

REVERSE_SEND_MONEY_COMMON

LOAD_MONEY_FUND_TRANSFER

REVERSE_LOAD_MONEY_FUND_TRANSFER

SEND_MONEY_FUND_TRANSFER

CANCEL_SEND_MONEY_FUND_TRANSFER

REVERSE_SEND_MONEY_FUND_TRANSFER

SEND_MONEY_CHECK

CANCEL_SEND_MONEY_CHECK

REVERSE_SEND_MONEY_CHECK

SEND_MONEY_EXPRESS_CHECK

CANCEL_SEND_MONEY_EXPRESS_CHECK

REVERSE_SEND_MONEY_EXPRESS_CHECK

LOAD_MONEY_WESTERN_UNION

REVERSE_LOAD_MONEY_WESTERN_UNION

SEND_MONEY_WESTERN_UNION

CANCEL_SEND_MONEY_WESTERN_UNION

REVERSE_SEND_MONEY_WESTERN_UNION

LOAD_MONEY_BARZAHLEN

REVERSE_LOAD_MONEY_BARZAHLEN

SEND_MONEY_BARZAHLEN

CANCEL_SEND_MONEY_BARZAHLEN

REVERSE_SEND_MONEY_BARZAHLEN

LOAD_MONEY_PBBA

REVERSE_LOAD_MONEY_PBBA

SEND_MONEY_PBBA

CANCEL_SEND_MONEY_PBBA

REVERSE_SEND_MONEY_PBBA

ACQUIRE_CREDIT

ACQUIRE_DEBIT

CANCEL_ACQUIRE_DEBIT

ACQUIRE_RESERVE_DEBIT

CANCEL_ACQUIRE_RESERVE_DEBIT

OCT_CREDIT

REVERSE_OCT_CREDIT

MSP_CREDIT

REVERSE_MSP_CREDIT

MSF_DEBIT

REVERSE_MSF_DEBIT

ABIT_CLOSING_ACCOUNT_LOAD

BALANCE_EXPIRY

SWEEP_REVENUE

OTHER

ACCEPTED_AUTHORIZATION

REJECTED_AUTHORIZATION

REVERSED_AUTHORIZATION

EXPIRED_AUTHORIZATION

LOAD_MONEY_INTERBANK

REVERSE_LOAD_MONEY_INTERBANK

SEND_MONEY_INTERBANK

CANCEL_SEND_MONEY_INTERBANK

REVERSE_SEND_MONEY_INTERBANK

LOAD_MONEY_CASH_POS

REVERSE_LOAD_MONEY_CASH_POS

SEND_MONEY_CASH_POS

CANCEL_SEND_MONEY_CASH_POS

REVERSE_SEND_MONEY_CASH_POS

LOAD_MONEY_CONSUMER

REVERSE_LOAD_MONEY_CONSUMER

SEND_MONEY_CONSUMER

CANCEL_SEND_MONEY_CONSUMER

REVERSE_SEND_MONEY_CONSUMER

LOAD_MONEY_CORPORATE

REVERSE_LOAD_MONEY_CORPORATE

SEND_MONEY_CORPORATE

CANCEL_SEND_MONEY_CORPORATE

REVERSE_SEND_MONEY_CORPORATE

LOAD_MONEY_A2A

REVERSE_LOAD_MONEY_A2A

SEND_MONEY_A2A

CANCEL_SEND_MONEY_A2A

REVERSE_SEND_MONEY_A2A

REVERSE_FEE

Sample Response v2 (XML)

<?xml version="1.0" encoding="UTF-8"?>
<transactions-lite-list-response xmlns="http://wirecardbank.com/rest-api">
    <pagination>
        <start>0</start>
        <end>10</end>
        <total>3</total>
    </pagination>
    <transactions>
        <transaction>
            <reference-id>AB884CFC5717DEC49D26758E240BE5DC</reference-id>
            <reference-type>CARD_USAGE</reference-type>
            <is-credit>false</is-credit>
            <amount currency="EUR">11.00</amount>
            <booking-date>2017-11-13T13:37:56Z</booking-date>
            <transaction-date>2017-11-13T14:37:56+01:00</transaction-date>
            <details>
            {
              "history": [
                {
                  "basicDetails":{
                    "referenceId":"AB884CFC5717DEC49D26758E240BE5DC",
                    "referenceType":"CARD_USAGE",
                    "creditType":"DEBIT",
                    "amount":11.00,
                    "currency":"EUR",
                    "bookingDate":"2017-12-04 16:28:38.852",
                    "transactionDate":"2017-12-04 16:28:38.852"
                   },
                  "transactionDetails": {
                    "merchant": "Test merchant",
                    "merchantCity": "Testcity",
                    "merchantCountry": "DE",
                    "originalAmount": {
                      "value": 11,
                      "currency": "EUR"
                    },
                    "authorizationId": "3315A865BCD1E1075A950BB5E4628317",
                    "approvalCode": "39517E9D09DA8216FFA48840DC0D6767",
                    "cardDetailRef": {
                      "refId": "D7F91C36C87711E7A4A8D481D760B5A1",
                      "cardRefId": "D7F91C36C87711E7A4A8D481D760B5A1",
                      "transactionSource": "POS"
                    },
                    "amountDetails": {
                      "originalAmount": {
                        "value": 11,
                        "currency": "EUR"
                      },
                      "amountWithoutFees": {
                        "value": 11,
                        "currency": "EUR"
                      },
                      "amountWithFees": {
                        "value": 11,
                        "currency": "EUR"
                      },
                      "totalFees": {
                        "value": 0,
                        "currency": "EUR"
                      },
                      "faceValueDiscount": {
                        "value": 0,
                        "currency": "EUR"
                      }
                    }
                  }
                },
                {
                  "authorizationDetails": {
                    "uniqueAuthorizationId": "315C56F06FA5DE6FF711634FE957F8C7",
                    "authorizationEventType": "ACCEPTED",
                    "authorizationDateTime": 1510580275343,
                    "amountInTransCurrency": {
                      "value": 0.11,
                      "currency": "EUR"
                    },
                    "amountInAccCurrency": {
                      "value": 0.11,
                      "currency": "EUR"
                    },
                    "acquirerName": "Aausfbyvzeyp",
                    "terminalId": "07562A6032372B6E992AEE6CFA40AC51",
                    "approvalCode": "39517E9D09DA8216FFA48840DC0D6767",
                    "responseCode": "1",
                    "insertDateTime": 1510580275343,
                    "issuerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "acquirerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "cardAccountRefId": "CARD_ACCOUNT_REF_ID",
                    "cardRefId": "D7F91C36C87711E7A4A8D481D760B5A1"
                  }
                },
                {
                  "authorizationDetails": {
                    "uniqueAuthorizationId": "8590370FB2D6148FBFF24B56C35CF70A",
                    "authorizationEventType": "REVERSED",
                    "authorizationDateTime": 1510580274602,
                    "amountInTransCurrency": {
                      "value": 0.1,
                      "currency": "EUR"
                    },
                    "amountInAccCurrency": {
                      "value": 0.1,
                      "currency": "EUR"
                    },
                    "acquirerName": "Ivlsuvxitlvi",
                    "terminalId": "533F974C4D9A54BC0105FDA8BD947354",
                    "approvalCode": "39517E9D09DA8216FFA48840DC0D6767",
                    "responseCode": "1",
                    "insertDateTime": 1510580274602,
                    "issuerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "acquirerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "cardAccountRefId": "CARD_ACCOUNT_REF_ID",
                    "cardRefId": "D7F91C36C87711E7A4A8D481D760B5A1"
                  }
                },
                {
                  "authorizationDetails": {
                    "uniqueAuthorizationId": "5BB03AEB7508CA55EB380723EB43B565",
                    "authorizationEventType": "ACCEPTED",
                    "authorizationDateTime": 1510580273972,
                    "amountInTransCurrency": {
                      "value": 0.1,
                      "currency": "EUR"
                    },
                    "amountInAccCurrency": {
                      "value": 0.1,
                      "currency": "EUR"
                    },
                    "acquirerName": "Gnrrsputvrei",
                    "terminalId": "19434F70692115C9B535A20D02ABFC1E",
                    "approvalCode": "39517E9D09DA8216FFA48840DC0D6767",
                    "responseCode": "1",
                    "insertDateTime": 1510580273972,
                    "issuerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "acquirerFee": {
                      "value": 0,
                      "currency": "EUR"
                    },
                    "cardAccountRefId": "CARD_ACCOUNT_REF_ID",
                    "cardRefId": "D7F91C36C87711E7A4A8D481D760B5A1"
                  }
                }
              ]
            }
            </details>
            <booking-status>PROCESSED</booking-status>
        </transaction>
        <transaction>
            <reference-id>D933982EC87711E7A4A8D481D760B5A1</reference-id>
            <reference-type>MANUAL_LOAD</reference-type>
            <is-credit>true</is-credit>
            <amount currency="EUR">8.75</amount>
            <booking-date>2017-11-13T13:37:52Z</booking-date>
            <transaction-date>2017-11-13T14:37:52+01:00</transaction-date>
            <details>
            {
              "basicDetails":{
                "referenceId":"D933982EC87711E7A4A8D481D760B5A1",
                "referenceType":"MANUAL_LOAD",
                "creditType":"CREDIT",
                "amount":8.75,
                "currency":"EUR",
                "bookingDate":"2017-12-04 16:28:38.852",
                "transactionDate":"2017-12-04 16:28:38.852"
               },
              "transactionDetails": {
                "usage": "Loaded from Catfish (manual_load)",
                "originalAmount": {
                  "value": 10,
                  "currency": "EUR"
                },
                "totalFee": {
                  "value": 1.25,
                  "currency": "EUR"
                },
                "undisplayable": false,
                "transactionStatus": "PROCESSED",
                "amountDetails": {
                  "originalAmount": {
                    "value": 10,
                    "currency": "EUR"
                  },
                  "amountWithoutFees": {
                    "value": 8.75,
                    "currency": "EUR"
                  },
                  "amountWithFees": {
                    "value": 10,
                    "currency": "EUR"
                  },
                  "totalFees": {
                    "value": 1.25,
                    "currency": "EUR"
                  },
                  "faceValueDiscount": {
                    "value": 0,
                    "currency": "EUR"
                  }
                }
              }
            }
            </details>
            <booking-status>PROCESSED</booking-status>
        </transaction>
        <transaction>
            <reference-id>D81AFC24C87711E7A4A8D481D760B5A1</reference-id>
            <reference-type>CARD_ISSUING_FEE</reference-type>
            <is-credit>false</is-credit>
            <amount currency="EUR">4.00</amount>
            <booking-date>2017-11-13T13:37:51Z</booking-date>
            <transaction-date>2017-11-13T14:37:51+01:00</transaction-date>
            <details>
            {
              "basicDetails":{
                "referenceId":"D81AFC24C87711E7A4A8D481D760B5A1",
                "referenceType":"CARD_ISSUING_FEE",
                "creditType":"DEBIT",
                "amount":4.00,
                "currency":"EUR",
                "bookingDate":"2017-12-04 16:28:38.852",
                "transactionDate":"2017-12-04 16:28:38.852"
              },
              "transactionDetails": {
                "totalFee": {
                  "value": 4,
                  "currency": "EUR"
                },
                "undisplayable": false,
                "transactionStatus": "PROCESSED",
                "amountDetails": {
                  "originalAmount": {
                    "value": 0,
                    "currency": "EUR"
                  },
                  "amountWithoutFees": {
                    "value": 0,
                    "currency": "EUR"
                  },
                  "amountWithFees": {
                    "value": 4,
                    "currency": "EUR"
                  },
                  "totalFees": {
                    "value": 4,
                    "currency": "EUR"
                  },
                  "faceValueDiscount": {
                    "value": 0,
                    "currency": "EUR"
                  }
                }
              }
            }
            </details>
            <booking-status>PROCESSED</booking-status>
        </transaction>
    </transactions>
</transactions-lite-list-response>

Sample Response v2 (JSON)

{
    "criteria": {
        "start-row": 0,
        "end-row": 75,
        "total-rows": 1
    },
    "transactions":
        {
            "amount": {
                "currency": "EUR",
                "value": 15
            },
            "details": "{\"basicDetails\":{\"referenceId\":\"1192C2BF257611E9B907021503FC68B1\",\"referenceType\":\"CREDIT_CARD_TOPUP\",\"creditType\":\"CREDIT\",\"amount\":15.00,\"currency\":\"EUR\",\"bookingDate\":\"2019-01-31 17:34:24.271\",\"transactionDate\":\"2019-01-31 17:34:24.271\"},\"transactionDetails\":{\"totalFee\":{\"value\":1.25,\"currency\":\"EUR\"},\"undisplayable\":false,\"transactionStatus\":\"PROCESSED\",\"creditCard\":{\"maskedPan\":\"472766******3918\",\"alias\":\"\",\"category\":\"CREDIT\"},\"amountDetails\":{\"originalAmount\":{\"value\":15.00,\"currency\":\"EUR\"},\"amountWithoutFees\":{\"value\":15.00,\"currency\":\"EUR\"},\"amountWithFees\":{\"value\":16.25,\"currency\":\"EUR\"},\"totalFees\":{\"value\":1.25,\"currency\":\"EUR\"}}}}",
            "reference-id": "1192C2BF257611E9B907021503FC68B1",
            "reference-type": "CREDIT_CARD_TOPUP",
            "is-credit": true,
            "booking-date": "2019-01-31T16:34:24Z",
            "transaction-date": "2019-01-31T17:34:24+01:00",
            "booking-status": "PENDING",
            "source-event-type": "TRANSACTION_EVENT"
        }
    ]
}

Basic details

Element Name Element Type

referenceId

String

referenceType

String

creditType

String (CREDIT, DEBIT)

amount

BigDecimal

currency

String

bookingDate

Formatted into String (e.g. 2017-12-04 16:28:38.852)

transactionDate

Formatted into String (e.g. 2017-12-04 16:28:38.852)

Transaction details

Whenever a transaction is a Transaction Event (not an Authorization Event), the following elements could appear on the details section. Most of them are optional, so they are not guaranteed to be on the response.

Element Name Element Type

sender

String

receiver

String

sender-mobile-number

String

recipient-mobile-number

String

transfer-identifier

String

usage

String

merchant

String

merchant-city

String

merchant-country

String

original-amount

AmountType

total-fee

AmountType

third-party-aggregated-fee

AmountType

voucher-code

String

merge-id

String

iban

String

swift

String

bank-code

String

bank-name

String

bank-account

String

bank-account-type

String

authorization-id

String

card-detail-ref

TransactionDetailsType.CardDetailRef

mandate-info

TransactionDetailsType.MandateInfo

creditor-id

String

original-transaction-date

DateTime

credit-card

TransactionDetailsType.CreditCard

amount-details

TransactionDetailsType.AmountDetails

px-correlation-id

String

mobile-number

String

transaction-date-time-stamp

String

creditCardUsage

String

guwid

String

activation-code

String

clearing-id

String

exchange-rate-used

String

original-operation-reference

String

cancelled-transaction-ref

String

terminal-id

String

due-date

String

ticket-id

String

barcode

String

transaction-status

String

px-correlation-id

String

business-purpose

String

business-status

String

reason-code

String

approval-code

String

acquirer-fee

String

wepLogin

String

wepName

String

alias

String

billingDate

Date or DateTime

sender-brand

String

recipient-brand

String

Whenever a transaction is an Authorization Event, the following elements could be on the details section. Most of them are optional, so they are not guaranteed to be on the response.

Element Name Element Type

unique-authorization-id

String

authorization-event-type

AuthorizationEventType

transaction-source

TransactionSourceType

authorization-date-time

DateTime

amount-in-trans-currency

AmountType

amount-in-acc-currency

AmountType

secure-3d-check

Boolean

acquirer-id

String

acquirer-name

String

acquirer-ref

String

merchant-id

String

merchant-name

String

merchant-country

String

merchant-city

String

merchant-category-code

String

terminal-id

String

terminal-time-stamp

DateTime

approval-code

String

response-code

String

cvx-check

Boolean

recurring

Boolean

entry-mode

String

trace-number

String

insert-date-time

DateTime

issuer-fee

AmountType

acquirer-fee

AmountType

card-account-ref-id

String

available-balance

AmountType

available-balance-before

AmountType

rev-request-id

String

client-ref-id

String

card-ref-id

String

token-requestor-id

String

The elements above can contain some complex types besides strings and dates. In that case, the content of the elements (and sub-elements) are specified below.

AmountType

Element Name Element Type

value

BigDecimal

currency

String

DateTime

Something in this format: 2016-08-11T08:49:30Z

TransactionDetailsType.CardDetailRef

Element Name Element Type

ref-id

String

transaction-source

String

TransactionDetailsType.MandateInfo

Element Name Element Type

mandate-id

String

mandate-timestamp

String

TransactionDetailsType.CreditCard

Element Name Element Type

masked-pan

String

alias

String

category

CardCategoryType

CardCategoryType

Card Category Type values

CREDIT

DEBIT

PREPAID

UNKNOWN

TransactionDetailsType.AmountDetails

Element Name Element Type

original-amount

AmountType

amount-without-fees

AmountType

amount-with-fees

AmountType

total-fees

AmountType

AuthorizationEventType

Authorization Event Type values

ACCEPTED

REJECTED

EXPIRED

REVERSED

TransactionSourceType

Transaction Source Type values

ECOMMERCE

ATM

POS

CASH

MOTO

IMPRINT

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request: XML request might not be conform to the specification.

403

GENERAL_ERROR

Could not retrieve transactions. Used for downgrading non-compatible error codes.

403

INVALID_PAGINATION_PARAMETERS

Specified pagination parameters are invalid.

500

UNKNOWN_ERROR

Error unknown, internal error.

8. Topup and Send Money

8.1. 3DSecure Credit Card Top-up Service

This method is used for topping-up a user’s account via credit card. The credit-card must be 3D secure, and the user should have enrolled in the 3D secure transaction with the issuing bank.

The client has to supply either the credit-card-identifier or all the other credit card elements: type, number and expiration-date. Based on the configuration, the user may be forced to perform a 3DSecure top-up, or the standard top-up secured just by the cvc. If it’s a 3DSecure transaction, the service-response will contain the acs-url, to which the user should be re-directed to, and the parameters that need to be passed to the acs-url.

8.1.1. 3DSecure Credit Card Top-up Service Request

HTTP Method: PUT

URL: <base-URL>/{brandName}/user/{loginAlias}/top-up[/creditcard][?aliasType={aliasType}]

where [/creditcard] is an optional parameter and can be omitted

Element: top-up-request

Elements Version Description

method

all

CREDITCARD (Ignored if provided in the URL)

amount

all

Amount of the top-up including the 3-character currency-code

display-name

all

Optional name provided by the user to reference the financial instrument (e.g. credit-card) with which the top-up is done.

credit-card

all

Specific top-up details based on the chosen method

8.1.2. 3DSecure Credit Card Top-up Service Request with credit-card identifier

Top-up can be done using an already registered credit-card if the identifier is sent. The identifier can be retrieved by the client by calling the list service. When sending a top-up request with a credit-card identifier, the display-name element of the request will be ignored.

Element: credit-card

Elements Version Description

identifier

all

System-identifier of this credit-card as defined in the CCP system. Should be the value of the identifier returned by credit-cards list service.

cvc-code

all

The CVC may be required for certain credit card transactions.

Sample Request with credit card identifier - XML

<?xml version="1.0" encoding="UTF-8"?>
<top-up-request xmlns="http://wirecardbank.com/rest-api">
  <method>CREDITCARD</method>
  <credit-card>
    <identifier>DFAD0A5E2E3511E2</identifier>
    <cvc-code>123</cvc-code>
  </credit-card>
  <amount currency="EUR">100.00</amount>
</top-up-request>

8.1.3. 3DSecure Credit Card Top-up Service Request with credit card details

When sending a top-up request with credit card details, the card will be registered with the given value of the display-name element. A registration only occurs if the complete payment flow is successful. The card-user may not enter the card details for further top-ups using this card.

Element: credit-card

Elements Version Description

number

all

credit-card number.

expiration-date

all

expiry-date of the credit-card in the format MM/YYYY. Other formats will be rejected.

type

all

One of the following values: MASTERCARD, VISA, MAESTRO.

cvc-code

all

The CVC may be required for certain credit card transactions.

Sample Request with credit card details - XML

<?xml version="1.0" encoding="UTF-8"?>
<top-up-request xmlns="http://wirecardbank.com/rest-api">
  <method>CREDITCARD</method>
  <credit-card>
    <number>4444333322221111</number>
    <expiration-date>01/2050</expiration-date>
    <type>VISA</type>
    <cvc-code>007</cvc-code>
  </credit-card>
  <display-name>My Visa Card</display-name>
  <amount currency="EUR">100.00</amount>
</top-up-request>

Sample Request with credit card details - JSON

{  "amount" : {
      "currency" : "EUR",
      "value" : "5.00"
   },
   "credit-card" : {
      "cvc-code" : "999",
      "expiration-date" : "12/2019",
      "number" : "4203583657905941",
      "type" : "VISA"
   },
   "display-name" : "CARD HOLDER",
   "method" : "CREDITCARD"
}

8.1.4. 3DSecure Credit Card Top-up Service Response

Element: top-up-response

Elements Version Description

acs-url

all

The URL to which the user should be re-directed to. This is the card-issuer’s Access Control Server (ACS), where the user has to perform authentication.

post-params

all

List of parameters to be passed in the HTTPS POST request to the acs-url.

Element: post-params

Elements Version Description

entry

all

Key-value pair specifying the name and value of the parameter.

Sample Response - XML

<?xml version="1.0" encoding="UTF-8"?>
<top-up-response xmlns="http://wirecardbank.com/rest-api">
  <acs-url>https://3dsecure-test.wirecard.com/acssim/app/bank</acs-url>
  <post-params>
    <entry key="PaReq">eJxtk11PgzAUhu</entry>
    <entry key="TermUrl">
      https://www.mywirecard.com/api/threeds?guwid=A123D234ABF478
    </entry>
    <entry key="MD">Wirecard</entry>
  </post-params>
</top-up-response>

Sample Response - JSON

{ "acs-url" : "https://3dsecure-test.wirecard.com/acssim/app/bank",
  "post-params" : { "entry" : [
        { "key" : "PaReq",
            "value" : "eJxtk11PgzAUhu"
        },
        { "key" : "TermUrl",
            "value" : "https://www.mywirecard.com/api/threeds?guwid=A123D234ABF478"
        },
        { "key" : "MD",
            "value" : "Wirecard"
        }
  ] }
}

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request: xml request might not be conform to the specification, missing Parameters, or similar

403

OPERATION_NOT_ALLOWED

Credit-card top-up is not allowed for this brand.

403

BLOCKED_CUSTOMER

User (formerly called customer) is not allowed the credit-card top-up.

403

CARD_NOT_3D_SECURE

Credit-card is not 3D secure eligible.

403

CARD_NOT_ENROLLED

Credit-card is 3D secure eligible but not enrolled.

403

CARD_LOCKED

Card has been blocked for transactions maybe because it was reported stolen.

403

LIMIT_VIOLATED

The top-up limit of the user was exceeded.

403

INVALID_AMOUNT

Amount is not a valid positive decimal number

403

VALIDATION_FAILED_EXPIRY_DATE

Expiry Date was in an incorrect format

403

PAST_EXPIRY_DATE

Expiry Date was in the past

403

VALIDATION_FAILED_CARD_NUMBER

Credit-card number was invalid

403

LOCKED_CUSTOMER

User (formerly called customer) has failed to register multiple times, and is now locked to prevent fraud.

403

DUPLICATE_DISPLAY_NAME

User has already registered a card with the given display-name

403

CREDITCARD_ALREADY_REGISTERED

The card has already been registered by the user.

403

WIRECARD_BIN_CHECK_ERROR

The card was rejected since it is a Wirecard Bank prepaid card.

403

TOP_UP_FAILED_ERROR

Payment was unable to be processed, maybe because the 3Ds password / expiry-date / cvc etc. were incorrect.

403

CVC_CODE_REQUIRED

CVC is required

403

3DS_VALIDATION_ERROR_KEY

For your security, a top-up is only possible with credit cards participating in the 3-D Secure (Verified by VISA or MasterCard SecureCode) technology. Despite your credit card is 3-D Secure eligible, you are not enrolled in the 3-D Secure Program. For more information on how to enable the 3-D Secure feature, please contact your issuing bank directly.

403

3DS_ENROLLMENT_ERROR_KEY

Due to technical reasons we were unable to complete the 3-D Secure enrollment check (Verified by VISA or MasterCard SecureCode) and therefore the transaction cannot be performed. Please try again later.

403

3DS_TECHNICAL_ERROR_KEY

It was not possible to complete the transaction with this credit card.

403

GENERAL_ERROR_KEY

Unable to authorize money.

500

500

INTERNAL_EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

8.1.5. Processing Advice

One of the parameters to be posted to the ACS URL is called TermUrl (See sample response above). This is the URL to which the ACS re-directs the request to process the payment. If 3DS with credit-card verification-code (cvc) is used, then the client needs to send the cvc as an HTTP POST parameter to this URL. The suggested approach is to intercept the re-direct to the TermUrl from the ACS, and then add the cvc before posting to the TermUrl. The name of the post-parameter should be "cvc". Please see diagram below to explain the process.

3ds-topup-advice

8.2. Send Money P2P Service

The service transfers money between two legitimated users. (Please check kyc-level element from the User-Info-Service Response first – user must be in “LEGITIMATED" state to be eligible for SendMoneyP2P).

8.2.1. Send Money P2P Service Request

HTTP Method: PUT

URL version 1: <base-URL>/{brandName}/user/{loginAlias}/send-money-p2p/{send-money-p2p-ref-id}[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/send-money-p2p/{send-money-p2p-ref-id}[?aliasType={aliasType}]

URL version 3: <base-URL>/v3/{brandName}/user/{loginAlias}/send-money-p2p/{send-money-p2p-ref-id}[?aliasType={aliasType}]

URL Parameters

Client implementations must generate a {send-money-p2p-ref-id} to identify a P2P transaction.

Sending two identical requests with the same {send-money-p2p-ref-id} and equal transaction details will result in a single P2P transaction on the back end (idempotent request). This can be used to reliably implement retries .e.g. when a network outage occurs.

Parameter Required Description

send-money-p2p-ref-id

Yes

The value of {send-money-p2p-ref-id} is unique for the user {loginAlias} and contains up to 32 alphanumeric characters.

Element: send-money-p2p-request

Elements Version Description

receiver-identifier

all

The element to identify the receiver of the money

amount

all

The amount in a given currency, which must be the user’s account currency.

usage

all

Optional field to add a usage message for the money transfer

Element: receiver-identifier

Elements Version Description

loading-number

all

13 digit number that identifies the card. It will be used to uniquely identify the receiver.

email

all

Email of the intended receiver. It will be used to uniquely identify the receiver.

mobile-number

all

Mobile-number of the intended receiver. It will be used to uniquely identify the receiver.

Note: At least one of email/mobile-number should be present

Sample Request

<?xml version="1.0" encoding="UTF-8"?>
<send-money-p2p-request xmlns="http://wirecardbank.com/rest-api">
  <receiver-identifier>
    <email>one@test.de</email>
  </receiver-identifier>
  <amount currency="EUR">100.00</amount>
  <usage>Rent August 2012</usage>
</send-money-p2p-request>

8.2.2. Send Money P2P Service Response

HTTP Response Codes

Status Error-Key Version Description

200

N/A

all

OK

400

400

all

Bad Request: xml request might not be conform to the specification, missing Parameters, or similar

403

SENDER_LIMIT_ VIOLATION

v1

P2P cannot be performed because of a limit violation of the sender – usually indicating the brand limits for the sender have been violated. (Do not give too specific details in UI)

403

SENDER_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a limit violation of the sender – usually indicating the brand limits (except daily, weekly, monthly and yearly limit) for the sender have been violated.

403

SENDER_LIMIT_ VIOLATIONS

v3

P2P cannot be performed because of a limit violation of the sender – usually indicating the brand limits (except daily, weekly, monthly and yearly limit) for the sender have been violated. The exact violated limits are shown in a comma separated list in the associated error response description field.

403

SENDER_DAILY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a daily limit violation of the sender.

403

SENDER_WEEKLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a weekly limit violation of the sender.

403

SENDER_MONTHLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a monthly limit violation of the sender.

403

SENDER_YEARLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a yearly limit violation of the sender.

403

RECEIVER_LIMIT_ VIOLATION

v1

P2P cannot be performed because of a limit violation of the receiver – usually indicating the brand limits for the receiver have been violated. (Do not give too specific details in UI)

403

RECEIVER_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a limit violation of the receiver – usually indicating the brand limits (except daily, weekly, monthly and yearly limit) for the receiver have been violated.

403

RECIPIENT_LIMIT_ VIOLATIONS

v3

P2P cannot be performed because of a limit violation of the recipient – usually indicating the brand limits (except daily, weekly, monthly and yearly limit) for the receiver have been violated. The exact violated limits are shown in a comma separated list in the associated error response description field.

403

RECEIVER_DAILY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a daily limit violation of the receiver.

403

RECEIVER_WEEKLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a weekly limit violation of the receiver.

403

RECEIVER_MONTHLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a monthly limit violation of the receiver.

403

RECEIVER_YEARLY_LIMIT_ VIOLATION

v2

P2P cannot be performed because of a yearly limit violation of the receiver.

403

RECEIVER_NOT_ LEGITIMATED

v1,v2

Send-Money-P2P receiver not legitimated (P3).

403

RECIPIENT_NOT_ LEGITIMATED

v3

Send-Money-P2P receiver not legitimated (P3).

403

RECEIVER_NOT_FOUND

v1,v2

Receiver of the p2p money transfer not found during send-money-p2p transaction.

403

RECIPIENT_NOT_FOUND

v3

Recipient of the p2p money transfer not found during send-money-p2p transaction.

403

RECEIVER_NOT_ACTIVE

v1,v2

send-money-p2p receiver business level is not active.

403

RECIPIENT_NOT_ACTIVE

v3

send-money-p2p recipient business level is not active.

403

SENDER_RECEIVER_ IDENTICAL

all

sender and receiver of send-money-p2p are identical.

403

RECEIVER_CURRENCY_ INCOMPATIBLE

v1,v2

Transaction amount currency not found our not compatible to receiver’s currency

403

RECIPIENT_CURRENCY_ INCOMPATIBLE

v3

Transaction amount currency not found our not compatible to recipient’s currency

403

INVALID_AMOUNT

all

Negative or null amount not allowed.

403

SENDER_INSUFFICIENT_ FUNDS

all

Sender funds insufficient for completing the operation.

403

SEND_MONEY_FAILED

all

Send money failed, internal error.

403

SEND_MONEY_FAILED_ WRONG:SMS_CODE

all

Wrong sms code.

403

P2PVALIDATION SENDER_NOT_FOUND

all

Sender not found.

403

LOGIN_ALIAS_TYPE_NOT_UNIQUE

all

Recipient cannot be found, because the given login alias type is set to be shared for the brand.

409

TRANSACTION_ALREADY_ USED

all

Transaction id already used.

500

UNKNOWN_ERROR

all

Error unknown, internal error.

The HTTP response codes are summarized in the following table:

Method Status Description

GET, PUT

200

OK

GET, PUT

403

Handled Business Error with XML Error Response

GET, PUT

500

Internal server error – please contact support

Elements Description

error-code

The general error code. In most cases it’s equal to the http error code.

error-key

The more specific alphanumeric code to an error.

Note: The different error response structures are both possible for certain service versions (i.e. service consumers should expect both).

Sample Response (v1 - v3)

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
    <error-code>401</error-code>
    <error-key>UNAUTHORIZED</error-key>
</error-response>

Sample Response (v3)

<?xml version="1.0" encoding="UTF-8"?>
<error-response
    xmlns="http://wirecardbank.com/rest-api">
    <error-code>403</error-code>
    <errors>
        <error>
            <error-key>INVALID_AMOUNT</error-key>
            <error-message>INVALID_AMOUNT</error-message>
        </error>
        <error>
            <error-key>RECEIVER_NOT_FOUND</error-key>
            <error-message>RECEIVER_NOT_FOUND</error-message>
        </error>
        <error>
            <error-key>RECEIVER_NOT_LEGITIMATED</error-key>
            <error-message>RECEIVER_NOT_LEGITIMATED</error-message>
        </error>
    </errors>
</error-response>

8.3. Send Money Bank Account Service

The service transfers money from user’s account to an external bank account that is already registered in CCP or to external bank account which is not registered in CCP.
When specifying bank-account-identifier element, money are moved to registered bank accounts. it can be US ABA, SGBA or IBAN account.
When specifying receiver with first/last name IBAN/BIC, money are moved to any external bank account.
When specifying global-receiver money are moved to external US or Singapore Bank account. The bank account details must have IBAN, BIC (optional). Or routing-number, account-number, bank-name (optional), bank-account-type (optional*) in case of US ABA Bank account. Registered bank accounts must be in VALIDATED state.

*: ``bank-account-type`` can be mandatory depending on brand configuration, by default it is optional.

8.3.1. Send Money Bank Account Service Request

HTTP Method: PUT

URL: <base-URL>/{brandName}/user/{loginAlias}/send-money-bankaccount/{send-money-bankaccount-ref-id}[?aliasType={aliasType}]

URL Parameters

Client implementations must generate a {send-money-bankaccount-ref-id} to identify a transaction.

Sending two identical requests with the same {send-money-bankaccount-ref-id} and equal transaction details will result in a single transaction on the back end (idempotent request). This can be used to reliably implement retries .e.g. when a network outage occurs.

Parameter Required Description

send-money-bankaccount-ref-id

Yes

The value of {send-money-bankaccount-ref-id} is unique for the user {loginAlias} and contains up to 32 alphanumeric characters.

Element: send-money-bankaccount-request

Elements Version Description

receiver

all

Receiver of the SEPA credit, specifies first/last name and IBAN/BIC. Either receiver or bank-account-identifier element should be specified, but not both.

bank-account-identifier

all

System-identifier of the used bank account as defined in the CCP system. Should be the value of the identifier returned by bank account list service. Either receiver or bank-account-identifier element should be specified, but not both.

global-receiver

v3

US ABA bank account money receiver, specifies first/last name routing-number, account-number, bank-name, bank-account-type. Either global-receiver or bank-account-identifier element should be specified, but not both.

amount

all

The amount in EUR currency, which must be the user’s account currency.

reason-for-transfer

all

Optional field (128 characters) to add a reason for the money transfer.

date-of-execution

all

Date (format YYYY-MM-DD) when the booking on the bank-side should be executed. Only supported for brands using the bank-agent.

Element: receiver

Elements Version Description

first-name

all

First name of the SEPA credit receiver. (32 characters)

last-name

all

Last name of the SEPA credit receiver, mandatory parameter. (32 characters)

iban

all

IBAN of the SEPA credit receiver, mandatory parameter. (IBAN)

bic

all

BIC of the SEPA credit receiver, optional parameter.

Element: global-receiver

Elements Data Type Version Description

first-name

String

v3

First name of the SEPA credit receiver. (32 characters)

last-name

String

v3

Last name of the SEPA credit receiver, mandatory parameter. (32 characters)

routing-number

Number

v3

US or Singapore Bank Account routing number 9 characters.

account-number

Number

v3

US or Singapore Bank Account account number 17 characters.

bank-name

String

v3

US or Singapore Bank name - optional 100 characters.

bank-account-type

String

v3

US or Singapore Bank Account type - optional or mandatory depending on brand configuration. NOT_SPECIFIED (default, if optional), CHECKING, SAVING.

Sample Request with receiver

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<send-money-bankaccount-request xmlns="http://wirecardbank.com/rest-api">
  <receiver>
      <first-name>Mr Great</first-name>
      <last-name>Tester</last-name>
      <iban>DE15750492223220492173</iban>
      <bic>ELYTBR14</bic>
  </receiver>
  <amount currency="EUR">1.00</amount>
  <reason-for-transfer>New reason</reason-for-transfer>
</send-money-bankaccount-request>

Sample Request with global-receiver

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<send-money-bankaccount-request xmlns="http://wirecardbank.com/rest-api">
  <global-receiver>
      <first-name>Mr Great</first-name>
      <last-name>Tester</last-name>
      <routing-number>121122676</routing-number>
      <account-number>2132654522</account-number>
      <bank-name>US-Bank</bank-name>
      <bank-account-type>SAVING</bank-account-type>
  </global-receiver>
  <amount currency="USD">1.00</amount>
  <reason-for-transfer>New reason</reason-for-transfer>
</send-money-bankaccount-request>

Sample Request with bank-account-identifier

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<send-money-bankaccount-request xmlns="http://wirecardbank.com/rest-api">
    <bank-account-identifier>0A873F9594A411E3B59390B11C9735A6</bank-account-identifier>
    <amount currency="EUR">100.00</amount>
    <reason-for-transfer>A reason</reason-for-transfer>
</send-money-bankaccount-request>

8.3.2. Send Money Bank Account Service Response

Element: send-money-bankaccount-response

Elements Version Description

receiver

all

Receiver of the SEPA credit, specifies first/last name and IBAN/BIC. This element is returned for request with receiver (Not registered bank account).

bank-account-identifier

all

System-identifier of the registered bank account as defined in the CCP system. Should be the value of the identifier returned by bank account list service. This element is returned for request with bank-account-identifier (registered bank account).

amount

all

The amount in EUR currency, which must be the user’s account currency.

fee

all

The fee in EUR currency.

total-amount

all

The total amount (including fee) in EUR currency.

reason-for-transfer

all

Optional field (128 characters) to add a reason

Element: receiver

Elements Version Description

first-name

all

First name of the SEPA credit receiver.

last-name

all

Last name of the SEPA credit receiver, mandatory parameter.

iban

all

IBAN of the SEPA credit receiver, mandatory parameter.

bic

all

BIC of the SEPA credit receiver, optional parameter.

Sample Response with receiver

<?xml version="1.0" encoding="UTF-8"?>
<send-money-bankaccount-response xmlns="http://wirecardbank.com/rest-api">
    <receiver>
        <first-name>Mr Great</first-name>
        <last-name>Tester</last-name>
        <iban>DE15750492223220492173</iban>
        <bic>ELYTBR14</bic>
    </receiver>
    <amount currency="EUR">1.00</amount>
    <fee currency="EUR">1.01</fee>
    <total-amount currency="EUR">2.0100</total-amount>
    <reason-for-transfer>New reason</reason-for-transfer>
</send-money-bankaccount-response>

Sample Response with global-receiver

<?xml version="1.0" encoding="UTF-8"?>
<send-money-bankaccount-response xmlns="http://wirecardbank.com/rest-api">
    <global-receiver>
        <first-name>Mr Great</first-name>
        <last-name>Tester</last-name>
        <routing-number>121122676</routing-number>
        <account-number>2132654522</account-number>
        <bank-name>US-Bank</bank-name>
        <bank-account-type>SAVING</bank-account-type>
    </global-receiver>
    <amount currency="USD">1.00</amount>
    <fee currency="USD">1.01</fee>
    <total-amount currency="USD">2.0100</total-amount>
    <reason-for-transfer>New reason</reason-for-transfer>
</send-money-bankaccount-response>

Sample Response with bank-account-identifier

<?xml version="1.0" encoding="UTF-8"?>
<send-money-bankaccount-response>
    <bank-account-identifier>0A873F9594A411E3B59390B11C9735A6</bank-account-identifier>
    <amount currency="EUR">100.00</amount>
    <fee currency="EUR">1.01</fee>
    <total-amount currency="EUR">101.01</total-amount>
    <reason-for-transfer>A reason</reason-for-transfer>
</send-money-bankaccount-response>

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request: xml request might not be conform to the specification, missing Parameters, or similar.

403

OPERATION_NOT_ALLOWED

Send money to bank account is not allowed for this brand.

403

BLOCKED_CUSTOMER

Customer is not allowed to send money to bank account.

403

INVALID_AMOUNT

Negative or null amount not allowed.

403

INVALID_CURRENCY

The currency code is not valid for the operation.

403

NO_BANK_ ACCOUNT_ EXIST

No bank account associated with the identifier.

403

BANK_ACCOUNT_NOT_IN_VALID_STATE

The bank account is not in valid state.

403

MISSING_IBAN

The bank account associated with the identifier doesn’t have IBAN.

403

INVALID_IBAN_OR_BIC

IBAN or BIC is invalid.

403

MISSING_ACCOUNT_OR_ROUTING_NUMBER

Bank account or bank code/routing number is missing.

403

INVALID_ACCOUNT_OR_ROUTING_NUMBER

Bank account or bank code/routing number is invalid.

403

SENDER_INSUFFICIENT_ FUNDS

Sender funds insufficient for completing the operation.

403

LIMIT_VIOLATED

The sending limit of the user was exceeded.

403

SEND_MONEY_FAILED_ERROR

Send money failed, internal error.

403

GENERAL_ERROR_KEY

Unable to authorize money.

403

TRANSACTION_ALREADY_ USED

Transaction id already used.

403

MISSING_ACCOUNT_TYPE

Bank account type is configured as mandatory and hasn’t been supplied as either CHECKING or SAVING

500

UNKNOWN_ERROR

Error unknown, internal error.

500

500

INTERNAL_ EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

Sample Response

<error-response xmlns="http://wirecardbank.com/rest-api">
    <error-code>403</error-code>
    <error-key>BANK_ACCOUNT_NOT_IN_VALID_STATE</error-key>
    <error-message>The bank account is not in valid state</error-message>
</error-response>

9. Card and Card Program

9.1. Cards Listing Service

This service lists all cards of a user. A system-reference of the card is also returned, which can be used to then request the details of a particular card.

9.1.1. Cards Listing Service Request

HTTP Method: GET

URL: <base-URL>/{brandName}/user/{loginAlias}/cards-summary[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/cards-summary[?aliasType={aliasType}]

URL version 3: <base-URL>/v3/{brandName}/user/{loginAlias}/cards-summary[?aliasType={aliasType}]

9.1.2. Cards Listing Service Response

Element: cards-summary-response

Elements Version Description

card-summary

all

Element that contains the summary of the card. Multiple instances may be present.

Element: card-summary

Elements Usage Version Description

identifier

Required

all

Identifier of the card as understood by the CCP system.

display-name

Required

all

Display name of the card, as configured in the brand setup

program-name

Required

all

Partner-defined card setup name. It can be used to differentiate different cards in the current card bundle of a user.

status

Required

all

The status of the card – one of ACTIVE, INACTIVE, LOCKED or CLOSED

pin-updatable

Required

from v2

Whether the pin of the card can be changed by the user: true/false

combocard-identifier

Optional

from v3

Identifier of the combo card that contains this embedded card, if applicable

card-ref-id

Required

from v3

External identifier of the card

lock-reason

Optional

from v3

The reason why the card is locked

Sample Response Version 1

<?xml version="1.0" encoding="UTF-8"?>
<cards-summary-response xmlns="http://wirecardbank.com/rest-api">
  <card-summary>
    <identifier>DFAD0A5E2E3511E2</identifier>
    <display-name>Plastic Card</display-name>
    <program-name>classic</program-name>
    <status>ACTIVE</status>
  </card-summary>
  <card-summary>
    <identifier>DFAD0A5E2E3511E3</identifier>
    <display-name>Virtual Card</display-name>
    <program-name>virtual</program-name>
    <status>LOCKED</status>
  </card-summary>
</cards-summary-response>

Sample Response Version 2

<?xml version="1.0" encoding="UTF-8"?>
<cards-summary-response xmlns="http://wirecardbank.com/rest-api">
  <card-summary>
    <identifier>DFAD0A5E2E3511E2</identifier>
    <display-name>Plastic Card</display-name>
    <program-name>classic</program-name>
    <status>ACTIVE</status>
    <pin-updatable>false</pin-updatable>
  </card-summary>
  <card-summary>
    <identifier>DFAD0A5E2E3511E3</identifier>
    <display-name>Virtual Card</display-name>
    <program-name>virtual</program-name>
    <status>LOCKED</status>
    <pin-updatable>true</pin-updatable>
  </card-summary>
</cards-summary-response>

Sample Response Version 3

<?xml version="1.0" encoding="UTF-8"?>
<cards-summary-response xmlns="http://wirecardbank.com/rest-api">
  <card-summary>
    <identifier>DFAD0A5E2E3511E2</identifier>
    <display-name>Plastic Card</display-name>
    <program-name>classic</program-name>
    <status>ACTIVE</status>
    <pin-updatable>false</pin-updatable>
  </card-summary>
  <card-summary>
    <identifier>DFAD0A5E2E3511E3</identifier>
    <display-name>Virtual Card</display-name>
    <program-name>virtual</program-name>
    <status>LOCKED</status>
    <pin-updatable>true</pin-updatable>
    <combocard-identifier>DFAD0A5E2E3511E2</combocard-identifier>
    <card-ref-id>8B593C16CEDE11E4A46F001A7DDA7106</card-ref-id>
    <lock-reason>CARD_LOCKED_BY_USER</lock-reason>
  </card-summary>
</cards-summary-response>

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

401

401

Missing authentication credentials

401

INVALID_CREDENTIALS

User not found or closed or invalid password

403

LOGIN_IN_REGISTRATION

User still in registration

500

500

INTERNAL_ EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

9.2. Card Details Service

The service provides information about the users' card. The information comprises card holder name, card number, card expiration date, Card Verification Code (CVC) and status. A card can have 1 of the 4 possible statuses: ACTIVE, INACTIVE, LOCKED or CLOSED. In case a card is in another state than ACTIVE, the details returned will be masked.

In V2 (version2), the new service is coupled with the brand configuration of the <invocation-resources> at the card setup level. For instance, the details of all cards belonging to a card setup will not be shown if specifically configured in the brand configuration.

9.2.1. Card Details Service Request

HTTP Method: GET

URL: <base-URL>/{brandName}/user/{loginAlias}/card[?aliasType={aliasType}]

The above URL is deprecated and will not be supported in future releases

URL version 1: <base-URL>/{brandName}/user/{loginAlias}/card/{identifier}[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/card/{identifier}[?aliasType={aliasType}]

URL Parameters

Parameter Required Description

identifier

Yes

The value of the identifier element returned by the Cards Listing Service.

9.2.2. Card Details Service Response

Element: card-response

Elements Version Description

holder-name

all

The name of the card holder as printed on the front of the card

number

all

The card-number, as printed on the front of the card

expiration-date

all

The expiration date, as printed on the front of the card

cvc

all

The CVC, as printed on the back of the card

status

all

The status of the card – one of ACTIVE, INACTIVE, LOCKED or CLOSED

HTTP Response Codes

Status Error-Key Version Description

200

N/A

all

OK

404

404

all

No card available

403

SHOW_CARD_DETAILS_NOT_ALLOWED

v2

Card details cannot be sent/shown

Sample Response Version 1 (ACTIVE)

<?xml version="1.0" encoding="UTF-8"?>
<card-response xmlns="http://wirecardbank.com/rest-api">
  <holder-name>Max Mustermann</holder-name>
  <number>4444333322221111</number>
  <expiration-date>5/2015</expiration-date>
  <cvc>111</cvc>
  <status>ACTIVE</status>
</card-response>

Sample Response Version 1 (other statuses)

<?xml version="1.0" encoding="UTF-8"?>
<card-response xmlns="http://wirecardbank.com/rest-api">
  <holder-name>Max Mustermann</holder-name>
  <number>444433******1111</number>
  <expiration-date>**/****</expiration-date>
  <cvc>***</cvc>
  <status>LOCKED</status>
</card-response>

Sample Response Version 2 and card details can be shown (ACTIVE)

<?xml version="1.0" encoding="UTF-8"?>
<card-response xmlns="http://wirecardbank.com/rest-api">
  <holder-name>Max Mustermann</holder-name>
  <number>4444333322221111</number>
  <expiration-date>5/2015</expiration-date>
  <cvc>111</cvc>
  <status>ACTIVE</status>
</card-response>

Sample Response Version 2 and card details can be shown (other statuses)

<?xml version="1.0" encoding="UTF-8"?>
<card-response xmlns="http://wirecardbank.com/rest-api">
  <holder-name>Max Mustermann</holder-name>
  <number>444433******1111</number>
  <expiration-date>**/****</expiration-date>
  <cvc>***</cvc>
  <status>LOCKED</status>
</card-response>

Sample Response Version 2 and card details cannot be shown

<error-response xmlns="http://wirecardbank.com/rest-api">
  <error-code>403</error-code>
  <error-key>SHOW_CARD_DETAILS_NOT_ALLOWED</error-key>
  <error-message>card details cannot be sent</error-message>
</error-response>

10. Unauthenticated Services

10.1. User-Registration Service

This service is used to register new users into the system.

10.1.1. User-Registration Service Request

HTTP Method: PUT

URL version 7: <base-URL>/v7/{brandName}/register-user/

URL version 6: <base-URL>/v6/{brandName}/register-user/

URL version 5: <base-URL>/v5/{brandName}/register-user/

URL version 4: <base-URL>/v4/{brandName}/register-user/

URL version 3: <base-URL>/v3/{brandName}/register-user/

URL version 2: <base-URL>/v2/{brandName}/register-user/

Element: register-user-request

Elements Version Description Required Restrictions

partner-identification-id

all

The partner identification code given by Wirecard to authenticate that the request is originating from partner infrastructure (e.g. call-center). Do NOT provide it to the end-user like on mobile-devices.

No

String - 50

deviceId

all

If you’re using device recognition for the users, check the documentation of http://threatmetrix.com/ how to send the information and the Wirecard-session id as well as the attached document. The Wirecard-session id equals the deviceId to be passed to the service. It consists of: yourBrandID_ sessionIDOfEndUser

No

String - 4096

ipAddressV4

all

Pass ipAddress in v4 format in the ipAddressV4 field

No

Check the accepted format for IPv4

salutation

all

A flag indicating the user’s salutation.

No

MR / MS / MRS

first-name

all

The user’s first-name or given-name.

No

String - 50

middle-name

all

The user’s middle-name.

No

String - 50

last-name

all

The user’s last-name or surname.

No

String - 50

maiden-name

all

The user’s maiden-name.

No

String - 50

nationality

all

The country of which the user is a citizen of.

No

2 character country-code.

birth-date

all

The user’s birth date. The user’s age should be above 18 and below 120 years.

No

Format: YYYY-MM-DD

title

>= v3

The user’s title (Dr., Phd. etc).

No

String - 20

marital-status

>= v3

The user’s marital status (single, divorced, civil union etc).

No

String - 50

job

>= v3

The user’s job title.

No

String - 50

city-of-birth

all

The user’s city of birth.

No

String - 100

mobile-number

all

The user’s mobile number.

No

It should start with +, followed by country code, followed by the local number. E.g. "+491234567890".

landline-number

all

The user’s landline number.

No

It should start with +, followed by country code, followed by the local number. E.g. "+498912345678".

email

all

The user’s email address.

No

Maximum 100 characters

house-details

all

Building or house details. Typically should be used above/before the street-name field, and should be used essentially for FR, ES and UK customers.

No

String - 100

street

all

The street name of the user’s address.

No

String - 80

house-number

all

Optional house number of the user’s address.

No

String - 20

address-line-two

all

Optional field allowing the user to submit any additional address details.

No

String - 100

city

all

The city in which the user resides.

No

String - 100

region

all

Optional field allowing the user to enter the state / region / district

No

String - 100

zipcode

all

The zip or postal code of the user’s address.

No

String - 20

country-of-residence

all

The 2 character country code the user currently resides in. If not existing the country-of-residence will be taken from the brand.

No

http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2

locale

all

Language preference. Select from the 8 language codes. If not existing the locale will be taken from the brand

No

BG, CS, DA, DE, EN, ES, FR, HU, HR, IT, IS, LT, NL, NO, PL, RM, SK, RU, RO, SV, TR

account-number

>= v3

The account number for the user. Used for migration purposes.

No

String - 14

login-name

all

The unique login name or the loading number of the Consumer Cards Platform application user.

No

String - 30

password

all

The password of the user. This service may require the password depending on the brand configurations. It’s required when the user is doing the registration himself/herself using the CCP UI. Not required from call-center.

No

min 8 characters, Max 16 characters. Should contain at-least 1 alphabet and at-least 1 numeral.

verification-code

all

The verification-code used in mobile-number registration. This is not required if the request is being made from a call-centre.

No

A character string that can contain numbers, small cap alphabets. Length: 1-20

security-question

all

A security question to retrieve lost passwords. This should be one of the pre-defined values.

No

N/A

security-answer

all

The answer to the security question.

No

String - 3-255

referrer-merchant-ID

all

ID of the referrer merchant.

No

String - 100

brand-membershipId

all

Membership ID of the user of the brand.

No

String - 30

gift-card-upgrade

all

Optional details section for gift-cards in case the user wants to upgrade a gift-card to mywirecard.

No

N/A

card-program-name

all

Optional. Used to register for another card-program than the default one for the brand.

No

String - 50

bank-account

all

Optional section for the user to register his/her bank-account during sign-up.

No

N/A

account-currency

all

Optional field allowing the user to register his/her currency during sign-up

No

3-character currency-code.

marketing-opt-ins

all

Optional element describing the options chosen by the user to receive marketing communications.

No

N/A

card-pin

all

The card-pin chosen by the user. This Pin will be set for all cards, which have ‘Set Card PIN’ enabled in the Brand. Pin will only be accepted if it has at least 3 unique digits and is not a sequence.

No

4-digit number

terms-of-use-accepted

all

Whether all the terms and conditions have been accepted. If it is missing, it will default to false

No

true / false

cplcid

>= v3

Card Production Lifecycle ID. Used as login alias by some mobile apps.

No

String - 1-100

rns-mpa-id

>= v3

Optional. GCMID (RNS-MPA-ID) to be used for HCE Vault identification.

No

String - 4096

custom-fields

>= v3

Custom registration fields for specific brand. Optional use. Multiple instances of this element can occur.

No

N/A

regulatory-ids

>= v5

Regulatory ids of the customer. Optional use. Multiple instances of this element can occur.

No

N/A

person-identification

>= v3

Optional section to create the user person identification(id card)

No

N/A

card-expiry-date

>= v4

Tentative expiry date used to issue the card(s). Will be used for issuing ONLY IF it is earlier than the value defined by the ACTUAL issuing system (e.g. WDP, CETREL).

No

Format MM/yyyy

t-pin

>= v4

Telephone pin chosen by the user. With telephone pin user can use IVR system.

No

String - 10

global-user-name

>= v5

A globally unique user name

No

String - 30

Element: gift-card-upgrade

Elements Version Description

loading-number

all

13 digit number that identifies the card.

card-last-four-digits

all

Last 4 digits of the card-number.

Element: bank-account

Elements Version Description

iban

all

The International Bank Account Number (IBAN) of the bank account.

bic

all

The Bank Identifier Code (BIC) number of the bank account (optional).

account-holder

all

The name of the account holder (optional)

Element: marketing-opt-ins

Elements Version Description

opt-in-topic

all

Element describing the details of the opt-in. Multiple instances of this element can be present. At-least one instance of this element should be present

Element: opt-in-topic

Elements Version Description

opt-in-mode

all

One of EMAIL, PHONE, POST, PUSH_NOTIFICATION. Multiple instances of this element can occur. But at-least one should be present

Attributes Version Description

name

all

Name of the opt-in. Mandatory

Element: custom-fields

A group of custom fields specific to brand’s user registration process.

Attributes Version Description Required

scope

>= v3

The scope of a custom field is defined in the brand.xml. The scope value in the request is ignored. The scope attribute will be removed in the next version.

No

Elements Version Description

custom-field

>= v3

List of custom fields. Multiple instances of this element can occur.

Element: custom-field

One custom field specific to brand’s user registration process.

Attributes Version Description Restrictions

name

>= v3

Name of the specific field. Required.

String containing letters, number or dash(dash can be neither the first nor the last char) - 100

value

>= v3

Value of the specific field. Required.

String - 256

Element: RegulatoryId A regulatory id belonging to the person in registration.

The RegulatoryId type has two attributes (type and country) and a value (max length 100) for the actual id number.

Attributes Data type Usage Description

type

Uppercase letters and underscores, max. length 32

Required

The type of regulatory id, e.g. CURP for Mexico, SSN for the U.S., Emirate ID, German IDNR.

country

CountryCodeType

Required

The two-letter country code (ISO 3166-1 alpha-2) where the id belongs to, e.g. MX or US

Element: person-identification

Attributes Version Description Required Restrictions

type

>= v3

The type of the id card

No

One of IDENTITY_CARD, PASSPORT, CHILD_TRAVEL_DOCUMENT, BIRTH_CERTIFICATE, OTHER

id-number

>= v3

The id card number

No

String - 50

issuing-authority

>= v3

The name of authority which issued the id card

No

String - 256

issuing-country

>= v3

Two letters of the country where the card was issued

No

String - 2

issuing-date

>= v3

The issuing date

No

Format: YYYY-MM-DD

place-of-birth

>= v3

The user’s place of birth

No

String - 50

expiration-date

>= v3

The expiration date of the id card

No

Format: YYYY-MM-DD

Note 1: All elements that have been specified as mandatory cannot have empty values

Note 2: Fields mentioned as String – xx allow UTF-8 characters with the specified length. (http://www.utf8-chartable.de)

Note 3: Salutation is now being validated to allow MRS (misses) as a node value - in addition to MR and MS - only if the brand is not processed by CETREL. This particularity can be found in the brand configuration (processor node).

Sample Request 1

<?xml version="1.0" encoding="UTF-8"?>
<register-user-request xmlns="http://wirecardbank.com/rest-api">
  <salutation>MR</salutation>
  <first-name>John</first-name>
  <last-name>Smith</last-name>
  <nationality>DE</nationality>
  <birth-date>1992-09-24</birth-date>
  <mobile-number>+491234567890</mobile-number>
  <email>abc@def.co.de</email>
  <street>Abcdef str.</street>
  <house-number>12a</house-number>
  <city>Atlantis</city>
  <zipcode>12345</zipcode>
  <country-of-residence>FR</country-of-residence>
  <locale>EN</locale>
  <login-name>johnsmith1980</login-name>
  <password>Johnny_1992</password>
  <security-question>FIRST_PET_NAME</security-question>
  <security-answer>secret!</security-answer>
  <referrer-merchant-ID>123456</referrer-merchant-ID>
  <brand-membershipId>12345678</brand-membershipId>
  <gift-card-upgrade>
    <loading-number>2123456789012</loading-number>
    <card-last-four-digits>1234</card-last-four-digits>
  </gift-card-upgrade>
  <card-program-name>virtual</card-program-name>
  <bank-account>
    <iban>DE89370400440532013000</iban>
    <bic>AAAAZZ00111</bic>
    <account-holder>Nameof Accountholder</account-holder>
  </bank-account>
  <terms-of-use-accepted>true</terms-of-use-accepted>
  <cplcid>4750002B823123213334300802A08720023B</cplcid>
  <card-expiry-date>06/2016</card-expiry-date>
</register-user-request>

Sample Request 2 - Custom Registration Fields

<?xml version="1.0" encoding="UTF-8"?>
<register-user-request xmlns="http://wirecardbank.com/rest-api">
  <salutation>MR</salutation>
  <first-name>John</first-name>
  <last-name>Smith</last-name>
  <nationality>DE</nationality>
  <birth-date>1992-09-24</birth-date>
  <mobile-number>+491234567890</mobile-number>
  <email>abc@def.co.de</email>
  <house-details>1A Seastone Cottages</house-details>
  <street>Station Road</street>
  <address-line-two>Weybourne</address-line-two>
  <city>HOLT</city>
  <zipcode>12345</zipcode>
  <country-of-residence>GB</country-of-residence>
  <locale>EN</locale>
  <login-name>johnsmith1980</login-name>
  <password>Johnny_1992</password>
  <security-question>FIRST_PET_NAME</security-question>
  <security-answer>secret!</security-answer>
  <referrer-merchant-ID>123456</referrer-merchant-ID>
  <brand-membershipId>12345678</brand-membershipId>
  <gift-card-upgrade>
    <loading-number>2123456789012</loading-number>
    <card-last-four-digits>1234</card-last-four-digits>
  </gift-card-upgrade>
  <card-program-name>virtual</card-program-name>
  <bank-account>
    <bic>AAAAZZ00111</bic>
    <iban>DE89370400440532013000</iban>
    <account-holder>Nameof Accountholder</account-holder>
  </bank-account>
  <marketing-opt-ins>
    <opt-in-topic name="basic_info"/>
    <opt-in-topic name="extra_info">
      <opt-in-mode>PHONE</opt-in-mode>
      <opt-in-mode>EMAIL</opt-in-mode>
    </opt-in-topic>
  </marketing-opt-ins>
  <terms-of-use-accepted>true</terms-of-use-accepted>
  <cplcid>4750002B823123213334300802A08720023B</cplcid>
  <custom-fields>
        <custom-field name="customer-category" value="PLATINUM" />
        <custom-field name="contract-type" value="post-paid" />
  </custom-fields>
  <regulatory-ids>
      <regulatory-id country="MX" type="CURP">HEGG560427MVZRRL04</regulatory-id>
      <regulatory-id country="US" type="SSN">123456789</regulatory-id>
      <regulatory-id country="US" type="IDNR">12345678901</regulatory-id>
  </regulatory-ids>
  <global-user-name>uePsOIpeAFgWxR0E</global-user-name>
</register-user-request>

Sample Request 3 - JSON

{
    "salutation":"MR",
    "nationality":"DE",
    "email":"abc@def.co.de",
    "street":"Station Road",
    "city":"HOLT",
    "zipcode":"12345",
    "locale":"EN",
    "password":"Johnny_1992",
    "first-name":"John",
    "last-name":"Smith",
    "birth-date":"1992-09-24",
    "mobile-number":"+491234567890",
    "house-details":"1A Seastone Cottages",
    "address-line-two":"Weybourne",
    "country-of-residence":"GB",
    "login-name":"johnsmith1980",
    "security-question":"FIRST_PET_NAME",
    "security-answer":"secret!",
    "referrer-merchant-ID":"123456",
    "brand-membershipId":"12345678",
    "gift-card-upgrade":{
        "loading-number":"2123456789012",
        "card-last-four-digits":"1234"
    },
    "card-program-name":"virtual",
    "bank-account":{
        "iban":"DE89370400440532013000",
        "bic":"AAAAZZ00111",
        "account-holder":"Nameof Accountholder"
    },
    "marketing-opt-ins":{
        "opt-in-topic":[{
            "name":"extra_info",
            "opt-in-mode":["PHONE","EMAIL"]
        },{
            "name":"basic_info",
            "opt-in-mode":[]
        }]},
    "terms-of-use-accepted":true,
    "cplcid": "4750002B823123213334300802A08720023B",
    "custom-fields":  [
               {
                 "custom-field" :[{
                        "name":"customer-category",
                        "value":"PLATINUM"
                    }]
                },
                {
                       "custom-field":[{
                        "name":"contract-type",
                        "value":"post-paid"
                        }]
                 }],
     "regualtory-ids":  [
                    {
                      "regualtory-id" :[{
                             "country":"MX",
                             "type":"CURP",
                             "value":"HEGG560427MVZRRL04"

                         }]
                    },
                    {
                       "regualtory-id" :[{
                             "country":"US",
                             "type":"SSN",
                             "value":"23456789"

                         }]
                    }],
    "card-expiry-date":"06/2016"
}

Sample Request 4 - Only required fields

<?xml version="1.0" encoding="UTF-8"?>
<register-user-request xmlns="http://wirecardbank.com/rest-api">
  <email>abc@def.co.de</email>
  <terms-of-use-accepted>true</terms-of-use-accepted>
</register-user-request>

Sample Request 5 - JSON example request

{
    "deviceId": "4578",
    "ipAddressV4": "10.10.24.124",
    "salutation": "MR",
    "first-name": "asd",
    "last-name": "asd",
    "nationality": "DE",
    "birth-date": "1979-04-20",
    "email": "asd@wirecard.com",
    "street": "asd",
    "house-number": "12",
    "city": "asd",
    "zipcode": "12432",
    "country-of-residence": "DE",
    "locale": "DE",
    "login-name": "asd",
    "password": "aaaa1111",
    "verification-code": "aaaa1111",
    "security-question": "MOTHER_PLACE_OF_BIRTH",
    "security-answer": "asd",
    "terms-of-use-accepted": "true"
}

10.1.2. User-Registration Service Response

Element: register-user-response

Elements Version Description

login-name

all

A confirmation that the user was created with this login-name.

login-identifier

>= v4

The 32 chars long generated login identifier.

status

all

The status of the user registration. One of: ACTIVE, IN_REGISTRATION (mobile-number-registration still pending), LOCKED (User registered but is locked due to risk / fraud checks)

business-status

>= v6

The business status of the user. One of: ACTIVE, IN_REGISTRATION, LOCKED, CLOSED

loading-number

>= v7

The loading number of the user which is a string with 13 digits.

feedback-messages

all

A list of feedback messages (warnings) that occurred during the registration process and have to be acted upon, but did not prevent the registration from completing successfully.

Element: feedback-message

Elements Version Description

code

all

error code

message

all

A detailed description matching the code

Element: code

Values Version Description

ACTIVATION_ACCOUNT_GENERAL_ERROR

all

User was registered, but the account activation failed

BANK_ACCOUNT_NOT_REGISTERED

all

User was registered, but bank account was not registered

BANK_ACCOUNT_ALREADY_EXIST

all

User was registered, but the bank account already exists

MISSING_BANK_ ACCOUNT__DETAILS

all

Bank account doesn’t contain BIC or IBAN

INVALID__ ACCOUNT_ DETAILS

all

Bank account contains a invalid BIC or IBAN

INCONSISTENT_OPT_IN

all

Incorrect opt-in modes specified

TRANSACTION_FAILED_AND_BANK_ACCOUNT_DELETED

all

The bank account is not valid and it was deleted

SMS_SEND_ERROR

all

Sample Response

<?xml version="1.0" encoding="UTF-8"?>
<register-user-response xmlns="http://wirecardbank.com/rest-api">
    <login-name>johnsmith1980</login-name>
    <login-identifier>8295BEBFED2611E5BA0300A0C6000016</login-identifier>
    <status>ACTIVE</status>
    <business-status>LOCKED</business-status>
    <loading-number>2040811789761</loading-number>
    <feedback-messages/>
</register-user-response>

HTTP Response Codes

Status Error-Key Description

200

N/A

Registration OK but check feedback-messages for warnings

400

400

Bad Request: xml request might not be conform to the specification specification, missing Parameters, or similar

403

CHARACTER_VALIDATION

A given character for first or last name is not supported by the system

403

CUSTOMER_WITH_THIS_PHONE_NUMBER_EXISTS

Customer with this mobile phone number already exists

403

USER_WITH_THIS_CPLCID_EXISTS

User with this CPLCID already exists.

403

GIFT_CARD_IN_INVALID_STATE

Gift card is in an invalid state

403

GIFTCARD_ALREADY_REGISTERED_WITH_USER

Giftcard is already registered with an user

403

GIFTCARD_LAST4CARD_DIGITS_INVALID

The last 4 card digits are invalid.

403

GENERAL

A general error

403

INVALID_LOCALE_FOR_BRAND

The locale is not supported by the brand

403

MOBILE_NOT_ELIGIBLE_REJECT_USER

User can not register

403

MOBILE_NOT_ELIGIBLE_SELECT_DIFFERENT_CARD_PROGRAM

The mobile device is not eligible for mobile cards, choose another card program

403

MOBILE_NOT_ELIGIBLE_TRY_AGAIN

The eligibility check was unsuccessful, try again

403

MOBILE_NOT_ELIGIBLE_SYSTEM_ERROR

A system error occurred, try again later

403

MOBILE_NOT_ELIGIBLE_NO_SPTSM_CONFIG_IN_BRAND

This brand does not contain a proper SPTSM Configuration

403

MOBILE_REQUIRED_SELECT_DIFFERENT_CARD_PROGRAM

A mobile number is required for the chosen card program.

403

MOBILE_PHONE_DOES_NOT_MATCH_ALLOWED_PREFIX

The mobile phone does not match an allowed prefix. This can happen when users try to use phone numbers from invalid countries or providers.

403

MOBILE_PHONE_WRONG_FORMAT

The mobile phone number is not well formatted e.g. you have a prefix and trailing 0 like +4901740123456

403

NO_GIFTCARD_EXISTS

No giftcard is registered

403

NO_REFERENCE_NUMBER_AVAILABLE_FOR_UPGRADE

No reference number available for upgrade

403

PIN_ILLEGAL_SEQUENCE

Pin rejected because it contains a sequence, like for example "1234", "8765" or "8901"

403

PIN_ILLEGAL_3_UNIQUE_DIGITS_REQUIRED

Pin rejected because it does not have 3 unique digits

403

SALUTATION_IS_NOT_ALLOWED

Salutation is not allowed for this brand

403

USER_ADDRESS_INCOMPLETE

Returned when a customer registers for a physical card program, but does not specify a complete address. In such cases the shipment of the physical card (plastic card, sticker) cannot be executed.

403

USER_WITH_THIS_LOGIN_NAME_EXISTS

User with this login name already exists

403

USER_WITH_THIS_EMAIL_EXISTS

User with this email address already exists

403

VALIDATION_FAILED

Validation of the incoming data failed. Contains a list of descriptions, which are expected to be handled by the client. At the end of the error-message, it contains a list in the format of: keys:#reasonKey1#reasonKey2

403

ACCOUNT_ CURRENCY_NOT_SUPPORTED

Account currency is not supported for the given brand and country of residence

403

INVALID_COUNTRY_OF_REGISTRATION

Country based on IP address used during registration is not supported for a given brand

403

INVALID_COUNTRY_OF_RESIDENCE

Country of residence is not supported for a given brand

403

WIRECARD_BANK_ACCOUNT

Wirecard bank accounts are not allowed

403

WRONG_VERIFICATION_CODE_FOR_MOBILE_NUMBER

Invalid verification code for mobile number, the verification code from the verification step must be present in this call as well, if the mobile phone has been verified already.

403

CUSTOM_FIELD_FORBIDDEN

Forbidden custom fields used: <list of errors>.

403

CUSTOM_FIELD_MISSING

Missing mandatory custom fields: <list of errors>.

403

VALIDATION_ERROR_CUSTOMER_ALREADY_EXISTS

Validation failed during duplicate checks

403

INVALID_CARD_EXPIRY_DATE

The card expiry date is outside the allowed range

403

TELEPIN_ILLEGAL_SEQUENCE

Telepin is not allowed to contain this sequence

403

TELEPIN_NOT_UNIQUE_DIGITS

Telepin should have unique digits

403

TELEPIN_VALIDATION_FAILED

Telepin validation failed: only digits allowed

403

TELEPIN_NOT_PROVIDED

Telepin should be provided

403

TELEPIN_NOT_SUPPORTED_BY_BRAND

Telepin should not be provided, telepin is disabled.

403

VALIDATION_ERROR_REGEXP

Data format error.

500

500

INTERNAL_EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

Sample Error Response

Apart from the common error structure this service can also throw the multi-error response. For more details about the error handling please refer to General Error Response section.

<?xml version="1.0" encoding="UTF-8"?>
<error-response xmlns="http://wirecardbank.com/rest-api">
    <error-code>403</error-code>
    <errors>
        <error>
            <error-key>VALIDATION_ERROR_CUSTOMER_ALREADY_EXISTS</error-key>
            <error-message>ALL - The customer already exists.</error-message>
        </error>
    </errors>
</error-response>

11. Registered Credit Cards and Bank Accounts

11.1. Credit-Cards-List Service

This service lists all the external credit cards which can be used for top up the account.

11.1.1. Credit-Cards-List Service Request

HTTP Method: GET

URL version 1: <base-URL>/{brandName}/user/{loginAlias}/credit-cards[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/credit-cards[?aliasType={aliasType}]

11.1.2. Credit-Cards-List Service Response

Element: credit-cards-response

Elements Version Description

credit-cards

all

Contains the list of credit-cards registered by the user.

Element: credit-cards

Elements Version Description

credit-card

all

Details of the credit-card.

Element: credit-card

Elements Version Description

identifier

all

System-identifier of this credit-card as understood by the CCP system. This is not to be displayed to the user.

number

all

Credit-card number. It’s not fully displayed. i.e. some digits are masked.

expiration-date

all

Expiry-date of the credit-card.

status

v2

Status of the card.

date-added

v2

Date when the card was added.

display-name

all

Optional name given to the credit-card by the user during registration.

Sample Response Version 1

<?xml version="1.0" encoding="UTF-8"?>
<credit-cards-response xmlns="http://wirecardbank.com/rest-api">
  <credit-cards>
    <credit-card>
      <identifier>DFAD0A5E2E3511E2A6B9F04DA225A685</identifier>
      <number>420000******0000</number>
      <expiration-date>01/2015</expiration-date>
      <display-name>TEST</display-name>
    </credit-card>
    <credit-card>
      <identifier>DFAD0A5E2EASDFA34534G04DA225A685</identifier>
      <number>421111******0000</number>
      <expiration-date>01/2015</expiration-date>
    </credit-card>
  </credit-cards>
</credit-cards-response>

Sample Response Version 2

<?xml version="1.0" encoding="UTF-8"?>
<credit-cards-response xmlns="http://wirecardbank.com/rest-api">
  <credit-cards>
    <credit-card>
      <identifier>DFAD0A5E2E3511E2A6B9F04DA225A685</identifier>
      <number>420000******0000</number>
      <expiration-date>01/2015</expiration-date>
      <status>NOT_VALIDATED</status>
      <date-added>2013-10-10T11:46:11Z</date-added>
      <display-name>TEST</display-name>
    </credit-card>
  </credit-cards>
</credit-cards-response>

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

401

401

Missing authentication credentials

401

INVALID_CREDENTIALS

User not found or closed or invalid password

403

LOGIN_IN_REGISTRATION

User still in registration

500

500

INTERNAL_ EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

11.2. Register Credit-Card Service

This service register a new credit-card of the user he/she which allow him/her to perform top-ups.

11.2.1. Register Credit-Card Service Request

HTTP Method: POST

URL: <base-URL>/{brandName}/user/{loginAlias}/credit-cards

Element: credit-card

Elements Version Description

display-name

all

Optional name given to the credit-card by the user during registration.

number

all

Credit-card number.

expiry-date

all

Expiry-date of the credit-card.

type

all

Brand name for this card. It might be only VISA or MASTERCARD

Sample Request

<?xml version="1.0" encoding="UTF-8"?>
<credit-card xmlns="http://wirecardbank.com/rest-api">
 <display-name>Thomas Muller Visa</display-name>
 <number>4444333322221111</number>
 <expiry-date>01/2020</expiry-date>
 <type>VISA</type>
</credit-card>

11.2.2. Register Credit-Card Service Response

Response body is empty even when credit-card is created.

HTTP Response Codes

Status Error-Key Description

200

N/A

Created

400

400

Bad Request, possible reasons: common BadRequestproblems, XML request not conform to the specification

403

LOCKED_CUSTOMER

Customer is not allowed to register a credit card

403

VALIDATION_FAILED_CARD_NUMBER

Invalid credit card number entered

403

CREDITCARD_ALREADY_REGISTERED

Card already in use

403

WIRECARD_BIN_CHECK_ERROR

The card was rejected since it is a Wirecard Bank prepaid card.

403

PAST_EXPIRY_DATE

The credit card is expired

403

DUPLICATE_DISPLAY_NAME

User has already registered a card with the given display-name

403

BIN_NOT_IN_RANGE

The credit card is rejected due not being in valid BIN range specified in the brand

500

INTERNAL_EXCEPTION

Any internal exception

504

GATEWAY_TIMEOUT

Communication to back-end failed. The client may retry.

11.3. Bank-Account-Registration Service

This service register a bank account. Bank account could be IBAN or ABA (US bank account) or SGBA (Singapore)

11.3.1. Bank-Account-Registration Service Request

HTTP Method: PUT

URL: <base-URL>/{brandName}/user/{loginAlias}/bank-account-registration

Element: bank-account-registration-request

Elements Version Group Description

iban

all

IBAN

International Bank Account Number (IBAN).

bic

all

IBAN

Bank Identifier Code (BIC) - optional.

routing-number

all

ABA, SGBA

US or Singapore Bank Account routing number 9 characters.

account-number

all

ABA, SGBA

US or Singapore Bank Account account number 17 characters.

bank-name

all

ABA, SGBA

US or Singapore Bank name - optional 100 characters.

bank-account-type

all

ABA, SGBA

US or Singapore Bank Account type - optional. NOT_SPECIFIED (default), CHECKING, SAVING.

terms-accepted

all

ABA, SGBA

US or SingaporeUS Bank terms and conditions - optional.

display-name

all

IBAN, ABA, SGBA

Display name of the bank account.

Sample IBAN Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bank-account-registration-request
    xmlns="http://wirecardbank.com/rest-api">
    <iban>DE21514206000032423234</iban>
    <bic>HANDDEFFXXX</bic>
    <display-name>DisplayName</display-name>
</bank-account-registration-request>

Sample ABA Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<bank-account-registration-request
    xmlns="http://wirecardbank.com/rest-api">
    <routing-number>121122676</routing-number>
    <account-number>2132654522</account-number>
    <bank-name>US-Bank</bank-name>
    <bank-account-type>SAVING</bank-account-type>
    <display-name>DisplayName</display-name>
</bank-account-registration-request>

11.3.2. Bank-Account-Registration Service Response

HTTP Response Codes

Status Error-Key Description

200

N/A

OK

400

400

Bad Request, possible reasons: common BadRequestproblems, xml request not conform to the specification

403

BLOCKED_CUSTOMER

Customer is not allowed to register a new bank account

403

INVALID_ACCOUNT_DETAILS

Invalid or missing bank account details

403

WIRECARD_BANK_ACCOUNT

Wirecard bank accounts are not allowed

403

BANK_ACCOUNT_ALREADY_IN_USE

Bank account registered by another user

403

BANK_ACCOUNT_REGISTRATION_FAILED

Bank account was not registered

403

TRANSACTION_FAILED_AND_BANK_ACCOUNT_DELETED

The bank account is not valid and it was deleted

403

TERMS_NOT_ACCEPTED

Terms of usage were not accepted.

403

BANK_ACCOUNT_NUMBER_TYPE_IS_NOT_CONFIGURED

Bank account number is not IBAN and it is not configured in brand supported-bank-account-number-type

500

500

INTERNAL_ EXCEPTION

504

504

GATEWAY_TIMEOUT - Communication to backend failed. The client may retry.

11.4. Bank-Accounts-List Service

This service lists all the registered bank accounts of the user, using which he/she can perform the top-up.

11.4.1. Bank-Accounts-List Service Request

HTTP Method: GET

URL version 1: <base-URL>/{brandName}/user/{loginAlias}/bank-accounts[?aliasType={aliasType}]

URL version 2: <base-URL>/v2/{brandName}/user/{loginAlias}/bank-accounts[?aliasType={aliasType}]

URL version 3: <base-URL>/v3/{brandName}/user/{loginAlias}/bank-accounts[?aliasType={aliasType}]

11.4.2. Bank-Accounts-List Service Response

Element: bank-accounts-response

Elements Version Description

bank-accounts

all

Contains the list of validated bank accounts registered by the user.

Element: bank-accounts

Elements Version Description

bank-account

all

Details of the validated bank account.

Element: bank-account

Elements Version Description

account-number

all

Account number of the bank account.

routing-number

all

Routing number of the bank account.

identifier

all

System-identifier of this bank account as understood by the CCP system. This is not to be displayed to the user.

display-name

all

Optional name given to the bank account by the user during registration.

iban

v2

The International Bank Account Number (IBAN) of the bank account.

bic

v2

The Bank Identifier Code (BIC) of the bank account (optional).

status

v2

The status of the bank account.

bank-account-type

v3

US Bank Account type SAVING or CHECKING (optional).

bank-name

v3

Name of the Bank (optional)

bank-account-number-type

v4

Bank Account number type ABA, IBAN, SGBA or NATIONAL_BANK_ACCOUNT.

Sample Response Version 1

<?xml version="1.0" encoding="UTF-8"?>
<bank-accounts-response xmlns="http://wirecardbank.com/rest-api">
  <bank-accounts>
    <bank-account>
      <account-number>1111111111</account-number>
      <routing-number>30020900</routing-number>
      <identifier>123123124erwr</identifier>
      <display-name>Test</display-name>
    </bank-account>
  </bank-accounts>
</bank-accounts-response>

Sample Response Version 2

<?xml version="1.0" encoding="UTF-8"?>
<bank-accounts-response xmlns="http://wirecardbank.com/rest-api">
  <bank-accounts>
    <bank-account>
      <account-number>2312531246</account-number>
      <routing-number>30020900</routing-number>
      <identifier>59E5BADD45DE11E2A06D00163E000118</identifier>
      <display-name>Test bank account</display-name>
      <iban>DE78300209002312531245</iban>
      <bic>CMCIDEDDXXX</bic>
      <status>VALIDATED</status>
    </bank-account>
  </bank-accounts>
</bank-accounts-response>