API essentials

API routes

The connectivity to the debiX API can be established via multiple network channels. The bank can choose which one to rely on for the test and production environments.

Here is a list of the available connectivity channels and related paths:

SSFN

Environment	URL
PROD	https://api.six.ssfn.ch/api/debix/bank/v2
TEST	https://api-preprod.np.six.ssfn.ch/api/debix/bank/v2

P2P

Environment	URL
PROD	https://api.p2p.six-group.com/api/debix/bank/v2
TEST	https://api-preprod.np.p2p.six-group.com/api/debix/bank/v2

Internet

Environment	URL
PROD	https://api.six-group.com/api/debix/bank/v2
TEST	https://api-preprod.np.six-group.com/api/debix/bank/v2

Example

Each path must be combined with the API platform URL. Therefore, all endpoints are defined with a related path.

Here is an example for the /healthcheck endpoint:

Encoding

As defined in RFC4627, the encoding for JSON content is UTF-8.

HTTP verbs

The endpoints use the appropriate HTTP verb for the operations.

Verb	Description
GET	Retrieve resources
POST	Create resources
PUT	Update resources with full data
DELETE	Delete resources

Some resources offer a search method via a POST request, e.g. POST /digitalcards/search. The search parameters must be provided in the body of the POST request.

HTTP headers

HTTP headers let the client and the server forward additional information with an HTTP request or response. An HTTP header consists of its case-insensitive name followed by a colon (:), then by its value.

Request headers

The following headers must be used for every request:

• accept: application/json
• x-request-id A unique identifier for a request and response pair.
• content-length: <length> Must be specified for requests with a payload.

Response headers

The API always indicates the return type with a content-type header.

Response codes

The result of the endpoint's operation is reflected in the HTTP status code. The standard HTTP status codes are used:

HTTP status code	Summary	Description
200	OK	The request was handled successfully
201	Created	A new resource was created
304	Not modified	The resource has not been changed
400	Bad request	The request parameters are invalid
401	Unauthorized	The authentication information is missing
403	Forbidden	No access to the resource
404	Not found	The resource could not be found
500	Internal server error	An unexpected condition was encountered
503	Service unavailable	The server cannot handle the request

Error responses

Error responses include an HTTP status code and a JSON response body that contains details about the error:

Error codes

The application error codes are used in the body of an error response.

Application error	Error code	Description
MISSING_MANDATORY_PARAMETER	4100	A mandatory parameter is missing.
PARAMETER_VALIDATION_FAILED	4102	The validation of the provided request parameters failed.
AUTHORIZATION_FAILED	4401	The authorization failed.
ENDPOINT_NOT_ENTITLED	4402	The entitlement is missing for the requested endpoint.
OPTIMISTIC_LOCK_ERROR	4409	The operation failed due to optimistic locking.
UNKNOWN_CARD	4430	The card for the provided attributes could not be found.
DIGITAL_CARD_STATUS_UPDATE_NOT_ALLOWED	4431	Updating the digital card status from the current status to the requested status is not allowed.
BANK_CLEARING_NUMBER_NOT_CONFIGURED	4432	The bank clearing number is not configured on the issuer.
UNKNOWN_WALLET_PROVIDER	4433	The wallet provider is unknown.
THREE_DS_NOT_ENABLED_FOR_ISSUER	4434	3DS registration is not enabled for the given issuer.
CARD_ALREADY_REGISTERED_FOR_THREE_DS	4435	The card is already registered for 3DS.
CARD_INACTIVE	4436	The card is not active.
DIGITAL_CARD_HAS_PENDING_STATUS	4437	The digital card has currently a pending status which prevents further status updates.
CARD_STATUS_UPDATE_NOT_ALLOWED	4438	Updating the card status from the current status to the requested status is not allowed.
CARD_HAS_PENDING_STATUS	4439	The card has currently a pending status which prevents further status updates.
SET_PIN_NOT_ALLOWED_FOR_BLOCKED_OR_DELETED_CARD	4440	The pin cannot be set for a blocked or deleted card.
PIN_PREVIOUSLY_PASSED_TO_NEWER_CARD	4442	The pin was previously passed to a newer card.
UNKNOWN_PARENT_CARD	4443	The parent card could not be found.
VIRTUAL_CARD_EQUALS_PARENT_CARD	4444	The virtual card equals the parent card.
CARD_ALREADY_EXISTING	4445	The card already exists.
DELIVERY_INFORMATION_FOR_OTRC_MISSING	4446	The delivery information for otrc is missing.
NO_CARD_DETAILS_AVAILABLE	4447	No card details are available for this card.
AUTHENTICATION_METHOD_CHANGE_NOT_ALLOWED	4448	Updating the authentication method from the current to the requested method is not allowed.
TOKENIZATION_NOT_SUPPORTED	4449	Issuer does not support tokenization.
NO_CERTIFICATE_FOUND	4450	No certificate is registered for this issuer.
INVALID_JWS_SIGNATURE	4451	The signature of the JWS is invalid.
START_SET_PIN_NOT_CALLED	4452	The Start Set Pin was not called to initiate the Set Pin.
THREE_DS_OOB_NOT_ENABLED_FOR_ISSUER	4453	3DS OOB is not enabled for the given issuer.
EXCLUDED_WALLET_PROVIDER	4454	Wallet provider is excluded for issuer.
UNKNOWN_MERCHANT	4455	Merchant id unknown.
UNKNOWN_WALLET_TYPE	4456	The wallet type is unknown.
CARD_NOT_REGISTERED_FOR_THREE_DS	4457	The card is not registered for 3DS.
RETRIEVE_PIN_NOT_ALLOWED_FOR_DELETED_CARD	4458	The pin cannot be retrieved for a deleted card.
ECOMMERCE_FEATURE_TOGGLE_NOT_ACTIVATED	4460	The card is not allowed to perform e-commerce transactions.
INCOMPLETE_OR_MISSING_ADDRESS_DATA	4461	The card's address data is missing or incomplete.
DELIVERY_INFORMATION_FOR_CARD_OR_PIN_MISSING	4462	The delivery information for the PIN or physical card is missing.
CARD_EXPRESS_CODE_MISSING	4463	The card express code is missing.
PIN_EXPRESS_CODE_MISSING	4464	The PIN express code is missing.
PRODUCER_CODE_MISSING	4465	The producer code is missing.
CARDLINE1_MISSING	4466	The first line to be printed on the card is missing.
OPERATION_FAILED	5001	The requested operation failed.
TECHNICAL_ERROR	5002	A technical error occurred.

Standard error codes

Some application error codes may be returned from any endpoint and are excluded from the detailed endpoint descriptions:

• 4401
• 4409
• 5001
• 5002

Request validation error codes may be returned from any POST and PUT endpoint with request arguments and are excluded from the detailed endpoint descriptions:

• 4100
• 4102

Authentication and Authorization

Authentication and authorization are described in the section Security