Skip to main content
API docs by Redocly

debiX API (2.25.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 or physical 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)
contactlessActivationStatus ACTIVATED_CONFIRMED

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
  • 4462: DELIVERY_INFORMATION_FOR_CARD_OR_PIN_MISSING
  • 4463: CARD_EXPRESS_CODE_MISSING
  • 4464: PIN_EXPRESS_CODE_MISSING
  • 4465: PRODUCER_CODE_MISSING
  • 4466: CARDLINE1_MISSING
  • 4469: PIN_DELIVERY_NOT_ALLOWED_FOR_VIRTUAL_CARD
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. EMV-Profile must be set for a physical card order.

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.

chipApplication
string (ChipApplication)
Enum: "EMVI20" "EMVI24"

Indicates what chip will be applied to the card. If no chipApplication is provided, EMVI20 will be applied in the order.

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.

cardDelivery
string (DatamailerDeliveryDestination)
Enum: "DELIVER_TO_BANK" "DELIVER_TO_CARDHOLDER"

The destination of the card delivery. Must be set for a physical card order.

cardExpressCode
string (CardExpressCode)
Enum: "A_POST" "B_POST" "REGISTERED" "COURIER"

Defines the express code of the card delivery. Must be set for a physical card order and CardDelivery is DELIVER_TO_CARDHOLDER.

subCardType
string (SubCardType) = 2 characters

Sub card type that is linked to a dedicated BIN range and specifies a product like 'Platinum', 'EUR' or 'Student'. It must be configured in bank master data, otherwise field can not be used.

required
object (OnlineLimits)

The monthly and daily retail and cash transactions limits.

object (FeatureToggles)

Contains the values of the feature toggles for the card. In card order requests, the contactlessActivationStatus will be ignored.

cardPlasticCode
required
string (CardPlasticCode) = 2 characters

Plastic code of the card.

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

Delivery type of OTRC. Only used for virtual cards.

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

Delivery destination of OTRC datamailer. Only used for virtual cards.

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

Defines the express code of the OTRC datamailer delivery. Must only be set for a virtual card.

object (DeliveryInformation)

Delivery address of card, PIN and OTRC; only required when OTRC, PIN, or card is delivered to cardholder.

pinDatamailerDelivery
string (DatamailerDeliveryDestination)
Enum: "DELIVER_TO_BANK" "DELIVER_TO_CARDHOLDER"

Delivery destination of the PIN. Only used for physical cards.

pinDatamailerExpressCode
string (DatamailerExpressCode)
Enum: "A_POST" "B_POST" "REGISTERED"

The quickness of the PIN delivery. Must be set for a physical card order.

producerCode
string (ProducerCode)
Enum: "THALES" "EXCEET_GERMANY" "EXCEET_SWITZERLAND" "NID"

Defines the producer of the ordered card. Must only be set for a physical card order.

producerInfo
string (ProducerInfo)

Information for the producer of the card. E.g. to print the EUR-label on the card.

object (EmvProfile)

Information about the EMV-Profile. Must be set for a physical card order.

cardholderDataTrack
string (CardholderDataTrack) [ 2 .. 26 ] characters

A formatted combination of family name, name and title. Must only be set for a Mastercard physical card order. Valid formats include:

  • FAMILYNAME/
  • FAMILYNAME/NAME
  • FAMILYNAME/NAME.DR
  • FAMILYNAME/.DR
cardLine1
string (CardLine)

This line will be printed on the front side of the card. At least the first card line is required for a physical card order.

cardLine2
string (CardLine)

This line will be printed on the front side of the card. At least the first card line is required for a physical card order.

object (ParentCardReference)

Reference to a card from which settings can be inherited.

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

required
object (CardTokenExtension)

Extension to card token to identify a card.

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). For issuers with special regulations (e.g. PSD2), please refer to the additional indications provided under the “password” field.

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

isBlocked
boolean

Defines if the card is ordered blocked.

Responses

Request samples

Content type
application/json
{
  • "cardOrderData": {
    • "cardId": {
      },
    • "accountNumber": "AB-4567890123456",
    • "iban": "CH3456789012345678901",
    • "cardMaterial": "PHYSICAL",
    • "language": "DE",
    • "chipApplication": "EMVI20",
    • "branchNumber": 1,
    • "transactionAuthorizer": "ALWAYS_SIX",
    • "cardDelivery": "DELIVER_TO_BANK",
    • "cardExpressCode": "A_POST",
    • "subCardType": "A1",
    • "onlineLimits": {
      },
    • "featureToggles": {
      },
    • "cardPlasticCode": "F0",
    • "otrcDelivery": "NONE",
    • "otrcDatamailerDelivery": "DELIVER_TO_BANK",
    • "otrcDatamailerExpressCode": "A_POST",
    • "deliveryInformation": {
      },
    • "pinDatamailerDelivery": "DELIVER_TO_BANK",
    • "pinDatamailerExpressCode": "A_POST",
    • "producerCode": "THALES",
    • "producerInfo": "string",
    • "emvProfile": {
      },
    • "cardholderDataTrack": "SCHWEIZER/PETER",
    • "cardLine1": "string",
    • "cardLine2": "string"
    },
  • "parentCardReference": {
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "cardTokenExtension": {
      },
    • "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": [
      ]
    },
  • "isBlocked": false
}

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's details.

Returns the status and the details of the given card.

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

  • 4430 - UNKNOWN_CARD
  • 4447 - NO_CARD_DETAILS_AVAILABLE
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    }
}

Response samples

Content type
application/json
{
  • "aliasId": "e336c8c8-2945-4be3-af3e-951ec2d01219",
  • "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",
    • "markedAsDelayedDelete": true,
    • "transactionAuthorizer": "ALWAYS_SIX",
    • "cardOrderDateTime": "2024-04-13T08:30:00Z"
    },
  • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
  • "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",
    • "contactlessActivationStatus": "UNKNOWN"
    },
  • "onlineLimits": {
    • "totalLimitPerMonth": 20000,
    • "cashLimitPerMonth": 10000,
    • "totalLimitPerDay": 5000,
    • "cashLimitPerDay": 1000
    },
  • "threeDsInformation": {
    • "paymentAuthenticationMethods": {
      },
    • "mobilePhoneNumber": "+41797778899"
    }
}

Modifies the data of a card.

Allows the modification of certain data fields belonging to a card.

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

  • 4430 - UNKNOWN_CARD
  • 4436 - CARD_INACTIVE
  • 4447 - NO_CARD_DETAILS_AVAILABLE
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Fields to modify. Not all fields are mandatory.

required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

object (CardMutationBccData)

Information about the cardholder to mutate.

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
required
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). For issuers with special regulations (e.g. PSD2), please refer to the additional indications provided under the “password” field.

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 (CardMutationFraudConfiguration)

Controls the fraud configuration of a card.

restrictedRegions
required
Array of strings (RestrictedRegions) [ 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 (RestrictedCountries) [ 1 .. 300 ] items [ items[A-Z]{2} ]

A list of countries from which authorizations will be declined.

object (CardMutationCardApplication)

Controls card application settings for the EMV-Profile, online limits and transaction authorizer.

object (EmvProfile)

Information about the EMV-Profile. Must be set for a physical card order.

object (OnlineLimits)

The monthly and daily retail and cash transactions limits.

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

contactlessActivationStatus
boolean (CardMutationContactlessActivationStatus)

Controls whether contactless is enabled.

object (CardMutationFeatureToggles)

Feature Toggles to mutate.

eCommerceAllowed
boolean

Indicates if the use of ecommerce is allowed.

trxOnlyAsChipAndPin
boolean

Indicates if cvm is active, i.e. card can do transaction only as Chip and PIN.

magStripePaymentAllowed
boolean

Defines if magnetic stripe payments are allowed.

automaticBilling
boolean

Indicates if the cardholder participates to the automatic billing update.

purchaseWithCashBackAllowed
boolean

Defines if purchase with cash back is allowed.

blockedMerchantCategoryCodes
Array of integers <int32> (MerchantCategoryCode) [ 1 .. 10 ] items [ items <int32 > [ 0 .. 9999 ] ]

List of blocked merchant category codes.

merchantInitiatedTrxAllowed
boolean

Indicates if merchant initiated transactions - such as Recurring, Installment, Unscheduled - are allowed.

atmAllowed
boolean

Defines if withdrawals are allowed at ATMs.

posAllowed
boolean

Defines if payments are allowed at POS terminals.

motoAllowed
boolean

Defines if mail or phone orders are allowed.

bypassGeoblocking
boolean

Defines if geo blocking is ignored for the card.

moneySendReceiveAllowance
string (MoneySendReceiveAllowance)
Enum: "NOT_ALLOWED" "RECEIVE_ALLOWED" "SEND_ALLOWED" "RECEIVE_AND_SEND_ALLOWED"

Defines conditions if money send to and receive from another cardholder is allowed.

reservationAllowed
boolean

Defines if reservation transactions are allowed.

transactionPushEnabled
boolean

Defines if transactions are pushed to debiX.

gamblingAndBettingAllowance
string (GamblingAndBettingAllowance)
Enum: "ALLOWED" "NOT_ALLOWED" "CARD_NOT_PRESENT_NOT_ALLOWED" "CARD_PRESENT_NOT_ALLOWED"

Defines condition when gambling and betting transactions are allowed.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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": [
      ]
    },
  • "cardApplication": {
    • "emvProfile": {
      },
    • "onlineLimits": {
      },
    • "transactionAuthorizer": "ALWAYS_SIX"
    },
  • "contactlessActivationStatus": true,
  • "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"
    }
}

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

Returns the card identifier.

Returns the card identifier, i.e. short card id, of the given card.

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

  • 4430 - UNKNOWN_CARD
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

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

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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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" "DELETE_IMMEDIATELY" "DELETE_AT_END_OF_NEXT_MONTH"

Distinguishes the type of the card update.

required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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. Note: cardBlockReason is a mandatory parameter which must be provided when action = BLOCK.

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"

Indicates the need of a card replacement when the card has been blocked. This is only an indicator and does not trigger the actual card replacement.

Responses

Request samples

Content type
application/json
{
  • "action": "BLOCK",
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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.

Starts 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
  • 4442 - PIN_PREVIOUSLY_PASSED_TO_NEWER_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 card identifiers.

string (StartSetPinRequest)

JSON Web Token signed by the issuer to get an ephemeral public key from debiX 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
text/plain
Example
{
  "alg": "ES256 (example)",
  "typ": "JWT"
}

Sets the PIN for the given card.

Sets the PIN for the given 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
  • 4442 - PIN_PREVIOUSLY_PASSED_TO_NEWER_CARD
  • 4450 - NO_CERTIFICATE_FOUND
  • 4451 - INVALID_JWS_SIGNATURE
  • 4452 - START_SET_PIN_NOT_CALLED
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 identifiers, 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 given card.

Get PIN of the given 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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

Orders a PIN datamailer for the specified card.

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

  • 4430 - UNKNOWN_CARD
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Details of the PIN datamailer order.

required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

deliveryDestination
required
string (DatamailerDeliveryDestination)
Enum: "DELIVER_TO_BANK" "DELIVER_TO_CARDHOLDER"

Delivery destination of PIN.

expressCode
required
string (DatamailerExpressCode)
Enum: "A_POST" "B_POST" "REGISTERED"

The quickness of the PIN delivery.

object (DeliveryInformation)

The delivery information must be set if the PIN is delivered to the cardholder.

address
required
Array of strings (UnstructuredAddress) [ 1 .. 6 ] items [ items <= 35 characters ]

Unstructured address of simple address lines.

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

Country code in format ISO 3166-1 alpha 2.

salutationText
string <= 50 characters

Salutation text for the delivery.

mailerText
integer <int32>

Selects the individual text container for printing onto the datamailer. Can be set if the PIN is delivered to the cardholder.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "deliveryDestination": "DELIVER_TO_BANK",
  • "expressCode": "A_POST",
  • "deliveryInformation": {
    • "address": [
      ],
    • "country": "CH",
    • "salutationText": "string"
    },
  • "mailerText": 0
}

Response samples

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

Sensitive card data

Retrieves sensitive card data.

Gets 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 identifiers 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
  • 4467 - THREE_DS_PASSWORD_NOT_ALLOWED
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Card identifier and 3DS-related data.

required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (ThreeDsData)

Relevant data to register a card for 3DS with a specific authentication method based on the setup desired by the issuer (i.e. for 3DS via SIX SDK or 3DS OOB).

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). For issuers with special regulations (e.g. PSD2), please refer to the additional indications provided under the “password” field.

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.

password
string (Password) non-empty

This parameter must be used exclusively by issuers with special regulations (e.g., PSD2). It must be provided if the issuer intends to register a card for 3DS with SMS as secondary authentication method (i.e. SMS as fallback) or if the issuer intends to register a card with SMS_ONLY as primary and unique authentication method. In these cases, the phoneNumber field must also be provided.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "threeDsData": {
    • "userId": "2345872",
    • "phoneNumber": "+41797778899",
    • "language": "DE",
    • "authId": "480463608",
    • "authenticationMethod": "PIN",
    • "biometricType": "ANDROID_BIOMETRIC",
    • "pinCode": "12345",
    • "password": "password"
    }
}

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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Contains 3DS-related data.

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). For issuers with special regulations (e.g. PSD2), please refer to the additional indications provided under the “password” field.

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.

password
string (Password) non-empty

This parameter must be used exclusively by issuers with special regulations (e.g., PSD2). It must be provided if the issuer intends to register a card for 3DS with SMS as secondary authentication method (i.e. SMS as fallback) or if the issuer intends to register a card with SMS_ONLY as primary and unique authentication method. In these cases, the phoneNumber field must also be provided.

Responses

Request samples

Content type
application/json
{
  • "threeDsData": {
    • "userId": "2345872",
    • "phoneNumber": "+41797778899",
    • "language": "DE",
    • "authId": "480463608",
    • "authenticationMethod": "PIN",
    • "biometricType": "ANDROID_BIOMETRIC",
    • "pinCode": "12345",
    • "password": "password"
    }
}

Response samples

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

Deregisters the given 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

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 the given 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    }
}

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 an online One-Time-Registration-Code (OTRC) for the given card.

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

  • 4430 - UNKNOWN_CARD
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

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

Orders an One-Time-Registration-Code (OTRC) via datamailer.

Get a datamailer with the 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json

Details of the OTRC datamailer.

delivery
required
string (DatamailerDeliveryDestination)
Enum: "DELIVER_TO_BANK" "DELIVER_TO_CARDHOLDER"

Delivery destination of the OTRC datamailer.

expressCode
required
string (DatamailerExpressCode)
Enum: "A_POST" "B_POST" "REGISTERED"

Defines the express code of the OTRC datamailer delivery.

object (DeliveryInformation)

Delivery information for the OTRC datamailer.

address
required
Array of strings (UnstructuredAddress) [ 1 .. 6 ] items [ items <= 35 characters ]

Unstructured address of simple address lines.

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

Country code in format ISO 3166-1 alpha 2.

salutationText
string <= 50 characters

Salutation text for the delivery.

mailerText
integer <int32>

Selects the individual text container for printing onto the datamailer.

Responses

Request samples

Content type
application/json
{
  • "delivery": "DELIVER_TO_BANK",
  • "expressCode": "A_POST",
  • "deliveryInformation": {
    • "address": [
      ],
    • "country": "CH",
    • "salutationText": "string"
    },
  • "mailerText": 0
}

Response samples

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

Provisioning wallet encryption for scheme push provisioning (Beta)

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

Get data for push provisioning of the given card to a Apple Pay wallet.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its card token, into an Apple Pay wallet.

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
  • 4454 - EXCLUDED_WALLET_PROVIDER
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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

The cardholder name as printed on the card.

nonce
required
string

Nonce, passed back in the response.

nonceSignature
required
string

Nonce signature, passed back in the response.

applePublicCertificates
required
Array of strings

Apple's certificates to be used in the Diffie-Hellman key exchange. Base64 encoded DER certificate chain.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "cardholderName": "Peter Meier",
  • "nonce": "string",
  • "nonceSignature": "string",
  • "applePublicCertificates": [
    • "string"
    ]
}

Response samples

Content type
application/json
{
  • "activationData": "for Mastercard see '#/components/schemas/MastercardTokenizationAuthenticationValue'",
  • "ephemeralPublicKey": "string",
  • "encryptedData": "see '#/components/schemas/ApplePayCardCredentials'"
}

Get data for Mastercard push provisioning of the given card to a Google Pay wallet.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its card token, into a Google Pay wallet.

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
  • 4454 - EXCLUDED_WALLET_PROVIDER
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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

The cardholder name as printed on the card.

clientWalletAccountId
required
string

The active wallet id of the current Google Pay wallet. Client-provided consumer ID that identifies the wallet account holder entity.

clientDeviceId
required
string

Stable device identification set by wallet provider. Could be a computer identifier or ID tied to hardware such as TEE_ID or SE_ID.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "cardholderName": "Peter Meier",
  • "clientWalletAccountId": "string",
  • "clientDeviceId": "string"
}

Response samples

Content type
application/json
{
  • "base64GooglePayOpaquePaymentCard": "for Mastercard see '#/components/schemas/MastercardGooglePayOpaquePaymentCard'"
}

Get data for push provisioning of the given card to a Samsung Pay wallet.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its card token, into a Samsung Pay wallet.

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
  • 4454 - EXCLUDED_WALLET_PROVIDER
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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

The cardholder name as printed on the card.

clientWalletAccountId
required
string

The active wallet id of the current Samsung Pay wallet. Client-provided consumer ID that identifies the wallet account holder entity.

clientDeviceId
required
string

Stable device identification set by wallet provider. Could be a computer identifier or ID tied to hardware such as TEE_ID or SE_ID.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "cardholderName": "Peter Meier",
  • "clientWalletAccountId": "string",
  • "clientDeviceId": "string"
}

Response samples

Content type
application/json
{
  • "base64SamsungPayOpaquePaymentCard": "for Mastercard see '#/components/schemas/MastercardGooglePayOpaquePaymentCard'"
}

Provisioning wallet encryption

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

Returns encrypted card data.

Deprecated, use one of POST /cards/{cardToken}/apple-pay/provisioning-data, POST /cards/{cardToken}/google-pay/provisioning-data, POST /cards/{cardToken}/samsung-pay/provisioning-data instead.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its card token, 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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

The cardholder name as printed on the card.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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 card token, into a wallet with Thales SDK. The code is valid for 20 seconds in the production environment and 60 seconds in test environment.

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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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]{0,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
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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 card and email address 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Email address for which to return the registered DPAN.

emailAddress
required
string (EmailAddress) non-empty

Email address to identify the customer.

Responses

Request samples

Content type
application/json
{
  • "emailAddress": "peter.schweizer@mailbox.org"
}

Response samples

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

Returns an authorization code.

Returns an authorization code for the provisioning of a funding debit card, specified by its card token, into a wallet with Thales SDK. The code is valid for 20 seconds in the production environment and 60 seconds in test environment.

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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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 ^[4,5][0-9]{15}$
Examples: 4234567890123456

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": "4234567890123456",
  • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
  • "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 for the given card using filter arguments.

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

  • 4430 - UNKNOWN_CARD
  • 4433 - UNKNOWN_WALLET_PROVIDER
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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.

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
{
  • "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 card token. 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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.

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

The status of the digital card.

digitalCardStatusUpdateReason
required
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
{
  • "commissionedDigitalCards": [
    • "4234567890123456"
    ],
  • "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 ^[4,5][0-9]{15}$
Examples: 4234567890123456

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
required
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 of the last 120 days for cards and digital cards.

Returns a list of authorizations.

Returns a list of authorizations for the given card using filter arguments; only the authorizations of the last 120 days are available. 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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.

object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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
{
  • "cardTokenEntension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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; only the authorizations of the last 120 days are available. 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 ^[4,5][0-9]{15}$
Examples: 4234567890123456

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 for the given card using filter arguments; only the presentments of the last 120 days are available. 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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.

object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "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
}

Visa Alias Directory (Beta)

Visa Alias Directory related operations. Feature under development, subject to change.

Creates an alias in the Alias Directory.

Creates an alias in the Alias Directory and associates the specified cards with the alias.

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

  • 4430 - UNKNOWN_CARD
  • 4521 - ALIAS_ALREADY_EXISTS
  • 4523 - VISA_ALIAS_DIRECTORY_INVALID_CARD_EXPIRATION
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
Request Body schema: application/json
aliasType
required
string (VisaADAliasType)
Enum: "PHONE" "EMAIL"

The type of alias provided in aliasValue.

aliasValue
required
string (VisaADAliasValue) [ 1 .. 128 ] characters

The value of the alias, e.g., phone number or email address. If phone number is used for alias, this should be provided in accordance with ITU-T E.164 (2010) number structure. Please note that in the E.164 format, the "+" prefix or leading zeros are not included.

required
object (VisaADConsent)

Consent details.

presenter
required
string

Identifies the presenter of consent to the consumer.

validFromDateTime
required
string <date-time>

Date and time from which on the consent is valid, in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z. Only accepts present and past dates.

version
required
string [ 1 .. 9 ] characters

Specific version of the terms and conditions that the customer accepts for the user solution.

required
object (VisaADProfile)

Profile details for the customer that owns the alias.

lastName
required
string [ 1 .. 35 ] characters

Last name in English. Clients in CEMEA and the EU must use only one first letter of customer’s last name followed by dot symbol to create or modify an Alias record. For example, Alias record for customer John Smith should be created or modified by the issuer with First and Last name fields as 'John S.'

ISO20022 element name: Creditor -> Name

firstName
required
string [ 1 .. 35 ] characters

First name in English

ISO20022 element name: Creditor -> Name

middleName
string [ 1 .. 35 ] characters

Middle name in English

Array of objects [ 1 .. 2 ] items

Contact information.

dateOfBirth
string (VisaADDateOfBirth) = 10 characters ^\d\d\d\d\-\d\d\-\d\d$
lastNameLocal
string [ 1 .. 35 ] characters

Last name in local language. Clients in CEMEA and the EU must use only one first letter of customer’s last name followed by dot symbol to create or modify an Alias record. For example, Alias record for customer John Smith should be created or modified by the issuer with First and Last name fields as 'John S.'

preferredName
string

Preferred name (or the 'known-as' name).

firstNameLocal
string [ 1 .. 35 ] characters

First name in local language.

middleNameLocal
string [ 1 .. 35 ] characters

Middle name in local language.

required
Array of objects (VisaADCard) [ 1 .. 10 ] items
Array ([ 1 .. 10 ] items)
nameOnCard
required
string (VisaADNameOnCard) [ 1 .. 120 ] characters

The name which is printed on the card.

cardType
string (VisaADCardType) [ 1 .. 70 ] characters

Card type description. Reference to Field 62.23—Product ID of available card products.

required
object (VisaADBillingAddress)
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

preferredFor
Array of strings (VisaADPreferredFor) [ 1 .. 3 ] items
Items Enum: "RECEIVE" "SEND" "PAY"

Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Receiving allows for funds to be pushed into the payment credential. Sending allows for funds to be sent from the payment credential. Paying allows for the payment credential to be used for purchases. More than one preferred type can be used.

Responses

Request samples

Content type
application/json
{
  • "aliasType": "PHONE",
  • "aliasValue": "41791112233",
  • "consent": {
    • "presenter": "Bank A",
    • "validFromDateTime": "2021-12-01T10:00:00Z",
    • "version": "1.0"
    },
  • "profile": {
    • "lastName": "R.",
    • "firstName": "Hans",
    • "middleName": "Ruedi",
    • "contactInfo": [
      ],
    • "dateOfBirth": "1947-02-01",
    • "lastNameLocal": "R.",
    • "preferredName": "Hansruedi",
    • "firstNameLocal": "Hans",
    • "middleNameLocal": "Ruedi"
    },
  • "cards": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "aliasId": "e336c8c8-2945-4be3-af3e-951ec2d01219"
}

Retrieves an alias from the Alias Directory.

Retrieves information about a specific alias.

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

  • 4520 - UNKNOWN_ALIAS
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "aliasValue": "41791112233",
  • "consent": {
    • "presenter": "Bank A",
    • "validFromDateTime": "2021-12-01T10:00:00Z",
    • "version": "1.0"
    },
  • "profile": {
    • "lastName": "R.",
    • "firstName": "Hans",
    • "middleName": "Ruedi",
    • "contactInfo": [
      ],
    • "dateOfBirth": "1947-02-01",
    • "lastNameLocal": "R.",
    • "preferredName": "Hansruedi",
    • "firstNameLocal": "Hans",
    • "middleNameLocal": "Ruedi"
    },
  • "aliasType": "PHONE",
  • "aliasStatus": "ACTIVE"
}

Updates an alias in the Alias Directory.

Updates the information associated with the alias such as the identification, profile, or consent.

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

  • 4520 - UNKNOWN_ALIAS
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
object (VisaADConsent)

Consent details.

presenter
required
string

Identifies the presenter of consent to the consumer.

validFromDateTime
required
string <date-time>

Date and time from which on the consent is valid, in ISO UTC format YYYY-MM-DDThh:mm:ss.000Z. Only accepts present and past dates.

version
required
string [ 1 .. 9 ] characters

Specific version of the terms and conditions that the customer accepts for the user solution.

required
object (VisaADProfile)

Profile details for the customer that owns the alias.

lastName
required
string [ 1 .. 35 ] characters

Last name in English. Clients in CEMEA and the EU must use only one first letter of customer’s last name followed by dot symbol to create or modify an Alias record. For example, Alias record for customer John Smith should be created or modified by the issuer with First and Last name fields as 'John S.'

ISO20022 element name: Creditor -> Name

firstName
required
string [ 1 .. 35 ] characters

First name in English

ISO20022 element name: Creditor -> Name

middleName
string [ 1 .. 35 ] characters

Middle name in English

Array of objects [ 1 .. 2 ] items

Contact information.

dateOfBirth
string (VisaADDateOfBirth) = 10 characters ^\d\d\d\d\-\d\d\-\d\d$
lastNameLocal
string [ 1 .. 35 ] characters

Last name in local language. Clients in CEMEA and the EU must use only one first letter of customer’s last name followed by dot symbol to create or modify an Alias record. For example, Alias record for customer John Smith should be created or modified by the issuer with First and Last name fields as 'John S.'

preferredName
string

Preferred name (or the 'known-as' name).

firstNameLocal
string [ 1 .. 35 ] characters

First name in local language.

middleNameLocal
string [ 1 .. 35 ] characters

Middle name in local language.

Responses

Request samples

Content type
application/json
{
  • "consent": {
    • "presenter": "Bank A",
    • "validFromDateTime": "2021-12-01T10:00:00Z",
    • "version": "1.0"
    },
  • "profile": {
    • "lastName": "R.",
    • "firstName": "Hans",
    • "middleName": "Ruedi",
    • "contactInfo": [
      ],
    • "dateOfBirth": "1947-02-01",
    • "lastNameLocal": "R.",
    • "preferredName": "Hansruedi",
    • "firstNameLocal": "Hans",
    • "middleNameLocal": "Ruedi"
    }
}

Response samples

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

Deletes an alias in the Alias Directory.

Deletes a specified alias which entails a deletion of the corresponding Visa Alias Directory card registrations.

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

  • 4520 - UNKNOWN_ALIAS
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

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 status of an alias in the Alias Directory.

Updates the status of the specified alias.

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

  • 4520 - UNKNOWN_ALIAS
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
aliasStatus
required
string (VisaADAliasUpdatingStatus)
Enum: "ACTIVE" "DISABLED"

The updating status of an alias.

Responses

Request samples

Content type
application/json
{
  • "aliasStatus": "ACTIVE"
}

Response samples

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

Retrieves all the cards corresponding to an alias.

Retrieves all the cards corresponding to the alias of the specified Alias ID.

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

  • 4520 - UNKNOWN_ALIAS
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "cards": [
    • {
      }
    ]
}

Registers a card for Visa Alias Directory.

Registers the given card for Visa Alias Directory under the alias of the specified Alias ID.

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

  • 4430 - UNKNOWN_CARD
  • 4520 - UNKNOWN_ALIAS
  • 4423 - VISA_ALIAS_DIRECTORY_INVALID_CARD_EXPIRATION
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
object (VisaADCard)

Card in the context of Visa Alias Directory.

nameOnCard
required
string (VisaADNameOnCard) [ 1 .. 120 ] characters

The name which is printed on the card.

cardType
string (VisaADCardType) [ 1 .. 70 ] characters

Card type description. Reference to Field 62.23—Product ID of available card products.

required
object (VisaADBillingAddress)
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

preferredFor
Array of strings (VisaADPreferredFor) [ 1 .. 3 ] items
Items Enum: "RECEIVE" "SEND" "PAY"

Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Receiving allows for funds to be pushed into the payment credential. Sending allows for funds to be sent from the payment credential. Paying allows for the payment credential to be used for purchases. More than one preferred type can be used.

Responses

Request samples

Content type
application/json
{
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "cardType": "Visa Platinum",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "preferredFor": [
      ]
    }
}

Response samples

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

Updates a card in the Alias Directory.

Updates the given card for Visa Alias Directory under the alias of the specified Alias ID.

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

  • 4430 - UNKNOWN_CARD
  • 4520 - UNKNOWN_ALIAS
  • 4522 - CARD_NOT_REGISTERED_IN_VISA_ALIAS_DIRECTORY
  • 4423 - VISA_ALIAS_DIRECTORY_INVALID_CARD_EXPIRATION
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
object (VisaADCard)

Card in the context of Visa Alias Directory.

nameOnCard
required
string (VisaADNameOnCard) [ 1 .. 120 ] characters

The name which is printed on the card.

cardType
string (VisaADCardType) [ 1 .. 70 ] characters

Card type description. Reference to Field 62.23—Product ID of available card products.

required
object (VisaADBillingAddress)
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

preferredFor
Array of strings (VisaADPreferredFor) [ 1 .. 3 ] items
Items Enum: "RECEIVE" "SEND" "PAY"

Indicates if a payment credential is a preferred Receiving, Sending, or Paying account. Receiving allows for funds to be pushed into the payment credential. Sending allows for funds to be sent from the payment credential. Paying allows for the payment credential to be used for purchases. More than one preferred type can be used.

Responses

Request samples

Content type
application/json
{
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "cardType": "Visa Platinum",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "preferredFor": [
      ]
    }
}

Response samples

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

Retrieves a card registered in the Alias Directory.

Retrieves a specific card corresponding to the alias of the specified Alias ID.

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

  • 4430 - UNKNOWN_CARD
  • 4520 - UNKNOWN_ALIAS
  • 4522 - CARD_NOT_REGISTERED_IN_VISA_ALIAS_DIRECTORY
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "cardType": "Visa Platinum",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "preferredFor": [
      ]
    }
}

Deletes a card from the Alias Directory.

Deletes the given card from the alias of the specified Alias ID.

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

  • 4430 - UNKNOWN_CARD
  • 4520 - UNKNOWN_ALIAS
  • 4522 - CARD_NOT_REGISTERED_IN_VISA_ALIAS_DIRECTORY
  • 4524 - ISSUER_NOT_CONFIGURED_FOR_VISA_ALIAS_DIRECTORY
path Parameters
aliasId
required
string (VisaADAliasId) = 36 characters
Examples: e336c8c8-2945-4be3-af3e-951ec2d01219

Identifier of the alias

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

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

Visa Click to Pay Issuer Offered

Visa Click to Pay Issuer Offered operations to enroll and manage cards for Visa Click to Pay.

Initiates a new customer enrollment for Visa Click to Pay.

Starts the process of enrolling a new customer and a card for Visa Click to Pay, and provides a requestTraceId in the response to retrieve the status of the enrollment. As part of the request processing, a digital card will be generated for the enrolled card. The status of the customer is set to ACTIVE after a successful enrollment.

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

  • 4430 - UNKNOWN_CARD
  • 4436 - CARD_INACTIVE
  • 4501 - CUSTOMER_ALREADY_ENROLLED_FOR_C2P
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Request to enroll a customer and a card for Visa Click to Pay.

required
object (VisaC2PEnrollingCustomer)

Contains the information about a customer to be enrolled.

email
required
string (VisaC2PCustomerEmail) [ 1 .. 256 ] characters

The customer's email address.

locale
required
string (VisaC2PCustomerLocale) [ 2 .. 5 ] characters

The customer's locale.

phone
required
string (VisaC2PCustomerPhone) [ 1 .. 15 ] characters

The customer's phone number in ITU-T E.164 format, without "+" symbol and leading zeros.

lastName
required
string (VisaC2PCustomerLastName) [ 1 .. 35 ] characters

The customer's last name.

firstName
required
string (VisaC2PCustomerFirstName) [ 1 .. 35 ] characters

The customer's first name.

middleName
string (VisaC2PCustomerMiddleName) [ 1 .. 35 ] characters

The customer's middle name.

countryCode
required
string (VisaC2PCustomerCountryCode) = 3 characters

The customer's country code in the ISO 3166 (alpha 3) format.

customerId
required
string <uuid> (VisaC2PCustomerId)

Unique identifier for the customer.

object (VisaC2PCustomerNationalIdentifier)

The customer's national identifier.

required
object (VisaC2PCard)

Contains the information about the card, which must be valid when enrolling for Click to Pay.

nameOnCard
required
string [ 1 .. 120 ] characters

The name which is printed on the card.

required
object (VisaC2PBillingAddress)

The card's billing address.

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

required
object (YearMonth)

Responses

Request samples

Content type
application/json
{
  • "customer": {
    • "email": "peter.schweizer@mailbox.org",
    • "locale": "de_CH",
    • "phone": "41791231212",
    • "lastName": "Muster",
    • "firstName": "Maximilian",
    • "middleName": "Alexander",
    • "countryCode": "CHE",
    • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    • "nationalIdentifier": {
      }
    },
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "expiration": {
      }
    }
}

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Provides the customer's information along with the enrolled cards.

Retrieves all information about the customer stored in Visa Click to Pay, including their enrolled cards.

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

  • 4502 - UNKNOWN_CUSTOMER
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "customer": {
    • "email": "peter.schweizer@mailbox.org",
    • "locale": "de_CH",
    • "phone": "41791231212",
    • "lastName": "Muster",
    • "firstName": "Maximilian",
    • "middleName": "Alexander",
    • "countryCode": "CHE",
    • "customerId": "87d8e330-2878-4742-a86f-dbbb3bf522ac",
    • "customerStatus": "ACTIVE",
    • "nationalIdentifier": {
      }
    },
  • "enrolledCards": [
    • {
      }
    ]
}

Updates the customer's information in Visa Click to Pay.

Overwrites existing data for the specified customer, and provides a requestTraceId in the response to retrieve the status of this action. It is recommended to retrieve the latest customer information in Click to Pay and populate all data fields, including the ones that do not change. Therefore, the complete customer information need to be sent again if the customer is ACTIVE. If the status in the request is set to DISABLED, then the update will not be performed and Click to Pay will give an error.

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

  • 4502 - UNKNOWN_CUSTOMER
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Request to update the customer's information.

required
object (VisaC2PUpdatingCustomer)

Contains the information about the customer update.

email
required
string (VisaC2PCustomerEmail) [ 1 .. 256 ] characters

The customer's email address.

locale
required
string (VisaC2PCustomerLocale) [ 2 .. 5 ] characters

The customer's locale.

phone
required
string (VisaC2PCustomerPhone) [ 1 .. 15 ] characters

The customer's phone number in ITU-T E.164 format, without "+" symbol and leading zeros.

lastName
required
string (VisaC2PCustomerLastName) [ 1 .. 35 ] characters

The customer's last name.

firstName
required
string (VisaC2PCustomerFirstName) [ 1 .. 35 ] characters

The customer's first name.

middleName
string (VisaC2PCustomerMiddleName) [ 1 .. 35 ] characters

The customer's middle name.

countryCode
required
string (VisaC2PCustomerCountryCode) = 3 characters

The customer's country code in the ISO 3166 (alpha 3) format.

customerStatus
string (VisaC2PCustomerStatus)
Enum: "ACTIVE" "DISABLED"

The status of the enrolled customer.

object (VisaC2PCustomerNationalIdentifier)

The customer's national identifier.

Responses

Request samples

Content type
application/json
{
  • "customer": {
    • "email": "peter.schweizer@mailbox.org",
    • "locale": "de_CH",
    • "phone": "41791231212",
    • "lastName": "Muster",
    • "firstName": "Maximilian",
    • "middleName": "Alexander",
    • "countryCode": "CHE",
    • "customerStatus": "ACTIVE",
    • "nationalIdentifier": {
      }
    }
}

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Deletes an enrolled customer from Visa Click to Pay.

Deletes all data previously sent to Visa Click to Pay for the specified customer, including all linked cards and digital cards. Provides a requestTraceId in the response to retrieve the status of this action.

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

  • 4502 - UNKNOWN_CUSTOMER
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Enrolls a card for a customer in Visa Click to Pay.

Enrolls a card for an existing customer already registered with Visa Click to Pay, and provides a requestTraceId in the response to retrieve the status of this action. As part of the request processing, a digital card will be generated for the enrolled card.

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

  • 4430 - UNKNOWN_CARD
  • 4436 - CARD_INACTIVE
  • 4502 - UNKNOWN_CUSTOMER
  • 4503 - CARD_ALREADY_ENROLLED_FOR_C2P
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Request to enroll a card for Visa Click to Pay.

required
object (VisaC2PCard)

Contains the information about the card, which must be valid when enrolling for Click to Pay.

nameOnCard
required
string [ 1 .. 120 ] characters

The name which is printed on the card.

required
object (VisaC2PBillingAddress)

The card's billing address.

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

required
object (YearMonth)

Responses

Request samples

Content type
application/json
{
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "expiration": {
      }
    }
}

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Updates the card information in Visa Click to Pay.

Updates existing data for the specified card, and provides a requestTraceId in the response to retrieve the status of this action. It is recommended to retrieve the latest card information in Click to Pay and populate all data fields, including the ones that do not change. Therefore, the complete card information need to be sent again.

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

  • 4430 - UNKNOWN_CARD
  • 4502 - UNKNOWN_CUSTOMER
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required

Request to update the card information.

required
object (VisaC2PCard)

Contains the information about the card, which must be valid when enrolling for Click to Pay.

nameOnCard
required
string [ 1 .. 120 ] characters

The name which is printed on the card.

required
object (VisaC2PBillingAddress)

The card's billing address.

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$

Unique card token of a card.

required
object (YearMonth)

Responses

Request samples

Content type
application/json
{
  • "card": {
    • "nameOnCard": "Peter Schweizer",
    • "billingAddress": {
      },
    • "cardToken": "CTK-54716A6080B14CF19CEA3C170F85B1DD",
    • "expiration": {
      }
    }
}

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Deletes an enrolled card from Visa Click to Pay.

Deletes a card (including the digital card) from Visa Click to Pay, and provides a requestTraceId in the response to retrieve the status of this action.

Note: Deleting a customer's last card does not automatically remove the customer from Visa Click to Pay.

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

  • 4430 - UNKNOWN_CARD
  • 4502 - UNKNOWN_CUSTOMER
  • 4504 - C2P_HAS_PENDING_REQUEST
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
customerId
required
string <uuid> (VisaC2PCustomerId)

Identifier of the customer.

cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "requestTraceId": "f628c109-3289-492a-a630-ff94de86e182"
}

Returns the status of a previously triggered action.

Provides the result of the operation corresponding to the requestTraceId from the previously initiated action. The requestTraceId is valid for 7 days from the time of receipt. If the action fails, the errorDetails will contain the errors received from Visa Click to Pay.

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

  • 4505 - UNKNOWN_C2P_REQUEST_TRACE_ID
  • 4506 - C2P_NOT_SUPPORTED_BY_ISSUER
path Parameters
requestTraceId
required
string <uuid> (VisaC2PRequestTraceId)

Identifier of the request trace.

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Responses

Response samples

Content type
application/json
{
  • "status": "IN_PROGRESS",
  • "errors": [
    • {
      }
    ]
}

Mastercard Click to Pay (Beta)

Provides an operation to enroll Mastercard Click to Pay.

Enrolls a card in Mastercard Click to Pay.

Enrolls a card in Mastercard Click to Pay. As part of the request processing, a digital card will be generated for the enrolled card.

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

  • 4430 - UNKNOWN_CARD
  • 4436 - CARD_INACTIVE
  • 4449 - TOKENIZATION_NOT_SUPPORTED
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

header Parameters
x-request-id
string

A unique identifier for a request and response pair.

Request Body schema: application/json
required
required
object (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

required
object (ClickToPayMastercardConsumer)

Consumer details for Mastercard Click to Pay

emailAddress
required
string [ 1 .. 256 ] characters

The customer's email address.

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

The phone number without country code.

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

The country code of the phone number.

languageCode
required
string >= 2 characters

Consumer-provided language choice. ISO 639-1 Code.

firstName
required
string <= 30 characters

Consumer-provided first name.

lastName
required
string <= 30 characters

Consumer-provided last name.

street
required
string <= 25 characters

Consumer-provided street name.

streetNo
required
string <= 5 characters

Consumer-provided street number.

postalCode
required
string [ 1 .. 10 ] characters

Postal or zip code of the address.

city
required
string [ 1 .. 32 ] characters

The city of the address.

countryCode
required
string = 2 characters

ISO 3166 alpha 2 country code.

required
object (ClickToPayMastercardComplianceSettings)

Contains URIs to the latest privacy policy and terms and conditions for Mastercard Click to Pay.

privacyUri
required
string >= 15 characters

Latest version of privacy policy URI.

termsAndConditionsUri
required
string >= 15 characters

Latest version of terms and conditions URI.

Responses

Request samples

Content type
application/json
{}

Response samples

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

Deprecated

Deprecated endpoints.

Returns encrypted card data.

Deprecated, use one of POST /cards/{cardToken}/apple-pay/provisioning-data, POST /cards/{cardToken}/google-pay/provisioning-data, POST /cards/{cardToken}/samsung-pay/provisioning-data instead.

Returns the encrypted card data for the provisioning of a funding debit card, specified by its card token, 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
path Parameters
cardToken
required
string (CardToken) = 36 characters ^CTK-[0-9a-fA-F]{32}$
Examples: CTK-54716A6080B14CF19CEA3C170F85B1DD

Card token

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 (CardTokenExtension)

Extension to card token to identify a card.

required
object (YearMonth)
cardSequenceNumber
required
integer <int32> (CardSequenceNumber) [ 0 .. 9 ]

Sequence number of the card.

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

The cardholder name as printed on the card.

Responses

Request samples

Content type
application/json
{
  • "cardTokenExtension": {
    • "cardExpiry": {
      },
    • "cardSequenceNumber": 2
    },
  • "cardholderName": "Peter Meier"
}

Response samples

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