Skip to main content
API docs by Redocly

debiX API (2.10.0)

Download OpenAPI specification:Download

Health check

Allows to verify the availability of the API, the access to it across all layers, as well as the client authentication.

Health check using GET method.

Returns a status message of the system.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "message": "The healthcheck GET request was successfully received and processed.",
  • "requestDateTime": "2021-10-03T16:03:09.101+02:00",
  • "receivedHeaders": [
    • {
      }
    ],
  • "apiVersion": "1.0.0"
}

Health check using POST method.

Returns the request body. This operation will not modify the system.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Any message which is expected in the response.

message
required
string [ 1 .. 100 ] characters

Expected response message from health check.

Responses

Request samples

Content type
application/json
{
  • "message": "Any string"
}

Response samples

Content type
application/json
{
  • "message": "The healthcheck GET request was successfully received and processed.",
  • "requestDateTime": "2021-10-03T16:03:09.101+02:00",
  • "receivedHeaders": [
    • {
      }
    ],
  • "apiVersion": "1.0.0"
}

Health check using PUT method.

Returns the request body. This operation will not modify the system.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Any message which is expected in the response.

message
required
string [ 1 .. 100 ] characters

Expected response message from health check.

Responses

Request samples

Content type
application/json
{
  • "message": "Any string"
}

Response samples

Content type
application/json
{
  • "message": "The healthcheck GET request was successfully received and processed.",
  • "requestDateTime": "2021-10-03T16:03:09.101+02:00",
  • "receivedHeaders": [
    • {
      }
    ],
  • "apiVersion": "1.0.0"
}

Card lifecycle

Orders new cards, retrieves and updates card data.

Orders a new card.

Orders a new virtual card optionally with a reference to an existing parent card.

In case the feature toggle values are not specified in the request, either directly, or by referencing a parentCard with the takeoverFeatureToggles set to true, the feature toggles will receive the following default values:

Feature Flag Default Value
eCommerceAllowed true
trxOnlyAsChipAndPin false
magStripePaymentAllowed true
automaticBilling true
purchaseWithCashBackAllowed true
merchantInitiatedTrxAllowed true
atmAllowed true
posAllowed true
motoAllowed true
bypassGeoblocking true
moneySendReceiveAllowance RECEIVE_AND_SEND_ALLOWED
reservationAllowed true
transactionPushEnabled true
gamblingAndBettingAllowance ALLOWED
blockedMerchantCategoryCodes (empty List)

In addition to standard application error codes, the following codes can be returned:

  • 4432: BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4443: UNKNOWN_PARENT_CARD
  • 4444: VIRTUAL_CARD_EQUALS_PARENT_CARD
  • 4445: CARD_ALREADY_EXISTING
  • 4446: DELIVERY_INFORMATION_FOR_OTRC_MISSING
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Configuration specifying the new card to be ordered.

required
object (CardOrderData)

Card data needed to order the card. Online limits are required if they should not be taken over from the parent card. In this version, only cardMaterial VIRTUAL is supported.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

accountNumber
required
string (AccountNumber) [ 1 .. 16 ] characters

Unique number identifying a bank account.

iban
required
string (Iban) = 21 characters

IBAN of the bank account for which the card was issued.

cardMaterial
required
string (CardMaterial)
Enum: "PHYSICAL" "VIRTUAL"

Distinguishes physical from virtual cards.

language
required
string (Language)
Enum: "DE" "FR" "IT" "EN"

Correspondence language.

branchNumber
integer <int32> (BranchNumber) [ 0 .. 9999 ]

Branch number of the site where the account was initially created.

transactionAuthorizer
required
string (TransactionAuthorizer)
Enum: "ALWAYS_SIX" "ISSUER_WITH_FALLBACK_SIX" "SIX_WITH_FALLBACK_ISSUER" "ISSUER_WITH_FALLBACK_SIX_AND_OTHER_LIMITS"

Authorizer for retail and ATM transactions.

subCardType
string (SubCardType) = 2 characters

Sub card type that is linked to the BIN range and specifies a product like 'Platinum', 'Gold', 'Student' etc.

required
object (OnlineLimits)

The monthly and daily retail and cash transactions limits.

object (FeatureToggles)

Contains the values of the feature toggles for the card.

cardPlasticCode
required
string (CardPlasticCode) = 2 characters

Plastic code of the card.

otrcDelivery
string (OtrcDelivery)
Default: "NONE"
Enum: "NONE" "DATAMAILER" "ONLINE"

Delivery type of OTRC. Currently not used for virtual cards.

otrcDatamailerDelivery
string (OtrcDatamailerDelivery)
Enum: "DELIVER_TO_BANK" "DELIVER_TO_CARDHOLDER"

Defines the delivery of the OTRC datamailer.

otrcDatamailerExpressCode
string (OtrcDatamailerExpressCode)
Enum: "A_POST" "B_POST" "REGISTERED"

Defines the express code of the OTRC datamailer delivery.

object

Delivery address of card, PIN and OTRC; only required with otrcDelivery DATAMAILER.

object (ParentCardReference)

Reference to a card from which settings can be inherited.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

shareLimits
required
boolean

Indicates if the limits should be shared with the parent card.

deleteAfterFirstUse
required
boolean

Indicates if the parent card shall be deleted after first use of new card.

takeoverPin
required
boolean

Indicates if the PIN shall be taken over from the parent card.

takeoverContactlessActivationStatus
required
boolean

Indicates if the contactless activation status shall be taken over from the parent card.

takeoverFeatureToggles
required
boolean

Indicates if the feature toggles shall be taken over from the parent card.

takeoverBillingUpdater
required
boolean

Indicates if the new card shall be linked to the account of the parent card within the Mastercard automated billing updater (ABU) resp. the VISA Account Updater (VAU).

object (BccData)

Information about the cardholder from the bank card central.

salutation
required
string (Salutation)
Enum: "NOT_SET" "MR" "MS" "FIRM"

Salutation code of a cardholder.

firstName
required
string (FirstName) <= 25 characters

First name

familyName
required
string (FamilyName) <= 25 characters

Family name

street
required
string <= 25 characters

Street name.

streetNo
string <= 5 characters

Street number.

city
required
string <= 25 characters

Location city.

postalCode
required
string <= 10 characters

Postal code.

country
required
string (Country) [A-Z]{2}

Country code in format ISO 3166-1 alpha 2.

phoneNumber
string (PhoneNumber) ^([+]|00)[1-9][0-9]{8,18}$

Mobile or landline phone number. Note: phoneNumber is a mandatory parameter which must be provided to register a card with authentication method SMS_ONLY, PIN, BIOMETRIC or BIOMETRIC_WITH_PIN_FALLBACK. Furthermore, phoneNumber must also be provided in case the issuer desires to register a card for DELEGATED as primary authentication method, with additionally SMS as fallback (as secondary authentication method).

birthdate
string <date>

Birthdate to identify the customer.

emailAddress
string

Email address to identify the customer.

customerRelationshipOpeningDate
string <date>

Date when the customer relationship was opened; used to identify the customer.

accountOpeningDate
string <date>

Date when the account was opened; used to identify the customer.

Array of objects (AccountAuthority) [ 0 .. 4 ] items
individualIdentificationTag
string <= 80 characters

Individual tag to identify the customer.

ebankingContractNo
string <= 15 characters

Ebanking contract number to identify the customer.

object (FraudConfiguration)

The fraud configuration, containing restrictions for countries and regions. Authorizations from a country will be declined if the country itself, or the region it belongs to, is restricted.

restrictedRegions
Array of strings (Region) [ 1 .. 10 ] items
Items Enum: "SWITZERLAND_AND_LIECHTENSTEIN" "EUROPE" "EASTERN_EUROPE_AND_CENTRAL_ASIA" "AFRICA" "CANADA" "USA_AND_MEXICO" "LATIN_AMERICA_AND_CARIBBEAN" "MIDDLE_EAST_ASIA_PACIFIC_AUSTRALIA"

A list of regions from which authorizations will be declined.

restrictedCountries
Array of strings (Country) [ 1 .. 300 ] items [[A-Z]{2}]

A list of countries from which authorizations will be declined.

riskShieldListing
Array of strings (RiskShieldList) [ 1 .. 100 ] items

A list of monitoring lists in RiskShield on which a card can be listed.

Responses

Request samples

Content type
application/json
{
  • "cardOrderData": {
    • "cardId": {
      },
    • "accountNumber": "AB-4567890123456",
    • "iban": "CH3456789012345678901",
    • "cardMaterial": "PHYSICAL",
    • "language": "DE",
    • "branchNumber": 1,
    • "transactionAuthorizer": "ALWAYS_SIX",
    • "subCardType": "A1",
    • "onlineLimits": {
      },
    • "featureToggles": {
      },
    • "cardPlasticCode": "F0",
    • "otrcDelivery": "NONE",
    • "otrcDatamailerDelivery": "DELIVER_TO_BANK",
    • "otrcDatamailerExpressCode": "A_POST",
    • "deliveryInformation": {
      }
    },
  • "parentCardReference": {
    • "cardId": {
      },
    • "shareLimits": true,
    • "deleteAfterFirstUse": true,
    • "takeoverPin": true,
    • "takeoverContactlessActivationStatus": true,
    • "takeoverFeatureToggles": true,
    • "takeoverBillingUpdater": true
    },
  • "bccData": {
    • "salutation": "NOT_SET",
    • "firstName": "Peter",
    • "familyName": "Schweizer",
    • "street": "Bahnhofstrasse",
    • "streetNo": "1",
    • "city": "Zürich",
    • "postalCode": "8001",
    • "country": "CH",
    • "phoneNumber": "+41797778899",
    • "birthdate": "2000-12-31",
    • "emailAddress": "peter.schweizer@mailbox.org",
    • "customerRelationshipOpeningDate": "2021-12-31",
    • "accountOpeningDate": "2021-12-31",
    • "accountAuthorities": [
      ],
    • "individualIdentificationTag": "Owner of a sailing boat",
    • "ebankingContractNo": "ABC-56789012345"
    },
  • "fraudConfiguration": {
    • "restrictedRegions": [
      ],
    • "restrictedCountries": [
      ],
    • "riskShieldListing": [
      ]
    }
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

Returns the card details.

Returns the status and the details of the specified card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4447 - NO_CARD_DETAILS_AVAILABLE
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Identifier of the card for which to return the details.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    }
}

Response samples

Content type
application/json
{
  • "commonCardInformation": {
    • "accountNumber": "AB-4567890123456",
    • "iban": "CH3456789012345678901",
    • "cardMaterial": "PHYSICAL",
    • "plasticCode": "F0",
    • "subCardType": "A1",
    • "language": "DE",
    • "status": "ACTIVE",
    • "cardStatusUpdateReason": "ISSUER_DECISION",
    • "blockInformation": {
      },
    • "pinRemainingRetries": 2,
    • "pinRecoveryStatus": "NO_PIN_ORDERED"
    },
  • "bccData": {
    • "salutation": "NOT_SET",
    • "firstName": "Peter",
    • "familyName": "Schweizer",
    • "street": "Bahnhofstrasse",
    • "streetNo": "1",
    • "city": "Zürich",
    • "postalCode": "8001",
    • "country": "CH",
    • "phoneNumber": "+41797778899",
    • "birthdate": "2000-12-31",
    • "emailAddress": "peter.schweizer@mailbox.org",
    • "customerRelationshipOpeningDate": "2021-12-31",
    • "accountOpeningDate": "2021-12-31",
    • "accountAuthorities": [
      ],
    • "individualIdentificationTag": "Owner of a sailing boat",
    • "ebankingContractNo": "ABC-56789012345"
    },
  • "fraudConfiguration": {
    • "restrictedRegions": [
      ],
    • "restrictedCountries": [
      ],
    • "riskShieldListing": [
      ]
    },
  • "featureToggles": {
    • "eCommerceAllowed": true,
    • "trxOnlyAsChipAndPin": true,
    • "magStripePaymentAllowed": true,
    • "automaticBilling": true,
    • "purchaseWithCashBackAllowed": true,
    • "blockedMerchantCategoryCodes": [
      ],
    • "merchantInitiatedTrxAllowed": true,
    • "atmAllowed": true,
    • "posAllowed": true,
    • "motoAllowed": true,
    • "bypassGeoblocking": true,
    • "moneySendReceiveAllowance": "NOT_ALLOWED",
    • "reservationAllowed": true,
    • "transactionPushEnabled": true,
    • "gamblingAndBettingAllowance": "ALLOWED"
    },
  • "threeDsInformation": {
    • "paymentAuthenticationMethods": {
      },
    • "mobilePhoneNumber": "+41797778899"
    }
}

Returns the card token.

Returns the unique card token of the specified card.

In addition to standard application error codes, following codes can be returned:

  • 4430 - UNKNOWN_CARD
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Identifier of the card for which to return the card token.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    }
}

Response samples

Content type
application/json
{
  • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD"
}

Modifies the status of a card.

Modifies the status of the specified card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4438 - CARD_STATUS_UPDATE_NOT_ALLOWED
  • 4439 - CARD_HAS_PENDING_STATUS
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Contains the new status to be set on the card. In case of a blocking action, contains also the block reason.

action
required
string (UpdateCardStatusAction)
Enum: "BLOCK" "UNBLOCK"

Distinguishes the type of the card update.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
cardStatusUpdateReason
required
string (CardStatusUpdateReason)
Enum: "ISSUER_DECISION" "USER_DECISION"

The reason for the status update of the card.

cardBlockReason
string (CardBlockReason)
Enum: "NO_INFORMATION" "CARD_LOST_WITHOUT_PIN" "CARD_STOLEN_WITHOUT_PIN" "FRAUD" "CREDIT_STANDING" "TOO_MANY_INVALID_PIN_ATTEMPTS" "CARD_LOST_WITH_PIN" "CARD_STOLEN_WITH_PIN" "PICK_UP_BM_TM" "CARD_DID_NOT_ARRIVE" "PIN_DID_NOT_ARRIVE" "FRAUD_SUSPECTED_ANALYSIS" "FRAUD_SUSPECTED_CARDHOLDER_FEEDBACK_REQUIRED" "TECHNICAL_REASON" "DEFECTIVE_CARD" "CARD_TEMPORARILY_BLOCKED"

The reason why the card was blocked.

cardBlockOrigin
string (CardBlockOriginViaBank)
Enum: "ONLINE_BANKING_BY_CARDHOLDER" "MOBILE_BANKING_BY_CARDHOLDER" "THREE_DS_CARDMANAGEMENT_APP_BY_CARDHOLDER" "BACKEND_OF_BANK_BY_BANK" "BACKEND_OF_BANK_BY_CARDHOLDER"

Initiator and channel of the card blocking when the card is blocked via the bank.

blockedCardReplacement
string (BlockedCardReplacement)
Enum: "NO_REPLACEMENT" "CARD" "CARD_WITH_PIN_MAILER" "CARD_WITH_PIN_AND_OTRC_MAILER" "CARD_WITH_OTRC_MAILER" "CARD_WITH_UNKNOWN_MAILER"

The need of a card replacement when the card has been blocked.

Responses

Request samples

Content type
application/json
{
  • "action": "BLOCK",
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "cardStatusUpdateReason": "ISSUER_DECISION",
  • "cardBlockReason": "NO_INFORMATION",
  • "cardBlockOrigin": "ONLINE_BANKING_BY_CARDHOLDER",
  • "blockedCardReplacement": "NO_REPLACEMENT"
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

PIN management

Sets and manages the PIN for a card.

Start a PIN set operation.

First call to be able to set the PIN for the specified card. debiX returns an ephemeral public key to encrypt the PIN on the issuer's side for the '/set-pin' call.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4440 - SET_PIN_NOT_ALLOWED_FOR_BLOCKED_OR_DELETED_CARD
  • 4441 - SET_PIN_NOT_ALLOWED_FOR_VIRTUAL_CARD
  • 4442 - PIN_PREVIOUSLY_PASSED_TO_NEWER_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: text/plain
required

Signed request to get debiX's ephemeral public key, it contains a card identifier.

string (StartSetPinRequest)

JSON Web Token signed by the issuer to get an ephemeral public key from debiX for the given cardId.

  • The algorithm of the JWS signature can be one of RS256/384/512, PS256/384/512, ES256/384/512 or EdDsa/Ed25519. ES256 is recommended.
  • The JOSE header must contain a 'x5t#S256' parameter with the X.509 certificate SHA-256 thumbprint of the key used to sign the token. (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8)

Responses

Request samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT",
  "x5t#S256": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEp"
}

Response samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT"
}

Sets the PIN for the specified card.

Sets the PIN for the specified card. The PIN is encrypted with the shared key derived from debiX's ephemeral public key from the '/start-set-pin' request and the issuer's ephemeral private key corresponding to the issuer's ephemeral public key in this request (clientEphPubKey).

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4440 - SET_PIN_NOT_ALLOWED_FOR_BLOCKED_OR_DELETED_CARD
  • 4441 - SET_PIN_NOT_ALLOWED_FOR_VIRTUAL_CARD
  • 4442 - PIN_PREVIOUSLY_PASSED_TO_NEWER_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
  • 4452 - START_SET_PIN_NOT_CALLED
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: text/plain
required

Signed request for the PIN set operation, containing card identifier, encryption parameters and encrypted PIN.

string (SetPinRequest)

JSON Web Token signed by the issuer to set the PIN for the given card.

  • The algorithm of the JWS signature can be one of RS256/384/512, PS256/384/512, ES256/384/512 or EdDsa/Ed25519. ES256 is recommended.
  • The JOSE header must contain a 'x5t#S256' parameter with the X.509 certificate SHA-256 thumbprint of the key used to sign the token. (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8)

Responses

Request samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT",
  "x5t#S256": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEp"
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

Gets the PIN for the specified card.

Get PIN of the specified card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
  • 4458 - RETRIEVE_PIN_NOT_ALLOWED_FOR_DELETED_CARD
  • 4459 - RETRIEVE_PIN_NOT_ALLOWED_FOR_VIRTUAL_CARD
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: text/plain
required

Signed request for the PIN, containing card identifier and encryption parameters.

string (GetPinRequest)

JSON Web Token signed by the issuer, containing all parameters for securely retrieving the PIN.

  • The algorithm of the JWS signature can be one of RS256/384/512, PS256/384/512, ES256/384/512 or EdDsa/Ed25519. ES256 is recommended.
  • The JOSE header must contain a 'x5t#S256' parameter with the X.509 certificate SHA-256 thumbprint of the key used to sign the token. (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8)

Responses

Request samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT",
  "x5t#S256": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEp"
}

Response samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT"
}

Sensitive card data

Retrieves sensitive card data.

Get card credentials.

Get credentials (PAN, CVV) of the specified card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: text/plain
required

Signed request for the credentials, containing card identifier and encryption parameters.

string (CardCredentialsRequest)

JSON Web Token signed by the issuer, containing all parameters for securely retrieving sensitive card credentials.

  • The algorithm of the JWS signature can be one of RS256/384/512, PS256/384/512, ES256/384/512 or EdDsa/Ed25519. ES256 is recommended.
  • The JOSE header must contain a 'x5t#S256' parameter with the X.509 certificate SHA-256 thumbprint of the key used to sign the token. (https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.8)

Responses

Request samples

Content type
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT",
  "x5t#S256": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEp"
}

Response samples

Content type
text/plain
Example
{
  "alg": "none",
  "typ": "JWT"
}

3DS lifecycle

Allows card registrations and deregistrations for 3DS and updates 3DS-related card data.

Registers the card for 3DS.

If a card with the provided card data is not yet registered for 3DS, the registration will take place.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4434 - THREE_DS_NOT_ENABLED_FOR_ISSUER
  • 4435 - CARD_ALREADY_REGISTERED_FOR_THREE_DS
  • 4436 - CARD_INACTIVE
  • 4453 - THREE_DS_OOB_NOT_ENABLED_FOR_ISSUER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card and 3DS-related data.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
required
object (ThreeDsData)

Relevant data to register a card for 3DS with a specific authentication method based on the setup desired by the issuer. Authentication method DELEGATED additionally requires an authId and SMS_ONLY additionally requires a phoneNumber.

userId
string non-empty

Identifier assigned to a particular user by the issuer. Note: userId is a mandatory parameter when registering a card with authentication method PIN, BIOMETRIC or BIOMETRIC_WITH_PIN_FALLBACK.

phoneNumber
string (PhoneNumber) ^([+]|00)[1-9][0-9]{8,18}$

Mobile or landline phone number. Note: phoneNumber is a mandatory parameter which must be provided to register a card with authentication method SMS_ONLY, PIN, BIOMETRIC or BIOMETRIC_WITH_PIN_FALLBACK. Furthermore, phoneNumber must also be provided in case the issuer desires to register a card for DELEGATED as primary authentication method, with additionally SMS as fallback (as secondary authentication method).

language
required
string (Language)
Enum: "DE" "FR" "IT" "EN"

Correspondence language.

authId
string (AuthId) [ 1 .. 36 ] characters

Identifier for the device used for 3DS. Note: authId is a mandatory parameter which must be provided when registering a card with authentication method PIN, BIOMETRIC, BIOMETRIC_WITH_PIN_FALLBACK or DELEGATED.

authenticationMethod
required
string (AuthenticationMethod)
Enum: "PIN" "BIOMETRIC" "BIOMETRIC_WITH_PIN_FALLBACK" "DELEGATED" "SMS_ONLY" "NONE"

User authentication method. For 3DS Out-of-Band (OOB), authentication method DELEGATED must be selected.

biometricType
string (BiometricType)
Enum: "ANDROID_BIOMETRIC" "IOS_BIOMETRIC"

Type of biometric authentication; required for authentication method BIOMETRIC and BIOMETRIC_WITH_PIN_FALLBACK.

pinCode
string (PinCode) non-empty

PIN code used for 3DS authentication; required for authentication method PIN and BIOMETRIC_WITH_PIN_FALLBACK.

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "threeDsData": {
    • "userId": "2345872",
    • "phoneNumber": "+41797778899",
    • "language": "DE",
    • "authId": "480463608",
    • "authenticationMethod": "PIN",
    • "biometricType": "ANDROID_BIOMETRIC",
    • "pinCode": "12345"
    }
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

Updates the 3DS data.

If the request contains new information, the 3DS data will be updated for the given card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4434 - THREE_DS_NOT_ENABLED_FOR_ISSUER
  • 4453 - THREE_DS_OOB_NOT_ENABLED_FOR_ISSUER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card and 3DS-related data.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
required
object (PartialThreeDsData)

Partial data pertaining to a 3DS registration.

userId
string non-empty

Identifier assigned to a particular user by the issuer. Note: userId is a mandatory parameter when registering a card with authentication method PIN, BIOMETRIC or BIOMETRIC_WITH_PIN_FALLBACK.

phoneNumber
string (PhoneNumber) ^([+]|00)[1-9][0-9]{8,18}$

Mobile or landline phone number. Note: phoneNumber is a mandatory parameter which must be provided to register a card with authentication method SMS_ONLY, PIN, BIOMETRIC or BIOMETRIC_WITH_PIN_FALLBACK. Furthermore, phoneNumber must also be provided in case the issuer desires to register a card for DELEGATED as primary authentication method, with additionally SMS as fallback (as secondary authentication method).

language
string (Language)
Enum: "DE" "FR" "IT" "EN"

Correspondence language.

authId
string (AuthId) [ 1 .. 36 ] characters

Identifier for the device used for 3DS. Note: authId is a mandatory parameter which must be provided when registering a card with authentication method PIN, BIOMETRIC, BIOMETRIC_WITH_PIN_FALLBACK or DELEGATED.

authenticationMethod
string (AuthenticationMethod)
Enum: "PIN" "BIOMETRIC" "BIOMETRIC_WITH_PIN_FALLBACK" "DELEGATED" "SMS_ONLY" "NONE"

User authentication method. For 3DS Out-of-Band (OOB), authentication method DELEGATED must be selected.

biometricType
string (BiometricType)
Enum: "ANDROID_BIOMETRIC" "IOS_BIOMETRIC"

Type of biometric authentication; required for authentication method BIOMETRIC and BIOMETRIC_WITH_PIN_FALLBACK.

pinCode
string (PinCode) non-empty

PIN code used for 3DS authentication; required for authentication method PIN and BIOMETRIC_WITH_PIN_FALLBACK.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "threeDsData": {
    • "userId": "2345872",
    • "phoneNumber": "+41797778899",
    • "language": "DE",
    • "authId": "480463608",
    • "authenticationMethod": "PIN",
    • "biometricType": "ANDROID_BIOMETRIC",
    • "pinCode": "12345"
    }
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

Deregisters a card from 3DS and deletes the corresponding data.

If a card with the provided identifier is known to debiX, it will be deregistered from 3DS and the corresponding data deleted.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Identifier of the card to be deregistered from 3DS.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    }
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

3DS details

Retrieves details for 3DS.

Returns the 3DS details for this card.

Returns the details for the current 3DS registration.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4436 - CARD_INACTIVE
  • 4457 - CARD_NOT_REGISTERED_FOR_THREE_DS
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json

Identifier of the card for which to return the 3DS details.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    }
}

Response samples

Content type
application/json
{
  • "phoneNumber": "+41797778899",
  • "language": "DE",
  • "userId": "2345872",
  • "threeDsStatus": "ACTIVE",
  • "threeDsRegistrationDateTime": "2021-10-03T16:03:09.101+02:00",
  • "smsFallback": true,
  • "authenticationMethod": "PIN",
  • "otrcStatus": "DISABLED",
  • "otrcValidity": "2021-10-03T16:03:09.101+02:00"
}

OTRC order

Allows an OTRC to be created and delivered on demand.

Orders an One-Time-Registration-Code (OTRC)

Get a One-Time-Registration-Code (OTRC) for the specified card.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json

Identifier of the card for which the OTRC will be ordered.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    }
}

Response samples

Content type
application/json
{
  • "otrc": 0,
  • "otrcExpirationDateTime": "2024-10-03T16:03:09.101+02:00"
}

Provisioning wallet encryption

Provides encrypted card data for the Wallet In-App provisioning of cards via Thales SDK.

Returns encrypted card data.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its cardId, into a wallet with Thales SDK.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4436 - CARD_INACTIVE
  • 4449 - TOKENIZATION_NOT_SUPPORTED
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card data to encrypt.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
cardholderName
required
string (CardHolderName) [ 2 .. 26 ] characters

The cardholder name as printed on the card.

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "cardholderName": "Peter Meier"
}

Response samples

Content type
application/json
{
  • "encryptedCardData": "string",
  • "primaryAccountIdentifier": "string",
  • "panSuffix": "0123",
  • "publicKeyId": "tshKid"
}

Returns an authorization code.

Returns an authorization code for the provisioning of a funding debit card, specified by its cardId, into a wallet with Thales SDK. The code is valid for five minutes.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4433 - UNKNOWN_WALLET_PROVIDER
  • 4436 - CARD_INACTIVE
  • 4449 - TOKENIZATION_NOT_SUPPORTED
  • 4454 - EXCLUDED_WALLET_PROVIDER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card identifier and wallet for the generation of the authorization code.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
wallet
required
string (WalletProvider)
  • "WALLET"
  • "ECOM"
  • "APPLE_PAY"
  • "SAMSUNG_PAY"
  • "GOOGLE_PAY"
  • "GARMIN_PAY"
  • "FITBIT_PAY"
  • "FACEBOOK"
  • "VISA_CHECKOUT"
  • "NETFLIX"
  • "ASIA_PAY_LIMITED"
  • "CYBERSOURCE"
  • "CHERRI_TECH"
  • "ADYEN"
  • "AMAZON"
  • "MENA_FZ_LLC"
  • "GLOBAL_PYT_AUSTRALIA"
  • "PAYSCOUT"
  • "SAFECHARGE"
  • "SECURECO"
  • "WORLDPAY"
  • "PAYPAL"
  • "BAMBORA_ONLINE"
  • "MYOB"
  • "HUAWEI_PAY"

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "wallet": "APPLE_PAY"
}

Response samples

Content type
application/json
{
  • "authorizationCode": "string"
}

Provisioning C2P encryption

Provides encrypted card data for the provisioning of cards for Click to Pay via Thales SDK.

Returns encrypted card data for click to pay.

Returns the encrypted card data for the provisioning of a funding debit card for click to pay into a wallet with Thales SDK.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4436 - CARD_INACTIVE
  • 4449 - TOKENIZATION_NOT_SUPPORTED
  • 4460 - ECOMMERCE_FEATURE_TOGGLE_NOT_ACTIVATED
  • 4461 - INCOMPLETE_OR_MISSING_ADDRESS_DATA
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card data to encrypt.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
cardholderName
required
string (CardHolderName) [ 2 .. 26 ] characters

The cardholder name as printed on the card.

emailAddress
required
string non-empty

Email address to identify the customer.

phoneNumber
required
string^[0-9]{5,12}$

The phone number without country code.

phoneNumberCountryCode
required
string^[1-9][0-9]{1,3}$

The country code of the phone number.

required
object (ClickToPayCardholderPostalAddress)

Postal address of cardholder as specified by the TSH Token Push and Control specification.

line1
required
string [ 1 .. 64 ] characters

First line of address containing the street and street number.

city
required
string [ 1 .. 32 ] characters

The city of the address.

postalCode
required
string [ 1 .. 10 ] characters

Postal or zip code of the address.

country
required
string = 3 characters

3-letter (alpha-3) country code as defined in ISO 3166-1.

required
object (ClickToPayIssuerClientInformation)
issuerAccountID
string <= 24 characters

This is not the card's PAN. It is required by VISA.

firstName
required
string [ 1 .. 80 ] characters
lastName
required
string [ 1 .. 80 ] characters
locale
string = 5 characters

Language in which to communicate with the customer. This is the ISO639-1 language code followed by "_" separator then ISO 3166-1 alpha-2 country code.

country
string = 2 characters

2-letter (alpha-2) country code as defined in ISO 3166-1.

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "cardholderName": "Peter Meier",
  • "emailAddress": "peter.schweizer@mailbox.org",
  • "phoneNumber": "795625655",
  • "phoneNumberCountryCode": "41",
  • "address": {
    • "line1": "Hardturmstrasse 201",
    • "city": "Zürich",
    • "postalCode": "8005",
    • "country": "CHE"
    },
  • "issuerClientInformation": {
    • "issuerAccountID": "1234567890",
    • "firstName": "Peter",
    • "lastName": "Meier",
    • "locale": "de_CH",
    • "country": "CH"
    }
}

Response samples

Content type
application/json
{
  • "encryptedCardData": "string",
  • "scheme": "MASTERCARD",
  • "publicKeyId": "tshKid",
  • "tokenRequestorId": "40010075338"
}

Checks for existing click-to-pay registrations.

Returns the DPAN associated with the given arguments for click-to-pay. Will return no DPAN if no association exists.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4449 - TOKENIZATION_NOT_SUPPORTED
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Identifier of the card for which to return the registered DPAN.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
emailAddress
required
string (EmailAddress) non-empty

Email address to identify the customer.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "emailAddress": "peter.schweizer@mailbox.org"
}

Response samples

Content type
application/json
{
  • "dpan": "1234567890123456"
}

Returns an authorization code.

Returns an authorization code for the provisioning of a funding debit card, specified by its cardId, into a wallet with Thales SDK. The code is valid for five minutes.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4433 - UNKNOWN_WALLET_PROVIDER
  • 4436 - CARD_INACTIVE
  • 4449 - TOKENIZATION_NOT_SUPPORTED
  • 4454 - EXCLUDED_WALLET_PROVIDER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card identifier and wallet for the generation of the authorization code.

required
object (CardId)

Complex object representing a card consisting of bank clearing number, card number, card type, card sequence number and card expiry.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
required
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (YearMonth)
wallet
required
string (WalletProvider)
  • "WALLET"
  • "ECOM"
  • "APPLE_PAY"
  • "SAMSUNG_PAY"
  • "GOOGLE_PAY"
  • "GARMIN_PAY"
  • "FITBIT_PAY"
  • "FACEBOOK"
  • "VISA_CHECKOUT"
  • "NETFLIX"
  • "ASIA_PAY_LIMITED"
  • "CYBERSOURCE"
  • "CHERRI_TECH"
  • "ADYEN"
  • "AMAZON"
  • "MENA_FZ_LLC"
  • "GLOBAL_PYT_AUSTRALIA"
  • "PAYSCOUT"
  • "SAFECHARGE"
  • "SECURECO"
  • "WORLDPAY"
  • "PAYPAL"
  • "BAMBORA_ONLINE"
  • "MYOB"
  • "HUAWEI_PAY"

Responses

Request samples

Content type
application/json
{
  • "cardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1,
    • "cardSeqNumber": 2,
    • "cardExpiry": {
      }
    },
  • "wallet": "APPLE_PAY"
}

Response samples

Content type
application/json
{
  • "authorizationCode": "string"
}

Token lifecycle management

Retrieves and manages digital cards (tokens) for cards.

Returns a digital card.

Returns the digital card specified by the dpan in the request.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
path Parameters
dpan
required
string (Dpan) = 16 characters
Example: 1234567890123456

Digital card number.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "digitalCardId": "eb404f8d-656b-4e51-8872-88c42fa55536",
  • "dpan": "1234567890123456",
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "scheme": "MASTERCARD",
  • "status": "ACTIVE",
  • "pendingStatus": "RESUMPTION_PENDING",
  • "digitalCardExpiry": {
    • "month": "01",
    • "year": "21"
    },
  • "wallet": "APPLE_PAY",
  • "tokenRequestor": {
    • "id": 1111111111,
    • "name": "Zalando"
    },
  • "productId": "Bank Card Gold",
  • "provisioningDate": "2021-10-03T16:03:09.101+02:00",
  • "deviceType": "IPHONE",
  • "deviceName": "Peter's iPhone",
  • "digitalCardStatusUpdateReason": "ISSUER_DECISION"
}

Returns a list of digital cards.

Returns a list of digital cards using filter arguments.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4433 - UNKNOWN_WALLET_PROVIDER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Filter for the digital card search.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
wallet
string (WalletProvider)
  • "WALLET"
  • "ECOM"
  • "APPLE_PAY"
  • "SAMSUNG_PAY"
  • "GOOGLE_PAY"
  • "GARMIN_PAY"
  • "FITBIT_PAY"
  • "FACEBOOK"
  • "VISA_CHECKOUT"
  • "NETFLIX"
  • "ASIA_PAY_LIMITED"
  • "CYBERSOURCE"
  • "CHERRI_TECH"
  • "ADYEN"
  • "AMAZON"
  • "MENA_FZ_LLC"
  • "GLOBAL_PYT_AUSTRALIA"
  • "PAYSCOUT"
  • "SAFECHARGE"
  • "SECURECO"
  • "WORLDPAY"
  • "PAYPAL"
  • "BAMBORA_ONLINE"
  • "MYOB"
  • "HUAWEI_PAY"
object (TokenRequestor)

Information about the token requestor.

id
string <= 11 characters

The id of the token requestor.

name
string <= 64 characters

The name of the token requestor.

object (YearMonthRange)

Year-month range lower and upper bounds (both inclusive).

object (YearMonth)
object (YearMonth)
object (DateTimeRange)

Date-time range lower and upper bounds (both inclusive).

from
string <date-time>

Date-time lower bound (inclusive).

to
string <date-time>

Date-time upper bound (inclusive).

status
string (DigitalCardStatus)
Enum: "ACTIVE" "SUSPENDED" "DELETED"

The status of the digital card.

object (Paging)

Contains paging properties.

pageNumber
integer <int32>
Default: 0

Page number for paging starting with zero.

pageSize
integer <int32> [ 20 .. 100 ]
Default: 100

Limitation of the page size.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "wallet": "APPLE_PAY",
  • "tokenRequestor": {
    • "id": 1111111111,
    • "name": "Zalando"
    },
  • "digitalCardExpiryRange": {
    • "from": {
      },
    • "to": {
      }
    },
  • "provisioningDateTimeRange": {
    • "from": "2022-01-01T00:00:00.000+02.00",
    • "to": "2022-12-31T23:59:59.999+02.00"
    },
  • "status": "ACTIVE",
  • "paging": {
    • "pageNumber": 0,
    • "pageSize": 50
    }
}

Response samples

Content type
application/json
{
  • "digitalCards": [
    • {
      }
    ],
  • "totalRecords": 1021
}

Updates the status of digital cards of a card.

Updates the status of the digital cards of a funding debit card, specified by its shortCardId. The status update is triggered only for those digital cards which can be updated.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4431 - DIGITAL_CARD_STATUS_UPDATE_NOT_ALLOWED
  • 4437 - DIGITAL_CARD_HAS_PENDING_STATUS
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Update request for the status of digital cards of a card.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
status
required
string (DigitalCardStatus)
Enum: "ACTIVE" "SUSPENDED" "DELETED"

The status of the digital card.

digitalCardStatusUpdateReason
string (DigitalCardStatusUpdateReason)
Enum: "ISSUER_DECISION" "USER_DECISION"

The reason for the status update of the digital card.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "status": "ACTIVE",
  • "digitalCardStatusUpdateReason": "ISSUER_DECISION"
}

Response samples

Content type
application/json
{
  • "commissionedDigitalCards": [
    • "1234567890123456"
    ],
  • "rejectedDigitalCards": [
    • {
      }
    ]
}

Updates the status of a digital card.

Triggers the status update of the digital card specified by the dpan in the request.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4431 - DIGITAL_CARD_STATUS_UPDATE_NOT_ALLOWED
  • 4437 - DIGITAL_CARD_HAS_PENDING_STATUS
path Parameters
dpan
required
string (Dpan) = 16 characters
Example: 1234567890123456

Digital card number.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Update request for the status of the digital card.

status
required
string (DigitalCardStatus)
Enum: "ACTIVE" "SUSPENDED" "DELETED"

The status of the digital card.

digitalCardStatusUpdateReason
string (DigitalCardStatusUpdateReason)
Enum: "ISSUER_DECISION" "USER_DECISION"

The reason for the status update of the digital card.

Responses

Request samples

Content type
application/json
{
  • "status": "ACTIVE",
  • "digitalCardStatusUpdateReason": "ISSUER_DECISION"
}

Response samples

Content type
application/json
{
  • "applicationError": "OPERATION_FAILED",
  • "errorCode": 5001,
  • "description": "The requested operation failed.",
  • "errors": [
    • {
      }
    ],
  • "errorToken": "618503aa-7beb-4d3d-986e-36f1fdbd0e13"
}

Transaction list

Retrieves not expired transactions for cards and digital cards.

Returns a list of authorizations.

Returns a list of authorizations using filter arguments. The list is ordered by transaction date from newest to oldest.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4456 - UNKNOWN_WALLET_TYPE
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Filter arguments for the authorizations search.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

object (YearMonth)
month
required
string

The two digit number of the month starting at 01 for January.

year
required
string

The last two digits of the year.

walletType
string (WalletType) <= 1 characters
  • "A": Apple Pay
  • "F": Fitbit
  • "G": G&D Wallet ErsteBank
  • "I": Raipay
  • "L": LAKS/Disiseq
  • "M": Merchant Tokenization
  • "O": Google Pay
  • "P": PSA-Wallet
  • "R": Garmin/Fitpay
  • "S": Samsung Pay
  • "T": Tappy
  • "W": Fidesmo
  • "X": Xiaomi
  • "Z": Zepp1
  • "?": Unknown Wallet Type
onlyDigitalCardBased
boolean
Default: true

Determines if only digital card based authorizations should be returned.

object (DateRange)

Date range lower and upper bounds (both inclusive).

from
string <date>

Start date (inclusive).

to
string <date>

End date (inclusive).

object (Paging)

Contains paging properties.

pageNumber
integer <int32>
Default: 0

Page number for paging starting with zero.

pageSize
integer <int32> [ 20 .. 100 ]
Default: 100

Limitation of the page size.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "cardSeqNumber": 2,
  • "cardExpiry": {
    • "month": "01",
    • "year": "21"
    },
  • "walletType": "A",
  • "onlyDigitalCardBased": true,
  • "transactionDateRange": {
    • "from": "2024-01-01",
    • "to": "2024-12-31"
    },
  • "paging": {
    • "pageNumber": 0,
    • "pageSize": 50
    }
}

Response samples

Content type
application/json
{
  • "authorizations": [
    • {
      }
    ],
  • "totalRecords": 1021
}

Returns a list of authorizations for a digital card.

Returns a list of authorizations for a digital card, specified by the dpan, using filter arguments. The list is ordered by transaction date from newest to oldest.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
path Parameters
dpan
required
string (Dpan) = 16 characters
Example: 1234567890123456

Digital card number.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json

Filter arguments for the authorizations search.

object (DateRange)

Date range lower and upper bounds (both inclusive).

from
string <date>

Start date (inclusive).

to
string <date>

End date (inclusive).

object (Paging)

Contains paging properties.

pageNumber
integer <int32>
Default: 0

Page number for paging starting with zero.

pageSize
integer <int32> [ 20 .. 100 ]
Default: 100

Limitation of the page size.

Responses

Request samples

Content type
application/json
{
  • "transactionDateRange": {
    • "from": "2024-01-01",
    • "to": "2024-12-31"
    },
  • "paging": {
    • "pageNumber": 0,
    • "pageSize": 50
    }
}

Response samples

Content type
application/json
{
  • "authorizations": [
    • {
      }
    ],
  • "totalRecords": 1021
}

Returns a list of presentments

Returns a list of presentments using filter arguments. The list is ordered by transaction date from newest to oldest.

In addition to standard application error codes, the following codes can be returned:

  • 4430 - UNKNOWN_CARD
  • 4432 - BANK_CLEARING_NUMBER_NOT_CONFIGURED
  • 4456 - UNKNOWN_WALLET_TYPE
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Filter arguments for the presentment search.

required
object (ShortCardId)

Complex object representing a card consisting of bank clearing number, card number and card type.

bankClearingNumber
required
integer <int32> (BankClearingNumber) [ 100 .. 99999 ]

Unique number used to identify each bank agency or branch in the bank directory.

cardNumber
required
integer <int32> (CardNumber) [ 1 .. 99999999 ]

Card number of the card.

cardType
required
integer <int32> (CardType) [ 1 .. 3 ]

A single digit that distinguishes the card types of the schemes.

  • 1: Debit mastercard
  • 3: Visa debit
cardSeqNumber
integer <int32> (CardSeqNumber) [ 0 .. 9 ]

Sequence number of the card.

object (YearMonth)
month
required
string

The two digit number of the month starting at 01 for January.

year
required
string

The last two digits of the year.

walletType
string (WalletType) <= 1 characters
  • "A": Apple Pay
  • "F": Fitbit
  • "G": G&D Wallet ErsteBank
  • "I": Raipay
  • "L": LAKS/Disiseq
  • "M": Merchant Tokenization
  • "O": Google Pay
  • "P": PSA-Wallet
  • "R": Garmin/Fitpay
  • "S": Samsung Pay
  • "T": Tappy
  • "W": Fidesmo
  • "X": Xiaomi
  • "Z": Zepp1
  • "?": Unknown Wallet Type
object (DateRange)

Date range lower and upper bounds (both inclusive).

from
string <date>

Start date (inclusive).

to
string <date>

End date (inclusive).

object (Paging)

Contains paging properties.

pageNumber
integer <int32>
Default: 0

Page number for paging starting with zero.

pageSize
integer <int32> [ 20 .. 100 ]
Default: 100

Limitation of the page size.

Responses

Request samples

Content type
application/json
{
  • "shortCardId": {
    • "bankClearingNumber": 50000,
    • "cardNumber": 12345678,
    • "cardType": 1
    },
  • "cardSeqNumber": 2,
  • "cardExpiry": {
    • "month": "01",
    • "year": "21"
    },
  • "walletType": "A",
  • "transactionDateRange": {
    • "from": "2024-01-01",
    • "to": "2024-12-31"
    },
  • "paging": {
    • "pageNumber": 0,
    • "pageSize": 50
    }
}

Response samples

Content type
application/json
{
  • "presentments": [
    • {
      }
    ],
  • "totalRecords": 1021
}

Beta

Feature under development, subject to change.