From fbf787b75c08514a345d73c9d81ba756132ab154 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Thu, 16 May 2024 16:33:28 +0200
Subject: [PATCH 01/29] initial specification of new Card API model
---
cardInfoAPI.yaml | 2582 ++++++++++++++++------------------------------
1 file changed, 882 insertions(+), 1700 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 8ffe49b..61d36d1 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -1,401 +1,85 @@
-openapi: "3.0.3"
+openapi: 3.1.0
info:
- version: "0.6"
+ version: 0.7
title: Common Card Info API (Public)
- description:
- This specification defines a common card info API for payment cards used in Switzerland. The API is supposed to be used to retrieve payment card infos (read only).
- termsOfService: 'Tbd'
+ description: >
+ This specification defines a common card info API for payment cards used in Switzerland.
+ The API is supposed to be used to retrieve payment card infos (read only).
+ # TODO update description
contact:
email: info@common-api.ch
license:
name: Apache 2.0
- url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://card.common-api.ch
externalDocs:
description: Find out more about SFTI API specifications
- url: 'https://www.common-api.ch'
+ url: https://www.common-api.ch
+
+# TODO make more detailed description
+tags:
+ - name: Cards
+ description: Operations related with managing cards
+ - name: Card-tokens
+ description: Operations related with managing card tokens
+ - name: Transactions
+ description: Operations related with retrieving card transactions
+
security:
- ApiKeyAuth: []
- OAuth2:
- read
- write
-tags:
- - name: cards
- description: Operations related with managing cards
- - name: card-accounts
- description: Operations related with managing card accounts
- - name: statements
- description: Operations related with retrieving card account statements
- - name: transactions
- description: Operations related with retrieving card transactions
- - name: persons
- description: Operations related with managing persons
- - name: card-contracts
- description: Operations related with managing card contracts
- - name: card-accountbundles
- description: --
- - name: card-consents
- description: '[not used] Operations related with managing card consents'
-
paths:
/cards:
get:
tags:
- - cards
- description: List of cards for the authenticated context including all related information, optional filtered by personId / cardContractId / cardAccountId, sorted by cardId.
- summary: Return the list of all cards for the authenticated context (filtered and sorted)
+ - Cards
+ summary: # TODO
+ description: # TODO
parameters:
- - $ref: '#/components/parameters/transactionId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all cards with all related information sorted by cardId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardList:
- type: array
- items:
- $ref: '#/components/schemas/card'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /cards/card-tokens:
- get:
- tags:
- - card-tokens
- description: Card token (Child card) derived from parent card
- summary: TODO
- parameters:
- - $ref: '#/components/parameters/cardTokenId'
- - name: deviceName
- in: query
- description: Name of device, where token is used
- required: false
- example: apple
- schema:
- type: string
- enum:
- - apple
- - samsung
- - other
- - name: cardLink
- in: query
- description: TODO
+ - in: query
+ name: contract_reference
required: true
- example: TODO
schema:
- type: string
- - name: dpan
- in: query
- description: TODO
+ $ref: '#/components/schemas/ContractReference'
+ - in: query
+ name: person_reference
required: true
- example: TODO
- schema:
- type: string
- format: uuid
- - name: statusGeneric
- in: query
- description: TODO
- required: false
- example: TODO
schema:
- type: string
- - name: walletTypeName
- in: query
- description: Issuer of token card
- required: false
- example: TODO
- schema:
- type: string
- enum:
- - mastercard
- - visa
- - amex
- - dinersclub
- - apple pay
- - google pay
- - other
- - name: provisionDate
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- format: Date
- - name: expireDate
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- format: Date
- - name: schemeTokenId
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- enum:
- - TODO
- - $ref: '#/components/schemas/cardTransaction'
- responses:
- '200':
- description: Paginated list of all token cards with all related information sorted by cardTokenId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardList:
- type: array
- items:
- $ref: '#/components/schemas/cardToken'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-accounts:
- get:
- tags:
- - card-accounts
- description: List of card accounts for the authenticated context including all related information, filtered by query, sorted by cardAccountId.
- summary: Return the list of all card accounts for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/transactionId'
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/statementId'
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/cardContractId'
+ $ref: '#/components/schemas/PersonReference'
- in: query
- name: IBAN
- description: International Bank Account Number that is associated with the payment card account. Note, that one IBAN can be associated to multiple card accounts.
- required: false
+ name: card_id
+ required: true
schema:
- type: string
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all card accounts with all related information sorted by cardAccountId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardAccountList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccount'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-accounts/statements:
- get:
- tags:
- - statements
- description: List of card account statements for the authenticated context including all related information, filtered by query, sorted by cardAccountStatementId.
- summary: Return the list of all card account statements for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/cardAccountId'
+ $ref: '#/components/schemas/CardId'
- in: query
- name: fromDate
- description: Date from which statement entries should be retrieved
- required: false
+ name: card_status
+ required: true
schema:
- $ref: '#/components/schemas/date'
+ $ref: '#/components/schemas/CardStatus'
- in: query
- name: untilDate
- description: Date until which statement entries should be retrieved
+ name: card_account_id
required: false
schema:
- $ref: '#/components/schemas/date'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all card account statements with all related information sorted by cardAccountStatementId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardAccountStatementList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccountStatement'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-transactions:
- get:
- tags:
- - transactions
- description: List of card transactions for the authenticated context including all related information, filtered by query, sorted by cardTransactionId.
- summary: Return the list of all card transactions for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/cardAccountId'
+ $ref: '#/components/schemas/CardAccountId'
- in: query
- name: inclName
- description: Only retrieve transactions that include this text in as a merchant name
- required: false
- example: Hotel
- schema:
- type: string
- - name: inclLocation
- in: query
- description: Only retrieve transactions that include this text in as a merchant location
- required: false
- example: London
- schema:
- type: string
- - name: inclCountry
- in: query
- description: Only retrieve transactions that include this text in as a merchant country
+ name: bank_account_reference
required: false
- example: Italien
schema:
- type: string
- - name: fromDate
- in: query
- description: Only retrieve transactions starting from this date (YYYY-MM-DD)
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - name: untilDate
- in: query
- description: Only retrieve transactions up until this date (YYYY-MM-DD)
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ $ref: '#/components/schemas/BankAccountReference'
responses:
'200':
- description: Paginated list of all card transactions with all related information sorted by cardTransactionId
+ description: # TODO
+ headers:
+ # TODO headers?
content:
application/json:
schema:
- type: object
- properties:
- cardTransactionList:
- type: array
- items:
- $ref: '#/components/schemas/cardTransaction'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
+ $ref: '#/components/schemas/CardDetails'
+ # TODO which standard error responses should be removed?
'400':
$ref: '#/components/responses/standard400'
'401':
@@ -413,131 +97,38 @@ paths:
'503':
$ref: '#/components/responses/standard503'
- /persons:
+ /card-tokens:
get:
tags:
- - persons
- description: List of persons for the authenticated context including all related information, filtered by query which also allows searching, sorted by personId.
- summary: Return the list of all persons for the authenticated context (filtered and sorted)
+ - Card-tokens
+ summary: # TODO
+ description: # TODO
parameters:
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/cardContractId'
- - in: query
- name: personSurName
- description: First name of the customer.
- required: false
- schema:
- $ref: '#/components/schemas/personSurName'
- - in: query
- name: personName
- description: Last name of the customer.
- required: false
- schema:
- $ref: '#/components/schemas/personName'
- - in: query
- name: companyName
- description: 'Retrieve a list of customers given the company name.'
- required: false
- schema:
- $ref: '#/components/schemas/entityName'
- in: query
- name: birthDate
- description: Date of birth of the person.
- required: false
+ name: token_id
+ required: true
schema:
- $ref: '#/components/schemas/date'
+ $ref: '#components/schemas/TokenId'
- in: query
- name: contractType
- description: Possible values are consumer, business, corporate (if left empty, any will be provided)
- required: false
+ name: funding_card_id
+ required: true
schema:
- $ref: '#/components/schemas/contractType'
+ $ref: '#components/schemas/FundingCardId'
- in: query
- name: searchType
- description: Possible values are same, soundex, ccv
- required: false
+ name: token_status
+ required: true
schema:
- type: string
- enum:
- - same
- - soundex
- - cvv
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ $ref: '#components/schemas/TokenStatus'
responses:
'200':
- description: Paginated list of all person with all related information sorted by personId
- content:
- application/json:
- schema:
- type: object
- properties:
- personList:
- type: array
- items:
- $ref: '#/components/schemas/person'
- _links:
- $ref: '#/components/schemas/linksPagination'
+ description: # TODO
headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-contracts:
- get:
- tags:
- - card-contracts
- description: List of cards contracts for the authenticated context including all related information, filtered by query, sorted by cardContractId.
- summary: Return the list of all card contracts for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all queried card contracts with all related information sorted by cardContractsId
+ # TODO headers?
content:
application/json:
schema:
- type: object
- properties:
- cardContractList:
- type: array
- items:
- $ref: '#/components/schemas/cardContract'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
+ $ref: '#/components/schemas/CardTokenDetails'
+ # TODO which standard error responses should be removed?
'400':
$ref: '#/components/responses/standard400'
'401':
@@ -555,40 +146,39 @@ paths:
'503':
$ref: '#/components/responses/standard503'
- /card-accountbundles:
+ /card-transactions:
get:
tags:
- - card-accountbundles
- description: --
- summary: --
+ - Card-tokens
+ summary: # TODO
+ description: # TODO
parameters:
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/cardContractId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - in: query
+ name: transaction_id
+ required: false
+ schema:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
+ - in: query
+ name: authorization_id
+ required: false
+ schema:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c # TODO use unique values if not indicating same parameters to avoid confusions?
+ description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
responses:
'200':
- description: --
+ description: # TODO
+ headers:
+ # TODO headers?
content:
application/json:
schema:
- type: object
- properties:
- cardAccountbundleList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccountbundle'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
+ $ref: '#/components/schemas/CardTokenDetails'
+ # TODO which standard error responses should be removed?
'400':
$ref: '#/components/responses/standard400'
'401':
@@ -606,1000 +196,756 @@ paths:
'503':
$ref: '#/components/responses/standard503'
-
-# -------------------------
-# -------- Models ---------
-# -------------------------
components:
- securitySchemes:
- ApiKeyAuth:
- type: apiKey
- in: header
- name: X-API-Key
-
- OAuth2:
- type: oauth2
- flows:
- authorizationCode:
- authorizationUrl: https://example.com/oauth/authorize
- tokenUrl: https://example.com/oauth/token
- scopes:
- read: Grants read access
- write: Grants write access
-
schemas:
- # ---- Card Account Object ----
- cardAccount:
- description: The representation of a card account object
+ CardDetails:
+ title: # TODO
+ description: #TODO
type: object
required:
- - cardAccountId
+ - contract_reference
+ - person_reference
+ - card_id
+ - embossing_line_1
+ - embossing_line_2
+ - pan_4_digits
+ - expiry_date
+ - card_status
+ - currency
+ - image
+ - product_id
+ - product_name
+ - scheme
+ - issuing_type
+ - product_type
+ - product_line
+ - card_limit_cycle
+ - card_limit_daily
+ - issuer_id
+ - issuer_name
+ - language
properties:
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- cards:
- type: array
- description: List of card_uids linked to this account
- items:
- $ref: '#/components/schemas/card'
+ contract_reference:
+ $ref: '#/components/schemas/ContractReference'
+ person_reference:
+ $ref: '#/components/schemas/PersonReference'
+ card_id:
+ $ref: '#/components/schemas/CardId'
+ embossing_line_1:
+ $ref: '#/components/schemas/EmbossingLine1'
+ embossing_line_2:
+ $ref: '#/components/schemas/EmbossingLine2'
+ pan_4_digits:
+ $ref: '#/components/schemas/Pan4Digits'
+ expiry_date:
+ $ref: '#/components/schemas/ExpiryDate'
+ initial_issuing_date:
+ $ref: '#/components/schemas/InitialIssuingDate'
+ card_status:
+ $ref: '#/components/schemas/CardStatus'
currency:
- $ref: '#/components/schemas/currency'
- ibanAccount:
- $ref: '#/components/schemas/paymentQrIbanAccount'
- billingCycle:
- type: string
- description: code that determines the billing cycle
- example: monthly
- enum:
- - weekly
- - monthly
- - quarterly
- - halfyearly
- - yearly
- cardAccountStatus:
- $ref: '#/components/schemas/genericStatus'
- cardLoyality:
- $ref: '#/components/schemas/cardLoyality'
- paymentDetails:
- type: object
- properties:
- paymentType:
- $ref: '#/components/schemas/paymentType'
- paymentOption:
- $ref: '#/components/schemas/paymentOption'
- statementDetails:
- type: object
- properties:
- deliveryType:
- type: string
- example: paper
- description: Description of the delivery format of the statement.
- enum:
- - paper
- - paperless
- - estatement
- - other
- activeDeliveryFee:
- type: number
- example: 1.0
- description: Amount charged to the customer for each statement delivery. Typically, paperless is free.
- nextStatementDate:
- $ref: '#/components/schemas/date'
- # ---------
-
- # ---- Card Loyality Object ----
- cardLoyality:
- description: The representation of a card loyality object
- type: object
- required:
- - cardLoyalityId
- properties:
- cardLoyalityId:
- $ref: '#/components/schemas/entityId'
- name:
- type: string
- description: Program name
- example: surprize
- reference:
- type: string
- example: "2501021032295"
- description: Additional reference number if available
- enrollment_date:
- $ref: '#/components/schemas/date'
- # ---------
-
- # ---- Card API Object ----
- cardApi:
- description: List of APIs supported for a API consumer
- type: string
- example: get:cards
- # ---------
+ $ref: '#/components/schemas/Currency'
+ image:
+ $ref: '#/components/schemas/Image'
+ product_id:
+ $ref: '#/components/schemas/ProductId'
+ product_name:
+ $ref: '#/components/schemas/ProductName'
+ scheme:
+ $ref: '#/components/schemas/Scheme'
+ category:
+ $ref: '#/components/schemas/Category'
+ issuing_type:
+ $ref: '#/components/schemas/IssuingType'
+ product_type:
+ $ref: '#/components/schemas/ProductType'
+ product_line:
+ $ref: '#/components/schemas/ProductLine'
+ card_limit_cycle:
+ $ref: '#/components/schemas/CardLimitCycle'
+ card_limit_daily:
+ $ref: '#/components/schemas/CardLimitDaily'
+ card_account_id:
+ $ref: '#/components/schemas/CardAccountId'
+ bank_account_reference:
+ $ref: '#/components/schemas/BankAccountReference'
+ issuer_id:
+ $ref: '#/components/schemas/IssuerId'
+ issuer_name:
+ $ref: '#/components/schemas/IssuerName'
+ distribution_partner_id:
+ $ref: '#/components/schemas/DistributionPartnerId'
+ distribution_partner_name:
+ $ref: '#/components/schemas/DistributionPartnerName'
+ language:
+ $ref: '#/components/schemas/Language'
+ CardTokenDetails:
+ title: # TODO
+ description: #TODO
+ type: object
+ required:
+ - token_id
+ - token_pan_4_digits
+ - token_requestor_id
+ - token_requestor_name
+ - funding_card_id
+ - token_status
+ - token_issuing_date
+ - token_scheme
+ properties:
+ token_id:
+ $ref: '#/components/schemas/TokenId'
+ token_pan_4_digits:
+ $ref: '#/components/schemas/TokenPan4Digits'
+ wallet_id:
+ $ref: '#/components/schemas/WalletId'
+ wallet_name:
+ $ref: '#/components/schemas/WalletName'
+ token_requestor_id:
+ $ref: '#/components/schemas/TokenRequestorId'
+ token_requestor_name:
+ $ref: '#/components/schemas/TokenRequestorName'
+ device_name:
+ $ref: '#/components/schemas/DeviceName'
+ device_type:
+ $ref: '#/components/schemas/DeviceType'
+ funding_card_id:
+ $ref: '#/components/schemas/FundingCardId'
+ token_status:
+ $ref: '#/components/schemas/TokenStatus'
+ token_issuing_date:
+ $ref: '#/components/schemas/TokenIssuingDate'
+ token_scheme:
+ $ref: '#/components/schemas/TokenScheme'
- # ---- Card Consent Object ----
- cardConsent:
- description: The representation of a card consent object
- type: object
- required:
- - cardConsentId
- - cardApiList
- - identificationType
- - identificationValue
- properties:
- cardConsentId:
- $ref: '#/components/schemas/entityId'
- identificationType:
- type: string
- example: card_uid
- description: Audit type field in order to identify the actual user who granted the consent. This field contains the type of identifier.
- identificationValue:
- type: string
- example: 404003004CCL50000
- description: Audit type field in order to identify the actual user who granted the consent. This field contains the actual identifier of the type defined before.
- cardApiList:
- type: array
- description: List of the APIs to which access is requested.
- items:
- $ref: '#/components/schemas/cardApi'
- # ---------
-
- # ---- Card Object ----
- card:
- description: The representation of a card objectw
- type: object
- required:
- - cardId
- properties:
- cardId:
- $ref: '#/components/schemas/entityId'
- personId:
- $ref: '#/components/schemas/entityId'
- contractId:
- $ref: '#/components/schemas/entityId'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- issuingPartnerId:
- $ref: '#/components/schemas/entityIdName'
- issuerId:
- $ref: '#/components/schemas/entityIdName'
- cardDetail:
- type: object
- required:
- - cardNumberCustomer
- properties:
- cardNumber:
- type: string
- example: 4566549683425654
- maxLength: 19
- description: Card number
- cardNumberCustomer:
- type: string
- example: 4566549683425654
- maxLength: 50
- description: Card number
- initialCreationDate:
- $ref: '#/components/schemas/date'
- expiryDate:
- type: string
- example: 05/19
- description: Card expiry date in the format MM/YY
- embossingLine1:
- type: string
- maxLength: 30
- example: FRANZ MUSTERMANN
- description: Embossing Line 1 contains the person name as visible on the card plastic
- embossingLine2:
- type: string
- maxLength: 30
- example: VISECA CARD SERVICES
- description: Embossing Line 2 may contain a person-specified or product-specific value, as visible on the card plastic
- purgedDate:
- $ref: '#/components/schemas/date'
- currency:
- $ref: '#/components/schemas/currency'
- card_scheme:
- type: string
- example: visa
- description: Card payment scheme
- enum:
- - mastercard
- - visa
- - amex
- - dinersclub
- - other
- productId:
- type: string
- example: "1010101"
- description: Issuer identifier of a card product
- productType:
- type: string
- example: prepaid
- description: States if the card is credit or debit. Prepaid cards are labelled as credit in this operation
- enum:
- - credit
- - debit
- - prepaid
- productCategory:
- type: string
- example: gold
- description: 'Product category corresponds to the tier of card: gold, platinum, basic etc.'
- productLine:
- $ref: '#/components/schemas/contractType'
- productName:
- type: string
- maxLength: 50
- example: World Mastercard Gold CHF
- description: Commercial name of the card product as defined by the bank
- cardImage:
- type: string
- example: "https://bank.ch/images/cardImage.png"
- description: URL to the (png) card image corresponding to the card
- cardRelationship:
- type: string
- example: main_card
- description: 'Identifies the nature of the card in regards to the overall account: main card or additional card'
- enum:
- - main_card
- - additional_card
- previousCardId:
- $ref: '#/components/schemas/entityId'
- previousReplacementDate:
- $ref: '#/components/schemas/date'
- replacementReason:
- type: string
- example: other
- description: Reason for the replacement of this card
- nextCardId:
- $ref: '#/components/schemas/entityId'
- nextReplacementDate:
- $ref: '#/components/schemas/date'
- atmDirectDebit:
- type: boolean
- description: A flag indicating if the ATM Direct Debit functionality is enabled
- example: true
- cardStatus:
- $ref: '#/components/schemas/genericStatus'
- # ---------
-
- # TODO: define object with properties
- cardToken:
- description: Card Account Token Information.
- type: object
- required:
- - cardTokenId
- properties:
- cardTokenId:
- type: string
- format: uuid
- description: UUID v4 of the card accountbundle
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
+ TransactionDetails:
+ title: # TODO
+ description: #TODO
+ type: object
+ required:
+ - transaction_date_time
+ - valuta_date
+ - transaction_status
+ - original_amount
+ - original_currency
+ - total_amount
+ - transaction_amount
+ - transaction_currency
+ - mcc
+ - mcc_description
+ - transaction_category
+ - card_id
+ properties:
+ transaction_id:
+ $ref: '#/components/schemas/TransactionId'
+ authorization_id:
+ $ref: '#/components/schemas/AuthorizationId'
+ transaction_date_time:
+ $ref: '#/components/schemas/TransactionDateTime'
+ valuta_date:
+ $ref: '#/components/schemas/ValutaDate'
+ statement_date:
+ $ref: '#/components/schemas/StatementDate'
+ transaction_status:
+ $ref: '#/components/schemas/TransactionStatus'
+ approval_code:
+ $ref: '#/components/schemas/ApprovalCode'
+ original_amount:
+ $ref: '#/components/schemas/OriginalAmount'
+ original_currency:
+ $ref: '#/components/schemas/OriginalCurrency'
+ total_amount:
+ $ref: '#/components/schemas/TotalAmount'
+ transaction_amount:
+ $ref: '#/components/schemas/TransactionAmount'
+ transaction_currency:
+ $ref: '#/components/schemas/TransactionCurrency'
+ fees:
+ $ref: '#/components/schemas/Fees'
+ exchange_rate:
+ $ref: '#/components/schemas/ExchangeRate'
+ exchange_rate_date:
+ $ref: '#/components/schemas/ExchangeRateDate'
+ description:
+ $ref: '#/components/schemas/Description'
+ merchant_name:
+ $ref: '#/components/schemas/MerchantName'
+ merchant_country:
+ $ref: '#/components/schemas/MerchantCountry'
+ merchant_city:
+ $ref: '#/components/schemas/MerchantCity'
+ mcc:
+ $ref: '#/components/schemas/Mcc'
+ mcc_description:
+ $ref: '#/components/schemas/MccDescription'
+ terminal_id:
+ $ref: '#/components/schemas/TerminalId'
+ card_acceptor_id:
+ $ref: '#/components/schemas/CardAcceptorId'
+ acquirer_id:
+ $ref: '#/components/schemas/AcquirerId'
+ channel:
+ $ref: '#/components/schemas/Channel'
+ transaction_category:
+ $ref: '#/components/schemas/TransactionCategory'
+ token_id:
+ $ref: '#/components/schemas/ReferenceTokenId'
+ cardholder_id:
+ $ref: '#/components/schemas/CardholderId'
+ card_account_id:
+ $ref: '#/components/schemas/ReferenceCardAccountId'
+ card_id:
+ $ref: '#/components/schemas/ReferenceCardId'
+ transaction_reference:
+ $ref: '#/components/schemas/TransactionReference'
- # ---- Card Account Statement ----
- cardAccountStatement:
- description: xy
- type: object
- required:
- - cardAccountStatementId
- properties:
- cardAccountStatementId:
- $ref: '#/components/schemas/entityId'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- statementCreationDate:
- $ref: '#/components/schemas/date'
- statementAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- paymentDueDate:
- $ref: '#/components/schemas/date'
- statementMinimalDueAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- paymentType:
- $ref: '#/components/schemas/paymentType'
- paymentOption:
- $ref: '#/components/schemas/paymentOption'
- # ---------
+ ContractReference:
+ type: string
+ maxLength: 50
+ examples:
+ swiss:
+ value: CH3456789012345678901
+ custom:
+ value: ABC-56789012345
+ description: Functional reference to a customer relationship/contract that is responsible for the card, defined by the Card Service Provider.
+
+ PersonReference:
+ type: string
+ maxLength: 50
+ example: 123456789
+ description: Functional reference to a cardholder, defined by the Card Service Provider.
- # ---- Card Transaction ----
- cardTransaction:
- description: Transaction object adapted for card use
- type: object
- required:
- - cardTransactionId
- properties:
- cardTransactionId:
- type: string
- format: uuid
- example: d452083f-8316-410d-a609-d49463687329
- description: Uuid v4 of the specific transaction. Must not change when the status (approved, booked, etc.) is changed.
- approvalCode:
- type: string
- example: Please-Provide-Example-and-MaxLength
- description: Additional transaction identifier provided by schemes or processing system
- transactionTimestamp:
- $ref: '#/components/schemas/dateTime'
- originalCurrencyAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- targetCurrencyAmountt:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- exchangeRate:
- type: string
- example: "0.957"
- pattern: "[0-9][.][0-9]{1,10}"
- maxLength: 12
- exchangeRateDate:
- $ref: '#/components/schemas/date'
- merchant:
- type: object
- description: Merchant information of the card transaction
- properties:
- merchantName:
- type: string
- example: COOP PRONTO
- description: Value that contains the merchant name and location
- merchantLocation:
- type: string
- example: Zurich
- # Please maxLength
- description: Value that contains the merchant name and location
- merchantLocationLatitude:
- type: string
- example: "-35.253252"
- # Please regex
- description: Value that contains the merchant name and location
- merchantLocationLongitude:
- type: string
- example: "174.071674"
- # Please regex
- description: Value that contains the merchant name and location
- merchantCountry:
- $ref: '#/components/schemas/country'
- merchangeCategoryCode:
- type: string
- example: "5411"
- description: Value that contains the merchant category code as defined by ISO 18245
- posEntryMode:
- $ref: '#/components/schemas/posEntryMode'
- terminalId:
- type: string
- description: Identifier of the point of sale terminal
- #Please add example and regex
- channel:
- type: string
- description: Showing if it was a eCommerce transaction or not
- enum:
- - ecom
- - other
- offline:
- type: string
- description: Indicator if the transaction was offline authorized
- #Please add example and regex
- statementDate:
- type: string
- format: date
- example: '2018-08-03'
- description: Settlement date
- fees:
- type: array
- description: |-
- This array shows individual fee objects that are associated with the
- transaction. Please note that multiple fee objects can be transmitted.
- items:
- $ref: '#/components/schemas/cardTransactionFee'
- state:
- type: string
- example: authorised
- description: Used to identify if a transactions has been settled (booked) or just authorised
- transactionCategory:
- type: string
- example: merchant
- description: Transaction type identifying merchant to non-merchant entries
- enum:
- - merchant
- - fee
- - atm
- transactionType:
- $ref: '#/components/schemas/cardTransactionType'
- personId:
- $ref: '#/components/schemas/entityId'
- personName:
- type: object
- description: Name of the person
- properties:
- company:
- $ref: '#/components/schemas/entityName'
- name:
- $ref: '#/components/schemas/personName'
- surName:
- $ref: '#/components/schemas/personSurName'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- cardId:
- $ref: '#/components/schemas/entityId'
- walletProvider:
- type: string
- example: Apple Pay
- description: Identifier of the wallet provider if transaction was perfomred with a payment token (e.g. mobile payment such as Apple Pay)
- token:
- type: string
- example: "1234"
- maxLength: 4
- description: last 4 digits of the token
- tokenRequestorId:
- type: string
- example: "1234"
- maxLength: 4
- description: last 4 digits of the token
- # Is this a duplicate of token?
- securityLevelIndicator:
- type: string
- # Please provide example and regex
- description: Security Level Indicator provides additional information about 3DS, recurring transactions and other authentication related information
- actionCode:
- type: string
- example: "121"
- description: The Action Code provides information about the why a transaction was approved or declined
- # ---------
+ CardId:
+ type: string
+ maxLength: 50
+ example: 4321A1B2C3DE1234
+ description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals)
- # ---- Card Transaction Fee ----
- cardTransactionFee:
- description: Individual fee objects that are associated with the transaction
- type: object
- properties:
- type:
- type: string
- example: Bearbeitungsgebühr 1.75%
- description: Name of the fee
- amount:
- $ref: '#/components/schemas/amount'
- currency:
- $ref: '#/components/schemas/currency'
- # ---------
+ EmbossingLine1:
+ type: string
+ maxLength: 35
+ example: Peter Schweizer
+ description: First line embossed on the card to indicate the cardholder.
- # ---- Card Transaction Type ----
- cardTransactionType:
- type: object
- properties:
- acquiringType:
- type: string
- # Please provide example
- description: Provides further insight into the interface used
- financialMeaning:
- type: string
- # Please provide example
- description: Additional functional information about a transaction
- transactionReference:
- type: string
- # Please provide example
- description: Provides information about connecting a transaction to a previous occurred transaction. E.g. Storno
- # -------
+ EmbossingLine2:
+ type: string
+ maxLength: 35
+ example: Peter Schweizer
+ description: Second line embossed on the card to indicate the cardholder.
- # ---- Card POS Entry Mode ----
- posEntryMode:
- type: object
- description: The POS Entry Mode object contain multiple fields that further define how the transaction was captured at its point of origin including information about authentication, payment infrastructure and other related topics.
- properties:
- cardDataInputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardCaptureCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- operatingEnvironment:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personPresent:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardPresent:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardDataInputMode:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationMethod:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationEntity:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardDataOutputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- terminalOutputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- pinCaptureCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ Pan4Digits:
+ type: string
+ maxLength: 4 # TODO use pattern: '\d{4}' or number?
+ example: 4321
+ description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
- # ---- Person ----
- person:
- description: Person information .
- type: object
- required:
- - personId
- properties:
- personId:
- $ref: '#/components/schemas/entityId'
- contractId:
- $ref: '#/components/schemas/entityId'
- personType:
- $ref: '#/components/schemas/contractType'
- isMainPerson:
- type: boolean
- description: Flag to identify if the person is a main person
- example: true
- personStatistics:
- type: object
- properties:
- total_accounts:
- type: integer
- example: 1
- description: Total number of accounts of a private customer or a company
- totalActivAccounts:
- type: integer
- description: Total number of active accounts of a private customer or a company
- example: 2
- totalCards:
- type: integer
- example: 1
- description: Total number of cards of a private customer or a company
- totalActiveCards:
- type: integer
- description: Total number of active cards of a private customer or a company
- personDetail:
- type: object
- properties:
- salutation:
- $ref: '#/components/schemas/personSalutation'
- company:
- $ref: '#/components/schemas/entityName'
- name:
- $ref: '#/components/schemas/personName'
- surName:
- $ref: '#/components/schemas/personSurName'
- middleName:
- $ref: '#/components/schemas/personMiddleName'
- address:
- $ref: '#/components/schemas/structuredAddress'
- country:
- $ref: '#/components/schemas/country'
- language:
- $ref: '#/components/schemas/language'
- nationality:
- $ref: '#/components/schemas/country'
- birthDay:
- $ref: '#/components/schemas/date'
- gender:
- $ref: '#/components/schemas/personGender'
- permit:
- $ref: '#/components/schemas/personPermit'
- externalReferenceId:
- type: string
- maxLength: 30
- example: No1
- description: Reference id of company customers (e.g. employee number)
- amloCheck:
- type: boolean
- example: true
- description: Flag to show if the Anti-Money Laundering Ordinance has been already checked for this customer
- adPermission:
- type: boolean
- example: false
- description: Flag to see if the customer give his/her permission to marketing advertisement
- phoneNumber:
- type: array
- description: Phone numbers of the person
- items:
- $ref: '#/components/schemas/personPhoneNumber'
- email:
- type: array
- description: Email addresses of the person
- items:
- $ref: '#/components/schemas/personEmail'
- # ---------
-
- # ---- Card Contract ----
- cardContract:
- description: Card Contract Information .
- type: object
- required:
- - cardContractId
- properties:
- cardContractId:
- type: string
- format: uuid
- description: UUID v4 of the card contract
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
- openingDate:
- description: Date when the card contract was created
- type: string
- format: date
- example: 2018-04-13
- purgedDate:
- description: Date that indicates if and when this card contract was purged in the processor system
- type: string
- format: date
- example: 2018-04-13
- cardAccounts:
- type: array
- items:
- $ref: '#/components/schemas/cardAccount'
- personId:
- $ref: '#/components/schemas/entityId'
- contractType:
- $ref: '#/components/schemas/contractType'
- issuingPartnerId:
- $ref: '#/components/schemas/entityIdName'
- issuerId:
- $ref: '#/components/schemas/entityIdName'
- fulfillEntity:
- $ref: '#/components/schemas/entityName'
- contractStatus:
- $ref: '#/components/schemas/genericStatus'
- # ---------
-
- # TODO: define object with properties
- cardAccountbundle:
- description: Card Accountbundle Information.
- type: object
- required:
- - cardAccountbundleId
- properties:
- cardAccountbundleId:
- type: string
- format: uuid
- description: UUID v4 of the card accountbundle
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
+ ExpiryDate:
+ $ref: '#/components/schemas/Date'
+ description: Last day when the card is valid and can be used for payments.
+
+ InitialIssuingDate:
+ $ref: '#/components/schemas/Date'
+ description: Date when card was issued initially.
+
+ CardStatus:
+ type: string
+ enum: # TODO list all allowed values in enum
+ - ACTIVE
+ - SUSPENDED
+ - BLOCKED
+ example: ACTIVE
+ description: |
+ Effective status of the card to indicate whether it can be used for payments; definition of enums:
+ - active: authorizations are possible
+ - suspended: authorizations are temporarily not possible
+ - blocked: authorizations are permanently not possible because the card was cancelled or permanently blocked for other reasons
+
+ Currency:
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ swiss:
+ value: CHF
+ eu:
+ value: EUR
+ description: Settlement currency of the card / card account in ISO code format.
+
+ Image:
+ type: string
+ format: uri # TODO! specify custom openAPI format or use pattern according to RFC3986
+ example: https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
+ description: URL reference to an image for the design of the card.
+
+ ProductId:
+ type: string
+ maxLength: 50
+ example: 1234567
+ description: Identifier for the card product.
- # ---- Card API Model ----
- contractType:
- description: Type of a contract
+ ProductName:
+ type: string
+ maxLength: 100
+ examples:
+ basic:
+ value: A1
+ gold:
+ value: MC/VI Gold CHF
+ description: Name for the card product assigned by the issuer.
+
+ Scheme:
type: string
enum:
- - business
- - corporate
- - consumer
- example: consumer
- entityId:
- type: string
- format: uuid
- description: UUID of an entity
- example: 1b19aeb0-60db-4160-8551-c37de178ca10
- entityName:
- type: string
- maxLength: 70
- description: Name of an entity
- example: Abteilung B
- personSurName:
- type: string
- maxLength: 70
- description: Sur name of person
- example: Muster
- personMiddleName:
- type: string
- maxLength: 70
- description: Middle name of person
- example: Gustav
- personName:
- type: string
- maxLength: 70
- description: Name of person
- example: Max
- personGender:
+ - mastercard
+ - visa
+ - americanexpress
+ example: mastercard
+ description: Card network which is used to process payments with the card.
+
+ Category:
+ type: string
+ enum: # TODO list all allowed values in enum
+ - primary_card
+ - additional_card
+ example: primary_card
+ description: Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect of certain lifecycle use cases.
+
+ IssuingType:
+ type: string
+ enum: # TODO enum value and description do not match
+ - physical
+ - virtual
+ example: physical
+ description: |
+ Specifies in which form the card is issued; definition of enums:
+ - plastic: the card is being embossed on a physical material and delivered to the cardholder by mail
+ - virtual: the card is being issued only virtually for digital usage
+
+ ProductType:
type: string
enum:
- - male
- - female
- - other
- example: female
- description: Gender of the person.
- personSalutation:
+ - credit
+ - debit
+ - prepaid
+ example: credit
+ description: Type of the card product.
+
+ ProductLine:
type: string
enum:
- - none
- - mr
- - mrs
- - company
- - male_academic
- - female_academic
- - male_nobility
- - female_nobility
- - neutral
- example: mrs
- description: Salutation for the person.
- language:
+ - consumer
+ - business
+ - corporate
+ example: consumer
+ description: Customer segment to which the card is offered.
+
+ CardLimitCycle:
+ type: integer
+ format: int32
+ example: 2000
+ description: Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations in the current cycle.
+
+ CardLimitDaily:
+ type: integer
+ format: int32
+ example: 2000
+ description: Total amount of authorizations possible for the card per day in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations on the current day.
+
+ CardAccountId:
+ type: string
+ maxLength: 50
+ example: AB-4567890123456
+ description: Technical reference to the card account which is used to settle the transactions of the card; can be empty for debit cards which are settled directly to the bank account.
+
+ BankAccountReference:
+ type: string
+ maxLength: 34
+ pattern: # TODO can we use a pattern for iban or similar?
+ example: CH3456789012345678901
+ description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
+
+ IssuerId:
+ type: string
+ maxLength: 50
+ example: 123456789
+ description: Identifier for the legal issuer of a card; responsible towards the schemes for keeping the rules.
+
+ IssuerName:
+ type: string
+ maxLength: 100
+ examples:
+ viseca:
+ value: Viseca Card Services
+ ubs:
+ value: UBS
+ zkb:
+ value: Zürcher Kantonalbank
+ description: Name of the legal issuer of a card.
+
+ DistributionPartnerId:
+ type: string
+ maxLength: 50
+ example: 123456789
+ description: Identifier for the organization which is distributing / selling cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+
+ DistributionPartnerName:
+ type: string
+ maxLength: 100
+ example: Zürcher Kantonalbank
+ description: Name of the organization which is distributing / issuing cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+
+ Language:
type: string
- example: fr
- description: Language - for example, preferred contact language
enum:
- - de
- - fr
- - it
- - en
- personPermit:
- description: Permit of a person
- type: object
- required:
- - permitStatus
- properties:
- permitStatus:
- type: string
- example: B
- description: Permit status
- enum:
- - C
- - B
- - other
- permitSince:
- $ref: '#/components/schemas/date'
- personPhoneNumber:
- description: Phone number of a person
- type: object
- required:
- - phoneNumber
- properties:
- phoneNumberType:
- type: string
- example: mobile
- description: phone number type
- enum:
- - mobile
- - mobile private
- - mobile business
- - fixline
- - fixline private
- - fixline business
- - other
- emailAddress:
- type: string
- maxLength: 30
- example: max.muster@company.ch
- description: Email address
- personEmail:
- description: Email address of a person
- type: object
- required:
- - emailAddress
- properties:
- emailType:
- type: string
- example: personal
- description: Email type
- enum:
- - personal
- - business
- - other
- emailAddress:
- type: string
- maxLength: 30
- example: max.muster@company.ch
- description: Email address
- entityIdName:
- description: Issuing entity of the card
- type: object
- required:
- - issuingEntityId
- properties:
- issuingEntityId:
- $ref: '#/components/schemas/entityId'
- name:
- $ref: '#/components/schemas/entityName'
+ - DE
+ - EN
+ - FR
+ - IT
+ example: DE
+ description: Preferred language of the cardholder for any communication.
+
+ TokenId:
+ type: string
+ format: uuid # TODO special format of id possible?
+ maxLength: 50
+ example: eb404f8d-656b-4e51-8872-88c42fa55536
+ description: Unique identifier for the token of a card, defined by the Card Service Provider.
+
+ TokenPan4Digits:
+ type: string
+ maxLength: 4
+ example: 4321
+ description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
+
+ WalletId:
+ type: string
+ maxLength: 10
+ example: 123
+ description: Identifier for the wallet in which the token is used and managed.
+
+ WalletName:
+ type: string
+ enum:
+ - APPLE_PAY
+ - SAMSUNG_PAY
+ - GOOGLE_PAY
+ - GARMIN_PAY
+ example: APPLE_PAY
+ description: Name of the wallet in which the token is used and managed.
+
+ TokenRequestorId:
+ type: string
+ maxLength: 11
+ example: 1111111111 # TODO 11 digits?
+ description: Identifier for the token requestor / token service provider.
+
+ TokenRequestorName:
+ type: string
+ maxLength: 100
+ example: Zalando
+ description: Name of the token requestor / token service provider.
+
+ DeviceName:
+ type: string
+ maxLength: 100
+ example: Peter's iPhone
+ description: Name of the device which is associated to the token, only available for device-based tokens.
+
+ DeviceType:
+ type: string
+ maxLength: 100
+ example: IPHONE
+ description: Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
- paymentType:
+ FundingCardId:
+ type: string
+ maxLength: 50
+ example: 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
+ description: Reference to the card that is used to fund the transactions of the token.
+
+ TokenStatus:
+ type: string
+ enum: # TODO list all allowed values in enum
+ - ACTIVE
+ - SUSPENDED
+ - BLOCKED
+ - PENDING
+ example: ACTIVE
+ description: |
+ Effective status of the token to indicate whether it can be used for payments; definition of enums:
+ - active: authorizations are possible
+ - suspended: authorizations are temporarily not possible
+ - blocked: authorizations are permanently not possible because the token was cancelled
+ - pending: authorizations are not possible because the token is not fully issued or currently in transition between status
+
+ TokenIssuingDate:
+ $ref: '#/components/schemas/Date'
+ description: Date when the token was issued.
+
+ TokenScheme:
type: string
- example: lsv
- description: Identifier of the payment method selected by the person to settle the account.
enum:
- - lsv
- - debit_direct
- - esr
- - ipi
- - pos
- paymentOption:
+ - mastercard
+ - visa
+ - americanexpress
+ example: mastercard
+ description: Scheme for which the token is issued.
+
+ TransactionId:
+ type: string
+ format: uuid
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
+
+ AuthorizationId:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
+
+ TransactionDateTime:
+ $ref: '#/components/schemas/DateTime'
+ description: Date and time when transaction was authorized, always in CH timezone.
+
+ ValutaDate:
+ $ref: '#/components/schemas/Date'
+ description: Date when the transaction becomes effective on the card account for calculating interest.
+
+ StatementDate:
+ $ref: '#/components/schemas/Date'
+ description: Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
+
+ TransactionStatus:
type: string
- example: full
- description: Identifier of the payment plan selected by the person to pay for a bill.
enum:
- - full
- - instalment
- - revolving
-
- genericStatus:
- description:
- 'Describes the status of a card object.
- Effective: Aggregated effective status on the entity based on directly and inherited status.
- Directly: Directly applied status on the entity. Note: At a contract level effective status and direct status are the same.
- Inherited: Inherited status on the entity. Note: At a contract level there is no inherited status
- Last Change: Date of the last change of the effective status.'
- type: object
- required:
- - effective
- properties:
- effective:
- $ref: '#/components/schemas/genericStatusEnum'
- direct:
- $ref: '#/components/schemas/genericStatusEnum'
- inherited:
- $ref: '#/components/schemas/genericStatusEnum'
- last_change:
- $ref: '#/components/schemas/date'
- genericStatusEnum:
- description: Status element
- type: object
- required:
- - status
- properties:
- status:
- type: string
- enum:
- - ok
- - nok
- - unknown
- - active
- - blocked
- - suspended_by_person
- - suspended_by_bank
- - suspended_by_issuer
- description: Status type
- detail:
- type: string
- description: 'Status detail in custom text'
- # ---------
+ - authorized
+ - booked
+ example: authorized
+ description: |
+ Status of the transaction; definition of enums:
+ - authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
+ - booked: transaction was cleared/settled and charged to the card account
- # ---- Common Data Model v1.2.0
- # ---- Date Formats
- date:
+ ApprovalCode:
type: string
- format: date
- example: 2018-04-13
- dateTime:
+ maxLength: 6
+ example: 803051 # TODO always numbers?
+ description: Identifies a transaction from the entity that authorized it; in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
+
+ OriginalAmount:
+ type: number
+ example: 2000.05 # TODO use string and pattern? format: float?
+ description: Amount of the transaction in the currency used by the merchant.
+
+ OriginalCurrency:
type: string
- format: date-time
- example: 2018-04-13T11:11:11Z
- # --------
- # ---- Links for Pagination----
- linksPagination:
- description: Links (or cursors) returned in the answer of an API call.
- type: object
- properties:
- self:
- type: string
- description: Link / cursor to the current result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=75&limit=25
- first:
- type: string
- description: Link / cursor to the first result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=0&limit=25
- previous:
- type: string
- description: Link / cursor to the previous result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=50&limit=25
- next:
- type: string
- description: Link / cursor to the next result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=100&limit=25
- last:
- type: string
- description: Link / cursor to the last result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=150&limit=25
- # ---------
+ pattern: '^[a-zA-Z0-9]{3}$'
+ example: CHF
+ description: Currency of the card account on which the transaction is charged.
- # ---- Account objects from payment API ----
- paymentQrIbanAccount:
- title: Payment QR-IBAN Account
- type: object
- required:
- - type
- - identification
- properties:
- type:
- type: string
- description: IBAN or QR-IBAN of the creditor.
- enum:
- - "IBAN"
- - "QR_IBAN"
- identification:
- type: string
- maxLength: 34
- example: "CH9300762011623852957"
- pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"
- # ---------
-
- # ---- Currency ----
- currency:
- description: ISO 4217 code
+ TotalAmount:
+ type: number
+ example: 1957.50 # TODO use string and pattern? format: float?
+ description: Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees); positive amounts are debit transactions, negative amounts are credit transactions.
+
+ TransactionAmount:
+ type: number
+ example: 1952.50
+ description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
+
+ TransactionCurrency:
type: string
- pattern: '[A-Z]{3}'
+ pattern: '^[a-zA-Z0-9]{3}$'
example: CHF
- # ---------
+ description: Currency of the card account on which the transaction is charged.
- # ---- Payment Currency Amount compatible to SFTI XS2A API----
- paymentCurrencyAmount:
- title: Payment Currency-Amount
+ Fees:
+ title: # TODO optional
+ description: #TODO
type: object
required:
- - currency
- - amount
+ - # TODO Required in object?
properties:
- currency:
- $ref: '#/components/schemas/currency'
- amount:
- $ref: '#/components/schemas/amount'
+ fee_name:
+ $ref: '#/components/schemas/FeeName'
+ fee_percentage:
+ $ref: '#/components/schemas/FeePercentage'
+ fee_amount:
+ $ref: '#/components/schemas/FeeAmount'
+ fee_currency:
+ $ref: '#/components/schemas/FeeCurrency'
- # ---- Amount ----
- amount:
+ ExchangeRate:
+ type: number
+ example: 1.0485930
+ description: Exchange rate for converting the originalAmount into the transactionAmount.
+
+ ExchangeRateDate:
+ $ref: '#/components/schemas/Date'
+ description: Date which was used to determine the exchange rate, usually the valutaDate.
+
+ Description:
type: string
- description: Amount given with fractional digits, the separator is a dot
- pattern: "[0-9]{1,12}([.][0-9]{1,5})?"
- maxLength: 18
- example: "10.25"
- # --------
-
- # ---- Address compliant to payment address (b.Link & ISO20022)----
- structuredAddress:
- title: Structured Address
- type: object
- required:
- - streetName
- - postCode
- - townName
- - country
- properties:
- streetName:
- type: string
- maxLength: 70
- example: "Rue de la gare"
- buildingNumber:
- type: string
- maxLength: 16
- example: "24"
- postCode:
- type: string
- maxLength: 16
- example: "2501"
- townName:
- type: string
- maxLength: 35
- example: "Biel"
- country:
- type: string
- maxLength: 2
- example: "CH"
- # -----------
- # ---- Country Code ----
- country:
+ maxLength: 100
+ example: Aufladung
+ description: Description of the purpose of the transaction and potentially a reference to the merchant.
+
+ MerchantName:
+ type: string
+ maxLength: 100
+ example: Yallo
+ description: Name of the merchant who requested the transaction.
+
+ MerchantCountry:
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ example: CHE
+ description: Country in which the merchant is located.
+
+ MerchantCity:
+ type: string
+ maxLength: 50
+ example: Zurich
+ description: City in which the merchant is located.
+
+ Mcc:
+ type: string
+ maxLength: 4
+ example: 4812 # TODO zip code = numbers only?
+ description: Merchant Category Code to identify the industry branch of the merchant.
+
+ MccDescription:
+ type: string
+ maxLength: 100
+ example: Telco
+ description: Description for the mcc.
+
+ TerminalId:
+ type: string
+ maxLength: 8
+ example: 12345678
+ description: Identifier for the terminal which has read the card data.
+
+ CardAcceptorId:
+ type: string
+ maxLength: 15
+ example: 87040
+ description: Identifier for the merchant who requested the transaction.
+
+ AcquirerId:
+ type: string
+ maxLength: 11
+ example: 12345678901 # TODO exactly 11 digits?
+ description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
+
+ Channel:
+ type: string
+ enum:
+ - standard
+ - ecommerce
+ example: standard
+ description: Channel that was used by the cardholder for executing the transaction, allows the identification of eCommerce transactions.
+
+ TransactionCategory:
+ type: string
+ maxLength: 50
+ examples:
+ 100:
+ value: Cash withdrawal
+ 103:
+ value: ATM operator refund
+ 117:
+ value: P2P payment charge sender
+ 118:
+ value: P2P payment credit recipient "merchant", "fee", "atm"
+ description: Category of the transaction, defined by the Card Service Provider.
+
+ ReferenceTokenId: # TODO TokenId already in use
+ type: string
+ maxLength: 50
+ example: eb404f8d-656b-4e51-8872-88c42fa55536
+ description: Reference to the token that was used for the transaction, only present for token-based transactions.
+
+ CardholderId:
+ type: string
+ maxLength: 50
+ example: Peter Schweizer
+ description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
+
+ ReferenceCardAccountId: # TODO CardAccountId already in use
+ type: string
+ maxLength: 50
+ example: AB-4567890123456
+ description: Reference to the card account which is used to settle the transaction; not provided by all Card Service Providers.
+
+ ReferenceCardId: # TODO CardId already in use
+ type: string
+ maxLength: 50
+ example: 4321A1B2C3DE1234
+ description: Reference to the card that was used for the transaction.
+
+ TransactionReference:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
+
+ FeeName:
+ type: string
+ maxLength: 50
+ examples:
+ tip:
+ value: transactionTipAmount
+ surcharge:
+ value: transactionSurchargeAmount
+ description: Name of the fee that is charged for the transaction; value is defined by the Issuer.
+
+ FeePercentage:
+ type: number
+ example: 3.5% # TODO type example mismatch
+ description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
+
+ FeeAmount:
+ type: number
+ example: 5.00
+ description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
+
+ FeeCurrency:
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ example: CHF
+ description: Currency that is used for charging the fee, usually the same as the currency of the card account.
+
+ Date:
+ type: string
+ format: date
+ example: 2018-04-13
+
+ DateTime:
type: string
- pattern: '[A-Z]{2}'
- example: CH
- description: 2-Letter ISO 3166-2 Country Code
- # ------------
- # ---- Error Response (compliant to SIX b.Link)
- commonErrorResponse:
+ format: date-time
+ example: 2018-04-13T11:11:11Z
+
+ CommonErrorResponse:
title: Common Error Response
type: object
properties:
type:
- $ref: '#/components/schemas/commonErrorType'
+ $ref: '#/components/schemas/CommonErrorType'
title:
type: string
- example:
- This is the general problem description
+ example: This is the general problem description
detail:
type: string
- example:
- Detailed problem description with respect to the current request
+ example: Detailed problem description with respect to the current request
instance:
type: string
- example:
- path/to/corresponding/resource
+ example: path/to/corresponding/resource
- commonErrorType:
+ CommonErrorType:
title: Common Error Type
- description: Error Types for commonErrorResponse.
+ description: Error Types for CommonErrorResponse.
type: string
enum:
- /problems/INVALID_PAYLOAD
@@ -1616,328 +962,164 @@ components:
- /problems/TECHNICAL_ERROR
- /problems/NOT_IMPLEMENTED
- /problems/SERVICE_UNAVAILABLE
- example: '/problems/TECHNICAL_ERROR'
- # ---- End Error Response
- # ---- End Common Data Model
+ example: /problems/TECHNICAL_ERROR
- # ---- Global Common Header Parameters ----
parameters:
- clientid_in_header:
- in: header
- name: X-CorAPI-Client-ID
- schema:
- type: string
- description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
- required: true
-
- correlation_in_header:
- in: header
- name: X-Correlation-ID
- schema:
- type: string
- description: Unique ID (defined by the caller) which will be reflected back in the response.
- required: true
-
- agent_in_header:
- in: header
- name: User-Agent
- schema:
- type: string
- description: Name and version of the of the Client software
- required: true
-
- offset:
- name: offset
- in: query
- description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
- required: false
- schema:
- type: integer
- format: int32
- example: 25
- minimum: 0
-
- cardConsentId:
- in: header
- name: cardConsentId
- description: Identifier for a consent that must have been given to allow data access.
- required: true
- schema:
- type: string
-
- cardId:
- name: cardId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
- description: Card ID
-
- cardTokenId:
- name: cardTokenId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
- description: Card Token ID
-
- personId:
- name: personId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
- description: Person ID
-
- cardAccountId:
- name: cardAccountId
- in: query
- description: Uuid v4 of a specific existing card account
- required: true
- example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
- schema:
- type: string
- format: uuid
- card-accountbundleId:
- name: card-accountbundleId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- transactionId:
- name: transactionId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- statementId:
- name: statementId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- cardContractId:
- name: cardContractId
- in: query
- description: Uuid v4 of a specific existing card contract
- required: true
- example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
- schema:
- type: string
- format: uuid
-
- limit:
- name: limit
- in: query
- description: Optional parameter for pagination. Maximum number of entries to be returned.
- required: true
- schema:
- type: integer
- format: int32
- example: 25
- minimum: 1
-
- cursor:
- name: cursor
- in: query
- description: Optional parameter for pagination. An opaque string value used for pagination.
- required: false
- schema:
- type: string
- example: cursorIDxyz
-
- # ---- Responses - Standard Errors Common Data Model v1.2.2----
+ securitySchemes:
+ - ApiKeyAuth:
+ type: apiKey
+ in: header
+ name: X-API-KEY
+ - OAuth2:
+ type: oauth2
+ flows:
+ authorizationCode:
+ authorizationUrl: https://example.com/oauth/authorize
+ tokenUrl: https://example.com/oauth/token
+ scopes:
+ read: Grants read access
+ write: Grants write access
+
responses:
+ # TODO adjust description due to actual use in API, descriptions are generic from RFC
standard400:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Bad Request - The 400 (Bad Request) status code indicates that the server cannot or
+ will not process the request due to something that is perceived to be
+ a client error (e.g., malformed request syntax, invalid request
+ message framing, or deceptive request routing).
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard401:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Unauthorized - The request has not been applied because it provides no valid authentication credentials for the target resource.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard403:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Forbidden - The server understood the request but refuses to authorize it.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Forbidden - The 403 (Forbidden) status code indicates that the server understood
+ the request but refuses to authorize it. A server that wishes to
+ make public why the request has been forbidden can describe that
+ reason in the response payload (if any).
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard404:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Not Found - The 404 (Not Found) status code indicates that the origin server did
+ not find a current representation for the target resource or is not
+ willing to disclose that one exists. A 404 status code does not
+ indicate whether this lack of representation is temporary or
+ permanent; the 410 (Gone) status code is preferred over 404 if the
+ origin server knows, presumably through some configurable means, that
+ the condition is likely to be permanent.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard405:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Method Not Allowed - The 405 (Method Not Allowed) status code indicates that the method
+ received in the request-line is known by the origin server but not
+ supported by the target resource. The origin server MUST generate an
+ Allow header field in a 405 response containing a list of the target
+ resource's currently supported methods.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard500:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Internal Server Error - The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling
+ the request.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard501:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Not Implemented - The server does not support the functionality required to fulfill the request.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Not Implemented - The 501 (Not Implemented) status code indicates that the server does
+ not support the functionality required to fulfill the request. This
+ is the appropriate response when the server does not recognize the
+ request method and is not capable of supporting it for any resource.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
+ $ref: '#/components/schemas/CommonErrorResponse'
+
standard503:
headers:
Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
+ $ref: '#/components/headers/Content-Type'
Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
+ $ref: '#/components/headers/Content-Language'
+ description: |
+ Service Unavailable - The 503 (Service Unavailable) status code indicates that the server is currently unable to handle the request due to a temporary overload
+ or scheduled maintenance, which will likely be alleviated after some
+ delay. The server MAY send a Retry-After header field
+ (Section 7.1.3) to suggest an appropriate amount of time for the
+ client to wait before retrying the request.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/commonErrorResponse'
- # ---- End Responses - Standard Errors
+ $ref: '#/components/schemas/CommonErrorResponse'
+
+ headers:
+ Content-Language:
+ description: #TODO
+ schema:
+ type: string
+ example: en
+
+ Content-Type:
+ description: # TODO
+ schema:
+ type: string
+ example: application/problem+json; charset=utf-8 according to RFC7807
From 3f9a1cce8240b923d9446924699a4e58f67194e8 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Thu, 16 May 2024 17:05:36 +0200
Subject: [PATCH 02/29] fix style guide issues
---
cardInfoAPI.yaml | 112 +++++++++++++++++++++++------------------------
1 file changed, 56 insertions(+), 56 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 61d36d1..5a57560 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -3,7 +3,7 @@ info:
version: 0.7
title: Common Card Info API (Public)
description: >
- This specification defines a common card info API for payment cards used in Switzerland.
+ This specification defines a common card info API for payment cards used in Switzerland.
The API is supposed to be used to retrieve payment card infos (read only).
# TODO update description
contact:
@@ -37,8 +37,8 @@ paths:
get:
tags:
- Cards
- summary: # TODO
- description: # TODO
+ summary: # TODO
+ description: # TODO
parameters:
- in: query
name: contract_reference
@@ -72,7 +72,7 @@ paths:
$ref: '#/components/schemas/BankAccountReference'
responses:
'200':
- description: # TODO
+ description: # TODO
headers:
# TODO headers?
content:
@@ -101,8 +101,8 @@ paths:
get:
tags:
- Card-tokens
- summary: # TODO
- description: # TODO
+ summary: # TODO
+ description: # TODO
parameters:
- in: query
name: token_id
@@ -121,7 +121,7 @@ paths:
$ref: '#components/schemas/TokenStatus'
responses:
'200':
- description: # TODO
+ description: # TODO
headers:
# TODO headers?
content:
@@ -150,28 +150,28 @@ paths:
get:
tags:
- Card-tokens
- summary: # TODO
- description: # TODO
+ summary: # TODO
+ description: # TODO
parameters:
- - in: query
- name: transaction_id
- required: false
- schema:
- type: string
- maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
- - in: query
- name: authorization_id
- required: false
- schema:
- type: string
- maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c # TODO use unique values if not indicating same parameters to avoid confusions?
- description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
+ - in: query
+ name: transaction_id
+ required: false
+ schema:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
+ - in: query
+ name: authorization_id
+ required: false
+ schema:
+ type: string
+ maxLength: 50
+ example: 9e19df54-47cb-494b-84dc-1c126e95a05c # TODO use unique values if not indicating same parameters to avoid confusions?
+ description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
responses:
'200':
- description: # TODO
+ description: # TODO
headers:
# TODO headers?
content:
@@ -199,8 +199,8 @@ paths:
components:
schemas:
CardDetails:
- title: # TODO
- description: #TODO
+ title: # TODO
+ description: #TODO
type: object
required:
- contract_reference
@@ -281,8 +281,8 @@ components:
$ref: '#/components/schemas/Language'
CardTokenDetails:
- title: # TODO
- description: #TODO
+ title: # TODO
+ description: #TODO
type: object
required:
- token_id
@@ -320,8 +320,8 @@ components:
$ref: '#/components/schemas/TokenScheme'
TransactionDetails:
- title: # TODO
- description: #TODO
+ title: # TODO
+ description: #TODO
type: object
required:
- transaction_date_time
@@ -436,7 +436,7 @@ components:
Pan4Digits:
type: string
- maxLength: 4 # TODO use pattern: '\d{4}' or number?
+ maxLength: 4 # TODO use pattern: '\d{4}' or number?
example: 4321
description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
@@ -450,7 +450,7 @@ components:
CardStatus:
type: string
- enum: # TODO list all allowed values in enum
+ enum: # TODO list all allowed values in enum
- ACTIVE
- SUSPENDED
- BLOCKED
@@ -473,7 +473,7 @@ components:
Image:
type: string
- format: uri # TODO! specify custom openAPI format or use pattern according to RFC3986
+ format: uri # TODO! specify custom openAPI format or use pattern according to RFC3986
example: https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
description: URL reference to an image for the design of the card.
@@ -504,7 +504,7 @@ components:
Category:
type: string
- enum: # TODO list all allowed values in enum
+ enum: # TODO list all allowed values in enum
- primary_card
- additional_card
example: primary_card
@@ -512,7 +512,7 @@ components:
IssuingType:
type: string
- enum: # TODO enum value and description do not match
+ enum: # TODO enum value and description do not match
- physical
- virtual
example: physical
@@ -560,7 +560,7 @@ components:
BankAccountReference:
type: string
maxLength: 34
- pattern: # TODO can we use a pattern for iban or similar?
+ pattern: # TODO can we use a pattern for iban or similar?
example: CH3456789012345678901
description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
@@ -606,7 +606,7 @@ components:
TokenId:
type: string
- format: uuid # TODO special format of id possible?
+ format: uuid # TODO special format of id possible?
maxLength: 50
example: eb404f8d-656b-4e51-8872-88c42fa55536
description: Unique identifier for the token of a card, defined by the Card Service Provider.
@@ -636,7 +636,7 @@ components:
TokenRequestorId:
type: string
maxLength: 11
- example: 1111111111 # TODO 11 digits?
+ example: 1111111111 # TODO 11 digits?
description: Identifier for the token requestor / token service provider.
TokenRequestorName:
@@ -660,12 +660,12 @@ components:
FundingCardId:
type: string
maxLength: 50
- example: 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
+ example: 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
description: Reference to the card that is used to fund the transactions of the token.
TokenStatus:
type: string
- enum: # TODO list all allowed values in enum
+ enum: # TODO list all allowed values in enum
- ACTIVE
- SUSPENDED
- BLOCKED
@@ -730,12 +730,12 @@ components:
ApprovalCode:
type: string
maxLength: 6
- example: 803051 # TODO always numbers?
+ example: 803051 # TODO always numbers?
description: Identifies a transaction from the entity that authorized it; in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
OriginalAmount:
type: number
- example: 2000.05 # TODO use string and pattern? format: float?
+ example: 2000.05 # TODO use string and pattern? format: float?
description: Amount of the transaction in the currency used by the merchant.
OriginalCurrency:
@@ -746,7 +746,7 @@ components:
TotalAmount:
type: number
- example: 1957.50 # TODO use string and pattern? format: float?
+ example: 1957.50 # TODO use string and pattern? format: float?
description: Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees); positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
@@ -761,11 +761,11 @@ components:
description: Currency of the card account on which the transaction is charged.
Fees:
- title: # TODO optional
- description: #TODO
+ title: # TODO optional
+ description: #TODO
type: object
required:
- - # TODO Required in object?
+ - # TODO Required in object?
properties:
fee_name:
$ref: '#/components/schemas/FeeName'
@@ -812,7 +812,7 @@ components:
Mcc:
type: string
maxLength: 4
- example: 4812 # TODO zip code = numbers only?
+ example: 4812 # TODO zip code = numbers only?
description: Merchant Category Code to identify the industry branch of the merchant.
MccDescription:
@@ -836,7 +836,7 @@ components:
AcquirerId:
type: string
maxLength: 11
- example: 12345678901 # TODO exactly 11 digits?
+ example: 12345678901 # TODO exactly 11 digits?
description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
Channel:
@@ -861,7 +861,7 @@ components:
value: P2P payment credit recipient "merchant", "fee", "atm"
description: Category of the transaction, defined by the Card Service Provider.
- ReferenceTokenId: # TODO TokenId already in use
+ ReferenceTokenId: # TODO TokenId already in use
type: string
maxLength: 50
example: eb404f8d-656b-4e51-8872-88c42fa55536
@@ -873,13 +873,13 @@ components:
example: Peter Schweizer
description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
- ReferenceCardAccountId: # TODO CardAccountId already in use
+ ReferenceCardAccountId: # TODO CardAccountId already in use
type: string
maxLength: 50
example: AB-4567890123456
description: Reference to the card account which is used to settle the transaction; not provided by all Card Service Providers.
- ReferenceCardId: # TODO CardId already in use
+ ReferenceCardId: # TODO CardId already in use
type: string
maxLength: 50
example: 4321A1B2C3DE1234
@@ -903,7 +903,7 @@ components:
FeePercentage:
type: number
- example: 3.5% # TODO type example mismatch
+ example: 3.5% # TODO type example mismatch
description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
FeeAmount:
@@ -1113,13 +1113,13 @@ components:
headers:
Content-Language:
- description: #TODO
+ description: #TODO
schema:
type: string
example: en
Content-Type:
- description: # TODO
+ description: # TODO
schema:
type: string
example: application/problem+json; charset=utf-8 according to RFC7807
From 37bcf2d42d9cf81b2012fef8acf0ce84b94f0780 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Thu, 16 May 2024 17:07:24 +0200
Subject: [PATCH 03/29] change openapi action config file
---
.github/workflows/lint-openapi.yaml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/lint-openapi.yaml b/.github/workflows/lint-openapi.yaml
index a10e982..b87fef6 100644
--- a/.github/workflows/lint-openapi.yaml
+++ b/.github/workflows/lint-openapi.yaml
@@ -11,6 +11,6 @@ on:
jobs:
openapi-lint:
- uses: swissfintechinnovations/.github/.github/workflows/reusable-lint-openapi-workflow.yaml@main
+ uses: swissfintechinnovations/.github/.github/workflows/reusable-lint-openapi-workflow.yaml@naming-conventions-part-2
with:
filenames: ${{ github.event.inputs.filenames || '*.yaml' }}
\ No newline at end of file
From b4b90721b4a3c76c2e6c2ef1d8d2a4ca45648362 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Tue, 21 May 2024 13:56:28 +0200
Subject: [PATCH 04/29] add pagination, split endpoints, removed responses
---
cardInfoAPI.yaml | 843 ++++++++++++++++++++++++++++++-----------------
1 file changed, 537 insertions(+), 306 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 5a57560..76ad8d0 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -1,6 +1,6 @@
openapi: 3.1.0
info:
- version: 0.7
+ version: 0.7.0
title: Common Card Info API (Public)
description: >
This specification defines a common card info API for payment cards used in Switzerland.
@@ -20,11 +20,11 @@ externalDocs:
# TODO make more detailed description
tags:
- name: Cards
- description: Operations related with managing cards
+ description: Operations related with managing cards.
- name: Card-tokens
- description: Operations related with managing card tokens
+ description: Operations related with managing card tokens.
- name: Transactions
- description: Operations related with retrieving card transactions
+ description: Operations related with retrieving card transactions.
security:
- ApiKeyAuth: []
@@ -35,29 +35,24 @@ security:
paths:
/cards:
get:
- tags:
- - Cards
summary: # TODO
description: # TODO
+ tags:
+ - Cards
parameters:
- in: query
name: contract_reference
- required: true
+ required: false
schema:
$ref: '#/components/schemas/ContractReference'
- in: query
name: person_reference
- required: true
+ required: false
schema:
$ref: '#/components/schemas/PersonReference'
- - in: query
- name: card_id
- required: true
- schema:
- $ref: '#/components/schemas/CardId'
- in: query
name: card_status
- required: true
+ required: false
schema:
$ref: '#/components/schemas/CardStatus'
- in: query
@@ -70,6 +65,8 @@ paths:
required: false
schema:
$ref: '#/components/schemas/BankAccountReference'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
responses:
'200':
description: # TODO
@@ -78,47 +75,105 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/CardDetails'
- # TODO which standard error responses should be removed?
+ type: object
+ properties:
+ cardList:
+ type: array
+ items:
+ $ref: '#/components/schemas/CardDetails'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
'400':
$ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
- /card-tokens:
+ /cards/{cardId}:
get:
+ summary: # TODO
+ description: # TODO
tags:
- - Card-tokens
+ - Cards
+ parameters:
+ - in: path
+ name: cardId
+ required: true
+ schema:
+ $ref: '#/components/schemas/CardId'
+ responses:
+ '200':
+ description: # TODO
+ headers:
+ # TODO headers?
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CardDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /cards/{cardId}/card-tokens:
+ get:
summary: # TODO
description: # TODO
+ tags:
+ - Card-tokens
parameters:
- - in: query
- name: token_id
+ - in: path
+ name: cardId
required: true
schema:
- $ref: '#components/schemas/TokenId'
+ $ref: '#/components/schemas/CardId'
- in: query
name: funding_card_id
- required: true
schema:
- $ref: '#components/schemas/FundingCardId'
+ $ref: '#/components/schemas/FundingCardId'
- in: query
name: token_status
+ schema:
+ $ref: '#/components/schemas/TokenStatus'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: # TODO
+ headers:
+ # TODO headers?
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ cardList:
+ type: array
+ items:
+ $ref: '#/components/schemas/CardTokenDetails'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /cards/{cardId}/card-tokens/{tokenId}:
+ get:
+ summary: # TODO
+ description: # TODO
+ tags:
+ - Card-tokens
+ parameters:
+ - in: path
+ name: cardId
required: true
schema:
- $ref: '#components/schemas/TokenStatus'
+ $ref: '#/components/schemas/CardId'
+ - in: path
+ name: tokenId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TokenId'
responses:
'200':
description: # TODO
@@ -128,47 +183,58 @@ paths:
application/json:
schema:
$ref: '#/components/schemas/CardTokenDetails'
- # TODO which standard error responses should be removed?
'400':
$ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
/card-transactions:
get:
- tags:
- - Card-tokens
summary: # TODO
description: # TODO
+ tags:
+ - Transactions
parameters:
- in: query
- name: transaction_id
+ name: authorization_id
required: false
schema:
- type: string
- maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
- - in: query
+ $ref: '#/components/schemas/AuthorizationId'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ responses:
+ '200':
+ description: # TODO
+ headers:
+ # TODO headers?
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/TransactionDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /card-transactions/{transactionId}:
+ get:
+ summary: # TODO
+ description: # TODO
+ tags:
+ - Transactions
+ parameters:
+ - in: path
+ name: transactionId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TransactionId'
+ - in: query # TODO necessary?
name: authorization_id
required: false
schema:
- type: string
- maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c # TODO use unique values if not indicating same parameters to avoid confusions?
- description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
+ $ref: '#/components/schemas/AuthorizationId'
responses:
'200':
description: # TODO
@@ -177,30 +243,17 @@ paths:
content:
application/json:
schema:
- $ref: '#/components/schemas/CardTokenDetails'
- # TODO which standard error responses should be removed?
+ $ref: '#/components/schemas/TransactionDetails'
'400':
$ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
components:
schemas:
CardDetails:
- title: # TODO
- description: #TODO
+ title: Card details
+ description: # TODO
type: object
required:
- contract_reference
@@ -280,181 +333,195 @@ components:
language:
$ref: '#/components/schemas/Language'
- CardTokenDetails:
- title: # TODO
- description: #TODO
- type: object
- required:
- - token_id
- - token_pan_4_digits
- - token_requestor_id
- - token_requestor_name
- - funding_card_id
- - token_status
- - token_issuing_date
- - token_scheme
- properties:
- token_id:
- $ref: '#/components/schemas/TokenId'
- token_pan_4_digits:
- $ref: '#/components/schemas/TokenPan4Digits'
- wallet_id:
- $ref: '#/components/schemas/WalletId'
- wallet_name:
- $ref: '#/components/schemas/WalletName'
- token_requestor_id:
- $ref: '#/components/schemas/TokenRequestorId'
- token_requestor_name:
- $ref: '#/components/schemas/TokenRequestorName'
- device_name:
- $ref: '#/components/schemas/DeviceName'
- device_type:
- $ref: '#/components/schemas/DeviceType'
- funding_card_id:
- $ref: '#/components/schemas/FundingCardId'
- token_status:
- $ref: '#/components/schemas/TokenStatus'
- token_issuing_date:
- $ref: '#/components/schemas/TokenIssuingDate'
- token_scheme:
- $ref: '#/components/schemas/TokenScheme'
-
- TransactionDetails:
- title: # TODO
- description: #TODO
- type: object
- required:
- - transaction_date_time
- - valuta_date
- - transaction_status
- - original_amount
- - original_currency
- - total_amount
- - transaction_amount
- - transaction_currency
- - mcc
- - mcc_description
- - transaction_category
- - card_id
- properties:
- transaction_id:
- $ref: '#/components/schemas/TransactionId'
- authorization_id:
- $ref: '#/components/schemas/AuthorizationId'
- transaction_date_time:
- $ref: '#/components/schemas/TransactionDateTime'
- valuta_date:
- $ref: '#/components/schemas/ValutaDate'
- statement_date:
- $ref: '#/components/schemas/StatementDate'
- transaction_status:
- $ref: '#/components/schemas/TransactionStatus'
- approval_code:
- $ref: '#/components/schemas/ApprovalCode'
- original_amount:
- $ref: '#/components/schemas/OriginalAmount'
- original_currency:
- $ref: '#/components/schemas/OriginalCurrency'
- total_amount:
- $ref: '#/components/schemas/TotalAmount'
- transaction_amount:
- $ref: '#/components/schemas/TransactionAmount'
- transaction_currency:
- $ref: '#/components/schemas/TransactionCurrency'
- fees:
- $ref: '#/components/schemas/Fees'
- exchange_rate:
- $ref: '#/components/schemas/ExchangeRate'
- exchange_rate_date:
- $ref: '#/components/schemas/ExchangeRateDate'
- description:
- $ref: '#/components/schemas/Description'
- merchant_name:
- $ref: '#/components/schemas/MerchantName'
- merchant_country:
- $ref: '#/components/schemas/MerchantCountry'
- merchant_city:
- $ref: '#/components/schemas/MerchantCity'
- mcc:
- $ref: '#/components/schemas/Mcc'
- mcc_description:
- $ref: '#/components/schemas/MccDescription'
- terminal_id:
- $ref: '#/components/schemas/TerminalId'
- card_acceptor_id:
- $ref: '#/components/schemas/CardAcceptorId'
- acquirer_id:
- $ref: '#/components/schemas/AcquirerId'
- channel:
- $ref: '#/components/schemas/Channel'
- transaction_category:
- $ref: '#/components/schemas/TransactionCategory'
- token_id:
- $ref: '#/components/schemas/ReferenceTokenId'
- cardholder_id:
- $ref: '#/components/schemas/CardholderId'
- card_account_id:
- $ref: '#/components/schemas/ReferenceCardAccountId'
- card_id:
- $ref: '#/components/schemas/ReferenceCardId'
- transaction_reference:
- $ref: '#/components/schemas/TransactionReference'
+ CardTokenDetails:
+ title: Card token details
+ description: #TODO
+ type: object
+ required:
+ - token_id
+ - token_pan_4_digits
+ - token_requestor_id
+ - token_requestor_name
+ - funding_card_id
+ - token_status
+ - token_issuing_date
+ - token_scheme
+ properties:
+ token_id:
+ $ref: '#/components/schemas/TokenId'
+ token_pan_4_digits:
+ $ref: '#/components/schemas/TokenPan4Digits'
+ wallet_id:
+ $ref: '#/components/schemas/WalletId'
+ wallet_name:
+ $ref: '#/components/schemas/WalletName'
+ token_requestor_id:
+ $ref: '#/components/schemas/TokenRequestorId'
+ token_requestor_name:
+ $ref: '#/components/schemas/TokenRequestorName'
+ device_name:
+ $ref: '#/components/schemas/DeviceName'
+ device_type:
+ $ref: '#/components/schemas/DeviceType'
+ funding_card_id:
+ $ref: '#/components/schemas/FundingCardId'
+ token_status:
+ $ref: '#/components/schemas/TokenStatus'
+ token_issuing_date:
+ $ref: '#/components/schemas/TokenIssuingDate'
+ token_scheme:
+ $ref: '#/components/schemas/TokenScheme'
+
+ TransactionDetails:
+ title: Transaction details
+ description: #TODO
+ type: object
+ required:
+ - transaction_date_time
+ - valuta_date
+ - transaction_status
+ - original_amount
+ - original_currency
+ - total_amount
+ - transaction_amount
+ - transaction_currency
+ - mcc
+ - mcc_description
+ - transaction_category
+ - card_id
+ properties:
+ transaction_id:
+ $ref: '#/components/schemas/TransactionId'
+ authorization_id:
+ $ref: '#/components/schemas/AuthorizationId'
+ transaction_date_time:
+ $ref: '#/components/schemas/TransactionDateTime'
+ valuta_date:
+ $ref: '#/components/schemas/ValutaDate'
+ statement_date:
+ $ref: '#/components/schemas/StatementDate'
+ transaction_status:
+ $ref: '#/components/schemas/TransactionStatus'
+ approval_code:
+ $ref: '#/components/schemas/ApprovalCode'
+ original_amount:
+ $ref: '#/components/schemas/OriginalAmount'
+ original_currency:
+ $ref: '#/components/schemas/OriginalCurrency'
+ total_amount:
+ $ref: '#/components/schemas/TotalAmount'
+ transaction_amount:
+ $ref: '#/components/schemas/TransactionAmount'
+ transaction_currency:
+ $ref: '#/components/schemas/TransactionCurrency'
+ fees:
+ $ref: '#/components/schemas/Fees'
+ exchange_rate:
+ $ref: '#/components/schemas/ExchangeRate'
+ exchange_rate_date:
+ $ref: '#/components/schemas/ExchangeRateDate'
+ description:
+ $ref: '#/components/schemas/Description'
+ merchant_name:
+ $ref: '#/components/schemas/MerchantName'
+ merchant_country:
+ $ref: '#/components/schemas/MerchantCountry'
+ merchant_city:
+ $ref: '#/components/schemas/MerchantCity'
+ mcc:
+ $ref: '#/components/schemas/Mcc'
+ mcc_description:
+ $ref: '#/components/schemas/MccDescription'
+ terminal_id:
+ $ref: '#/components/schemas/TerminalId'
+ card_acceptor_id:
+ $ref: '#/components/schemas/CardAcceptorId'
+ acquirer_id:
+ $ref: '#/components/schemas/AcquirerId'
+ channel:
+ $ref: '#/components/schemas/Channel'
+ transaction_category:
+ $ref: '#/components/schemas/TransactionCategory'
+ token_id:
+ $ref: '#/components/schemas/ReferenceTokenId'
+ cardholder_id:
+ $ref: '#/components/schemas/CardholderId'
+ card_account_id:
+ $ref: '#/components/schemas/ReferenceCardAccountId'
+ card_id:
+ $ref: '#/components/schemas/ReferenceCardId'
+ transaction_reference:
+ $ref: '#/components/schemas/TransactionReference'
ContractReference:
+ title: Contract reference
type: string
maxLength: 50
examples:
- swiss:
- value: CH3456789012345678901
- custom:
- value: ABC-56789012345
+ - CH3456789012345678901
+ - ABC-56789012345
description: Functional reference to a customer relationship/contract that is responsible for the card, defined by the Card Service Provider.
PersonReference:
+ title: Person reference
type: string
maxLength: 50
- example: 123456789
+ examples:
+ - 123456789
description: Functional reference to a cardholder, defined by the Card Service Provider.
-
+
CardId:
+ title: Card id
type: string
maxLength: 50
- example: 4321A1B2C3DE1234
+ examples:
+ - 4321A1B2C3DE1234
description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals)
EmbossingLine1:
+ title: Embossing line 1
type: string
maxLength: 35
- example: Peter Schweizer
+ examples:
+ - Peter Schweizer
description: First line embossed on the card to indicate the cardholder.
EmbossingLine2:
+ title: Embossing line 2
type: string
maxLength: 35
- example: Peter Schweizer
+ examples:
+ - Peter Schweizer
description: Second line embossed on the card to indicate the cardholder.
Pan4Digits:
+ title: Pan 4 digits
type: string
- maxLength: 4 # TODO use pattern: '\d{4}' or number?
- example: 4321
+ maxLength: 4
+ pattern: '^\d{4}$'
+ examples:
+ - 4321
description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
ExpiryDate:
+ title: Expiry date
$ref: '#/components/schemas/Date'
description: Last day when the card is valid and can be used for payments.
InitialIssuingDate:
+ title: Initial issuing date
$ref: '#/components/schemas/Date'
description: Date when card was issued initially.
CardStatus:
+ title: Card status
type: string
- enum: # TODO list all allowed values in enum
+ enum:
- ACTIVE
- SUSPENDED
- BLOCKED
- example: ACTIVE
+ examples:
+ - ACTIVE
description: |
Effective status of the card to indicate whether it can be used for payments; definition of enums:
- active: authorizations are possible
@@ -465,32 +532,32 @@ components:
type: string
pattern: '^[a-zA-Z0-9]{3}$'
examples:
- swiss:
- value: CHF
- eu:
- value: EUR
+ - CHF
+ - EUR
description: Settlement currency of the card / card account in ISO code format.
Image:
type: string
format: uri # TODO! specify custom openAPI format or use pattern according to RFC3986
- example: https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
+ examples:
+ - https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
description: URL reference to an image for the design of the card.
ProductId:
+ title: Product id
type: string
maxLength: 50
- example: 1234567
+ examples:
+ - 1234567
description: Identifier for the card product.
ProductName:
+ title: Product name
type: string
maxLength: 100
examples:
- basic:
- value: A1
- gold:
- value: MC/VI Gold CHF
+ - A1
+ - MC/VI Gold CHF
description: Name for the card product assigned by the issuer.
Scheme:
@@ -499,99 +566,119 @@ components:
- mastercard
- visa
- americanexpress
- example: mastercard
- description: Card network which is used to process payments with the card.
+ - dinersclub
+ examples:
+ - mastercard
+ description: Card network which is used to process payments with the card in switzerland.
Category:
type: string
- enum: # TODO list all allowed values in enum
+ enum:
- primary_card
- additional_card
- example: primary_card
+ examples:
+ - primary_card
description: Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect of certain lifecycle use cases.
IssuingType:
+ title: Issuing type
type: string
- enum: # TODO enum value and description do not match
+ enum:
- physical
- virtual
- example: physical
+ examples:
+ - physical
description: |
Specifies in which form the card is issued; definition of enums:
- - plastic: the card is being embossed on a physical material and delivered to the cardholder by mail
+ - physical: the card is being embossed on a physical material and delivered to the cardholder by mail
- virtual: the card is being issued only virtually for digital usage
ProductType:
+ title: Product type
type: string
enum:
- credit
- debit
- prepaid
- example: credit
+ examples:
+ - credit
description: Type of the card product.
ProductLine:
+ title: Product line
type: string
enum:
- consumer
- business
- corporate
- example: consumer
+ examples:
+ - consumer
description: Customer segment to which the card is offered.
CardLimitCycle:
+ title: Card limit cycle
type: integer
format: int32
- example: 2000
+ examples:
+ - 2000
description: Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations in the current cycle.
CardLimitDaily:
+ title: Card limit daily
type: integer
format: int32
- example: 2000
+ examples:
+ - 2000
description: Total amount of authorizations possible for the card per day in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations on the current day.
CardAccountId:
+ title: Card account id
type: string
maxLength: 50
- example: AB-4567890123456
+ examples:
+ - AB-4567890123456
description: Technical reference to the card account which is used to settle the transactions of the card; can be empty for debit cards which are settled directly to the bank account.
BankAccountReference:
+ title: Bank account reference
type: string
maxLength: 34
- pattern: # TODO can we use a pattern for iban or similar?
- example: CH3456789012345678901
+ examples:
+ - CH3456789012345678901
description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
IssuerId:
+ title: Issuer id
type: string
maxLength: 50
- example: 123456789
+ examples:
+ - 123456789
description: Identifier for the legal issuer of a card; responsible towards the schemes for keeping the rules.
IssuerName:
+ title: Issuer name
type: string
maxLength: 100
examples:
- viseca:
- value: Viseca Card Services
- ubs:
- value: UBS
- zkb:
- value: Zürcher Kantonalbank
+ - Viseca Card Services
+ - UBS
+ - Zürcher Kantonalbank
description: Name of the legal issuer of a card.
DistributionPartnerId:
+ title: Distribution partner id
type: string
maxLength: 50
- example: 123456789
+ examples:
+ - 123456789
description: Identifier for the organization which is distributing / selling cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
DistributionPartnerName:
+ title: Distribution partner name
type: string
maxLength: 100
- example: Zürcher Kantonalbank
+ examples:
+ - Zürcher Kantonalbank
description: Name of the organization which is distributing / issuing cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
Language:
@@ -601,76 +688,97 @@ components:
- EN
- FR
- IT
- example: DE
+ examples:
+ - DE
description: Preferred language of the cardholder for any communication.
TokenId:
+ title: Token id
type: string
format: uuid # TODO special format of id possible?
maxLength: 50
- example: eb404f8d-656b-4e51-8872-88c42fa55536
+ examples:
+ - eb404f8d-656b-4e51-8872-88c42fa55536
description: Unique identifier for the token of a card, defined by the Card Service Provider.
TokenPan4Digits:
+ title: Token pan 4 digits
type: string
maxLength: 4
- example: 4321
+ examples:
+ - 4321
description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
WalletId:
+ title: Wallet id
type: string
maxLength: 10
- example: 123
+ examples:
+ - 123
description: Identifier for the wallet in which the token is used and managed.
WalletName:
+ title: Wallet name
type: string
enum:
- APPLE_PAY
- SAMSUNG_PAY
- GOOGLE_PAY
- GARMIN_PAY
- example: APPLE_PAY
+ examples:
+ - APPLE_PAY
description: Name of the wallet in which the token is used and managed.
TokenRequestorId:
+ title: Token requestor id
type: string
maxLength: 11
- example: 1111111111 # TODO 11 digits?
+ examples:
+ - 1111111111 # TODO 11 digits?
description: Identifier for the token requestor / token service provider.
TokenRequestorName:
+ title: Token requestor name
type: string
maxLength: 100
- example: Zalando
+ examples:
+ - Zalando
description: Name of the token requestor / token service provider.
DeviceName:
+ title: Device name
type: string
maxLength: 100
- example: Peter's iPhone
+ examples:
+ - Peter's iPhone
description: Name of the device which is associated to the token, only available for device-based tokens.
DeviceType:
+ title: Device type
type: string
maxLength: 100
- example: IPHONE
+ examples:
+ - IPHONE
description: Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
FundingCardId:
+ title: Funding card id
type: string
maxLength: 50
- example: 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
+ examples:
+ - 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
description: Reference to the card that is used to fund the transactions of the token.
TokenStatus:
+ title: Token status
type: string
enum: # TODO list all allowed values in enum
- ACTIVE
- SUSPENDED
- BLOCKED
- PENDING
- example: ACTIVE
+ examples:
+ - ACTIVE
description: |
Effective status of the token to indicate whether it can be used for payments; definition of enums:
- active: authorizations are possible
@@ -679,89 +787,113 @@ components:
- pending: authorizations are not possible because the token is not fully issued or currently in transition between status
TokenIssuingDate:
+ title: Token issuing date
$ref: '#/components/schemas/Date'
description: Date when the token was issued.
TokenScheme:
+ title: Token scheme
type: string
enum:
- mastercard
- visa
- americanexpress
- example: mastercard
+ examples:
+ - mastercard
description: Scheme for which the token is issued.
TransactionId:
+ title: Transaction id
type: string
format: uuid
maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
AuthorizationId:
+ title: Authorization id
type: string
maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
TransactionDateTime:
+ title: Transaction date-time
$ref: '#/components/schemas/DateTime'
description: Date and time when transaction was authorized, always in CH timezone.
ValutaDate:
+ title: Valuta date
$ref: '#/components/schemas/Date'
description: Date when the transaction becomes effective on the card account for calculating interest.
StatementDate:
+ title: Statement date
$ref: '#/components/schemas/Date'
description: Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
TransactionStatus:
+ title: Transaction status
type: string
enum:
- authorized
- booked
- example: authorized
+ examples:
+ - authorized
description: |
Status of the transaction; definition of enums:
- authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
- booked: transaction was cleared/settled and charged to the card account
ApprovalCode:
+ title: Approval code
type: string
maxLength: 6
- example: 803051 # TODO always numbers?
+ examples:
+ - 803051 # TODO always numbers?
description: Identifies a transaction from the entity that authorized it; in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
OriginalAmount:
+ title: Original amount
type: number
- example: 2000.05 # TODO use string and pattern? format: float?
+ examples:
+ - 2000.05 # TODO use string and pattern? format: float?
description: Amount of the transaction in the currency used by the merchant.
OriginalCurrency:
+ title: Original currency
type: string
pattern: '^[a-zA-Z0-9]{3}$'
- example: CHF
+ examples:
+ - CHF
description: Currency of the card account on which the transaction is charged.
TotalAmount:
+ title: Total amount
type: number
- example: 1957.50 # TODO use string and pattern? format: float?
+ examples:
+ - 1957.50 # TODO use string and pattern? format: float?
description: Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees); positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
+ title: Transaction amount
type: number
- example: 1952.50
+ examples:
+ - 1952.50
description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
TransactionCurrency:
+ title: TransactionC currency
type: string
pattern: '^[a-zA-Z0-9]{3}$'
- example: CHF
+ examples:
+ - CHF
description: Currency of the card account on which the transaction is charged.
Fees:
- title: # TODO optional
+ title: Fees
description: #TODO
type: object
required:
@@ -777,66 +909,85 @@ components:
$ref: '#/components/schemas/FeeCurrency'
ExchangeRate:
+ title: Exchange rate
type: number
- example: 1.0485930
+ examples:
+ - 1.0485930
description: Exchange rate for converting the originalAmount into the transactionAmount.
ExchangeRateDate:
+ title: Exchange rate date
$ref: '#/components/schemas/Date'
description: Date which was used to determine the exchange rate, usually the valutaDate.
Description:
type: string
maxLength: 100
- example: Aufladung
+ examples:
+ - Aufladung
description: Description of the purpose of the transaction and potentially a reference to the merchant.
MerchantName:
+ title: Merchant name
type: string
maxLength: 100
- example: Yallo
+ examples:
+ - Yallo
description: Name of the merchant who requested the transaction.
MerchantCountry:
+ title: Merchant country
type: string
pattern: '^[a-zA-Z0-9]{3}$'
- example: CHE
+ examples:
+ - CHE
description: Country in which the merchant is located.
MerchantCity:
+ title: Merchant city
type: string
maxLength: 50
- example: Zurich
+ examples:
+ - Zurich
description: City in which the merchant is located.
Mcc:
type: string
maxLength: 4
- example: 4812 # TODO zip code = numbers only?
+ examples:
+ - 4812 # TODO zip code = numbers only?
description: Merchant Category Code to identify the industry branch of the merchant.
MccDescription:
+ title: Mcc description
type: string
maxLength: 100
- example: Telco
+ examples:
+ - Telco
description: Description for the mcc.
TerminalId:
+ title: Terminal id
type: string
maxLength: 8
- example: 12345678
+ examples:
+ - 12345678
description: Identifier for the terminal which has read the card data.
CardAcceptorId:
+ title: Card acceptor id
type: string
maxLength: 15
- example: 87040
+ examples:
+ - 87040
description: Identifier for the merchant who requested the transaction.
AcquirerId:
+ title: Acquirer id
type: string
maxLength: 11
- example: 12345678901 # TODO exactly 11 digits?
+ examples:
+ - 12345678901 # TODO exactly 11 digits?
description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
Channel:
@@ -844,88 +995,139 @@ components:
enum:
- standard
- ecommerce
- example: standard
+ examples:
+ - standard
description: Channel that was used by the cardholder for executing the transaction, allows the identification of eCommerce transactions.
TransactionCategory:
+ title: Transaction category
type: string
maxLength: 50
examples:
- 100:
- value: Cash withdrawal
- 103:
- value: ATM operator refund
- 117:
- value: P2P payment charge sender
- 118:
- value: P2P payment credit recipient "merchant", "fee", "atm"
+ - '100: Cash withdrawal'
+ - '103: ATM operator refund'
+ - '117: P2P payment charge sender'
+ - '118: P2P payment credit recipient "merchant", "fee", "atm"'
description: Category of the transaction, defined by the Card Service Provider.
ReferenceTokenId: # TODO TokenId already in use
+ title: Reference token id
type: string
maxLength: 50
- example: eb404f8d-656b-4e51-8872-88c42fa55536
+ examples:
+ - eb404f8d-656b-4e51-8872-88c42fa55536
description: Reference to the token that was used for the transaction, only present for token-based transactions.
CardholderId:
+ title: Cardholder id
type: string
maxLength: 50
- example: Peter Schweizer
+ examples:
+ - Peter Schweizer
description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
ReferenceCardAccountId: # TODO CardAccountId already in use
+ title: Reference card account id
type: string
maxLength: 50
- example: AB-4567890123456
+ examples:
+ - AB-4567890123456
description: Reference to the card account which is used to settle the transaction; not provided by all Card Service Providers.
ReferenceCardId: # TODO CardId already in use
+ title: Reference card id
type: string
maxLength: 50
- example: 4321A1B2C3DE1234
+ examples:
+ - 4321A1B2C3DE1234
description: Reference to the card that was used for the transaction.
TransactionReference:
+ title: Transaction reference
type: string
maxLength: 50
- example: 9e19df54-47cb-494b-84dc-1c126e95a05c
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
description: Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
FeeName:
+ title: Fee name
type: string
maxLength: 50
examples:
- tip:
- value: transactionTipAmount
- surcharge:
- value: transactionSurchargeAmount
+ - transactionTipAmount
+ - transactionSurchargeAmount
description: Name of the fee that is charged for the transaction; value is defined by the Issuer.
FeePercentage:
+ title: Fee percentage
type: number
- example: 3.5% # TODO type example mismatch
+ examples:
+ - 3.5% # TODO type example mismatch
description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
FeeAmount:
+ title: Fee amount
type: number
- example: 5.00
+ examples:
+ - 5.00
description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
FeeCurrency:
+ title: Fee currency
type: string
pattern: '^[a-zA-Z0-9]{3}$'
- example: CHF
+ examples:
+ - CHF
description: Currency that is used for charging the fee, usually the same as the currency of the card account.
Date:
type: string
format: date
- example: 2018-04-13
+ examples:
+ - 2018-04-13
DateTime:
+ title: Date-time
type: string
format: date-time
- example: 2018-04-13T11:11:11Z
+ examples:
+ - 2018-04-13T11:11:11Z
+
+ linksPagination:
+ description: Links (or cursors) returned in the answer of an API call.
+ type: object
+ properties:
+ self:
+ type: string
+ format: uri
+ description: Link / cursor to the current result set (based on the submitted pagination approach)
+ examples:
+ - /card-app/api/v1/products?offset=75&limit=25
+ first:
+ type: string
+ format: uri
+ description: Link / cursor to the first result set (based on the submitted pagination approach)
+ examples:
+ - /card-app/api/v1/products?offset=0&limit=25
+ previous:
+ type: string
+ format: uri
+ description: Link / cursor to the previous result set (based on the submitted pagination approach)
+ examples:
+ - /card-app/api/v1/products?offset=50&limit=25
+ next:
+ type: string
+ format: uri
+ description: Link / cursor to the next result set (based on the submitted pagination approach)
+ examples:
+ - /card-app/api/v1/products?offset=100&limit=25
+ last:
+ type: string
+ format: uri
+ description: Link / cursor to the last result set (based on the submitted pagination approach)
+ examples:
+ - /card-app/api/v1/products?offset=150&limit=25
CommonErrorResponse:
title: Common Error Response
@@ -935,13 +1137,16 @@ components:
$ref: '#/components/schemas/CommonErrorType'
title:
type: string
- example: This is the general problem description
+ examples:
+ - This is the general problem description
detail:
type: string
- example: Detailed problem description with respect to the current request
+ examples:
+ - Detailed problem description with respect to the current request
instance:
type: string
- example: path/to/corresponding/resource
+ examples:
+ - path/to/corresponding/resource
CommonErrorType:
title: Common Error Type
@@ -962,16 +1167,40 @@ components:
- /problems/TECHNICAL_ERROR
- /problems/NOT_IMPLEMENTED
- /problems/SERVICE_UNAVAILABLE
- example: /problems/TECHNICAL_ERROR
+ examples:
+ - /problems/TECHNICAL_ERROR
parameters:
+ limit:
+ name: limit
+ in: query
+ description: Optional parameter for pagination. Maximum number of entries to be returned.
+ required: false
+ schema:
+ type: integer
+ format: int32
+ minimum: 1
+ examples:
+ - 25
+
+ offset:
+ name: offset
+ in: query
+ description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
+ required: false
+ schema:
+ type: integer
+ format: int32
+ minimum: 0
+ examples:
+ - 25
securitySchemes:
- - ApiKeyAuth:
+ ApiKeyAuth:
type: apiKey
in: header
- name: X-API-KEY
- - OAuth2:
+ name: X-API-Key
+ OAuth2:
type: oauth2
flows:
authorizationCode:
@@ -1116,10 +1345,12 @@ components:
description: #TODO
schema:
type: string
- example: en
+ examples:
+ - en
Content-Type:
description: # TODO
schema:
type: string
- example: application/problem+json; charset=utf-8 according to RFC7807
+ examples:
+ - application/problem+json; charset=utf-8 according to RFC7807
From 5d9a2eafdbfcc8d298c4fce93675f1976a084294 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Tue, 21 May 2024 14:57:15 +0200
Subject: [PATCH 05/29] refactor multiple usage of parameters
---
cardInfoAPI.yaml | 53 ++++++++++++++++++++++++------------------------
1 file changed, 27 insertions(+), 26 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 76ad8d0..c31949b 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -95,11 +95,7 @@ paths:
tags:
- Cards
parameters:
- - in: path
- name: cardId
- required: true
- schema:
- $ref: '#/components/schemas/CardId'
+ - $ref: '#/components/parameters/path_cardId'
responses:
'200':
description: # TODO
@@ -121,11 +117,7 @@ paths:
tags:
- Card-tokens
parameters:
- - in: path
- name: cardId
- required: true
- schema:
- $ref: '#/components/schemas/CardId'
+ - $ref: '#/components/parameters/path_cardId'
- in: query
name: funding_card_id
schema:
@@ -164,16 +156,8 @@ paths:
tags:
- Card-tokens
parameters:
- - in: path
- name: cardId
- required: true
- schema:
- $ref: '#/components/schemas/CardId'
- - in: path
- name: tokenId
- required: true
- schema:
- $ref: '#/components/schemas/TokenId'
+ - $ref: '#/components/parameters/path_cardId'
+ - $ref: '#/components/parameters/path_tokenId'
responses:
'200':
description: # TODO
@@ -225,11 +209,7 @@ paths:
tags:
- Transactions
parameters:
- - in: path
- name: transactionId
- required: true
- schema:
- $ref: '#/components/schemas/TransactionId'
+ - $ref: '#/components/parameters/path_transactionId'
- in: query # TODO necessary?
name: authorization_id
required: false
@@ -538,7 +518,7 @@ components:
Image:
type: string
- format: uri # TODO! specify custom openAPI format or use pattern according to RFC3986
+ format: uri
examples:
- https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
description: URL reference to an image for the design of the card.
@@ -1171,6 +1151,27 @@ components:
- /problems/TECHNICAL_ERROR
parameters:
+ path_cardId:
+ in: path
+ name: cardId
+ required: true
+ schema:
+ $ref: '#/components/schemas/CardId'
+
+ path_tokenId:
+ in: path
+ name: tokenId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TokenId'
+
+ path_transactionId:
+ in: path
+ name: transactionId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TransactionId'
+
limit:
name: limit
in: query
From 0f47dc8d2e57e30dd69543de0be039e3376b3563 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Fri, 24 May 2024 11:33:11 +0200
Subject: [PATCH 06/29] Update cardInfoAPI.yaml
Added missing descriptions up to line 357
---
cardInfoAPI.yaml | 64 ++++++++++++++++++++++++------------------------
1 file changed, 32 insertions(+), 32 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index c31949b..d1517af 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -1,11 +1,11 @@
openapi: 3.1.0
info:
version: 0.7.0
- title: Common Card Info API (Public)
+ title: Common Card API (Public)
description: >
- This specification defines a common card info API for payment cards used in Switzerland.
- The API is supposed to be used to retrieve payment card infos (read only).
- # TODO update description
+ This specification defines a common card API for payment cards used in Switzerland.
+ The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
+ # TODO update description - proposal Christian
contact:
email: info@common-api.ch
license:
@@ -17,14 +17,14 @@ externalDocs:
description: Find out more about SFTI API specifications
url: https://www.common-api.ch
-# TODO make more detailed description
+# TODO make more detailed description - proposal Christian
tags:
- name: Cards
- description: Operations related with managing cards.
+ description: Operations for retrieving information about payment cards.
- name: Card-tokens
- description: Operations related with managing card tokens.
+ description: Operations for retrieving information about tokens associated with payment cards.
- name: Transactions
- description: Operations related with retrieving card transactions.
+ description: Operations for retrieving information about transactions and authorizations done with payment cards or tokens.
security:
- ApiKeyAuth: []
@@ -35,8 +35,8 @@ security:
paths:
/cards:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
+ description: This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - proposal Christian
tags:
- Cards
parameters:
@@ -69,7 +69,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: # TODO
+ description: One or multiple payment cards were found which match the query parameters. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
headers:
# TODO headers?
content:
@@ -90,15 +90,15 @@ paths:
/cards/{cardId}:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a single card which matches the id. # TODO - proposal Christian
+ description: This operation enables the retrieval of a single payment card when the cardId is already known.
The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
responses:
'200':
- description: # TODO
+ description: Single payment card was found. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -112,14 +112,14 @@ paths:
/cards/{cardId}/card-tokens:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
+ description: This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
- $ref: '#/components/parameters/path_cardId'
- in: query
- name: funding_card_id
+ name: funding_card_id # TODO shouldn't be needed, is the same as cardId
schema:
$ref: '#/components/schemas/FundingCardId'
- in: query
@@ -130,7 +130,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: # TODO
+ description: One or multiple tokens which exist for the referenced card. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
headers:
# TODO headers?
content:
@@ -151,8 +151,8 @@ paths:
/cards/{cardId}/card-tokens/{tokenId}:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
+ description: This operation enables the retrieval of a single token when the cardId and tokenId are already known.
The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
@@ -160,7 +160,7 @@ paths:
- $ref: '#/components/parameters/path_tokenId'
responses:
'200':
- description: # TODO
+ description: Single token was found. # TODO
headers:
# TODO headers?
content:
@@ -174,11 +174,11 @@ paths:
/card-transactions:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a list of transactions which match the provided query parameters. # TODO - proposal Christian
+ description: This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
tags:
- Transactions
- parameters:
+ parameters: # TODO further parameters to be added
- in: query
name: authorization_id
required: false
@@ -188,7 +188,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: # TODO
+ description: One or multiple transactions were found which match the query parameters. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -204,20 +204,20 @@ paths:
/card-transactions/{transactionId}:
get:
- summary: # TODO
- description: # TODO
+ summary: Provides a single transaction which matches the transactionId # TODO - proposal Christian
+ description: This operation enables the retrieval of a single transaction when the transactionId is already known.
The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
- - in: query # TODO necessary?
+ - in: query # TODO necessary? yes, but to be discussed whether it should be a separate endpoint or one path parameter can cover transactionId or authorizationId
name: authorization_id
required: false
schema:
$ref: '#/components/schemas/AuthorizationId'
responses:
'200':
- description: # TODO
+ description: Single token was found. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -233,7 +233,7 @@ components:
schemas:
CardDetails:
title: Card details
- description: # TODO
+ description: Describes a payment card with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- contract_reference
@@ -315,7 +315,7 @@ components:
CardTokenDetails:
title: Card token details
- description: #TODO
+ description: Describes a token with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- token_id
@@ -354,7 +354,7 @@ components:
TransactionDetails:
title: Transaction details
- description: #TODO
+ description: Describes a transaction with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- transaction_date_time
From 196bb2615cec366e82016467ebb62d783c5d62d2 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 11:31:25 +0200
Subject: [PATCH 07/29] feedback card workshop
---
cardInfoAPI.yaml | 260 +++++++++++++++++------------------------------
1 file changed, 92 insertions(+), 168 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index d1517af..9723b9f 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -35,8 +35,11 @@ security:
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
- description: This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - proposal Christian
+ summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
+ description: |
+ This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
+ In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
+ The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - proposal Christian
tags:
- Cards
parameters:
@@ -110,20 +113,21 @@ paths:
'500':
$ref: '#/components/responses/standard500'
- /cards/{cardId}/card-tokens:
+ /card-tokens:
get:
summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
description: This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
- - $ref: '#/components/parameters/path_cardId'
- in: query
- name: funding_card_id # TODO shouldn't be needed, is the same as cardId
+ name: card_id
+ required: false
schema:
- $ref: '#/components/schemas/FundingCardId'
+ $ref: '#/components/schemas/CardId'
- in: query
name: token_status
+ required: false
schema:
$ref: '#/components/schemas/TokenStatus'
- $ref: '#/components/parameters/limit'
@@ -149,15 +153,19 @@ paths:
'500':
$ref: '#/components/responses/standard500'
- /cards/{cardId}/card-tokens/{tokenId}:
+ /card-tokens/{tokenId}:
get:
summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
description: This operation enables the retrieval of a single token when the cardId and tokenId are already known.
The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
- - $ref: '#/components/parameters/path_cardId'
- $ref: '#/components/parameters/path_tokenId'
+ - in: query
+ name: card_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardId'
responses:
'200':
description: Single token was found. # TODO
@@ -178,12 +186,47 @@ paths:
description: This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
tags:
- Transactions
- parameters: # TODO further parameters to be added
+ parameters:
+ - in: query
+ name: authorization_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/AuthorizationReference'
- in: query
- name: authorization_id
+ name: clearing_reference
required: false
schema:
- $ref: '#/components/schemas/AuthorizationId'
+ $ref: '#/components/schemas/ClearingReference'
+ - in: query
+ name: card_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardId'
+ - in: query
+ name: token_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/TokenId'
+ - in: query
+ name: from_date
+ required: false
+ schema:
+ $ref: '#/components/schemas/DateTime'
+ - in: query
+ name: to_date
+ required: false
+ schema:
+ $ref: '#/components/schemas/DateTime'
+ - in: query
+ name: status
+ required: false
+ schemas:
+ $ref: '#/components/schemas/TransactionStatus'
+ - in: query
+ name: original_currency
+ required: false
+ schemas:
+ $ref: '#/components/schemas/OriginalCurrency'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
@@ -210,11 +253,6 @@ paths:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
- - in: query # TODO necessary? yes, but to be discussed whether it should be a separate endpoint or one path parameter can cover transactionId or authorizationId
- name: authorization_id
- required: false
- schema:
- $ref: '#/components/schemas/AuthorizationId'
responses:
'200':
description: Single token was found. # TODO - proposal Christian
@@ -357,14 +395,12 @@ components:
description: Describes a transaction with its relevant characteristics. # TODO - proposal Christian
type: object
required:
+ - transaction_id
- transaction_date_time
- valuta_date
- transaction_status
- original_amount
- original_currency
- - total_amount
- - transaction_amount
- - transaction_currency
- mcc
- mcc_description
- transaction_category
@@ -372,8 +408,10 @@ components:
properties:
transaction_id:
$ref: '#/components/schemas/TransactionId'
- authorization_id:
- $ref: '#/components/schemas/AuthorizationId'
+ authorization_reference:
+ $ref: '#/components/schemas/AuthorizationReference'
+ clearing_reference:
+ $ref: '#/components/schemas/ClearingReference'
transaction_date_time:
$ref: '#/components/schemas/TransactionDateTime'
valuta_date:
@@ -423,13 +461,13 @@ components:
transaction_category:
$ref: '#/components/schemas/TransactionCategory'
token_id:
- $ref: '#/components/schemas/ReferenceTokenId'
+ $ref: '#/components/schemas/TokenId'
cardholder_id:
$ref: '#/components/schemas/CardholderId'
card_account_id:
- $ref: '#/components/schemas/ReferenceCardAccountId'
+ $ref: '#/components/schemas/CardAccountId'
card_id:
- $ref: '#/components/schemas/ReferenceCardId'
+ $ref: '#/components/schemas/CardId'
transaction_reference:
$ref: '#/components/schemas/TransactionReference'
@@ -714,7 +752,7 @@ components:
type: string
maxLength: 11
examples:
- - 1111111111 # TODO 11 digits?
+ - 11111111111
description: Identifier for the token requestor / token service provider.
TokenRequestorName:
@@ -746,13 +784,13 @@ components:
type: string
maxLength: 50
examples:
- - 4321A1B2C3DE1234 # TODO use unique values if not indicating same parameters to avoid confusions?
+ - 4321A1B2C3DE1234
description: Reference to the card that is used to fund the transactions of the token.
TokenStatus:
title: Token status
type: string
- enum: # TODO list all allowed values in enum
+ enum:
- ACTIVE
- SUSPENDED
- BLOCKED
@@ -789,15 +827,23 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for booked transactions; Id does not overlap with authorizationId; at least one of authorizationId or transactionId is always present.
+ description: UUID to link AuthorizationReference and ClearingReference. # TODO - proposal Dominik
+
+ AuthorizationReference:
+ title: Authorization reference
+ type: string
+ maxLength: 50
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
- AuthorizationId:
- title: Authorization id
+ ClearingReference:
+ title: Clearing reference
type: string
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for authorized transactions; Id does not overlap with transactionId; at least one of authorizationId or transactionId is always present.
+ description: Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
TransactionDateTime:
title: Transaction date-time
@@ -830,16 +876,16 @@ components:
ApprovalCode:
title: Approval code
type: string
- maxLength: 6
+ pattern: '^\d{6}$'
examples:
- - 803051 # TODO always numbers?
+ - '803051'
description: Identifies a transaction from the entity that authorized it; in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
OriginalAmount:
title: Original amount
type: number
examples:
- - 2000.05 # TODO use string and pattern? format: float?
+ - 2000.05
description: Amount of the transaction in the currency used by the merchant.
OriginalCurrency:
@@ -854,7 +900,7 @@ components:
title: Total amount
type: number
examples:
- - 1957.50 # TODO use string and pattern? format: float?
+ - 1957.50
description: Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees); positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
@@ -865,7 +911,7 @@ components:
description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
TransactionCurrency:
- title: TransactionC currency
+ title: Transaction currency
type: string
pattern: '^[a-zA-Z0-9]{3}$'
examples:
@@ -935,7 +981,7 @@ components:
type: string
maxLength: 4
examples:
- - 4812 # TODO zip code = numbers only?
+ - 4812
description: Merchant Category Code to identify the industry branch of the merchant.
MccDescription:
@@ -967,7 +1013,7 @@ components:
type: string
maxLength: 11
examples:
- - 12345678901 # TODO exactly 11 digits?
+ - 12345678901
description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
Channel:
@@ -990,14 +1036,6 @@ components:
- '118: P2P payment credit recipient "merchant", "fee", "atm"'
description: Category of the transaction, defined by the Card Service Provider.
- ReferenceTokenId: # TODO TokenId already in use
- title: Reference token id
- type: string
- maxLength: 50
- examples:
- - eb404f8d-656b-4e51-8872-88c42fa55536
- description: Reference to the token that was used for the transaction, only present for token-based transactions.
-
CardholderId:
title: Cardholder id
type: string
@@ -1006,22 +1044,6 @@ components:
- Peter Schweizer
description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
- ReferenceCardAccountId: # TODO CardAccountId already in use
- title: Reference card account id
- type: string
- maxLength: 50
- examples:
- - AB-4567890123456
- description: Reference to the card account which is used to settle the transaction; not provided by all Card Service Providers.
-
- ReferenceCardId: # TODO CardId already in use
- title: Reference card id
- type: string
- maxLength: 50
- examples:
- - 4321A1B2C3DE1234
- description: Reference to the card that was used for the transaction.
-
TransactionReference:
title: Transaction reference
type: string
@@ -1043,8 +1065,8 @@ components:
title: Fee percentage
type: number
examples:
- - 3.5% # TODO type example mismatch
- description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
+ - 3.5
+ description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers. # TODO 3.5 = 3.5%
FeeAmount:
title: Fee amount
@@ -1151,12 +1173,12 @@ components:
- /problems/TECHNICAL_ERROR
parameters:
- path_cardId:
- in: path
- name: cardId
- required: true
- schema:
- $ref: '#/components/schemas/CardId'
+# path_cardId:
+# in: path
+# name: cardId
+# required: true
+# schema:
+# $ref: '#/components/schemas/CardId'
path_tokenId:
in: path
@@ -1229,71 +1251,6 @@ components:
schema:
$ref: '#/components/schemas/CommonErrorResponse'
- standard401:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Unauthorized - The request has not been applied because it provides no valid authentication credentials for the target resource.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
- standard403:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Forbidden - The 403 (Forbidden) status code indicates that the server understood
- the request but refuses to authorize it. A server that wishes to
- make public why the request has been forbidden can describe that
- reason in the response payload (if any).
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
- standard404:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Not Found - The 404 (Not Found) status code indicates that the origin server did
- not find a current representation for the target resource or is not
- willing to disclose that one exists. A 404 status code does not
- indicate whether this lack of representation is temporary or
- permanent; the 410 (Gone) status code is preferred over 404 if the
- origin server knows, presumably through some configurable means, that
- the condition is likely to be permanent.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
- standard405:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Method Not Allowed - The 405 (Method Not Allowed) status code indicates that the method
- received in the request-line is known by the origin server but not
- supported by the target resource. The origin server MUST generate an
- Allow header field in a 405 response containing a list of the target
- resource's currently supported methods.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
standard500:
headers:
Content-Type:
@@ -1308,39 +1265,6 @@ components:
schema:
$ref: '#/components/schemas/CommonErrorResponse'
- standard501:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Not Implemented - The 501 (Not Implemented) status code indicates that the server does
- not support the functionality required to fulfill the request. This
- is the appropriate response when the server does not recognize the
- request method and is not capable of supporting it for any resource.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
- standard503:
- headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
- Content-Language:
- $ref: '#/components/headers/Content-Language'
- description: |
- Service Unavailable - The 503 (Service Unavailable) status code indicates that the server is currently unable to handle the request due to a temporary overload
- or scheduled maintenance, which will likely be alleviated after some
- delay. The server MAY send a Retry-After header field
- (Section 7.1.3) to suggest an appropriate amount of time for the
- client to wait before retrying the request.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
headers:
Content-Language:
description: #TODO
From 76559a480bb01e6470344cd972d7d6a453badc77 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 12:05:23 +0200
Subject: [PATCH 08/29] typos
---
cardInfoAPI.yaml | 56 ++++++++++++++++++++++++------------------------
1 file changed, 28 insertions(+), 28 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 9723b9f..c655bdc 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -35,7 +35,7 @@ security:
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
+ summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
description: |
This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
@@ -72,7 +72,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple payment cards were found which match the query parameters. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
+ description: One or multiple payment cards were found which match the query parameters. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
headers:
# TODO headers?
content:
@@ -93,15 +93,15 @@ paths:
/cards/{cardId}:
get:
- summary: Provides a single card which matches the id. # TODO - proposal Christian
- description: This operation enables the retrieval of a single payment card when the cardId is already known.
The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
+ summary: Provides a single card which matches the id. # TODO - proposal Christian
+ description: This operation enables the retrieval of a single payment card when the cardId is already known.
The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
responses:
'200':
- description: Single payment card was found. # TODO - proposal Christian
+ description: Single payment card was found. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -115,8 +115,8 @@ paths:
/card-tokens:
get:
- summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
- description: This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
+ summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
+ description: This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
@@ -134,7 +134,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple tokens which exist for the referenced card. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
+ description: One or multiple tokens which exist for the referenced card. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
headers:
# TODO headers?
content:
@@ -155,7 +155,7 @@ paths:
/card-tokens/{tokenId}:
get:
- summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
+ summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
description: This operation enables the retrieval of a single token when the cardId and tokenId are already known.
The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Card-tokens
@@ -182,8 +182,8 @@ paths:
/card-transactions:
get:
- summary: Provides a list of transactions which match the provided query parameters. # TODO - proposal Christian
- description: This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
+ summary: Provides a list of transactions which match the provided query parameters. # TODO - proposal Christian
+ description: This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
tags:
- Transactions
parameters:
@@ -220,18 +220,18 @@ paths:
- in: query
name: status
required: false
- schemas:
+ schema:
$ref: '#/components/schemas/TransactionStatus'
- in: query
name: original_currency
required: false
- schemas:
+ schema:
$ref: '#/components/schemas/OriginalCurrency'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple transactions were found which match the query parameters. # TODO - proposal Christian
+ description: One or multiple transactions were found which match the query parameters. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -247,15 +247,15 @@ paths:
/card-transactions/{transactionId}:
get:
- summary: Provides a single transaction which matches the transactionId # TODO - proposal Christian
- description: This operation enables the retrieval of a single transaction when the transactionId is already known.
The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
+ summary: Provides a single transaction which matches the transactionId # TODO - proposal Christian
+ description: This operation enables the retrieval of a single transaction when the transactionId is already known.
The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
responses:
'200':
- description: Single token was found. # TODO - proposal Christian
+ description: Single token was found. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -271,7 +271,7 @@ components:
schemas:
CardDetails:
title: Card details
- description: Describes a payment card with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a payment card with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- contract_reference
@@ -353,7 +353,7 @@ components:
CardTokenDetails:
title: Card token details
- description: Describes a token with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a token with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- token_id
@@ -392,7 +392,7 @@ components:
TransactionDetails:
title: Transaction details
- description: Describes a transaction with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a transaction with its relevant characteristics. # TODO - proposal Christian
type: object
required:
- transaction_id
@@ -827,7 +827,7 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: UUID to link AuthorizationReference and ClearingReference. # TODO - proposal Dominik
+ description: UUID to link AuthorizationReference and ClearingReference. # TODO - proposal Dominik
AuthorizationReference:
title: Authorization reference
@@ -843,7 +843,7 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ description: Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
TransactionDateTime:
title: Transaction date-time
@@ -1173,12 +1173,12 @@ components:
- /problems/TECHNICAL_ERROR
parameters:
-# path_cardId:
-# in: path
-# name: cardId
-# required: true
-# schema:
-# $ref: '#/components/schemas/CardId'
+ path_cardId:
+ in: path
+ name: cardId
+ required: true
+ schema:
+ $ref: '#/components/schemas/CardId'
path_tokenId:
in: path
From 7df13cf7fa38663f768e5dbd0c18a6233d674c64 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 12:10:14 +0200
Subject: [PATCH 09/29] add yaml multiline style
---
cardInfoAPI.yaml | 24 ++++++++++++++++++------
1 file changed, 18 insertions(+), 6 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index c655bdc..b304b19 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -94,14 +94,16 @@ paths:
/cards/{cardId}:
get:
summary: Provides a single card which matches the id. # TODO - proposal Christian
- description: This operation enables the retrieval of a single payment card when the cardId is already known.
The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
+ description: >
+ This operation enables the retrieval of a single payment card when the cardId is already known.
+ The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
responses:
'200':
- description: Single payment card was found. # TODO - proposal Christian
+ description: Single payment card was found. # TODO - proposal Christian
headers:
# TODO headers?
content:
@@ -116,7 +118,10 @@ paths:
/card-tokens:
get:
summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
- description: This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
+ description: >
+ This operation enables the retrieval of a list of tokens associated with a payment card.
+ The tokens can be filtered further by status.
+ Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
@@ -156,7 +161,9 @@ paths:
/card-tokens/{tokenId}:
get:
summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
- description: This operation enables the retrieval of a single token when the cardId and tokenId are already known.
The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
+ description: >
+ This operation enables the retrieval of a single token when the cardId and tokenId are already known.T
+ The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Card-tokens
parameters:
@@ -183,7 +190,10 @@ paths:
/card-transactions:
get:
summary: Provides a list of transactions which match the provided query parameters. # TODO - proposal Christian
- description: This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
+ description: >
+ This operation enables the retrieval of a list of transactions performed with a payment card or token.
+ Different query parameters are provided to support an efficient retrieval of individual transactions.
+ With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
tags:
- Transactions
parameters:
@@ -248,7 +258,9 @@ paths:
/card-transactions/{transactionId}:
get:
summary: Provides a single transaction which matches the transactionId # TODO - proposal Christian
- description: This operation enables the retrieval of a single transaction when the transactionId is already known.
The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
+ description: >
+ his operation enables the retrieval of a single transaction when the transactionId is already known.
+ The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
tags:
- Transactions
parameters:
From 6be26245d4c03edeee02b518b8549d008e78052e Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 12:13:24 +0200
Subject: [PATCH 10/29] fix yaml lint issues
---
cardInfoAPI.yaml | 26 +++++++++++++-------------
1 file changed, 13 insertions(+), 13 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index b304b19..8ee0b6c 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -175,7 +175,7 @@ paths:
$ref: '#/components/schemas/CardId'
responses:
'200':
- description: Single token was found. # TODO
+ description: Single token was found. # TODO
headers:
# TODO headers?
content:
@@ -528,7 +528,7 @@ components:
title: Pan 4 digits
type: string
maxLength: 4
- pattern: '^\d{4}$'
+ pattern: '^\d{4}$'
examples:
- 4321
description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
@@ -618,8 +618,8 @@ components:
- virtual
examples:
- physical
- description: |
- Specifies in which form the card is issued; definition of enums:
+ description: >
+ Specifies in which form the card is issued; definition of enums:
- physical: the card is being embossed on a physical material and delivered to the cardholder by mail
- virtual: the card is being issued only virtually for digital usage
@@ -847,7 +847,7 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ description: Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
ClearingReference:
title: Clearing reference
@@ -880,10 +880,10 @@ components:
- booked
examples:
- authorized
- description: |
- Status of the transaction; definition of enums:
- - authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
- - booked: transaction was cleared/settled and charged to the card account
+ description: >
+ Status of the transaction; definition of enums:
+ - authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
+ - booked: transaction was cleared/settled and charged to the card account
ApprovalCode:
title: Approval code
@@ -932,7 +932,7 @@ components:
Fees:
title: Fees
- description: #TODO
+ description: # TODO
type: object
required:
- # TODO Required in object?
@@ -1078,7 +1078,7 @@ components:
type: number
examples:
- 3.5
- description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers. # TODO 3.5 = 3.5%
+ description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers. # TODO 3.5 = 3.5%
FeeAmount:
title: Fee amount
@@ -1244,7 +1244,7 @@ components:
scopes:
read: Grants read access
write: Grants write access
-
+
responses:
# TODO adjust description due to actual use in API, descriptions are generic from RFC
standard400:
@@ -1279,7 +1279,7 @@ components:
headers:
Content-Language:
- description: #TODO
+ description: # TODO
schema:
type: string
examples:
From 5901d927a36391523a8f58c39fb6f40f14ca891b Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 12:53:01 +0200
Subject: [PATCH 11/29] fix openAPI linter issues
---
cardInfoAPI.yaml | 46 +++++++++++++++++++++++-----------------------
1 file changed, 23 insertions(+), 23 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 8ee0b6c..86f9e2e 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -85,7 +85,7 @@ paths:
items:
$ref: '#/components/schemas/CardDetails'
_links:
- $ref: '#/components/schemas/linksPagination'
+ $ref: '#/components/schemas/LinksPagination'
'400':
$ref: '#/components/responses/standard400'
'500':
@@ -152,7 +152,7 @@ paths:
items:
$ref: '#/components/schemas/CardTokenDetails'
_links:
- $ref: '#/components/schemas/linksPagination'
+ $ref: '#/components/schemas/LinksPagination'
'400':
$ref: '#/components/responses/standard400'
'500':
@@ -497,7 +497,7 @@ components:
type: string
maxLength: 50
examples:
- - 123456789
+ - '123456789'
description: Functional reference to a cardholder, defined by the Card Service Provider.
CardId:
@@ -506,7 +506,7 @@ components:
maxLength: 50
examples:
- 4321A1B2C3DE1234
- description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals)
+ description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals).
EmbossingLine1:
title: Embossing line 1
@@ -530,7 +530,7 @@ components:
maxLength: 4
pattern: '^\d{4}$'
examples:
- - 4321
+ - '4321'
description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
ExpiryDate:
@@ -578,7 +578,7 @@ components:
type: string
maxLength: 50
examples:
- - 1234567
+ - '1234567'
description: Identifier for the card product.
ProductName:
@@ -682,7 +682,7 @@ components:
type: string
maxLength: 50
examples:
- - 123456789
+ - '123456789'
description: Identifier for the legal issuer of a card; responsible towards the schemes for keeping the rules.
IssuerName:
@@ -700,7 +700,7 @@ components:
type: string
maxLength: 50
examples:
- - 123456789
+ - '123456789'
description: Identifier for the organization which is distributing / selling cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
DistributionPartnerName:
@@ -736,7 +736,7 @@ components:
type: string
maxLength: 4
examples:
- - 4321
+ - '4321'
description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
WalletId:
@@ -744,7 +744,7 @@ components:
type: string
maxLength: 10
examples:
- - 123
+ - '123'
description: Identifier for the wallet in which the token is used and managed.
WalletName:
@@ -764,7 +764,7 @@ components:
type: string
maxLength: 11
examples:
- - 11111111111
+ - '11111111111'
description: Identifier for the token requestor / token service provider.
TokenRequestorName:
@@ -993,7 +993,7 @@ components:
type: string
maxLength: 4
examples:
- - 4812
+ - '4812'
description: Merchant Category Code to identify the industry branch of the merchant.
MccDescription:
@@ -1009,7 +1009,7 @@ components:
type: string
maxLength: 8
examples:
- - 12345678
+ - '12345678'
description: Identifier for the terminal which has read the card data.
CardAcceptorId:
@@ -1025,7 +1025,7 @@ components:
type: string
maxLength: 11
examples:
- - 12345678901
+ - '12345678901'
description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
Channel:
@@ -1045,7 +1045,7 @@ components:
- '100: Cash withdrawal'
- '103: ATM operator refund'
- '117: P2P payment charge sender'
- - '118: P2P payment credit recipient "merchant", "fee", "atm"'
+ - '118: P2P payment credit recipient "merchant", "fee", "atm"' # TODO example more than 50 chars
description: Category of the transaction, defined by the Card Service Provider.
CardholderId:
@@ -1108,38 +1108,38 @@ components:
examples:
- 2018-04-13T11:11:11Z
- linksPagination:
+ LinksPagination:
description: Links (or cursors) returned in the answer of an API call.
type: object
properties:
self:
type: string
format: uri
- description: Link / cursor to the current result set (based on the submitted pagination approach)
+ description: Link / cursor to the current result set (based on the submitted pagination approach).
examples:
- /card-app/api/v1/products?offset=75&limit=25
first:
type: string
format: uri
- description: Link / cursor to the first result set (based on the submitted pagination approach)
+ description: Link / cursor to the first result set (based on the submitted pagination approach).
examples:
- /card-app/api/v1/products?offset=0&limit=25
previous:
type: string
format: uri
- description: Link / cursor to the previous result set (based on the submitted pagination approach)
+ description: Link / cursor to the previous result set (based on the submitted pagination approach).
examples:
- /card-app/api/v1/products?offset=50&limit=25
next:
type: string
format: uri
- description: Link / cursor to the next result set (based on the submitted pagination approach)
+ description: Link / cursor to the next result set (based on the submitted pagination approach).
examples:
- /card-app/api/v1/products?offset=100&limit=25
last:
type: string
format: uri
- description: Link / cursor to the last result set (based on the submitted pagination approach)
+ description: Link / cursor to the last result set (based on the submitted pagination approach).
examples:
- /card-app/api/v1/products?offset=150&limit=25
@@ -1207,8 +1207,8 @@ components:
$ref: '#/components/schemas/TransactionId'
limit:
- name: limit
in: query
+ name: limit
description: Optional parameter for pagination. Maximum number of entries to be returned.
required: false
schema:
@@ -1219,8 +1219,8 @@ components:
- 25
offset:
- name: offset
in: query
+ name: offset
description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
required: false
schema:
From 7057cd13b1741abe06079c64febd32fcf2b7d249 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 27 May 2024 12:54:53 +0200
Subject: [PATCH 12/29] typo
---
cardInfoAPI.yaml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 86f9e2e..b3538f4 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -1045,7 +1045,7 @@ components:
- '100: Cash withdrawal'
- '103: ATM operator refund'
- '117: P2P payment charge sender'
- - '118: P2P payment credit recipient "merchant", "fee", "atm"' # TODO example more than 50 chars
+ - '118: P2P payment credit recipient "merchant", "fee", "atm"' # TODO example more than 50 chars
description: Category of the transaction, defined by the Card Service Provider.
CardholderId:
From 8c71dbbf388cd992d71fb69c073adfa8ab7b6b8b Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Fri, 31 May 2024 11:12:38 +0200
Subject: [PATCH 13/29] Added descriptions
---
cardInfoAPI.yaml | 89 ++++++++++++++++++++++++++----------------------
1 file changed, 49 insertions(+), 40 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index b3538f4..9cf75bf 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -5,7 +5,7 @@ info:
description: >
This specification defines a common card API for payment cards used in Switzerland.
The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
- # TODO update description - proposal Christian
+ # TODO update description - TO BE REVIEWED
contact:
email: info@common-api.ch
license:
@@ -17,7 +17,7 @@ externalDocs:
description: Find out more about SFTI API specifications
url: https://www.common-api.ch
-# TODO make more detailed description - proposal Christian
+# TODO make more detailed description - TO BE REVIEWED
tags:
- name: Cards
description: Operations for retrieving information about payment cards.
@@ -35,11 +35,11 @@ security:
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters. # TODO - proposal Christian
+ summary: Provides a list of cards which match the provided query parameters. # TODO - TO BE REVIEWED
description: |
This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
- The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - proposal Christian
+ The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - TO BE REVIEWED
tags:
- Cards
parameters:
@@ -72,7 +72,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple payment cards were found which match the query parameters. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
+ description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -93,17 +93,17 @@ paths:
/cards/{cardId}:
get:
- summary: Provides a single card which matches the id. # TODO - proposal Christian
+ summary: Provides a single card which matches the id. # TODO - TO BE REVIEWED
description: >
This operation enables the retrieval of a single payment card when the cardId is already known.
- The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - proposal Christian
+ The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
responses:
'200':
- description: Single payment card was found. # TODO - proposal Christian
+ description: Single payment card was found. If the cardId was not found, a 400 is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -117,11 +117,11 @@ paths:
/card-tokens:
get:
- summary: Provides a list of card tokens which are associated with a card. # TODO - proposal Christian
+ summary: Provides a list of card tokens which are associated with a card. # TODO - TO BE REVIEWED
description: >
This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
- Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - proposal Christian
+ Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - TO BE REVIEWED
tags:
- Card-tokens
parameters:
@@ -139,7 +139,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple tokens which exist for the referenced card. # TODO - proposal Christian - TODO to be agreed how he case when no cards are found is handled: 200 with empty response vs. 400
+ description: Card tokens were found which match the query parameters. If no card tokens matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -160,10 +160,10 @@ paths:
/card-tokens/{tokenId}:
get:
- summary: Provides a single token which matches the cardId and tokenId # TODO - proposal Christian
+ summary: Provides a single token which matches the cardId and tokenId # TODO - TO BE REVIEWED
description: >
This operation enables the retrieval of a single token when the cardId and tokenId are already known.T
- The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - proposal Christian
+ The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
tags:
- Card-tokens
parameters:
@@ -175,7 +175,7 @@ paths:
$ref: '#/components/schemas/CardId'
responses:
'200':
- description: Single token was found. # TODO
+ description: Single token was found. If the tokenId was not found, a 400 is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -189,11 +189,11 @@ paths:
/card-transactions:
get:
- summary: Provides a list of transactions which match the provided query parameters. # TODO - proposal Christian
+ summary: Provides a list of transactions which match the provided query parameters. # TODO - TO BE REVIEWED
description: >
This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
- With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - proposal Christian
+ With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - TO BE REVIEWED
tags:
- Transactions
parameters:
@@ -241,7 +241,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: One or multiple transactions were found which match the query parameters. # TODO - proposal Christian
+ description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -257,17 +257,17 @@ paths:
/card-transactions/{transactionId}:
get:
- summary: Provides a single transaction which matches the transactionId # TODO - proposal Christian
+ summary: Provides a single transaction which matches the transactionId # TODO - TO BE REVIEWED
description: >
- his operation enables the retrieval of a single transaction when the transactionId is already known.
- The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - proposal Christian
+ This operation enables the retrieval of a single transaction when the transactionId is already known.
+ The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
responses:
'200':
- description: Single token was found. # TODO - proposal Christian
+ description: Single token was found. If the transactionId was not found, a 400 is returned. # TODO - TO BE REVIEWED
headers:
# TODO headers?
content:
@@ -283,7 +283,7 @@ components:
schemas:
CardDetails:
title: Card details
- description: Describes a payment card with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a payment card with its relevant characteristics. # TODO - TO BE REVIEWED
type: object
required:
- contract_reference
@@ -365,7 +365,7 @@ components:
CardTokenDetails:
title: Card token details
- description: Describes a token with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a token with its relevant characteristics. # TODO - TO BE REVIEWED
type: object
required:
- token_id
@@ -404,7 +404,7 @@ components:
TransactionDetails:
title: Transaction details
- description: Describes a transaction with its relevant characteristics. # TODO - proposal Christian
+ description: Describes a transaction with its relevant characteristics. # TODO - TO BE REVIEWED
type: object
required:
- transaction_id
@@ -847,7 +847,8 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ description: >
+ Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
ClearingReference:
title: Clearing reference
@@ -855,7 +856,8 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ description: >
+ Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
TransactionDateTime:
title: Transaction date-time
@@ -932,10 +934,10 @@ components:
Fees:
title: Fees
- description: # TODO
+ description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
type: object
required:
- - # TODO Required in object?
+ - fee_name
properties:
fee_name:
$ref: '#/components/schemas/FeeName'
@@ -1017,7 +1019,7 @@ components:
type: string
maxLength: 15
examples:
- - 87040
+ - '87040'
description: Identifier for the merchant who requested the transaction.
AcquirerId:
@@ -1045,7 +1047,10 @@ components:
- '100: Cash withdrawal'
- '103: ATM operator refund'
- '117: P2P payment charge sender'
- - '118: P2P payment credit recipient "merchant", "fee", "atm"' # TODO example more than 50 chars
+ - '118: P2P payment credit recipient'
+ - 'merchant'
+ - 'fee'
+ - 'atm'
description: Category of the transaction, defined by the Card Service Provider.
CardholderId:
@@ -1078,7 +1083,9 @@ components:
type: number
examples:
- 3.5
- description: Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers. # TODO 3.5 = 3.5%
+ description: >
+ Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
+ Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal). # TODO verify description
FeeAmount:
title: Fee amount
@@ -1100,6 +1107,7 @@ components:
format: date
examples:
- 2018-04-13
+ description: General date that is used for different attributes, format is 'YYYY-MM-DD'
DateTime:
title: Date-time
@@ -1107,6 +1115,7 @@ components:
format: date-time
examples:
- 2018-04-13T11:11:11Z
+ description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ss' # TODO - include timezone?
LinksPagination:
description: Links (or cursors) returned in the answer of an API call.
@@ -1145,20 +1154,24 @@ components:
CommonErrorResponse:
title: Common Error Response
+ description: General error response structure used in different response codes.
type: object
properties:
type:
$ref: '#/components/schemas/CommonErrorType'
title:
type: string
+ description: Short name for the problem
examples:
- This is the general problem description
detail:
type: string
+ description: More details about the problem
examples:
- Detailed problem description with respect to the current request
instance:
type: string
+ description: Reference to an individual entity or request which caused the problem
examples:
- path/to/corresponding/resource
@@ -1209,7 +1222,6 @@ components:
limit:
in: query
name: limit
- description: Optional parameter for pagination. Maximum number of entries to be returned.
required: false
schema:
type: integer
@@ -1217,11 +1229,11 @@ components:
minimum: 1
examples:
- 25
+ description: Optional parameter for pagination. Maximum number of entries to be returned.
offset:
in: query
name: offset
- description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
required: false
schema:
type: integer
@@ -1229,6 +1241,7 @@ components:
minimum: 0
examples:
- 25
+ description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
securitySchemes:
ApiKeyAuth:
@@ -1246,7 +1259,7 @@ components:
write: Grants write access
responses:
- # TODO adjust description due to actual use in API, descriptions are generic from RFC
+ # TODO adjust description due to actual use in API, descriptions are generic from RFC - TO BE REVIEWED
standard400:
headers:
Content-Type:
@@ -1254,10 +1267,7 @@ components:
Content-Language:
$ref: '#/components/headers/Content-Language'
description: |
- Bad Request - The 400 (Bad Request) status code indicates that the server cannot or
- will not process the request due to something that is perceived to be
- a client error (e.g., malformed request syntax, invalid request
- message framing, or deceptive request routing).
+ Client Error - The request could not be processed due to a problem in the data provided. This could be for any of the reasons of the HTML standard that would result in a 4xx code.
content:
application/problem+json:
schema:
@@ -1270,8 +1280,7 @@ components:
Content-Language:
$ref: '#/components/headers/Content-Language'
description: |
- Internal Server Error - The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling
- the request.
+ Internal Server Error - The request could not be processed due to a problem at the data provider. This could be for any of the reasons of the HTML standard that would result in a 5xx code.
content:
application/problem+json:
schema:
From 2a081b0bb654580037966eedd0b9bf3aac1410a6 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Fri, 31 May 2024 11:24:56 +0200
Subject: [PATCH 14/29] update openAPI action reference
---
.github/workflows/lint-openapi.yaml | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/.github/workflows/lint-openapi.yaml b/.github/workflows/lint-openapi.yaml
index b87fef6..a10e982 100644
--- a/.github/workflows/lint-openapi.yaml
+++ b/.github/workflows/lint-openapi.yaml
@@ -11,6 +11,6 @@ on:
jobs:
openapi-lint:
- uses: swissfintechinnovations/.github/.github/workflows/reusable-lint-openapi-workflow.yaml@naming-conventions-part-2
+ uses: swissfintechinnovations/.github/.github/workflows/reusable-lint-openapi-workflow.yaml@main
with:
filenames: ${{ github.event.inputs.filenames || '*.yaml' }}
\ No newline at end of file
From 831e26647b82f737b7e99964fd05a0a67b80cc1e Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Fri, 31 May 2024 14:23:49 +0200
Subject: [PATCH 15/29] refactor workshop discussions
---
cardInfoAPI.yaml | 185 +++++++++++++++++++++++++++++++++--------------
1 file changed, 131 insertions(+), 54 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 9cf75bf..4b11467 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -5,7 +5,6 @@ info:
description: >
This specification defines a common card API for payment cards used in Switzerland.
The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
- # TODO update description - TO BE REVIEWED
contact:
email: info@common-api.ch
license:
@@ -17,7 +16,6 @@ externalDocs:
description: Find out more about SFTI API specifications
url: https://www.common-api.ch
-# TODO make more detailed description - TO BE REVIEWED
tags:
- name: Cards
description: Operations for retrieving information about payment cards.
@@ -35,11 +33,11 @@ security:
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters. # TODO - TO BE REVIEWED
- description: |
+ summary: Provides a list of cards which match the provided query parameters.
+ description: >
This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
- The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - TO BE REVIEWED
+ The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number).
tags:
- Cards
parameters:
@@ -70,11 +68,15 @@ paths:
$ref: '#/components/schemas/BankAccountReference'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -93,19 +95,23 @@ paths:
/cards/{cardId}:
get:
- summary: Provides a single card which matches the id. # TODO - TO BE REVIEWED
+ summary: Provides a single card which matches the id.
description: >
This operation enables the retrieval of a single payment card when the cardId is already known.
- The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single payment card was found. If the cardId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single payment card was found. If the cardId was not found, a 400 is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -117,11 +123,11 @@ paths:
/card-tokens:
get:
- summary: Provides a list of card tokens which are associated with a card. # TODO - TO BE REVIEWED
+ summary: Provides a list of card tokens which are associated with a card.
description: >
This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
- Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - TO BE REVIEWED
+ Tokens are representations of a payment card used in specific wallets , wearables or merchants.
tags:
- Card-tokens
parameters:
@@ -137,11 +143,17 @@ paths:
$ref: '#/components/schemas/TokenStatus'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Card tokens were found which match the query parameters. If no card tokens matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: >
+ Card tokens were found which match the query parameters.
+ If no card tokens matched the parameters or access rights are missing, an empty list is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -160,10 +172,10 @@ paths:
/card-tokens/{tokenId}:
get:
- summary: Provides a single token which matches the cardId and tokenId # TODO - TO BE REVIEWED
+ summary: Provides a single token which matches the cardId and tokenId
description: >
This operation enables the retrieval of a single token when the cardId and tokenId are already known.T
- The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer.
tags:
- Card-tokens
parameters:
@@ -173,11 +185,15 @@ paths:
required: false
schema:
$ref: '#/components/schemas/CardId'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single token was found. If the tokenId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single token was found. If the tokenId was not found, a 400 is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -189,11 +205,11 @@ paths:
/card-transactions:
get:
- summary: Provides a list of transactions which match the provided query parameters. # TODO - TO BE REVIEWED
+ summary: Provides a list of transactions which match the provided query parameters.
description: >
This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
- With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - TO BE REVIEWED
+ With the Level 1 of the Common Card API only card-based financial transactions are included.
tags:
- Transactions
parameters:
@@ -239,11 +255,15 @@ paths:
$ref: '#/components/schemas/OriginalCurrency'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -257,19 +277,23 @@ paths:
/card-transactions/{transactionId}:
get:
- summary: Provides a single transaction which matches the transactionId # TODO - TO BE REVIEWED
+ summary: Provides a single transaction which matches the transactionId
description: >
This operation enables the retrieval of a single transaction when the transactionId is already known.
- The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single token was found. If the transactionId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single token was found. If the transactionId was not found, a 400 is returned.
headers:
- # TODO headers?
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
content:
application/json:
schema:
@@ -283,7 +307,7 @@ components:
schemas:
CardDetails:
title: Card details
- description: Describes a payment card with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a payment card with its relevant characteristics.
type: object
required:
- contract_reference
@@ -365,7 +389,7 @@ components:
CardTokenDetails:
title: Card token details
- description: Describes a token with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a token with its relevant characteristics.
type: object
required:
- token_id
@@ -404,7 +428,7 @@ components:
TransactionDetails:
title: Transaction details
- description: Describes a transaction with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a transaction with its relevant characteristics.
type: object
required:
- transaction_id
@@ -651,7 +675,10 @@ components:
format: int32
examples:
- 2000
- description: Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations in the current cycle.
+ description: >
+ Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card;
+ effective limit is provided that considers limits on the card and relationship;
+ does not indicate the actually available amount for authorizations in the current cycle.
CardLimitDaily:
title: Card limit daily
@@ -659,7 +686,10 @@ components:
format: int32
examples:
- 2000
- description: Total amount of authorizations possible for the card per day in the currency of the card; effective limit is provided that considers limits on the card and relationship; does not indicate the actually available amount for authorizations on the current day.
+ description: >
+ Total amount of authorizations possible for the card per day in the currency of the card;
+ effective limit is provided that considers limits on the card and relationship;
+ does not indicate the actually available amount for authorizations on the current day.
CardAccountId:
title: Card account id
@@ -667,7 +697,9 @@ components:
maxLength: 50
examples:
- AB-4567890123456
- description: Technical reference to the card account which is used to settle the transactions of the card; can be empty for debit cards which are settled directly to the bank account.
+ description: >
+ Technical reference to the card account which is used to settle the transactions of the card;
+ can be empty for debit cards which are settled directly to the bank account.
BankAccountReference:
title: Bank account reference
@@ -701,7 +733,9 @@ components:
maxLength: 50
examples:
- '123456789'
- description: Identifier for the organization which is distributing / selling cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+ description: >
+ Identifier for the organization which is distributing / selling cards to end customers
+ and who can define the services and branding of the card; empty if the card is distributed by the issuer.
DistributionPartnerName:
title: Distribution partner name
@@ -709,7 +743,9 @@ components:
maxLength: 100
examples:
- Zürcher Kantonalbank
- description: Name of the organization which is distributing / issuing cards to end customers and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+ description: >
+ Name of the organization which is distributing / issuing cards to end customers
+ and who can define the services and branding of the card; empty if the card is distributed by the issuer.
Language:
type: string
@@ -725,7 +761,7 @@ components:
TokenId:
title: Token id
type: string
- format: uuid # TODO special format of id possible?
+ format: uuid
maxLength: 50
examples:
- eb404f8d-656b-4e51-8872-88c42fa55536
@@ -847,8 +883,8 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: >
- Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ description: >
+ Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present.
ClearingReference:
title: Clearing reference
@@ -857,7 +893,7 @@ components:
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
description: >
- Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present.
TransactionDateTime:
title: Transaction date-time
@@ -893,7 +929,9 @@ components:
pattern: '^\d{6}$'
examples:
- '803051'
- description: Identifies a transaction from the entity that authorized it; in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
+ description: >
+ Identifies a transaction from the entity that authorized it;
+ in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
OriginalAmount:
title: Original amount
@@ -915,7 +953,9 @@ components:
type: number
examples:
- 1957.50
- description: Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees); positive amounts are debit transactions, negative amounts are credit transactions.
+ description: >
+ Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
+ positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
title: Transaction amount
@@ -934,7 +974,7 @@ components:
Fees:
title: Fees
- description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
+ description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
type: object
required:
- fee_name
@@ -1085,7 +1125,7 @@ components:
- 3.5
description: >
Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
- Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal). # TODO verify description
+ Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
FeeAmount:
title: Fee amount
@@ -1115,7 +1155,7 @@ components:
format: date-time
examples:
- 2018-04-13T11:11:11Z
- description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ss' # TODO - include timezone?
+ description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ss'.
LinksPagination:
description: Links (or cursors) returned in the answer of an API call.
@@ -1161,17 +1201,17 @@ components:
$ref: '#/components/schemas/CommonErrorType'
title:
type: string
- description: Short name for the problem
+ description: Short name for the problem.
examples:
- This is the general problem description
detail:
type: string
- description: More details about the problem
+ description: More details about the problem.
examples:
- Detailed problem description with respect to the current request
instance:
type: string
- description: Reference to an individual entity or request which caused the problem
+ description: Reference to an individual entity or request which caused the problem.
examples:
- path/to/corresponding/resource
@@ -1243,6 +1283,30 @@ components:
- 25
description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
+ clientid_in_header:
+ name: X-CorAPI-Client-ID
+ in: header
+ schema:
+ type: string
+ description: ID of the client forwarded to the provider.
+ required: true
+
+ correlation_in_header:
+ name: X-Correlation-ID
+ in: header
+ schema:
+ $ref: '#/components/headers/X-Correlation-ID'
+ description: Unique ID (defined by the caller) which will be reflected back in the response.
+ required: true
+
+ agent_in_header:
+ name: User-Agent
+ in: header
+ schema:
+ type: string
+ description: Name and version of the of the Client software.
+ required: true
+
securitySchemes:
ApiKeyAuth:
type: apiKey
@@ -1259,15 +1323,17 @@ components:
write: Grants write access
responses:
- # TODO adjust description due to actual use in API, descriptions are generic from RFC - TO BE REVIEWED
standard400:
headers:
Content-Type:
$ref: '#/components/headers/Content-Type'
Content-Language:
$ref: '#/components/headers/Content-Language'
- description: |
- Client Error - The request could not be processed due to a problem in the data provided. This could be for any of the reasons of the HTML standard that would result in a 4xx code.
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ description: >
+ Client Error - The request could not be processed due to a problem in the data provided.
+ This could be for any of the reasons of the HTML standard that would result in a 4xx code.
content:
application/problem+json:
schema:
@@ -1279,8 +1345,11 @@ components:
$ref: '#/components/headers/Content-Type'
Content-Language:
$ref: '#/components/headers/Content-Language'
- description: |
- Internal Server Error - The request could not be processed due to a problem at the data provider. This could be for any of the reasons of the HTML standard that would result in a 5xx code.
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ description: >
+ Internal Server Error - The request could not be processed due to a problem at the data provider.
+ This could be for any of the reasons of the HTML standard that would result in a 5xx code.
content:
application/problem+json:
schema:
@@ -1288,15 +1357,23 @@ components:
headers:
Content-Language:
- description: # TODO
+ description: Language of provided content.
schema:
type: string
examples:
- en
Content-Type:
- description: # TODO
+ description: Type of provided content.
schema:
type: string
examples:
+ - application/json
- application/problem+json; charset=utf-8 according to RFC7807
+
+ X-Correlation-ID:
+ description: Client defined ID from request to correlates HTTP requests between a client and server
+ schema:
+ type: string
+ examples:
+ - f058ebd6-02f7-4d3f-942e-904344e8cde5
\ No newline at end of file
From 4aabaeb85f08711d4b84cfbe996c2c2ef64c1844 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Fri, 31 May 2024 16:08:20 +0200
Subject: [PATCH 16/29] Update description, remove TODO
---
cardInfoAPI.yaml | 61 +++++++++++++++++++++++-------------------------
1 file changed, 29 insertions(+), 32 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 9cf75bf..4809f27 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -5,7 +5,6 @@ info:
description: >
This specification defines a common card API for payment cards used in Switzerland.
The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
- # TODO update description - TO BE REVIEWED
contact:
email: info@common-api.ch
license:
@@ -17,7 +16,6 @@ externalDocs:
description: Find out more about SFTI API specifications
url: https://www.common-api.ch
-# TODO make more detailed description - TO BE REVIEWED
tags:
- name: Cards
description: Operations for retrieving information about payment cards.
@@ -35,11 +33,11 @@ security:
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters. # TODO - TO BE REVIEWED
+ summary: Provides a list of cards which match the provided query parameters.
description: |
This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
- The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number). # TODO - TO BE REVIEWED
+ The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number).
tags:
- Cards
parameters:
@@ -72,7 +70,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned.
headers:
# TODO headers?
content:
@@ -93,17 +91,17 @@ paths:
/cards/{cardId}:
get:
- summary: Provides a single card which matches the id. # TODO - TO BE REVIEWED
+ summary: Provides a single card which matches the id.
description: >
This operation enables the retrieval of a single payment card when the cardId is already known.
- The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
responses:
'200':
- description: Single payment card was found. If the cardId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single payment card was found. If the cardId was not found, a 400 is returned.
headers:
# TODO headers?
content:
@@ -117,11 +115,11 @@ paths:
/card-tokens:
get:
- summary: Provides a list of card tokens which are associated with a card. # TODO - TO BE REVIEWED
+ summary: Provides a list of card tokens which are associated with a card.
description: >
This operation enables the retrieval of a list of tokens associated with a payment card.
The tokens can be filtered further by status.
- Tokens are representations of a payment card used in specific wallets , wearables or merchants. # TODO - TO BE REVIEWED
+ Tokens are representations of a payment card used in specific wallets , wearables or merchants.
tags:
- Card-tokens
parameters:
@@ -139,7 +137,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: Card tokens were found which match the query parameters. If no card tokens matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: Card tokens were found which match the query parameters. If no card tokens matched the parameters or access rights are missing, an empty list is returned.
headers:
# TODO headers?
content:
@@ -160,10 +158,10 @@ paths:
/card-tokens/{tokenId}:
get:
- summary: Provides a single token which matches the cardId and tokenId # TODO - TO BE REVIEWED
+ summary: Provides a single token which matches the cardId and tokenId
description: >
This operation enables the retrieval of a single token when the cardId and tokenId are already known.T
- The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer.
tags:
- Card-tokens
parameters:
@@ -175,7 +173,7 @@ paths:
$ref: '#/components/schemas/CardId'
responses:
'200':
- description: Single token was found. If the tokenId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single token was found. If the tokenId was not found, a 400 is returned.
headers:
# TODO headers?
content:
@@ -189,11 +187,11 @@ paths:
/card-transactions:
get:
- summary: Provides a list of transactions which match the provided query parameters. # TODO - TO BE REVIEWED
+ summary: Provides a list of transactions which match the provided query parameters.
description: >
This operation enables the retrieval of a list of transactions performed with a payment card or token.
Different query parameters are provided to support an efficient retrieval of individual transactions.
- With the Level 1 of the Common Card API only card-based financial transactions are included. # TODO - TO BE REVIEWED
+ With the Level 1 of the Common Card API only card-based financial transactions are included.
tags:
- Transactions
parameters:
@@ -241,7 +239,7 @@ paths:
- $ref: '#/components/parameters/offset'
responses:
'200':
- description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned. # TODO - TO BE REVIEWED
+ description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned.
headers:
# TODO headers?
content:
@@ -257,17 +255,17 @@ paths:
/card-transactions/{transactionId}:
get:
- summary: Provides a single transaction which matches the transactionId # TODO - TO BE REVIEWED
+ summary: Provides a single transaction which matches the transactionId
description: >
This operation enables the retrieval of a single transaction when the transactionId is already known.
- The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer. # TODO - TO BE REVIEWED
+ The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer.
tags:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
responses:
'200':
- description: Single token was found. If the transactionId was not found, a 400 is returned. # TODO - TO BE REVIEWED
+ description: Single token was found. If the transactionId was not found, a 400 is returned.
headers:
# TODO headers?
content:
@@ -283,7 +281,7 @@ components:
schemas:
CardDetails:
title: Card details
- description: Describes a payment card with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a payment card with its relevant characteristics.
type: object
required:
- contract_reference
@@ -365,7 +363,7 @@ components:
CardTokenDetails:
title: Card token details
- description: Describes a token with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a token with its relevant characteristics.
type: object
required:
- token_id
@@ -404,7 +402,7 @@ components:
TransactionDetails:
title: Transaction details
- description: Describes a transaction with its relevant characteristics. # TODO - TO BE REVIEWED
+ description: Describes a transaction with its relevant characteristics.
type: object
required:
- transaction_id
@@ -725,7 +723,7 @@ components:
TokenId:
title: Token id
type: string
- format: uuid # TODO special format of id possible?
+ format: uuid
maxLength: 50
examples:
- eb404f8d-656b-4e51-8872-88c42fa55536
@@ -839,7 +837,7 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: UUID to link AuthorizationReference and ClearingReference. # TODO - proposal Dominik
+ description: UUID to link AuthorizationReference and ClearingReference.
AuthorizationReference:
title: Authorization reference
@@ -848,7 +846,7 @@ components:
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
description: >
- Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present.
ClearingReference:
title: Clearing reference
@@ -857,7 +855,7 @@ components:
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
description: >
- Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present. # TODO remove one-of dependency?
+ Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present.
TransactionDateTime:
title: Transaction date-time
@@ -1085,7 +1083,7 @@ components:
- 3.5
description: >
Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
- Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal). # TODO verify description
+ Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
FeeAmount:
title: Fee amount
@@ -1115,7 +1113,7 @@ components:
format: date-time
examples:
- 2018-04-13T11:11:11Z
- description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ss' # TODO - include timezone?
+ description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'
LinksPagination:
description: Links (or cursors) returned in the answer of an API call.
@@ -1259,7 +1257,6 @@ components:
write: Grants write access
responses:
- # TODO adjust description due to actual use in API, descriptions are generic from RFC - TO BE REVIEWED
standard400:
headers:
Content-Type:
@@ -1288,14 +1285,14 @@ components:
headers:
Content-Language:
- description: # TODO
+ description: # TODO Dominik
schema:
type: string
examples:
- en
Content-Type:
- description: # TODO
+ description: # TODO Dominik
schema:
type: string
examples:
From 4b4ee6527dfdd174814ee9829455ae4ef8a56691 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Fri, 31 May 2024 16:50:05 +0200
Subject: [PATCH 17/29] Rename code / reference / id
---
cardInfoAPI.yaml | 108 +++++++++++++++++++++++------------------------
1 file changed, 54 insertions(+), 54 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 2f96567..b041afa 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -57,10 +57,10 @@ paths:
schema:
$ref: '#/components/schemas/CardStatus'
- in: query
- name: card_account_id
+ name: card_account_reference
required: false
schema:
- $ref: '#/components/schemas/CardAccountId'
+ $ref: '#/components/schemas/CardAccountReference'
- in: query
name: bank_account_reference
required: false
@@ -320,7 +320,7 @@ components:
- card_status
- currency
- image
- - product_id
+ - product_code
- product_name
- scheme
- issuing_type
@@ -328,7 +328,7 @@ components:
- product_line
- card_limit_cycle
- card_limit_daily
- - issuer_id
+ - issuer_code
- issuer_name
- language
properties:
@@ -354,8 +354,8 @@ components:
$ref: '#/components/schemas/Currency'
image:
$ref: '#/components/schemas/Image'
- product_id:
- $ref: '#/components/schemas/ProductId'
+ product_code:
+ $ref: '#/components/schemas/ProductCode'
product_name:
$ref: '#/components/schemas/ProductName'
scheme:
@@ -372,16 +372,16 @@ components:
$ref: '#/components/schemas/CardLimitCycle'
card_limit_daily:
$ref: '#/components/schemas/CardLimitDaily'
- card_account_id:
- $ref: '#/components/schemas/CardAccountId'
+ card_account_reference:
+ $ref: '#/components/schemas/CardAccountReference'
bank_account_reference:
$ref: '#/components/schemas/BankAccountReference'
- issuer_id:
- $ref: '#/components/schemas/IssuerId'
+ issuer_code:
+ $ref: '#/components/schemas/IssuerCode'
issuer_name:
$ref: '#/components/schemas/IssuerName'
- distribution_partner_id:
- $ref: '#/components/schemas/DistributionPartnerId'
+ distribution_partner_code:
+ $ref: '#/components/schemas/DistributionPartnerCode'
distribution_partner_name:
$ref: '#/components/schemas/DistributionPartnerName'
language:
@@ -394,7 +394,7 @@ components:
required:
- token_id
- token_pan_4_digits
- - token_requestor_id
+ - token_requestor_code
- token_requestor_name
- funding_card_id
- token_status
@@ -405,12 +405,12 @@ components:
$ref: '#/components/schemas/TokenId'
token_pan_4_digits:
$ref: '#/components/schemas/TokenPan4Digits'
- wallet_id:
- $ref: '#/components/schemas/WalletId'
+ wallet_code:
+ $ref: '#/components/schemas/WalletCode'
wallet_name:
$ref: '#/components/schemas/WalletName'
- token_requestor_id:
- $ref: '#/components/schemas/TokenRequestorId'
+ token_requestor_code:
+ $ref: '#/components/schemas/TokenRequestorCode'
token_requestor_name:
$ref: '#/components/schemas/TokenRequestorName'
device_name:
@@ -456,8 +456,8 @@ components:
$ref: '#/components/schemas/StatementDate'
transaction_status:
$ref: '#/components/schemas/TransactionStatus'
- approval_code:
- $ref: '#/components/schemas/ApprovalCode'
+ approval_number:
+ $ref: '#/components/schemas/ApprovalNumber'
original_amount:
$ref: '#/components/schemas/OriginalAmount'
original_currency:
@@ -486,26 +486,26 @@ components:
$ref: '#/components/schemas/Mcc'
mcc_description:
$ref: '#/components/schemas/MccDescription'
- terminal_id:
- $ref: '#/components/schemas/TerminalId'
- card_acceptor_id:
- $ref: '#/components/schemas/CardAcceptorId'
- acquirer_id:
- $ref: '#/components/schemas/AcquirerId'
+ terminal_reference:
+ $ref: '#/components/schemas/TerminalReference'
+ card_acceptor_reference:
+ $ref: '#/components/schemas/CardAcceptorReference'
+ acquirer_reference:
+ $ref: '#/components/schemas/AcquirerReference'
channel:
$ref: '#/components/schemas/Channel'
transaction_category:
$ref: '#/components/schemas/TransactionCategory'
token_id:
$ref: '#/components/schemas/TokenId'
- cardholder_id:
- $ref: '#/components/schemas/CardholderId'
- card_account_id:
- $ref: '#/components/schemas/CardAccountId'
+ cardholder_reference:
+ $ref: '#/components/schemas/CardholderReference'
+ card_account_reference:
+ $ref: '#/components/schemas/CardAccountReference'
card_id:
$ref: '#/components/schemas/CardId'
- transaction_reference:
- $ref: '#/components/schemas/TransactionReference'
+ related_transaction_id:
+ $ref: '#/components/schemas/RelatedTransactionId'
ContractReference:
title: Contract reference
@@ -597,8 +597,8 @@ components:
- https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
description: URL reference to an image for the design of the card.
- ProductId:
- title: Product id
+ ProductCode:
+ title: Product code
type: string
maxLength: 50
examples:
@@ -691,8 +691,8 @@ components:
effective limit is provided that considers limits on the card and relationship;
does not indicate the actually available amount for authorizations on the current day.
- CardAccountId:
- title: Card account id
+ CardAccountReference:
+ title: Card account reference
type: string
maxLength: 50
examples:
@@ -709,8 +709,8 @@ components:
- CH3456789012345678901
description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
- IssuerId:
- title: Issuer id
+ IssuerCode:
+ title: Issuer code
type: string
maxLength: 50
examples:
@@ -727,8 +727,8 @@ components:
- Zürcher Kantonalbank
description: Name of the legal issuer of a card.
- DistributionPartnerId:
- title: Distribution partner id
+ DistributionPartnerCode:
+ title: Distribution partner code
type: string
maxLength: 50
examples:
@@ -775,8 +775,8 @@ components:
- '4321'
description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
- WalletId:
- title: Wallet id
+ WalletCode:
+ title: Wallet code
type: string
maxLength: 10
examples:
@@ -795,8 +795,8 @@ components:
- APPLE_PAY
description: Name of the wallet in which the token is used and managed.
- TokenRequestorId:
- title: Token requestor id
+ TokenRequestorCode:
+ title: Token requestor code
type: string
maxLength: 11
examples:
@@ -923,8 +923,8 @@ components:
- authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
- booked: transaction was cleared/settled and charged to the card account
- ApprovalCode:
- title: Approval code
+ ApprovalNumber:
+ title: Approval number (also known as approval code)
type: string
pattern: '^\d{6}$'
examples:
@@ -1046,24 +1046,24 @@ components:
- Telco
description: Description for the mcc.
- TerminalId:
- title: Terminal id
+ TerminalReference:
+ title: Terminal reference (also known as terminal id)
type: string
maxLength: 8
examples:
- '12345678'
description: Identifier for the terminal which has read the card data.
- CardAcceptorId:
- title: Card acceptor id
+ CardAcceptorReference:
+ title: Card acceptor reference
type: string
maxLength: 15
examples:
- '87040'
description: Identifier for the merchant who requested the transaction.
- AcquirerId:
- title: Acquirer id
+ AcquirerReference:
+ title: Acquirer reference (also known as acquirer id)
type: string
maxLength: 11
examples:
@@ -1093,15 +1093,15 @@ components:
- 'atm'
description: Category of the transaction, defined by the Card Service Provider.
- CardholderId:
- title: Cardholder id
+ CardholderReference:
+ title: Cardholder reference
type: string
maxLength: 50
examples:
- Peter Schweizer
description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
- TransactionReference:
+ RelatedTransactionId:
title: Transaction reference
type: string
maxLength: 50
From b03e8c65e21585a121111fa23da4237a1933ebe8 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Mon, 3 Jun 2024 08:53:05 +0200
Subject: [PATCH 18/29] Added parameter descriptions
---
cardInfoAPI.yaml | 25 +++++++++++++++++++++++--
1 file changed, 23 insertions(+), 2 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index b041afa..42e769c 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -46,26 +46,31 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ContractReference'
+ description: Retrieves all cards related to a contract. Value has to be a functional reference to the contract that can be known by the end customer.
- in: query
name: person_reference
required: false
schema:
$ref: '#/components/schemas/PersonReference'
+ description: Retrieves all cards related to an individual person/cardholder. Value has to be a functional reference to the person that can be known by the end customer.
- in: query
name: card_status
required: false
schema:
$ref: '#/components/schemas/CardStatus'
+ description: Retrieves all cards in a certain status. Only one status can be filtered at a time.
- in: query
name: card_account_reference
required: false
schema:
$ref: '#/components/schemas/CardAccountReference'
+ description: Retrieves all cards related to a card account (not bank account). Value has to be a functional reference to the account that can be known by the end customer.
- in: query
name: bank_account_reference
required: false
schema:
$ref: '#/components/schemas/BankAccountReference'
+ description: Retrieves all cards related to a bank account (not card account). Value has to be a functional reference to the account that can be known by the end customer and is usually an IBAN.
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
@@ -136,11 +141,13 @@ paths:
required: false
schema:
$ref: '#/components/schemas/CardId'
+ description: Retrieves all tokens related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
- in: query
name: token_status
required: false
schema:
$ref: '#/components/schemas/TokenStatus'
+ description: Retrieves all tokens in a certain status. Only one status can be filtered at a time.
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
@@ -174,14 +181,14 @@ paths:
get:
summary: Provides a single token which matches the cardId and tokenId
description: >
- This operation enables the retrieval of a single token when the cardId and tokenId are already known.T
+ This operation enables the retrieval of a single token when the cardId and tokenId are already known.
The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer.
tags:
- Card-tokens
parameters:
- $ref: '#/components/parameters/path_tokenId'
- in: query
- name: card_id
+ name: card_id # TODO should we keep this parameter when it is anyway optional?
required: false
schema:
$ref: '#/components/schemas/CardId'
@@ -218,41 +225,52 @@ paths:
required: false
schema:
$ref: '#/components/schemas/AuthorizationReference'
+ description: >
+ Retrieves the transaction related to an individual authorization. Parameter can be used to also retrieve the cleared transaction based on the authorization reference.
- in: query
name: clearing_reference
required: false
schema:
$ref: '#/components/schemas/ClearingReference'
+ description: >
+ Retrieves the transaction related to an individual clearing.
+ Query parameter only returns results for cleared transactions (those booked on the card account for credit and prepaid or bank account for debit cards).
- in: query
name: card_id
required: false
schema:
$ref: '#/components/schemas/CardId'
+ description: Retrieves all transactions related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
- in: query
name: token_id
required: false
schema:
$ref: '#/components/schemas/TokenId'
+ description: Retrieves all transactions related to a token. Value has to be a technical identifier for the card that can be retrieved with the GET /card-tokens endpoint.
- in: query
name: from_date
required: false
schema:
$ref: '#/components/schemas/DateTime'
+ description: Retrieves all transactions that took place after the provided date time. Filtering is applied on the transaction_date_time attribute.
- in: query
name: to_date
required: false
schema:
$ref: '#/components/schemas/DateTime'
+ description: Retrieves all transactions that took place before the provided date time. Filtering is applied on the transaction_date_time attribute.
- in: query
name: status
required: false
schema:
$ref: '#/components/schemas/TransactionStatus'
+ description: Retrieves all transactions in a certain status. Only one status can be filtered at a time.
- in: query
name: original_currency
required: false
schema:
$ref: '#/components/schemas/OriginalCurrency'
+ description: Retrieves all transactions in a certain currency. Filtering is applied on the original_currency attribute.
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
@@ -1244,6 +1262,7 @@ components:
required: true
schema:
$ref: '#/components/schemas/CardId'
+ description: Identifier (technical) for a card for which information is requested.
path_tokenId:
in: path
@@ -1251,6 +1270,7 @@ components:
required: true
schema:
$ref: '#/components/schemas/TokenId'
+ description: Identifier (technical) for a token for which information is requested.
path_transactionId:
in: path
@@ -1258,6 +1278,7 @@ components:
required: true
schema:
$ref: '#/components/schemas/TransactionId'
+ description: Identifier (technical) for a transaction for which information is requested.
limit:
in: query
From e57978e56248276ddc6dcd3ae3037469f55d9d43 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Mon, 3 Jun 2024 09:05:46 +0200
Subject: [PATCH 19/29] Fix Linter findings
---
cardInfoAPI.yaml | 30 +++++++++++++++---------------
1 file changed, 15 insertions(+), 15 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 42e769c..df14a06 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -188,7 +188,7 @@ paths:
parameters:
- $ref: '#/components/parameters/path_tokenId'
- in: query
- name: card_id # TODO should we keep this parameter when it is anyway optional?
+ name: card_id # TODO should we keep this parameter when it is anyway optional?
required: false
schema:
$ref: '#/components/schemas/CardId'
@@ -995,7 +995,7 @@ components:
description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
type: object
required:
- - fee_name
+ - fee_name
properties:
fee_name:
$ref: '#/components/schemas/FeeName'
@@ -1106,9 +1106,9 @@ components:
- '103: ATM operator refund'
- '117: P2P payment charge sender'
- '118: P2P payment credit recipient'
- - 'merchant'
- - 'fee'
- - 'atm'
+ - merchant
+ - fee
+ - atm
description: Category of the transaction, defined by the Card Service Provider.
CardholderReference:
@@ -1165,7 +1165,7 @@ components:
format: date
examples:
- 2018-04-13
- description: General date that is used for different attributes, format is 'YYYY-MM-DD'
+ description: General date that is used for different attributes, format is 'YYYY-MM-DD'.
DateTime:
title: Date-time
@@ -1173,7 +1173,7 @@ components:
format: date-time
examples:
- 2018-04-13T11:11:11Z
- description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'
+ description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'.
LinksPagination:
description: Links (or cursors) returned in the answer of an API call.
@@ -1305,28 +1305,28 @@ components:
description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
clientid_in_header:
- name: X-CorAPI-Client-ID
in: header
+ name: X-CorAPI-Client-ID
+ required: true
schema:
type: string
description: ID of the client forwarded to the provider.
- required: true
correlation_in_header:
- name: X-Correlation-ID
in: header
+ name: X-Correlation-ID
+ required: true
schema:
$ref: '#/components/headers/X-Correlation-ID'
description: Unique ID (defined by the caller) which will be reflected back in the response.
- required: true
agent_in_header:
- name: User-Agent
in: header
+ name: User-Agent
+ required: true
schema:
type: string
description: Name and version of the of the Client software.
- required: true
securitySchemes:
ApiKeyAuth:
@@ -1393,8 +1393,8 @@ components:
- application/problem+json; charset=utf-8 according to RFC7807
X-Correlation-ID:
- description: Client defined ID from request to correlates HTTP requests between a client and server
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
schema:
type: string
examples:
- - f058ebd6-02f7-4d3f-942e-904344e8cde5
\ No newline at end of file
+ - f058ebd6-02f7-4d3f-942e-904344e8cde5
From 35c1e96a2f0e5dc1ffc53738a19efc0de4429f03 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Mon, 3 Jun 2024 16:04:35 +0200
Subject: [PATCH 20/29] Add uuid format for ids
---
cardInfoAPI.yaml | 3 +++
1 file changed, 3 insertions(+)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index df14a06..850bddd 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -545,6 +545,7 @@ components:
CardId:
title: Card id
type: string
+ format: uuid
maxLength: 50
examples:
- 4321A1B2C3DE1234
@@ -848,6 +849,7 @@ components:
FundingCardId:
title: Funding card id
type: string
+ format: uuid
maxLength: 50
examples:
- 4321A1B2C3DE1234
@@ -1122,6 +1124,7 @@ components:
RelatedTransactionId:
title: Transaction reference
type: string
+ format: uuid
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
From 1b471f7f02b828ef4ac6568da456a1d18888cac4 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Tue, 4 Jun 2024 12:55:36 +0200
Subject: [PATCH 21/29] fix trailing spaces
---
cardInfoAPI.yaml | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index 850bddd..e3478d6 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -156,7 +156,7 @@ paths:
responses:
'200':
description: >
- Card tokens were found which match the query parameters.
+ Card tokens were found which match the query parameters.
If no card tokens matched the parameters or access rights are missing, an empty list is returned.
headers:
X-Correlation-ID:
@@ -233,7 +233,7 @@ paths:
schema:
$ref: '#/components/schemas/ClearingReference'
description: >
- Retrieves the transaction related to an individual clearing.
+ Retrieves the transaction related to an individual clearing.
Query parameter only returns results for cleared transactions (those booked on the card account for credit and prepaid or bank account for debit cards).
- in: query
name: card_id
@@ -763,7 +763,7 @@ components:
examples:
- Zürcher Kantonalbank
description: >
- Name of the organization which is distributing / issuing cards to end customers
+ Name of the organization which is distributing / issuing cards to end customers
and who can define the services and branding of the card; empty if the card is distributed by the issuer.
Language:
@@ -974,7 +974,7 @@ components:
examples:
- 1957.50
description: >
- Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
+ Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
@@ -1145,7 +1145,7 @@ components:
examples:
- 3.5
description: >
- Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
+ Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
FeeAmount:
From eb6d3e58372366043094eb32a67fb3e18af1b617 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Tue, 4 Jun 2024 15:50:49 +0200
Subject: [PATCH 22/29] rename spec file name, address ref error
---
cardInfoAPI-Level1.yaml | 1407 ++++++++++++++++++++
cardInfoAPI.yaml | 2768 +++++++++++++++++++++++----------------
2 files changed, 3061 insertions(+), 1114 deletions(-)
create mode 100644 cardInfoAPI-Level1.yaml
diff --git a/cardInfoAPI-Level1.yaml b/cardInfoAPI-Level1.yaml
new file mode 100644
index 0000000..36bd063
--- /dev/null
+++ b/cardInfoAPI-Level1.yaml
@@ -0,0 +1,1407 @@
+openapi: 3.1.0
+info:
+ version: 0.7.0
+ title: Common Card API (Public)
+ description: >
+ This specification defines a common card API for payment cards used in Switzerland.
+ The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
+ contact:
+ email: info@common-api.ch
+ license:
+ name: Apache 2.0
+ url: https://www.apache.org/licenses/LICENSE-2.0.html
+servers:
+ - url: https://card.common-api.ch
+externalDocs:
+ description: Find out more about SFTI API specifications
+ url: https://www.common-api.ch
+
+tags:
+ - name: Cards
+ description: Operations for retrieving information about payment cards.
+ - name: Card-tokens
+ description: Operations for retrieving information about tokens associated with payment cards.
+ - name: Transactions
+ description: Operations for retrieving information about transactions and authorizations done with payment cards or tokens.
+
+security:
+ - ApiKeyAuth: []
+ - OAuth2:
+ - read
+ - write
+
+paths:
+ /cards:
+ get:
+ summary: Provides a list of cards which match the provided query parameters.
+ description: >
+ This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
+ In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
+ The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number).
+ tags:
+ - Cards
+ parameters:
+ - in: query
+ name: contract_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/ContractReference'
+ description: Retrieves all cards related to a contract. Value has to be a functional reference to the contract that can be known by the end customer.
+ - in: query
+ name: person_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/PersonReference'
+ description: Retrieves all cards related to an individual person/cardholder. Value has to be a functional reference to the person that can be known by the end customer.
+ - in: query
+ name: card_status
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardStatus'
+ description: Retrieves all cards in a certain status. Only one status can be filtered at a time.
+ - in: query
+ name: card_account_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardAccountReference'
+ description: Retrieves all cards related to a card account (not bank account). Value has to be a functional reference to the account that can be known by the end customer.
+ - in: query
+ name: bank_account_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/BankAccountReference'
+ description: Retrieves all cards related to a bank account (not card account). Value has to be a functional reference to the account that can be known by the end customer and is usually an IBAN.
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ cardList:
+ type: array
+ items:
+ $ref: '#/components/schemas/CardDetails'
+ _links:
+ $ref: '#/components/schemas/LinksPagination'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /cards/{cardId}:
+ get:
+ summary: Provides a single card which matches the id.
+ description: >
+ This operation enables the retrieval of a single payment card when the cardId is already known.
+ The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer.
+ tags:
+ - Cards
+ parameters:
+ - $ref: '#/components/parameters/path_cardId'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Single payment card was found. If the cardId was not found, a 400 is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CardDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /card-tokens:
+ get:
+ summary: Provides a list of card tokens which are associated with a card.
+ description: >
+ This operation enables the retrieval of a list of tokens associated with a payment card.
+ The tokens can be filtered further by status.
+ Tokens are representations of a payment card used in specific wallets , wearables or merchants.
+ tags:
+ - Card-tokens
+ parameters:
+ - in: query
+ name: card_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardId'
+ description: Retrieves all tokens related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ - in: query
+ name: token_status
+ required: false
+ schema:
+ $ref: '#/components/schemas/TokenStatus'
+ description: Retrieves all tokens in a certain status. Only one status can be filtered at a time.
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: >
+ Card tokens were found which match the query parameters.
+ If no card tokens matched the parameters or access rights are missing, an empty list is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ cardList:
+ type: array
+ items:
+ $ref: '#/components/schemas/CardTokenDetails'
+ _links:
+ $ref: '#/components/schemas/LinksPagination'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /card-tokens/{tokenId}:
+ get:
+ summary: Provides a single token which matches the cardId and tokenId
+ description: >
+ This operation enables the retrieval of a single token when the cardId and tokenId are already known.
+ The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer.
+ tags:
+ - Card-tokens
+ parameters:
+ - $ref: '#/components/parameters/path_tokenId'
+ - in: query
+ name: card_id # TODO should we keep this parameter when it is anyway optional?
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardId'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Single token was found. If the tokenId was not found, a 400 is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/CardTokenDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /card-transactions:
+ get:
+ summary: Provides a list of transactions which match the provided query parameters.
+ description: >
+ This operation enables the retrieval of a list of transactions performed with a payment card or token.
+ Different query parameters are provided to support an efficient retrieval of individual transactions.
+ With the Level 1 of the Common Card API only card-based financial transactions are included.
+ tags:
+ - Transactions
+ parameters:
+ - in: query
+ name: authorization_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/AuthorizationReference'
+ description: >
+ Retrieves the transaction related to an individual authorization. Parameter can be used to also retrieve the cleared transaction based on the authorization reference.
+ - in: query
+ name: clearing_reference
+ required: false
+ schema:
+ $ref: '#/components/schemas/ClearingReference'
+ description: >
+ Retrieves the transaction related to an individual clearing.
+ Query parameter only returns results for cleared transactions (those booked on the card account for credit and prepaid or bank account for debit cards).
+ - in: query
+ name: card_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/CardId'
+ description: Retrieves all transactions related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ - in: query
+ name: token_id
+ required: false
+ schema:
+ $ref: '#/components/schemas/TokenId'
+ description: Retrieves all transactions related to a token. Value has to be a technical identifier for the card that can be retrieved with the GET /card-tokens endpoint.
+ - in: query
+ name: from_date
+ required: false
+ schema:
+ $ref: '#/components/schemas/DateTime'
+ description: Retrieves all transactions that took place after the provided date time. Filtering is applied on the transaction_date_time attribute.
+ - in: query
+ name: to_date
+ required: false
+ schema:
+ $ref: '#/components/schemas/DateTime'
+ description: Retrieves all transactions that took place before the provided date time. Filtering is applied on the transaction_date_time attribute.
+ - in: query
+ name: status
+ required: false
+ schema:
+ $ref: '#/components/schemas/TransactionStatus'
+ description: Retrieves all transactions in a certain status. Only one status can be filtered at a time.
+ - in: query
+ name: original_currency
+ required: false
+ schema:
+ $ref: '#/components/schemas/OriginalCurrency'
+ description: Retrieves all transactions in a certain currency. Filtering is applied on the original_currency attribute.
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ $ref: '#/components/schemas/TransactionDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+ /card-transactions/{transactionId}:
+ get:
+ summary: Provides a single transaction which matches the transactionId
+ description: >
+ This operation enables the retrieval of a single transaction when the transactionId is already known.
+ The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer.
+ tags:
+ - Transactions
+ parameters:
+ - $ref: '#/components/parameters/path_transactionId'
+ - $ref: '#/components/parameters/client_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Single token was found. If the transactionId was not found, a 400 is returned.
+ headers:
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/TransactionDetails'
+ '400':
+ $ref: '#/components/responses/standard400'
+ '500':
+ $ref: '#/components/responses/standard500'
+
+components:
+ schemas:
+ CardDetails:
+ title: Card details
+ description: Describes a payment card with its relevant characteristics.
+ type: object
+ required:
+ - contract_reference
+ - person_reference
+ - card_id
+ - embossing_line_1
+ - embossing_line_2
+ - pan_4_digits
+ - expiry_date
+ - card_status
+ - currency
+ - image
+ - product_code
+ - product_name
+ - scheme
+ - issuing_type
+ - product_type
+ - product_line
+ - card_limit_cycle
+ - card_limit_daily
+ - issuer_code
+ - issuer_name
+ - language
+ properties:
+ contract_reference:
+ $ref: '#/components/schemas/ContractReference'
+ person_reference:
+ $ref: '#/components/schemas/PersonReference'
+ card_id:
+ $ref: '#/components/schemas/CardId'
+ embossing_line_1:
+ $ref: '#/components/schemas/EmbossingLine1'
+ embossing_line_2:
+ $ref: '#/components/schemas/EmbossingLine2'
+ pan_4_digits:
+ $ref: '#/components/schemas/Pan4Digits'
+ expiry_date:
+ $ref: '#/components/schemas/ExpiryDate'
+ initial_issuing_date:
+ $ref: '#/components/schemas/InitialIssuingDate'
+ card_status:
+ $ref: '#/components/schemas/CardStatus'
+ currency:
+ $ref: '#/components/schemas/Currency'
+ image:
+ $ref: '#/components/schemas/Image'
+ product_code:
+ $ref: '#/components/schemas/ProductCode'
+ product_name:
+ $ref: '#/components/schemas/ProductName'
+ scheme:
+ $ref: '#/components/schemas/Scheme'
+ category:
+ $ref: '#/components/schemas/Category'
+ issuing_type:
+ $ref: '#/components/schemas/IssuingType'
+ product_type:
+ $ref: '#/components/schemas/ProductType'
+ product_line:
+ $ref: '#/components/schemas/ProductLine'
+ card_limit_cycle:
+ $ref: '#/components/schemas/CardLimitCycle'
+ card_limit_daily:
+ $ref: '#/components/schemas/CardLimitDaily'
+ card_account_reference:
+ $ref: '#/components/schemas/CardAccountReference'
+ bank_account_reference:
+ $ref: '#/components/schemas/BankAccountReference'
+ issuer_code:
+ $ref: '#/components/schemas/IssuerCode'
+ issuer_name:
+ $ref: '#/components/schemas/IssuerName'
+ distribution_partner_code:
+ $ref: '#/components/schemas/DistributionPartnerCode'
+ distribution_partner_name:
+ $ref: '#/components/schemas/DistributionPartnerName'
+ language:
+ $ref: '#/components/schemas/Language'
+
+ CardTokenDetails:
+ title: Card token details
+ description: Describes a token with its relevant characteristics.
+ type: object
+ required:
+ - token_id
+ - token_pan_4_digits
+ - token_requestor_code
+ - token_requestor_name
+ - funding_card_id
+ - token_status
+ - token_issuing_date
+ - token_scheme
+ properties:
+ token_id:
+ $ref: '#/components/schemas/TokenId'
+ token_pan_4_digits:
+ $ref: '#/components/schemas/TokenPan4Digits'
+ wallet_code:
+ $ref: '#/components/schemas/WalletCode'
+ wallet_name:
+ $ref: '#/components/schemas/WalletName'
+ token_requestor_code:
+ $ref: '#/components/schemas/TokenRequestorCode'
+ token_requestor_name:
+ $ref: '#/components/schemas/TokenRequestorName'
+ device_name:
+ $ref: '#/components/schemas/DeviceName'
+ device_type:
+ $ref: '#/components/schemas/DeviceType'
+ funding_card_id:
+ $ref: '#/components/schemas/FundingCardId'
+ token_status:
+ $ref: '#/components/schemas/TokenStatus'
+ token_issuing_date:
+ $ref: '#/components/schemas/TokenIssuingDate'
+ token_scheme:
+ $ref: '#/components/schemas/TokenScheme'
+
+ TransactionDetails:
+ title: Transaction details
+ description: Describes a transaction with its relevant characteristics.
+ type: object
+ required:
+ - transaction_id
+ - transaction_date_time
+ - valuta_date
+ - transaction_status
+ - original_amount
+ - original_currency
+ - mcc
+ - mcc_description
+ - transaction_category
+ - card_id
+ properties:
+ transaction_id:
+ $ref: '#/components/schemas/TransactionId'
+ authorization_reference:
+ $ref: '#/components/schemas/AuthorizationReference'
+ clearing_reference:
+ $ref: '#/components/schemas/ClearingReference'
+ transaction_date_time:
+ $ref: '#/components/schemas/TransactionDateTime'
+ valuta_date:
+ $ref: '#/components/schemas/ValutaDate'
+ statement_date:
+ $ref: '#/components/schemas/StatementDate'
+ transaction_status:
+ $ref: '#/components/schemas/TransactionStatus'
+ approval_number:
+ $ref: '#/components/schemas/ApprovalNumber'
+ original_amount:
+ $ref: '#/components/schemas/OriginalAmount'
+ original_currency:
+ $ref: '#/components/schemas/OriginalCurrency'
+ total_amount:
+ $ref: '#/components/schemas/TotalAmount'
+ transaction_amount:
+ $ref: '#/components/schemas/TransactionAmount'
+ transaction_currency:
+ $ref: '#/components/schemas/TransactionCurrency'
+ fees:
+ $ref: '#/components/schemas/Fees'
+ exchange_rate:
+ $ref: '#/components/schemas/ExchangeRate'
+ exchange_rate_date:
+ $ref: '#/components/schemas/ExchangeRateDate'
+ description:
+ $ref: '#/components/schemas/Description'
+ merchant_name:
+ $ref: '#/components/schemas/MerchantName'
+ merchant_country:
+ $ref: '#/components/schemas/MerchantCountry'
+ merchant_city:
+ $ref: '#/components/schemas/MerchantCity'
+ mcc:
+ $ref: '#/components/schemas/Mcc'
+ mcc_description:
+ $ref: '#/components/schemas/MccDescription'
+ terminal_reference:
+ $ref: '#/components/schemas/TerminalReference'
+ card_acceptor_reference:
+ $ref: '#/components/schemas/CardAcceptorReference'
+ acquirer_reference:
+ $ref: '#/components/schemas/AcquirerReference'
+ channel:
+ $ref: '#/components/schemas/Channel'
+ transaction_category:
+ $ref: '#/components/schemas/TransactionCategory'
+ token_id:
+ $ref: '#/components/schemas/TokenId'
+ cardholder_reference:
+ $ref: '#/components/schemas/CardholderReference'
+ card_account_reference:
+ $ref: '#/components/schemas/CardAccountReference'
+ card_id:
+ $ref: '#/components/schemas/CardId'
+ related_transaction_id:
+ $ref: '#/components/schemas/RelatedTransactionId'
+
+ ContractReference:
+ title: Contract reference
+ type: string
+ maxLength: 50
+ examples:
+ - CH3456789012345678901
+ - ABC-56789012345
+ description: Functional reference to a customer relationship/contract that is responsible for the card, defined by the Card Service Provider.
+
+ PersonReference:
+ title: Person reference
+ type: string
+ maxLength: 50
+ examples:
+ - '123456789'
+ description: Functional reference to a cardholder, defined by the Card Service Provider.
+
+ CardId:
+ title: Card id
+ type: string
+ format: uuid
+ maxLength: 50
+ examples:
+ - 4321A1B2C3DE1234
+ description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals).
+
+ EmbossingLine1:
+ title: Embossing line 1
+ type: string
+ maxLength: 35
+ examples:
+ - Peter Schweizer
+ description: First line embossed on the card to indicate the cardholder.
+
+ EmbossingLine2:
+ title: Embossing line 2
+ type: string
+ maxLength: 35
+ examples:
+ - Peter Schweizer
+ description: Second line embossed on the card to indicate the cardholder.
+
+ Pan4Digits:
+ title: Pan 4 digits
+ type: string
+ maxLength: 4
+ pattern: '^\d{4}$'
+ examples:
+ - '4321'
+ description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
+
+ ExpiryDate:
+ title: Expiry date
+ $ref: '#/components/schemas/Date'
+ description: Last day when the card is valid and can be used for payments.
+
+ InitialIssuingDate:
+ title: Initial issuing date
+ $ref: '#/components/schemas/Date'
+ description: Date when card was issued initially.
+
+ CardStatus:
+ title: Card status
+ type: string
+ enum:
+ - ACTIVE
+ - SUSPENDED
+ - BLOCKED
+ examples:
+ - ACTIVE
+ description: |
+ Effective status of the card to indicate whether it can be used for payments; definition of enums:
+ - active: authorizations are possible
+ - suspended: authorizations are temporarily not possible
+ - blocked: authorizations are permanently not possible because the card was cancelled or permanently blocked for other reasons
+
+ Currency:
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ - CHF
+ - EUR
+ description: Settlement currency of the card / card account in ISO code format.
+
+ Image:
+ type: string
+ format: uri
+ examples:
+ - https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
+ description: URL reference to an image for the design of the card.
+
+ ProductCode:
+ title: Product code
+ type: string
+ maxLength: 50
+ examples:
+ - '1234567'
+ description: Identifier for the card product.
+
+ ProductName:
+ title: Product name
+ type: string
+ maxLength: 100
+ examples:
+ - A1
+ - MC/VI Gold CHF
+ description: Name for the card product assigned by the issuer.
+
+ Scheme:
+ type: string
+ enum:
+ - mastercard
+ - visa
+ - americanexpress
+ - dinersclub
+ examples:
+ - mastercard
+ description: Card network which is used to process payments with the card in switzerland.
+
+ Category:
+ type: string
+ enum:
+ - primary_card
+ - additional_card
+ examples:
+ - primary_card
+ description: Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect of certain lifecycle use cases.
+
+ IssuingType:
+ title: Issuing type
+ type: string
+ enum:
+ - physical
+ - virtual
+ examples:
+ - physical
+ description: >
+ Specifies in which form the card is issued; definition of enums:
+ - physical: the card is being embossed on a physical material and delivered to the cardholder by mail
+ - virtual: the card is being issued only virtually for digital usage
+
+ ProductType:
+ title: Product type
+ type: string
+ enum:
+ - credit
+ - debit
+ - prepaid
+ examples:
+ - credit
+ description: Type of the card product.
+
+ ProductLine:
+ title: Product line
+ type: string
+ enum:
+ - consumer
+ - business
+ - corporate
+ examples:
+ - consumer
+ description: Customer segment to which the card is offered.
+
+ CardLimitCycle:
+ title: Card limit cycle
+ type: integer
+ format: int32
+ examples:
+ - 2000
+ description: >
+ Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card;
+ effective limit is provided that considers limits on the card and relationship;
+ does not indicate the actually available amount for authorizations in the current cycle.
+
+ CardLimitDaily:
+ title: Card limit daily
+ type: integer
+ format: int32
+ examples:
+ - 2000
+ description: >
+ Total amount of authorizations possible for the card per day in the currency of the card;
+ effective limit is provided that considers limits on the card and relationship;
+ does not indicate the actually available amount for authorizations on the current day.
+
+ CardAccountReference:
+ title: Card account reference
+ type: string
+ maxLength: 50
+ examples:
+ - AB-4567890123456
+ description: >
+ Technical reference to the card account which is used to settle the transactions of the card;
+ can be empty for debit cards which are settled directly to the bank account.
+
+ BankAccountReference:
+ title: Bank account reference
+ type: string
+ maxLength: 34
+ examples:
+ - CH3456789012345678901
+ description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
+
+ IssuerCode:
+ title: Issuer code
+ type: string
+ maxLength: 50
+ examples:
+ - '123456789'
+ description: Identifier for the legal issuer of a card; responsible towards the schemes for keeping the rules.
+
+ IssuerName:
+ title: Issuer name
+ type: string
+ maxLength: 100
+ examples:
+ - Viseca Card Services
+ - UBS
+ - Zürcher Kantonalbank
+ description: Name of the legal issuer of a card.
+
+ DistributionPartnerCode:
+ title: Distribution partner code
+ type: string
+ maxLength: 50
+ examples:
+ - '123456789'
+ description: >
+ Identifier for the organization which is distributing / selling cards to end customers
+ and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+
+ DistributionPartnerName:
+ title: Distribution partner name
+ type: string
+ maxLength: 100
+ examples:
+ - Zürcher Kantonalbank
+ description: >
+ Name of the organization which is distributing / issuing cards to end customers
+ and who can define the services and branding of the card; empty if the card is distributed by the issuer.
+
+ Language:
+ type: string
+ enum:
+ - DE
+ - EN
+ - FR
+ - IT
+ examples:
+ - DE
+ description: Preferred language of the cardholder for any communication.
+
+ TokenId:
+ title: Token id
+ type: string
+ format: uuid
+ maxLength: 50
+ examples:
+ - eb404f8d-656b-4e51-8872-88c42fa55536
+ description: Unique identifier for the token of a card, defined by the Card Service Provider.
+
+ TokenPan4Digits:
+ title: Token pan 4 digits
+ type: string
+ maxLength: 4
+ examples:
+ - '4321'
+ description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
+
+ WalletCode:
+ title: Wallet code
+ type: string
+ maxLength: 10
+ examples:
+ - '123'
+ description: Identifier for the wallet in which the token is used and managed.
+
+ WalletName:
+ title: Wallet name
+ type: string
+ enum:
+ - APPLE_PAY
+ - SAMSUNG_PAY
+ - GOOGLE_PAY
+ - GARMIN_PAY
+ examples:
+ - APPLE_PAY
+ description: Name of the wallet in which the token is used and managed.
+
+ TokenRequestorCode:
+ title: Token requestor code
+ type: string
+ maxLength: 11
+ examples:
+ - '11111111111'
+ description: Identifier for the token requestor / token service provider.
+
+ TokenRequestorName:
+ title: Token requestor name
+ type: string
+ maxLength: 100
+ examples:
+ - Zalando
+ description: Name of the token requestor / token service provider.
+
+ DeviceName:
+ title: Device name
+ type: string
+ maxLength: 100
+ examples:
+ - Peter's iPhone
+ description: Name of the device which is associated to the token, only available for device-based tokens.
+
+ DeviceType:
+ title: Device type
+ type: string
+ maxLength: 100
+ examples:
+ - IPHONE
+ description: Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
+
+ FundingCardId:
+ title: Funding card id
+ type: string
+ format: uuid
+ maxLength: 50
+ examples:
+ - 4321A1B2C3DE1234
+ description: Reference to the card that is used to fund the transactions of the token.
+
+ TokenStatus:
+ title: Token status
+ type: string
+ enum:
+ - ACTIVE
+ - SUSPENDED
+ - BLOCKED
+ - PENDING
+ examples:
+ - ACTIVE
+ description: |
+ Effective status of the token to indicate whether it can be used for payments; definition of enums:
+ - active: authorizations are possible
+ - suspended: authorizations are temporarily not possible
+ - blocked: authorizations are permanently not possible because the token was cancelled
+ - pending: authorizations are not possible because the token is not fully issued or currently in transition between status
+
+ TokenIssuingDate:
+ title: Token issuing date
+ $ref: '#/components/schemas/Date'
+ description: Date when the token was issued.
+
+ TokenScheme:
+ title: Token scheme
+ type: string
+ enum:
+ - mastercard
+ - visa
+ - americanexpress
+ examples:
+ - mastercard
+ description: Scheme for which the token is issued.
+
+ TransactionId:
+ title: Transaction id
+ type: string
+ format: uuid
+ maxLength: 50
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: UUID to link AuthorizationReference and ClearingReference.
+
+ AuthorizationReference:
+ title: Authorization reference
+ type: string
+ maxLength: 50
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: >
+ Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present.
+
+ ClearingReference:
+ title: Clearing reference
+ type: string
+ maxLength: 50
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: >
+ Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present.
+
+ TransactionDateTime:
+ title: Transaction date-time
+ $ref: '#/components/schemas/DateTime'
+ description: Date and time when transaction was authorized, always in CH timezone.
+
+ ValutaDate:
+ title: Valuta date
+ $ref: '#/components/schemas/Date'
+ description: Date when the transaction becomes effective on the card account for calculating interest.
+
+ StatementDate:
+ title: Statement date
+ $ref: '#/components/schemas/Date'
+ description: Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
+
+ TransactionStatus:
+ title: Transaction status
+ type: string
+ enum:
+ - authorized
+ - booked
+ examples:
+ - authorized
+ description: >
+ Status of the transaction; definition of enums:
+ - authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
+ - booked: transaction was cleared/settled and charged to the card account
+
+ ApprovalNumber:
+ title: Approval number (also known as approval code)
+ type: string
+ pattern: '^\d{6}$'
+ examples:
+ - '803051'
+ description: >
+ Identifies a transaction from the entity that authorized it;
+ in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
+
+ OriginalAmount:
+ title: Original amount
+ type: number
+ examples:
+ - 2000.05
+ description: Amount of the transaction in the currency used by the merchant.
+
+ OriginalCurrency:
+ title: Original currency
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ - CHF
+ description: Currency of the card account on which the transaction is charged.
+
+ TotalAmount:
+ title: Total amount
+ type: number
+ examples:
+ - 1957.50
+ description: >
+ Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
+ positive amounts are debit transactions, negative amounts are credit transactions.
+
+ TransactionAmount:
+ title: Transaction amount
+ type: number
+ examples:
+ - 1952.50
+ description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
+
+ TransactionCurrency:
+ title: Transaction currency
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ - CHF
+ description: Currency of the card account on which the transaction is charged.
+
+ Fees:
+ title: Fees
+ description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
+ type: object
+ required:
+ - fee_name
+ properties:
+ fee_name:
+ $ref: '#/components/schemas/FeeName'
+ fee_percentage:
+ $ref: '#/components/schemas/FeePercentage'
+ fee_amount:
+ $ref: '#/components/schemas/FeeAmount'
+ fee_currency:
+ $ref: '#/components/schemas/FeeCurrency'
+
+ ExchangeRate:
+ title: Exchange rate
+ type: number
+ examples:
+ - 1.0485930
+ description: Exchange rate for converting the originalAmount into the transactionAmount.
+
+ ExchangeRateDate:
+ title: Exchange rate date
+ $ref: '#/components/schemas/Date'
+ description: Date which was used to determine the exchange rate, usually the valutaDate.
+
+ Description:
+ type: string
+ maxLength: 100
+ examples:
+ - Aufladung
+ description: Description of the purpose of the transaction and potentially a reference to the merchant.
+
+ MerchantName:
+ title: Merchant name
+ type: string
+ maxLength: 100
+ examples:
+ - Yallo
+ description: Name of the merchant who requested the transaction.
+
+ MerchantCountry:
+ title: Merchant country
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ - CHE
+ description: Country in which the merchant is located.
+
+ MerchantCity:
+ title: Merchant city
+ type: string
+ maxLength: 50
+ examples:
+ - Zurich
+ description: City in which the merchant is located.
+
+ Mcc:
+ type: string
+ maxLength: 4
+ examples:
+ - '4812'
+ description: Merchant Category Code to identify the industry branch of the merchant.
+
+ MccDescription:
+ title: Mcc description
+ type: string
+ maxLength: 100
+ examples:
+ - Telco
+ description: Description for the mcc.
+
+ TerminalReference:
+ title: Terminal reference (also known as terminal id)
+ type: string
+ maxLength: 8
+ examples:
+ - '12345678'
+ description: Identifier for the terminal which has read the card data.
+
+ CardAcceptorReference:
+ title: Card acceptor reference
+ type: string
+ maxLength: 15
+ examples:
+ - '87040'
+ description: Identifier for the merchant who requested the transaction.
+
+ AcquirerReference:
+ title: Acquirer reference (also known as acquirer id)
+ type: string
+ maxLength: 11
+ examples:
+ - '12345678901'
+ description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
+
+ Channel:
+ type: string
+ enum:
+ - standard
+ - ecommerce
+ examples:
+ - standard
+ description: Channel that was used by the cardholder for executing the transaction, allows the identification of eCommerce transactions.
+
+ TransactionCategory:
+ title: Transaction category
+ type: string
+ maxLength: 50
+ examples:
+ - '100: Cash withdrawal'
+ - '103: ATM operator refund'
+ - '117: P2P payment charge sender'
+ - '118: P2P payment credit recipient'
+ - merchant
+ - fee
+ - atm
+ description: Category of the transaction, defined by the Card Service Provider.
+
+ CardholderReference:
+ title: Cardholder reference
+ type: string
+ maxLength: 50
+ examples:
+ - Peter Schweizer
+ description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
+
+ RelatedTransactionId:
+ title: Transaction reference
+ type: string
+ format: uuid
+ maxLength: 50
+ examples:
+ - 9e19df54-47cb-494b-84dc-1c126e95a05c
+ description: Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
+
+ FeeName:
+ title: Fee name
+ type: string
+ maxLength: 50
+ examples:
+ - transactionTipAmount
+ - transactionSurchargeAmount
+ description: Name of the fee that is charged for the transaction; value is defined by the Issuer.
+
+ FeePercentage:
+ title: Fee percentage
+ type: number
+ examples:
+ - 3.5
+ description: >
+ Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
+ Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
+
+ FeeAmount:
+ title: Fee amount
+ type: number
+ examples:
+ - 5.00
+ description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
+
+ FeeCurrency:
+ title: Fee currency
+ type: string
+ pattern: '^[a-zA-Z0-9]{3}$'
+ examples:
+ - CHF
+ description: Currency that is used for charging the fee, usually the same as the currency of the card account.
+
+ Correlation:
+ type: string
+ examples:
+ - f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Schema for X-Correlation-ID header.
+
+ Date:
+ type: string
+ format: date
+ examples:
+ - 2018-04-13
+ description: General date that is used for different attributes, format is 'YYYY-MM-DD'.
+
+ DateTime:
+ title: Date-time
+ type: string
+ format: date-time
+ examples:
+ - 2018-04-13T11:11:11Z
+ description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'.
+
+ LinksPagination:
+ description: Links (or cursors) returned in the answer of an API call.
+ type: object
+ properties:
+ self:
+ type: string
+ format: uri
+ description: Link / cursor to the current result set (based on the submitted pagination approach).
+ examples:
+ - /card-app/api/v1/products?offset=75&limit=25
+ first:
+ type: string
+ format: uri
+ description: Link / cursor to the first result set (based on the submitted pagination approach).
+ examples:
+ - /card-app/api/v1/products?offset=0&limit=25
+ previous:
+ type: string
+ format: uri
+ description: Link / cursor to the previous result set (based on the submitted pagination approach).
+ examples:
+ - /card-app/api/v1/products?offset=50&limit=25
+ next:
+ type: string
+ format: uri
+ description: Link / cursor to the next result set (based on the submitted pagination approach).
+ examples:
+ - /card-app/api/v1/products?offset=100&limit=25
+ last:
+ type: string
+ format: uri
+ description: Link / cursor to the last result set (based on the submitted pagination approach).
+ examples:
+ - /card-app/api/v1/products?offset=150&limit=25
+
+ CommonErrorResponse:
+ title: Common Error Response
+ description: General error response structure used in different response codes.
+ type: object
+ properties:
+ type:
+ $ref: '#/components/schemas/CommonErrorType'
+ title:
+ type: string
+ description: Short name for the problem.
+ examples:
+ - This is the general problem description
+ detail:
+ type: string
+ description: More details about the problem.
+ examples:
+ - Detailed problem description with respect to the current request
+ instance:
+ type: string
+ description: Reference to an individual entity or request which caused the problem.
+ examples:
+ - path/to/corresponding/resource
+
+ CommonErrorType:
+ title: Common Error Type
+ description: Error Types for CommonErrorResponse.
+ type: string
+ enum:
+ - /problems/INVALID_PAYLOAD
+ - /problems/MALFORMED_PAYLOAD
+ - /problems/INVALID_TOKEN
+ - /problems/EXPIRED_TOKEN
+ - /problems/INSUFFICIENT_PRIVILEGES
+ - /problems/NO_ACCESS_TO_RESOURCE
+ - /problems/RESOURCE_DOES_NOT_EXIST
+ - /problems/RESOURCE_NOT_READY
+ - /problems/RESOURCE_TOO_LARGE
+ - /problems/WRONG_METHOD
+ - /problems/OPERATION_NOT_ALLOWED
+ - /problems/TECHNICAL_ERROR
+ - /problems/NOT_IMPLEMENTED
+ - /problems/SERVICE_UNAVAILABLE
+ examples:
+ - /problems/TECHNICAL_ERROR
+
+ parameters:
+ path_cardId:
+ in: path
+ name: cardId
+ required: true
+ schema:
+ $ref: '#/components/schemas/CardId'
+ description: Identifier (technical) for a card for which information is requested.
+
+ path_tokenId:
+ in: path
+ name: tokenId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TokenId'
+ description: Identifier (technical) for a token for which information is requested.
+
+ path_transactionId:
+ in: path
+ name: transactionId
+ required: true
+ schema:
+ $ref: '#/components/schemas/TransactionId'
+ description: Identifier (technical) for a transaction for which information is requested.
+
+ limit:
+ in: query
+ name: limit
+ required: false
+ schema:
+ type: integer
+ format: int32
+ minimum: 1
+ examples:
+ - 25
+ description: Optional parameter for pagination. Maximum number of entries to be returned.
+
+ offset:
+ in: query
+ name: offset
+ required: false
+ schema:
+ type: integer
+ format: int32
+ minimum: 0
+ examples:
+ - 25
+ description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
+
+ client_in_header:
+ in: header
+ name: X-CorAPI-Client-ID
+ required: true
+ schema:
+ type: string
+ description: ID of the client forwarded to the provider.
+
+ correlation_in_header:
+ in: header
+ name: X-Correlation-ID
+ required: true
+ schema:
+ $ref: '#/components/schemas/Correlation'
+ description: Unique ID (defined by the caller) which will be reflected back in the response.
+
+ agent_in_header:
+ in: header
+ name: User-Agent
+ required: true
+ schema:
+ type: string
+ description: Name and version of the of the Client software.
+
+ securitySchemes:
+ ApiKeyAuth:
+ type: apiKey
+ in: header
+ name: X-API-Key
+ OAuth2:
+ type: oauth2
+ flows:
+ authorizationCode:
+ authorizationUrl: https://example.com/oauth/authorize
+ tokenUrl: https://example.com/oauth/token
+ scopes:
+ read: Grants read access
+ write: Grants write access
+
+ responses:
+ standard400:
+ headers:
+ Content-Type:
+ $ref: '#/components/headers/Content-Type'
+ Content-Language:
+ $ref: '#/components/headers/Content-Language'
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ description: >
+ Client Error - The request could not be processed due to a problem in the data provided.
+ This could be for any of the reasons of the HTML standard that would result in a 4xx code.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/CommonErrorResponse'
+
+ standard500:
+ headers:
+ Content-Type:
+ $ref: '#/components/headers/Content-Type'
+ Content-Language:
+ $ref: '#/components/headers/Content-Language'
+ X-Correlation-ID:
+ $ref: '#/components/headers/X-Correlation-ID'
+ description: >
+ Internal Server Error - The request could not be processed due to a problem at the data provider.
+ This could be for any of the reasons of the HTML standard that would result in a 5xx code.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/CommonErrorResponse'
+
+ headers:
+ Content-Language:
+ schema:
+ type: string
+ examples:
+ - en
+ description: Language of provided content.
+
+ Content-Type:
+ schema:
+ type: string
+ examples:
+ - application/json
+ - application/problem+json; charset=utf-8 according to RFC7807
+ description: Type of provided content.
+
+ X-Correlation-ID:
+ schema:
+ $ref: '#/components/schemas/Correlation'
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
index e3478d6..8ffe49b 100644
--- a/cardInfoAPI.yaml
+++ b/cardInfoAPI.yaml
@@ -1,87 +1,181 @@
-openapi: 3.1.0
+openapi: "3.0.3"
info:
- version: 0.7.0
- title: Common Card API (Public)
- description: >
- This specification defines a common card API for payment cards used in Switzerland.
- The API is supposed to be used by third parties to retrieve payment card information for scheme-based debit, credit or prepaid cards (read only).
+ version: "0.6"
+ title: Common Card Info API (Public)
+ description:
+ This specification defines a common card info API for payment cards used in Switzerland. The API is supposed to be used to retrieve payment card infos (read only).
+ termsOfService: 'Tbd'
contact:
email: info@common-api.ch
license:
name: Apache 2.0
- url: https://www.apache.org/licenses/LICENSE-2.0.html
+ url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
- url: https://card.common-api.ch
externalDocs:
description: Find out more about SFTI API specifications
- url: https://www.common-api.ch
-
-tags:
- - name: Cards
- description: Operations for retrieving information about payment cards.
- - name: Card-tokens
- description: Operations for retrieving information about tokens associated with payment cards.
- - name: Transactions
- description: Operations for retrieving information about transactions and authorizations done with payment cards or tokens.
-
+ url: 'https://www.common-api.ch'
security:
- ApiKeyAuth: []
- OAuth2:
- read
- write
+tags:
+ - name: cards
+ description: Operations related with managing cards
+ - name: card-accounts
+ description: Operations related with managing card accounts
+ - name: statements
+ description: Operations related with retrieving card account statements
+ - name: transactions
+ description: Operations related with retrieving card transactions
+ - name: persons
+ description: Operations related with managing persons
+ - name: card-contracts
+ description: Operations related with managing card contracts
+ - name: card-accountbundles
+ description: --
+ - name: card-consents
+ description: '[not used] Operations related with managing card consents'
+
paths:
/cards:
get:
- summary: Provides a list of cards which match the provided query parameters.
- description: >
- This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
- In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
- The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number).
tags:
- - Cards
+ - cards
+ description: List of cards for the authenticated context including all related information, optional filtered by personId / cardContractId / cardAccountId, sorted by cardId.
+ summary: Return the list of all cards for the authenticated context (filtered and sorted)
parameters:
- - in: query
- name: contract_reference
+ - $ref: '#/components/parameters/transactionId'
+ - $ref: '#/components/parameters/cardAccountId'
+ - $ref: '#/components/parameters/personId'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: Paginated list of all cards with all related information sorted by cardId
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ cardList:
+ type: array
+ items:
+ $ref: '#/components/schemas/card'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
+ '400':
+ $ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
+ '500':
+ $ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
+
+ /cards/card-tokens:
+ get:
+ tags:
+ - card-tokens
+ description: Card token (Child card) derived from parent card
+ summary: TODO
+ parameters:
+ - $ref: '#/components/parameters/cardTokenId'
+ - name: deviceName
+ in: query
+ description: Name of device, where token is used
required: false
+ example: apple
schema:
- $ref: '#/components/schemas/ContractReference'
- description: Retrieves all cards related to a contract. Value has to be a functional reference to the contract that can be known by the end customer.
- - in: query
- name: person_reference
+ type: string
+ enum:
+ - apple
+ - samsung
+ - other
+ - name: cardLink
+ in: query
+ description: TODO
+ required: true
+ example: TODO
+ schema:
+ type: string
+ - name: dpan
+ in: query
+ description: TODO
+ required: true
+ example: TODO
+ schema:
+ type: string
+ format: uuid
+ - name: statusGeneric
+ in: query
+ description: TODO
required: false
+ example: TODO
schema:
- $ref: '#/components/schemas/PersonReference'
- description: Retrieves all cards related to an individual person/cardholder. Value has to be a functional reference to the person that can be known by the end customer.
- - in: query
- name: card_status
+ type: string
+ - name: walletTypeName
+ in: query
+ description: Issuer of token card
required: false
+ example: TODO
schema:
- $ref: '#/components/schemas/CardStatus'
- description: Retrieves all cards in a certain status. Only one status can be filtered at a time.
- - in: query
- name: card_account_reference
+ type: string
+ enum:
+ - mastercard
+ - visa
+ - amex
+ - dinersclub
+ - apple pay
+ - google pay
+ - other
+ - name: provisionDate
+ in: query
+ description: TODO
required: false
+ example: TODO
schema:
- $ref: '#/components/schemas/CardAccountReference'
- description: Retrieves all cards related to a card account (not bank account). Value has to be a functional reference to the account that can be known by the end customer.
- - in: query
- name: bank_account_reference
+ type: string
+ format: Date
+ - name: expireDate
+ in: query
+ description: TODO
required: false
+ example: TODO
schema:
- $ref: '#/components/schemas/BankAccountReference'
- description: Retrieves all cards related to a bank account (not card account). Value has to be a functional reference to the account that can be known by the end customer and is usually an IBAN.
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ type: string
+ format: Date
+ - name: schemeTokenId
+ in: query
+ description: TODO
+ required: false
+ example: TODO
+ schema:
+ type: string
+ enum:
+ - TODO
+ - $ref: '#/components/schemas/cardTransaction'
responses:
'200':
- description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned.
- headers:
- X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ description: Paginated list of all token cards with all related information sorted by cardTokenId
content:
application/json:
schema:
@@ -90,64 +184,111 @@ paths:
cardList:
type: array
items:
- $ref: '#/components/schemas/CardDetails'
+ $ref: '#/components/schemas/cardToken'
_links:
- $ref: '#/components/schemas/LinksPagination'
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
- /cards/{cardId}:
+ /card-accounts:
get:
- summary: Provides a single card which matches the id.
- description: >
- This operation enables the retrieval of a single payment card when the cardId is already known.
- The cardId must be retrieved with the GET /cards operation before or stored locally at the API consumer.
tags:
- - Cards
+ - card-accounts
+ description: List of card accounts for the authenticated context including all related information, filtered by query, sorted by cardAccountId.
+ summary: Return the list of all card accounts for the authenticated context (filtered and sorted)
parameters:
- - $ref: '#/components/parameters/path_cardId'
+ - $ref: '#/components/parameters/transactionId'
+ - $ref: '#/components/parameters/cardId'
+ - $ref: '#/components/parameters/statementId'
+ - $ref: '#/components/parameters/personId'
+ - $ref: '#/components/parameters/card-accountbundleId'
+ - $ref: '#/components/parameters/cardContractId'
+ - in: query
+ name: IBAN
+ description: International Bank Account Number that is associated with the payment card account. Note, that one IBAN can be associated to multiple card accounts.
+ required: false
+ schema:
+ type: string
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single payment card was found. If the cardId was not found, a 400 is returned.
- headers:
- X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ description: Paginated list of all card accounts with all related information sorted by cardAccountId
content:
application/json:
schema:
- $ref: '#/components/schemas/CardDetails'
+ type: object
+ properties:
+ cardAccountList:
+ type: array
+ items:
+ $ref: '#/components/schemas/cardAccount'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
- /card-tokens:
+ /card-accounts/statements:
get:
- summary: Provides a list of card tokens which are associated with a card.
- description: >
- This operation enables the retrieval of a list of tokens associated with a payment card.
- The tokens can be filtered further by status.
- Tokens are representations of a payment card used in specific wallets , wearables or merchants.
tags:
- - Card-tokens
+ - statements
+ description: List of card account statements for the authenticated context including all related information, filtered by query, sorted by cardAccountStatementId.
+ summary: Return the list of all card account statements for the authenticated context (filtered and sorted)
parameters:
+ - $ref: '#/components/parameters/cardAccountId'
- in: query
- name: card_id
+ name: fromDate
+ description: Date from which statement entries should be retrieved
required: false
schema:
- $ref: '#/components/schemas/CardId'
- description: Retrieves all tokens related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ $ref: '#/components/schemas/date'
- in: query
- name: token_status
+ name: untilDate
+ description: Date until which statement entries should be retrieved
required: false
schema:
- $ref: '#/components/schemas/TokenStatus'
- description: Retrieves all tokens in a certain status. Only one status can be filtered at a time.
+ $ref: '#/components/schemas/date'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
@@ -155,122 +296,173 @@ paths:
- $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: >
- Card tokens were found which match the query parameters.
- If no card tokens matched the parameters or access rights are missing, an empty list is returned.
- headers:
- X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ description: Paginated list of all card account statements with all related information sorted by cardAccountStatementId
content:
application/json:
schema:
type: object
properties:
- cardList:
+ cardAccountStatementList:
type: array
items:
- $ref: '#/components/schemas/CardTokenDetails'
+ $ref: '#/components/schemas/cardAccountStatement'
_links:
- $ref: '#/components/schemas/LinksPagination'
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
- /card-tokens/{tokenId}:
+ /card-transactions:
get:
- summary: Provides a single token which matches the cardId and tokenId
- description: >
- This operation enables the retrieval of a single token when the cardId and tokenId are already known.
- The identifiers must be retrieved with the GET /cards/{cardId}/card-tokens operation before or stored locally at the API consumer.
tags:
- - Card-tokens
+ - transactions
+ description: List of card transactions for the authenticated context including all related information, filtered by query, sorted by cardTransactionId.
+ summary: Return the list of all card transactions for the authenticated context (filtered and sorted)
parameters:
- - $ref: '#/components/parameters/path_tokenId'
+ - $ref: '#/components/parameters/cardId'
+ - $ref: '#/components/parameters/cardAccountId'
- in: query
- name: card_id # TODO should we keep this parameter when it is anyway optional?
+ name: inclName
+ description: Only retrieve transactions that include this text in as a merchant name
+ required: false
+ example: Hotel
+ schema:
+ type: string
+ - name: inclLocation
+ in: query
+ description: Only retrieve transactions that include this text in as a merchant location
+ required: false
+ example: London
+ schema:
+ type: string
+ - name: inclCountry
+ in: query
+ description: Only retrieve transactions that include this text in as a merchant country
+ required: false
+ example: Italien
+ schema:
+ type: string
+ - name: fromDate
+ in: query
+ description: Only retrieve transactions starting from this date (YYYY-MM-DD)
+ required: false
+ schema:
+ $ref: '#/components/schemas/date'
+ - name: untilDate
+ in: query
+ description: Only retrieve transactions up until this date (YYYY-MM-DD)
required: false
schema:
- $ref: '#/components/schemas/CardId'
+ $ref: '#/components/schemas/date'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single token was found. If the tokenId was not found, a 400 is returned.
- headers:
- X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ description: Paginated list of all card transactions with all related information sorted by cardTransactionId
content:
application/json:
schema:
- $ref: '#/components/schemas/CardTokenDetails'
+ type: object
+ properties:
+ cardTransactionList:
+ type: array
+ items:
+ $ref: '#/components/schemas/cardTransaction'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
- /card-transactions:
+ /persons:
get:
- summary: Provides a list of transactions which match the provided query parameters.
- description: >
- This operation enables the retrieval of a list of transactions performed with a payment card or token.
- Different query parameters are provided to support an efficient retrieval of individual transactions.
- With the Level 1 of the Common Card API only card-based financial transactions are included.
tags:
- - Transactions
+ - persons
+ description: List of persons for the authenticated context including all related information, filtered by query which also allows searching, sorted by personId.
+ summary: Return the list of all persons for the authenticated context (filtered and sorted)
parameters:
+ - $ref: '#/components/parameters/cardId'
+ - $ref: '#/components/parameters/cardAccountId'
+ - $ref: '#/components/parameters/cardContractId'
- in: query
- name: authorization_reference
- required: false
- schema:
- $ref: '#/components/schemas/AuthorizationReference'
- description: >
- Retrieves the transaction related to an individual authorization. Parameter can be used to also retrieve the cleared transaction based on the authorization reference.
- - in: query
- name: clearing_reference
+ name: personSurName
+ description: First name of the customer.
required: false
schema:
- $ref: '#/components/schemas/ClearingReference'
- description: >
- Retrieves the transaction related to an individual clearing.
- Query parameter only returns results for cleared transactions (those booked on the card account for credit and prepaid or bank account for debit cards).
+ $ref: '#/components/schemas/personSurName'
- in: query
- name: card_id
+ name: personName
+ description: Last name of the customer.
required: false
schema:
- $ref: '#/components/schemas/CardId'
- description: Retrieves all transactions related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ $ref: '#/components/schemas/personName'
- in: query
- name: token_id
+ name: companyName
+ description: 'Retrieve a list of customers given the company name.'
required: false
schema:
- $ref: '#/components/schemas/TokenId'
- description: Retrieves all transactions related to a token. Value has to be a technical identifier for the card that can be retrieved with the GET /card-tokens endpoint.
+ $ref: '#/components/schemas/entityName'
- in: query
- name: from_date
+ name: birthDate
+ description: Date of birth of the person.
required: false
schema:
- $ref: '#/components/schemas/DateTime'
- description: Retrieves all transactions that took place after the provided date time. Filtering is applied on the transaction_date_time attribute.
+ $ref: '#/components/schemas/date'
- in: query
- name: to_date
+ name: contractType
+ description: Possible values are consumer, business, corporate (if left empty, any will be provided)
required: false
schema:
- $ref: '#/components/schemas/DateTime'
- description: Retrieves all transactions that took place before the provided date time. Filtering is applied on the transaction_date_time attribute.
+ $ref: '#/components/schemas/contractType'
- in: query
- name: status
+ name: searchType
+ description: Possible values are same, soundex, ccv
required: false
schema:
- $ref: '#/components/schemas/TransactionStatus'
- description: Retrieves all transactions in a certain status. Only one status can be filtered at a time.
- - in: query
- name: original_currency
- required: false
- schema:
- $ref: '#/components/schemas/OriginalCurrency'
- description: Retrieves all transactions in a certain currency. Filtering is applied on the original_currency attribute.
+ type: string
+ enum:
+ - same
+ - soundex
+ - cvv
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
@@ -278,967 +470,1136 @@ paths:
- $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned.
- headers:
- X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ description: Paginated list of all person with all related information sorted by personId
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/TransactionDetails'
+ type: object
+ properties:
+ personList:
+ type: array
+ items:
+ $ref: '#/components/schemas/person'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
- /card-transactions/{transactionId}:
+ /card-contracts:
get:
- summary: Provides a single transaction which matches the transactionId
- description: >
- This operation enables the retrieval of a single transaction when the transactionId is already known.
- The transactionId must be retrieved with the GET /card-transactions operation before or stored locally at the API consumer.
tags:
- - Transactions
+ - card-contracts
+ description: List of cards contracts for the authenticated context including all related information, filtered by query, sorted by cardContractId.
+ summary: Return the list of all card contracts for the authenticated context (filtered and sorted)
parameters:
- - $ref: '#/components/parameters/path_transactionId'
+ - $ref: '#/components/parameters/personId'
+ - $ref: '#/components/parameters/cardAccountId'
+ - $ref: '#/components/parameters/card-accountbundleId'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/clientid_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
responses:
'200':
- description: Single token was found. If the transactionId was not found, a 400 is returned.
+ description: Paginated list of all queried card contracts with all related information sorted by cardContractsId
+ content:
+ application/json:
+ schema:
+ type: object
+ properties:
+ cardContractList:
+ type: array
+ items:
+ $ref: '#/components/schemas/cardContract'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
headers:
X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
+ '400':
+ $ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
+ '500':
+ $ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
+
+ /card-accountbundles:
+ get:
+ tags:
+ - card-accountbundles
+ description: --
+ summary: --
+ parameters:
+ - $ref: '#/components/parameters/cardAccountId'
+ - $ref: '#/components/parameters/card-accountbundleId'
+ - $ref: '#/components/parameters/cardContractId'
+ - $ref: '#/components/parameters/limit'
+ - $ref: '#/components/parameters/offset'
+ - $ref: '#/components/parameters/clientid_in_header'
+ - $ref: '#/components/parameters/correlation_in_header'
+ - $ref: '#/components/parameters/agent_in_header'
+ responses:
+ '200':
+ description: --
content:
application/json:
schema:
- $ref: '#/components/schemas/TransactionDetails'
+ type: object
+ properties:
+ cardAccountbundleList:
+ type: array
+ items:
+ $ref: '#/components/schemas/cardAccountbundle'
+ _links:
+ $ref: '#/components/schemas/linksPagination'
+ headers:
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Reflects the ID (set by the caller) from the request.
'400':
$ref: '#/components/responses/standard400'
+ '401':
+ $ref: '#/components/responses/standard401'
+ '403':
+ $ref: '#/components/responses/standard403'
+ '404':
+ $ref: '#/components/responses/standard404'
+ '405':
+ $ref: '#/components/responses/standard405'
'500':
$ref: '#/components/responses/standard500'
+ '501':
+ $ref: '#/components/responses/standard501'
+ '503':
+ $ref: '#/components/responses/standard503'
+
+# -------------------------
+# -------- Models ---------
+# -------------------------
components:
+ securitySchemes:
+ ApiKeyAuth:
+ type: apiKey
+ in: header
+ name: X-API-Key
+
+ OAuth2:
+ type: oauth2
+ flows:
+ authorizationCode:
+ authorizationUrl: https://example.com/oauth/authorize
+ tokenUrl: https://example.com/oauth/token
+ scopes:
+ read: Grants read access
+ write: Grants write access
+
schemas:
- CardDetails:
- title: Card details
- description: Describes a payment card with its relevant characteristics.
+ # ---- Card Account Object ----
+ cardAccount:
+ description: The representation of a card account object
type: object
required:
- - contract_reference
- - person_reference
- - card_id
- - embossing_line_1
- - embossing_line_2
- - pan_4_digits
- - expiry_date
- - card_status
- - currency
- - image
- - product_code
- - product_name
- - scheme
- - issuing_type
- - product_type
- - product_line
- - card_limit_cycle
- - card_limit_daily
- - issuer_code
- - issuer_name
- - language
+ - cardAccountId
properties:
- contract_reference:
- $ref: '#/components/schemas/ContractReference'
- person_reference:
- $ref: '#/components/schemas/PersonReference'
- card_id:
- $ref: '#/components/schemas/CardId'
- embossing_line_1:
- $ref: '#/components/schemas/EmbossingLine1'
- embossing_line_2:
- $ref: '#/components/schemas/EmbossingLine2'
- pan_4_digits:
- $ref: '#/components/schemas/Pan4Digits'
- expiry_date:
- $ref: '#/components/schemas/ExpiryDate'
- initial_issuing_date:
- $ref: '#/components/schemas/InitialIssuingDate'
- card_status:
- $ref: '#/components/schemas/CardStatus'
+ cardAccountId:
+ $ref: '#/components/schemas/entityId'
+ cards:
+ type: array
+ description: List of card_uids linked to this account
+ items:
+ $ref: '#/components/schemas/card'
currency:
- $ref: '#/components/schemas/Currency'
- image:
- $ref: '#/components/schemas/Image'
- product_code:
- $ref: '#/components/schemas/ProductCode'
- product_name:
- $ref: '#/components/schemas/ProductName'
- scheme:
- $ref: '#/components/schemas/Scheme'
- category:
- $ref: '#/components/schemas/Category'
- issuing_type:
- $ref: '#/components/schemas/IssuingType'
- product_type:
- $ref: '#/components/schemas/ProductType'
- product_line:
- $ref: '#/components/schemas/ProductLine'
- card_limit_cycle:
- $ref: '#/components/schemas/CardLimitCycle'
- card_limit_daily:
- $ref: '#/components/schemas/CardLimitDaily'
- card_account_reference:
- $ref: '#/components/schemas/CardAccountReference'
- bank_account_reference:
- $ref: '#/components/schemas/BankAccountReference'
- issuer_code:
- $ref: '#/components/schemas/IssuerCode'
- issuer_name:
- $ref: '#/components/schemas/IssuerName'
- distribution_partner_code:
- $ref: '#/components/schemas/DistributionPartnerCode'
- distribution_partner_name:
- $ref: '#/components/schemas/DistributionPartnerName'
- language:
- $ref: '#/components/schemas/Language'
+ $ref: '#/components/schemas/currency'
+ ibanAccount:
+ $ref: '#/components/schemas/paymentQrIbanAccount'
+ billingCycle:
+ type: string
+ description: code that determines the billing cycle
+ example: monthly
+ enum:
+ - weekly
+ - monthly
+ - quarterly
+ - halfyearly
+ - yearly
+ cardAccountStatus:
+ $ref: '#/components/schemas/genericStatus'
+ cardLoyality:
+ $ref: '#/components/schemas/cardLoyality'
+ paymentDetails:
+ type: object
+ properties:
+ paymentType:
+ $ref: '#/components/schemas/paymentType'
+ paymentOption:
+ $ref: '#/components/schemas/paymentOption'
+ statementDetails:
+ type: object
+ properties:
+ deliveryType:
+ type: string
+ example: paper
+ description: Description of the delivery format of the statement.
+ enum:
+ - paper
+ - paperless
+ - estatement
+ - other
+ activeDeliveryFee:
+ type: number
+ example: 1.0
+ description: Amount charged to the customer for each statement delivery. Typically, paperless is free.
+ nextStatementDate:
+ $ref: '#/components/schemas/date'
+ # ---------
+
+ # ---- Card Loyality Object ----
+ cardLoyality:
+ description: The representation of a card loyality object
+ type: object
+ required:
+ - cardLoyalityId
+ properties:
+ cardLoyalityId:
+ $ref: '#/components/schemas/entityId'
+ name:
+ type: string
+ description: Program name
+ example: surprize
+ reference:
+ type: string
+ example: "2501021032295"
+ description: Additional reference number if available
+ enrollment_date:
+ $ref: '#/components/schemas/date'
+ # ---------
+
+ # ---- Card API Object ----
+ cardApi:
+ description: List of APIs supported for a API consumer
+ type: string
+ example: get:cards
+ # ---------
- CardTokenDetails:
- title: Card token details
- description: Describes a token with its relevant characteristics.
+
+ # ---- Card Consent Object ----
+ cardConsent:
+ description: The representation of a card consent object
+ type: object
+ required:
+ - cardConsentId
+ - cardApiList
+ - identificationType
+ - identificationValue
+ properties:
+ cardConsentId:
+ $ref: '#/components/schemas/entityId'
+ identificationType:
+ type: string
+ example: card_uid
+ description: Audit type field in order to identify the actual user who granted the consent. This field contains the type of identifier.
+ identificationValue:
+ type: string
+ example: 404003004CCL50000
+ description: Audit type field in order to identify the actual user who granted the consent. This field contains the actual identifier of the type defined before.
+ cardApiList:
+ type: array
+ description: List of the APIs to which access is requested.
+ items:
+ $ref: '#/components/schemas/cardApi'
+ # ---------
+
+ # ---- Card Object ----
+ card:
+ description: The representation of a card objectw
+ type: object
+ required:
+ - cardId
+ properties:
+ cardId:
+ $ref: '#/components/schemas/entityId'
+ personId:
+ $ref: '#/components/schemas/entityId'
+ contractId:
+ $ref: '#/components/schemas/entityId'
+ cardAccountId:
+ $ref: '#/components/schemas/entityId'
+ issuingPartnerId:
+ $ref: '#/components/schemas/entityIdName'
+ issuerId:
+ $ref: '#/components/schemas/entityIdName'
+ cardDetail:
+ type: object
+ required:
+ - cardNumberCustomer
+ properties:
+ cardNumber:
+ type: string
+ example: 4566549683425654
+ maxLength: 19
+ description: Card number
+ cardNumberCustomer:
+ type: string
+ example: 4566549683425654
+ maxLength: 50
+ description: Card number
+ initialCreationDate:
+ $ref: '#/components/schemas/date'
+ expiryDate:
+ type: string
+ example: 05/19
+ description: Card expiry date in the format MM/YY
+ embossingLine1:
+ type: string
+ maxLength: 30
+ example: FRANZ MUSTERMANN
+ description: Embossing Line 1 contains the person name as visible on the card plastic
+ embossingLine2:
+ type: string
+ maxLength: 30
+ example: VISECA CARD SERVICES
+ description: Embossing Line 2 may contain a person-specified or product-specific value, as visible on the card plastic
+ purgedDate:
+ $ref: '#/components/schemas/date'
+ currency:
+ $ref: '#/components/schemas/currency'
+ card_scheme:
+ type: string
+ example: visa
+ description: Card payment scheme
+ enum:
+ - mastercard
+ - visa
+ - amex
+ - dinersclub
+ - other
+ productId:
+ type: string
+ example: "1010101"
+ description: Issuer identifier of a card product
+ productType:
+ type: string
+ example: prepaid
+ description: States if the card is credit or debit. Prepaid cards are labelled as credit in this operation
+ enum:
+ - credit
+ - debit
+ - prepaid
+ productCategory:
+ type: string
+ example: gold
+ description: 'Product category corresponds to the tier of card: gold, platinum, basic etc.'
+ productLine:
+ $ref: '#/components/schemas/contractType'
+ productName:
+ type: string
+ maxLength: 50
+ example: World Mastercard Gold CHF
+ description: Commercial name of the card product as defined by the bank
+ cardImage:
+ type: string
+ example: "https://bank.ch/images/cardImage.png"
+ description: URL to the (png) card image corresponding to the card
+ cardRelationship:
+ type: string
+ example: main_card
+ description: 'Identifies the nature of the card in regards to the overall account: main card or additional card'
+ enum:
+ - main_card
+ - additional_card
+ previousCardId:
+ $ref: '#/components/schemas/entityId'
+ previousReplacementDate:
+ $ref: '#/components/schemas/date'
+ replacementReason:
+ type: string
+ example: other
+ description: Reason for the replacement of this card
+ nextCardId:
+ $ref: '#/components/schemas/entityId'
+ nextReplacementDate:
+ $ref: '#/components/schemas/date'
+ atmDirectDebit:
+ type: boolean
+ description: A flag indicating if the ATM Direct Debit functionality is enabled
+ example: true
+ cardStatus:
+ $ref: '#/components/schemas/genericStatus'
+ # ---------
+
+ # TODO: define object with properties
+ cardToken:
+ description: Card Account Token Information.
type: object
required:
- - token_id
- - token_pan_4_digits
- - token_requestor_code
- - token_requestor_name
- - funding_card_id
- - token_status
- - token_issuing_date
- - token_scheme
+ - cardTokenId
properties:
- token_id:
- $ref: '#/components/schemas/TokenId'
- token_pan_4_digits:
- $ref: '#/components/schemas/TokenPan4Digits'
- wallet_code:
- $ref: '#/components/schemas/WalletCode'
- wallet_name:
- $ref: '#/components/schemas/WalletName'
- token_requestor_code:
- $ref: '#/components/schemas/TokenRequestorCode'
- token_requestor_name:
- $ref: '#/components/schemas/TokenRequestorName'
- device_name:
- $ref: '#/components/schemas/DeviceName'
- device_type:
- $ref: '#/components/schemas/DeviceType'
- funding_card_id:
- $ref: '#/components/schemas/FundingCardId'
- token_status:
- $ref: '#/components/schemas/TokenStatus'
- token_issuing_date:
- $ref: '#/components/schemas/TokenIssuingDate'
- token_scheme:
- $ref: '#/components/schemas/TokenScheme'
+ cardTokenId:
+ type: string
+ format: uuid
+ description: UUID v4 of the card accountbundle
+ example: 576f8de3-6b30-4882-a7af-da2132a456cf
- TransactionDetails:
- title: Transaction details
- description: Describes a transaction with its relevant characteristics.
+ # ---- Card Account Statement ----
+ cardAccountStatement:
+ description: xy
type: object
required:
- - transaction_id
- - transaction_date_time
- - valuta_date
- - transaction_status
- - original_amount
- - original_currency
- - mcc
- - mcc_description
- - transaction_category
- - card_id
+ - cardAccountStatementId
properties:
- transaction_id:
- $ref: '#/components/schemas/TransactionId'
- authorization_reference:
- $ref: '#/components/schemas/AuthorizationReference'
- clearing_reference:
- $ref: '#/components/schemas/ClearingReference'
- transaction_date_time:
- $ref: '#/components/schemas/TransactionDateTime'
- valuta_date:
- $ref: '#/components/schemas/ValutaDate'
- statement_date:
- $ref: '#/components/schemas/StatementDate'
- transaction_status:
- $ref: '#/components/schemas/TransactionStatus'
- approval_number:
- $ref: '#/components/schemas/ApprovalNumber'
- original_amount:
- $ref: '#/components/schemas/OriginalAmount'
- original_currency:
- $ref: '#/components/schemas/OriginalCurrency'
- total_amount:
- $ref: '#/components/schemas/TotalAmount'
- transaction_amount:
- $ref: '#/components/schemas/TransactionAmount'
- transaction_currency:
- $ref: '#/components/schemas/TransactionCurrency'
- fees:
- $ref: '#/components/schemas/Fees'
- exchange_rate:
- $ref: '#/components/schemas/ExchangeRate'
- exchange_rate_date:
- $ref: '#/components/schemas/ExchangeRateDate'
- description:
- $ref: '#/components/schemas/Description'
- merchant_name:
- $ref: '#/components/schemas/MerchantName'
- merchant_country:
- $ref: '#/components/schemas/MerchantCountry'
- merchant_city:
- $ref: '#/components/schemas/MerchantCity'
- mcc:
- $ref: '#/components/schemas/Mcc'
- mcc_description:
- $ref: '#/components/schemas/MccDescription'
- terminal_reference:
- $ref: '#/components/schemas/TerminalReference'
- card_acceptor_reference:
- $ref: '#/components/schemas/CardAcceptorReference'
- acquirer_reference:
- $ref: '#/components/schemas/AcquirerReference'
+ cardAccountStatementId:
+ $ref: '#/components/schemas/entityId'
+ cardAccountId:
+ $ref: '#/components/schemas/entityId'
+ statementCreationDate:
+ $ref: '#/components/schemas/date'
+ statementAmount:
+ $ref: '#/components/schemas/paymentCurrencyAmount'
+ paymentDueDate:
+ $ref: '#/components/schemas/date'
+ statementMinimalDueAmount:
+ $ref: '#/components/schemas/paymentCurrencyAmount'
+ paymentType:
+ $ref: '#/components/schemas/paymentType'
+ paymentOption:
+ $ref: '#/components/schemas/paymentOption'
+ # ---------
+
+ # ---- Card Transaction ----
+ cardTransaction:
+ description: Transaction object adapted for card use
+ type: object
+ required:
+ - cardTransactionId
+ properties:
+ cardTransactionId:
+ type: string
+ format: uuid
+ example: d452083f-8316-410d-a609-d49463687329
+ description: Uuid v4 of the specific transaction. Must not change when the status (approved, booked, etc.) is changed.
+ approvalCode:
+ type: string
+ example: Please-Provide-Example-and-MaxLength
+ description: Additional transaction identifier provided by schemes or processing system
+ transactionTimestamp:
+ $ref: '#/components/schemas/dateTime'
+ originalCurrencyAmount:
+ $ref: '#/components/schemas/paymentCurrencyAmount'
+ targetCurrencyAmountt:
+ $ref: '#/components/schemas/paymentCurrencyAmount'
+ exchangeRate:
+ type: string
+ example: "0.957"
+ pattern: "[0-9][.][0-9]{1,10}"
+ maxLength: 12
+ exchangeRateDate:
+ $ref: '#/components/schemas/date'
+ merchant:
+ type: object
+ description: Merchant information of the card transaction
+ properties:
+ merchantName:
+ type: string
+ example: COOP PRONTO
+ description: Value that contains the merchant name and location
+ merchantLocation:
+ type: string
+ example: Zurich
+ # Please maxLength
+ description: Value that contains the merchant name and location
+ merchantLocationLatitude:
+ type: string
+ example: "-35.253252"
+ # Please regex
+ description: Value that contains the merchant name and location
+ merchantLocationLongitude:
+ type: string
+ example: "174.071674"
+ # Please regex
+ description: Value that contains the merchant name and location
+ merchantCountry:
+ $ref: '#/components/schemas/country'
+ merchangeCategoryCode:
+ type: string
+ example: "5411"
+ description: Value that contains the merchant category code as defined by ISO 18245
+ posEntryMode:
+ $ref: '#/components/schemas/posEntryMode'
+ terminalId:
+ type: string
+ description: Identifier of the point of sale terminal
+ #Please add example and regex
channel:
- $ref: '#/components/schemas/Channel'
- transaction_category:
- $ref: '#/components/schemas/TransactionCategory'
- token_id:
- $ref: '#/components/schemas/TokenId'
- cardholder_reference:
- $ref: '#/components/schemas/CardholderReference'
- card_account_reference:
- $ref: '#/components/schemas/CardAccountReference'
- card_id:
- $ref: '#/components/schemas/CardId'
- related_transaction_id:
- $ref: '#/components/schemas/RelatedTransactionId'
-
- ContractReference:
- title: Contract reference
- type: string
- maxLength: 50
- examples:
- - CH3456789012345678901
- - ABC-56789012345
- description: Functional reference to a customer relationship/contract that is responsible for the card, defined by the Card Service Provider.
-
- PersonReference:
- title: Person reference
- type: string
- maxLength: 50
- examples:
- - '123456789'
- description: Functional reference to a cardholder, defined by the Card Service Provider.
-
- CardId:
- title: Card id
- type: string
- format: uuid
- maxLength: 50
- examples:
- - 4321A1B2C3DE1234
- description: Technical reference to a card (unique, constant in the lifecycle of a card even in case of replacements or renewals).
-
- EmbossingLine1:
- title: Embossing line 1
- type: string
- maxLength: 35
- examples:
- - Peter Schweizer
- description: First line embossed on the card to indicate the cardholder.
+ type: string
+ description: Showing if it was a eCommerce transaction or not
+ enum:
+ - ecom
+ - other
+ offline:
+ type: string
+ description: Indicator if the transaction was offline authorized
+ #Please add example and regex
+ statementDate:
+ type: string
+ format: date
+ example: '2018-08-03'
+ description: Settlement date
+ fees:
+ type: array
+ description: |-
+ This array shows individual fee objects that are associated with the
+ transaction. Please note that multiple fee objects can be transmitted.
+ items:
+ $ref: '#/components/schemas/cardTransactionFee'
+ state:
+ type: string
+ example: authorised
+ description: Used to identify if a transactions has been settled (booked) or just authorised
+ transactionCategory:
+ type: string
+ example: merchant
+ description: Transaction type identifying merchant to non-merchant entries
+ enum:
+ - merchant
+ - fee
+ - atm
+ transactionType:
+ $ref: '#/components/schemas/cardTransactionType'
+ personId:
+ $ref: '#/components/schemas/entityId'
+ personName:
+ type: object
+ description: Name of the person
+ properties:
+ company:
+ $ref: '#/components/schemas/entityName'
+ name:
+ $ref: '#/components/schemas/personName'
+ surName:
+ $ref: '#/components/schemas/personSurName'
+ cardAccountId:
+ $ref: '#/components/schemas/entityId'
+ cardId:
+ $ref: '#/components/schemas/entityId'
+ walletProvider:
+ type: string
+ example: Apple Pay
+ description: Identifier of the wallet provider if transaction was perfomred with a payment token (e.g. mobile payment such as Apple Pay)
+ token:
+ type: string
+ example: "1234"
+ maxLength: 4
+ description: last 4 digits of the token
+ tokenRequestorId:
+ type: string
+ example: "1234"
+ maxLength: 4
+ description: last 4 digits of the token
+ # Is this a duplicate of token?
+ securityLevelIndicator:
+ type: string
+ # Please provide example and regex
+ description: Security Level Indicator provides additional information about 3DS, recurring transactions and other authentication related information
+ actionCode:
+ type: string
+ example: "121"
+ description: The Action Code provides information about the why a transaction was approved or declined
+ # ---------
- EmbossingLine2:
- title: Embossing line 2
- type: string
- maxLength: 35
- examples:
- - Peter Schweizer
- description: Second line embossed on the card to indicate the cardholder.
+ # ---- Card Transaction Fee ----
+ cardTransactionFee:
+ description: Individual fee objects that are associated with the transaction
+ type: object
+ properties:
+ type:
+ type: string
+ example: Bearbeitungsgebühr 1.75%
+ description: Name of the fee
+ amount:
+ $ref: '#/components/schemas/amount'
+ currency:
+ $ref: '#/components/schemas/currency'
+ # ---------
- Pan4Digits:
- title: Pan 4 digits
- type: string
- maxLength: 4
- pattern: '^\d{4}$'
- examples:
- - '4321'
- description: Last 4 digits of the PAN; values can change for the same cardId during the lifecycle.
+ # ---- Card Transaction Type ----
+ cardTransactionType:
+ type: object
+ properties:
+ acquiringType:
+ type: string
+ # Please provide example
+ description: Provides further insight into the interface used
+ financialMeaning:
+ type: string
+ # Please provide example
+ description: Additional functional information about a transaction
+ transactionReference:
+ type: string
+ # Please provide example
+ description: Provides information about connecting a transaction to a previous occurred transaction. E.g. Storno
+ # -------
- ExpiryDate:
- title: Expiry date
- $ref: '#/components/schemas/Date'
- description: Last day when the card is valid and can be used for payments.
+ # ---- Card POS Entry Mode ----
+ posEntryMode:
+ type: object
+ description: The POS Entry Mode object contain multiple fields that further define how the transaction was captured at its point of origin including information about authentication, payment infrastructure and other related topics.
+ properties:
+ cardDataInputCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ personAuthenticationCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ cardCaptureCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ operatingEnvironment:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ personPresent:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ cardPresent:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ cardDataInputMode:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ personAuthenticationMethod:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ personAuthenticationEntity:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ cardDataOutputCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ terminalOutputCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
+ pinCaptureCapability:
+ type: string
+ description: Please_Add_Description_and_Example_and_Regex-MaxLength
- InitialIssuingDate:
- title: Initial issuing date
- $ref: '#/components/schemas/Date'
- description: Date when card was issued initially.
+ # ---- Person ----
+ person:
+ description: Person information .
+ type: object
+ required:
+ - personId
+ properties:
+ personId:
+ $ref: '#/components/schemas/entityId'
+ contractId:
+ $ref: '#/components/schemas/entityId'
+ personType:
+ $ref: '#/components/schemas/contractType'
+ isMainPerson:
+ type: boolean
+ description: Flag to identify if the person is a main person
+ example: true
+ personStatistics:
+ type: object
+ properties:
+ total_accounts:
+ type: integer
+ example: 1
+ description: Total number of accounts of a private customer or a company
+ totalActivAccounts:
+ type: integer
+ description: Total number of active accounts of a private customer or a company
+ example: 2
+ totalCards:
+ type: integer
+ example: 1
+ description: Total number of cards of a private customer or a company
+ totalActiveCards:
+ type: integer
+ description: Total number of active cards of a private customer or a company
+ personDetail:
+ type: object
+ properties:
+ salutation:
+ $ref: '#/components/schemas/personSalutation'
+ company:
+ $ref: '#/components/schemas/entityName'
+ name:
+ $ref: '#/components/schemas/personName'
+ surName:
+ $ref: '#/components/schemas/personSurName'
+ middleName:
+ $ref: '#/components/schemas/personMiddleName'
+ address:
+ $ref: '#/components/schemas/structuredAddress'
+ country:
+ $ref: '#/components/schemas/country'
+ language:
+ $ref: '#/components/schemas/language'
+ nationality:
+ $ref: '#/components/schemas/country'
+ birthDay:
+ $ref: '#/components/schemas/date'
+ gender:
+ $ref: '#/components/schemas/personGender'
+ permit:
+ $ref: '#/components/schemas/personPermit'
+ externalReferenceId:
+ type: string
+ maxLength: 30
+ example: No1
+ description: Reference id of company customers (e.g. employee number)
+ amloCheck:
+ type: boolean
+ example: true
+ description: Flag to show if the Anti-Money Laundering Ordinance has been already checked for this customer
+ adPermission:
+ type: boolean
+ example: false
+ description: Flag to see if the customer give his/her permission to marketing advertisement
+ phoneNumber:
+ type: array
+ description: Phone numbers of the person
+ items:
+ $ref: '#/components/schemas/personPhoneNumber'
+ email:
+ type: array
+ description: Email addresses of the person
+ items:
+ $ref: '#/components/schemas/personEmail'
+ # ---------
+
+ # ---- Card Contract ----
+ cardContract:
+ description: Card Contract Information .
+ type: object
+ required:
+ - cardContractId
+ properties:
+ cardContractId:
+ type: string
+ format: uuid
+ description: UUID v4 of the card contract
+ example: 576f8de3-6b30-4882-a7af-da2132a456cf
+ openingDate:
+ description: Date when the card contract was created
+ type: string
+ format: date
+ example: 2018-04-13
+ purgedDate:
+ description: Date that indicates if and when this card contract was purged in the processor system
+ type: string
+ format: date
+ example: 2018-04-13
+ cardAccounts:
+ type: array
+ items:
+ $ref: '#/components/schemas/cardAccount'
+ personId:
+ $ref: '#/components/schemas/entityId'
+ contractType:
+ $ref: '#/components/schemas/contractType'
+ issuingPartnerId:
+ $ref: '#/components/schemas/entityIdName'
+ issuerId:
+ $ref: '#/components/schemas/entityIdName'
+ fulfillEntity:
+ $ref: '#/components/schemas/entityName'
+ contractStatus:
+ $ref: '#/components/schemas/genericStatus'
+ # ---------
+
+ # TODO: define object with properties
+ cardAccountbundle:
+ description: Card Accountbundle Information.
+ type: object
+ required:
+ - cardAccountbundleId
+ properties:
+ cardAccountbundleId:
+ type: string
+ format: uuid
+ description: UUID v4 of the card accountbundle
+ example: 576f8de3-6b30-4882-a7af-da2132a456cf
- CardStatus:
- title: Card status
+ # ---- Card API Model ----
+ contractType:
+ description: Type of a contract
type: string
enum:
- - ACTIVE
- - SUSPENDED
- - BLOCKED
- examples:
- - ACTIVE
- description: |
- Effective status of the card to indicate whether it can be used for payments; definition of enums:
- - active: authorizations are possible
- - suspended: authorizations are temporarily not possible
- - blocked: authorizations are permanently not possible because the card was cancelled or permanently blocked for other reasons
-
- Currency:
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
- - EUR
- description: Settlement currency of the card / card account in ISO code format.
-
- Image:
+ - business
+ - corporate
+ - consumer
+ example: consumer
+ entityId:
+ type: string
+ format: uuid
+ description: UUID of an entity
+ example: 1b19aeb0-60db-4160-8551-c37de178ca10
+ entityName:
+ type: string
+ maxLength: 70
+ description: Name of an entity
+ example: Abteilung B
+ personSurName:
+ type: string
+ maxLength: 70
+ description: Sur name of person
+ example: Muster
+ personMiddleName:
+ type: string
+ maxLength: 70
+ description: Middle name of person
+ example: Gustav
+ personName:
+ type: string
+ maxLength: 70
+ description: Name of person
+ example: Max
+ personGender:
type: string
- format: uri
- examples:
- - https://one-digitalservice.ch/public/Viseca/media/one-app-images/card-visuals/4_go_m_11_2017.png
- description: URL reference to an image for the design of the card.
-
- ProductCode:
- title: Product code
+ enum:
+ - male
+ - female
+ - other
+ example: female
+ description: Gender of the person.
+ personSalutation:
type: string
- maxLength: 50
- examples:
- - '1234567'
- description: Identifier for the card product.
-
- ProductName:
- title: Product name
- type: string
- maxLength: 100
- examples:
- - A1
- - MC/VI Gold CHF
- description: Name for the card product assigned by the issuer.
-
- Scheme:
- type: string
- enum:
- - mastercard
- - visa
- - americanexpress
- - dinersclub
- examples:
- - mastercard
- description: Card network which is used to process payments with the card in switzerland.
-
- Category:
- type: string
- enum:
- - primary_card
- - additional_card
- examples:
- - primary_card
- description: Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect of certain lifecycle use cases.
-
- IssuingType:
- title: Issuing type
- type: string
- enum:
- - physical
- - virtual
- examples:
- - physical
- description: >
- Specifies in which form the card is issued; definition of enums:
- - physical: the card is being embossed on a physical material and delivered to the cardholder by mail
- - virtual: the card is being issued only virtually for digital usage
-
- ProductType:
- title: Product type
- type: string
- enum:
- - credit
- - debit
- - prepaid
- examples:
- - credit
- description: Type of the card product.
-
- ProductLine:
- title: Product line
- type: string
- enum:
- - consumer
- - business
- - corporate
- examples:
- - consumer
- description: Customer segment to which the card is offered.
-
- CardLimitCycle:
- title: Card limit cycle
- type: integer
- format: int32
- examples:
- - 2000
- description: >
- Total amount of authorizations possible for the card per settlement cycle / month in the currency of the card;
- effective limit is provided that considers limits on the card and relationship;
- does not indicate the actually available amount for authorizations in the current cycle.
-
- CardLimitDaily:
- title: Card limit daily
- type: integer
- format: int32
- examples:
- - 2000
- description: >
- Total amount of authorizations possible for the card per day in the currency of the card;
- effective limit is provided that considers limits on the card and relationship;
- does not indicate the actually available amount for authorizations on the current day.
-
- CardAccountReference:
- title: Card account reference
- type: string
- maxLength: 50
- examples:
- - AB-4567890123456
- description: >
- Technical reference to the card account which is used to settle the transactions of the card;
- can be empty for debit cards which are settled directly to the bank account.
-
- BankAccountReference:
- title: Bank account reference
- type: string
- maxLength: 34
- examples:
- - CH3456789012345678901
- description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
-
- IssuerCode:
- title: Issuer code
- type: string
- maxLength: 50
- examples:
- - '123456789'
- description: Identifier for the legal issuer of a card; responsible towards the schemes for keeping the rules.
-
- IssuerName:
- title: Issuer name
- type: string
- maxLength: 100
- examples:
- - Viseca Card Services
- - UBS
- - Zürcher Kantonalbank
- description: Name of the legal issuer of a card.
-
- DistributionPartnerCode:
- title: Distribution partner code
- type: string
- maxLength: 50
- examples:
- - '123456789'
- description: >
- Identifier for the organization which is distributing / selling cards to end customers
- and who can define the services and branding of the card; empty if the card is distributed by the issuer.
-
- DistributionPartnerName:
- title: Distribution partner name
- type: string
- maxLength: 100
- examples:
- - Zürcher Kantonalbank
- description: >
- Name of the organization which is distributing / issuing cards to end customers
- and who can define the services and branding of the card; empty if the card is distributed by the issuer.
-
- Language:
- type: string
- enum:
- - DE
- - EN
- - FR
- - IT
- examples:
- - DE
- description: Preferred language of the cardholder for any communication.
-
- TokenId:
- title: Token id
- type: string
- format: uuid
- maxLength: 50
- examples:
- - eb404f8d-656b-4e51-8872-88c42fa55536
- description: Unique identifier for the token of a card, defined by the Card Service Provider.
-
- TokenPan4Digits:
- title: Token pan 4 digits
- type: string
- maxLength: 4
- examples:
- - '4321'
- description: Last 4 digits of the PAN for the token, usually shown in wallets or on receipts when the token is used for payments.
-
- WalletCode:
- title: Wallet code
- type: string
- maxLength: 10
- examples:
- - '123'
- description: Identifier for the wallet in which the token is used and managed.
-
- WalletName:
- title: Wallet name
- type: string
- enum:
- - APPLE_PAY
- - SAMSUNG_PAY
- - GOOGLE_PAY
- - GARMIN_PAY
- examples:
- - APPLE_PAY
- description: Name of the wallet in which the token is used and managed.
-
- TokenRequestorCode:
- title: Token requestor code
- type: string
- maxLength: 11
- examples:
- - '11111111111'
- description: Identifier for the token requestor / token service provider.
-
- TokenRequestorName:
- title: Token requestor name
- type: string
- maxLength: 100
- examples:
- - Zalando
- description: Name of the token requestor / token service provider.
-
- DeviceName:
- title: Device name
- type: string
- maxLength: 100
- examples:
- - Peter's iPhone
- description: Name of the device which is associated to the token, only available for device-based tokens.
-
- DeviceType:
- title: Device type
- type: string
- maxLength: 100
- examples:
- - IPHONE
- description: Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
-
- FundingCardId:
- title: Funding card id
- type: string
- format: uuid
- maxLength: 50
- examples:
- - 4321A1B2C3DE1234
- description: Reference to the card that is used to fund the transactions of the token.
-
- TokenStatus:
- title: Token status
- type: string
- enum:
- - ACTIVE
- - SUSPENDED
- - BLOCKED
- - PENDING
- examples:
- - ACTIVE
- description: |
- Effective status of the token to indicate whether it can be used for payments; definition of enums:
- - active: authorizations are possible
- - suspended: authorizations are temporarily not possible
- - blocked: authorizations are permanently not possible because the token was cancelled
- - pending: authorizations are not possible because the token is not fully issued or currently in transition between status
-
- TokenIssuingDate:
- title: Token issuing date
- $ref: '#/components/schemas/Date'
- description: Date when the token was issued.
-
- TokenScheme:
- title: Token scheme
- type: string
- enum:
- - mastercard
- - visa
- - americanexpress
- examples:
- - mastercard
- description: Scheme for which the token is issued.
-
- TransactionId:
- title: Transaction id
- type: string
- format: uuid
- maxLength: 50
- examples:
- - 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: UUID to link AuthorizationReference and ClearingReference.
-
- AuthorizationReference:
- title: Authorization reference
- type: string
- maxLength: 50
- examples:
- - 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: >
- Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present.
-
- ClearingReference:
- title: Clearing reference
- type: string
- maxLength: 50
- examples:
- - 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: >
- Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present.
-
- TransactionDateTime:
- title: Transaction date-time
- $ref: '#/components/schemas/DateTime'
- description: Date and time when transaction was authorized, always in CH timezone.
-
- ValutaDate:
- title: Valuta date
- $ref: '#/components/schemas/Date'
- description: Date when the transaction becomes effective on the card account for calculating interest.
-
- StatementDate:
- title: Statement date
- $ref: '#/components/schemas/Date'
- description: Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
-
- TransactionStatus:
- title: Transaction status
+ enum:
+ - none
+ - mr
+ - mrs
+ - company
+ - male_academic
+ - female_academic
+ - male_nobility
+ - female_nobility
+ - neutral
+ example: mrs
+ description: Salutation for the person.
+ language:
type: string
+ example: fr
+ description: Language - for example, preferred contact language
enum:
- - authorized
- - booked
- examples:
- - authorized
- description: >
- Status of the transaction; definition of enums:
- - authorized: transaction was approved from the issuer to the merchant, but not yet cleared; includes reservations
- - booked: transaction was cleared/settled and charged to the card account
-
- ApprovalNumber:
- title: Approval number (also known as approval code)
- type: string
- pattern: '^\d{6}$'
- examples:
- - '803051'
- description: >
- Identifies a transaction from the entity that authorized it;
- in combination with cardId and transactionDateTime usually unique (except for reversals or other special situations).
-
- OriginalAmount:
- title: Original amount
- type: number
- examples:
- - 2000.05
- description: Amount of the transaction in the currency used by the merchant.
-
- OriginalCurrency:
- title: Original currency
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
- description: Currency of the card account on which the transaction is charged.
-
- TotalAmount:
- title: Total amount
- type: number
- examples:
- - 1957.50
- description: >
- Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
- positive amounts are debit transactions, negative amounts are credit transactions.
-
- TransactionAmount:
- title: Transaction amount
- type: number
- examples:
- - 1952.50
- description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
-
- TransactionCurrency:
- title: Transaction currency
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
- description: Currency of the card account on which the transaction is charged.
-
- Fees:
- title: Fees
- description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
+ - de
+ - fr
+ - it
+ - en
+ personPermit:
+ description: Permit of a person
type: object
required:
- - fee_name
+ - permitStatus
properties:
- fee_name:
- $ref: '#/components/schemas/FeeName'
- fee_percentage:
- $ref: '#/components/schemas/FeePercentage'
- fee_amount:
- $ref: '#/components/schemas/FeeAmount'
- fee_currency:
- $ref: '#/components/schemas/FeeCurrency'
-
- ExchangeRate:
- title: Exchange rate
- type: number
- examples:
- - 1.0485930
- description: Exchange rate for converting the originalAmount into the transactionAmount.
-
- ExchangeRateDate:
- title: Exchange rate date
- $ref: '#/components/schemas/Date'
- description: Date which was used to determine the exchange rate, usually the valutaDate.
-
- Description:
- type: string
- maxLength: 100
- examples:
- - Aufladung
- description: Description of the purpose of the transaction and potentially a reference to the merchant.
-
- MerchantName:
- title: Merchant name
- type: string
- maxLength: 100
- examples:
- - Yallo
- description: Name of the merchant who requested the transaction.
-
- MerchantCountry:
- title: Merchant country
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHE
- description: Country in which the merchant is located.
-
- MerchantCity:
- title: Merchant city
- type: string
- maxLength: 50
- examples:
- - Zurich
- description: City in which the merchant is located.
-
- Mcc:
- type: string
- maxLength: 4
- examples:
- - '4812'
- description: Merchant Category Code to identify the industry branch of the merchant.
-
- MccDescription:
- title: Mcc description
- type: string
- maxLength: 100
- examples:
- - Telco
- description: Description for the mcc.
-
- TerminalReference:
- title: Terminal reference (also known as terminal id)
- type: string
- maxLength: 8
- examples:
- - '12345678'
- description: Identifier for the terminal which has read the card data.
-
- CardAcceptorReference:
- title: Card acceptor reference
- type: string
- maxLength: 15
- examples:
- - '87040'
- description: Identifier for the merchant who requested the transaction.
-
- AcquirerReference:
- title: Acquirer reference (also known as acquirer id)
- type: string
- maxLength: 11
- examples:
- - '12345678901'
- description: Identifies the acquirer who submitted the transaction; not provided by all Card Service Providers.
+ permitStatus:
+ type: string
+ example: B
+ description: Permit status
+ enum:
+ - C
+ - B
+ - other
+ permitSince:
+ $ref: '#/components/schemas/date'
+ personPhoneNumber:
+ description: Phone number of a person
+ type: object
+ required:
+ - phoneNumber
+ properties:
+ phoneNumberType:
+ type: string
+ example: mobile
+ description: phone number type
+ enum:
+ - mobile
+ - mobile private
+ - mobile business
+ - fixline
+ - fixline private
+ - fixline business
+ - other
+ emailAddress:
+ type: string
+ maxLength: 30
+ example: max.muster@company.ch
+ description: Email address
+ personEmail:
+ description: Email address of a person
+ type: object
+ required:
+ - emailAddress
+ properties:
+ emailType:
+ type: string
+ example: personal
+ description: Email type
+ enum:
+ - personal
+ - business
+ - other
+ emailAddress:
+ type: string
+ maxLength: 30
+ example: max.muster@company.ch
+ description: Email address
+ entityIdName:
+ description: Issuing entity of the card
+ type: object
+ required:
+ - issuingEntityId
+ properties:
+ issuingEntityId:
+ $ref: '#/components/schemas/entityId'
+ name:
+ $ref: '#/components/schemas/entityName'
- Channel:
+ paymentType:
type: string
+ example: lsv
+ description: Identifier of the payment method selected by the person to settle the account.
enum:
- - standard
- - ecommerce
- examples:
- - standard
- description: Channel that was used by the cardholder for executing the transaction, allows the identification of eCommerce transactions.
-
- TransactionCategory:
- title: Transaction category
- type: string
- maxLength: 50
- examples:
- - '100: Cash withdrawal'
- - '103: ATM operator refund'
- - '117: P2P payment charge sender'
- - '118: P2P payment credit recipient'
- - merchant
- - fee
- - atm
- description: Category of the transaction, defined by the Card Service Provider.
-
- CardholderReference:
- title: Cardholder reference
+ - lsv
+ - debit_direct
+ - esr
+ - ipi
+ - pos
+ paymentOption:
type: string
- maxLength: 50
- examples:
- - Peter Schweizer
- description: Reference to the cardholder who owns the card which was used for the transaction; not provided by all Card Service Providers.
-
- RelatedTransactionId:
- title: Transaction reference
- type: string
- format: uuid
- maxLength: 50
- examples:
- - 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
-
- FeeName:
- title: Fee name
- type: string
- maxLength: 50
- examples:
- - transactionTipAmount
- - transactionSurchargeAmount
- description: Name of the fee that is charged for the transaction; value is defined by the Issuer.
-
- FeePercentage:
- title: Fee percentage
- type: number
- examples:
- - 3.5
- description: >
- Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
- Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
-
- FeeAmount:
- title: Fee amount
- type: number
- examples:
- - 5.00
- description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
-
- FeeCurrency:
- title: Fee currency
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
- description: Currency that is used for charging the fee, usually the same as the currency of the card account.
+ example: full
+ description: Identifier of the payment plan selected by the person to pay for a bill.
+ enum:
+ - full
+ - instalment
+ - revolving
+
+ genericStatus:
+ description:
+ 'Describes the status of a card object.
+ Effective: Aggregated effective status on the entity based on directly and inherited status.
+ Directly: Directly applied status on the entity. Note: At a contract level effective status and direct status are the same.
+ Inherited: Inherited status on the entity. Note: At a contract level there is no inherited status
+ Last Change: Date of the last change of the effective status.'
+ type: object
+ required:
+ - effective
+ properties:
+ effective:
+ $ref: '#/components/schemas/genericStatusEnum'
+ direct:
+ $ref: '#/components/schemas/genericStatusEnum'
+ inherited:
+ $ref: '#/components/schemas/genericStatusEnum'
+ last_change:
+ $ref: '#/components/schemas/date'
+ genericStatusEnum:
+ description: Status element
+ type: object
+ required:
+ - status
+ properties:
+ status:
+ type: string
+ enum:
+ - ok
+ - nok
+ - unknown
+ - active
+ - blocked
+ - suspended_by_person
+ - suspended_by_bank
+ - suspended_by_issuer
+ description: Status type
+ detail:
+ type: string
+ description: 'Status detail in custom text'
+ # ---------
- Date:
+ # ---- Common Data Model v1.2.0
+ # ---- Date Formats
+ date:
type: string
format: date
- examples:
- - 2018-04-13
- description: General date that is used for different attributes, format is 'YYYY-MM-DD'.
-
- DateTime:
- title: Date-time
+ example: 2018-04-13
+ dateTime:
type: string
format: date-time
- examples:
- - 2018-04-13T11:11:11Z
- description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'.
-
- LinksPagination:
+ example: 2018-04-13T11:11:11Z
+ # --------
+ # ---- Links for Pagination----
+ linksPagination:
description: Links (or cursors) returned in the answer of an API call.
type: object
properties:
self:
type: string
- format: uri
- description: Link / cursor to the current result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=75&limit=25
+ description: Link / cursor to the current result set (based on the submitted pagination approach)
+ example: /card-app/api/v1/cards?offset=75&limit=25
first:
type: string
- format: uri
- description: Link / cursor to the first result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=0&limit=25
+ description: Link / cursor to the first result set (based on the submitted pagination approach)
+ example: /card-app/api/v1/cards?offset=0&limit=25
previous:
type: string
- format: uri
- description: Link / cursor to the previous result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=50&limit=25
+ description: Link / cursor to the previous result set (based on the submitted pagination approach)
+ example: /card-app/api/v1/cards?offset=50&limit=25
next:
type: string
- format: uri
- description: Link / cursor to the next result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=100&limit=25
+ description: Link / cursor to the next result set (based on the submitted pagination approach)
+ example: /card-app/api/v1/cards?offset=100&limit=25
last:
type: string
- format: uri
- description: Link / cursor to the last result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=150&limit=25
+ description: Link / cursor to the last result set (based on the submitted pagination approach)
+ example: /card-app/api/v1/cards?offset=150&limit=25
+ # ---------
+
+ # ---- Account objects from payment API ----
+ paymentQrIbanAccount:
+ title: Payment QR-IBAN Account
+ type: object
+ required:
+ - type
+ - identification
+ properties:
+ type:
+ type: string
+ description: IBAN or QR-IBAN of the creditor.
+ enum:
+ - "IBAN"
+ - "QR_IBAN"
+ identification:
+ type: string
+ maxLength: 34
+ example: "CH9300762011623852957"
+ pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"
+ # ---------
+
+ # ---- Currency ----
+ currency:
+ description: ISO 4217 code
+ type: string
+ pattern: '[A-Z]{3}'
+ example: CHF
+ # ---------
+
+ # ---- Payment Currency Amount compatible to SFTI XS2A API----
+ paymentCurrencyAmount:
+ title: Payment Currency-Amount
+ type: object
+ required:
+ - currency
+ - amount
+ properties:
+ currency:
+ $ref: '#/components/schemas/currency'
+ amount:
+ $ref: '#/components/schemas/amount'
- CommonErrorResponse:
+ # ---- Amount ----
+ amount:
+ type: string
+ description: Amount given with fractional digits, the separator is a dot
+ pattern: "[0-9]{1,12}([.][0-9]{1,5})?"
+ maxLength: 18
+ example: "10.25"
+ # --------
+
+ # ---- Address compliant to payment address (b.Link & ISO20022)----
+ structuredAddress:
+ title: Structured Address
+ type: object
+ required:
+ - streetName
+ - postCode
+ - townName
+ - country
+ properties:
+ streetName:
+ type: string
+ maxLength: 70
+ example: "Rue de la gare"
+ buildingNumber:
+ type: string
+ maxLength: 16
+ example: "24"
+ postCode:
+ type: string
+ maxLength: 16
+ example: "2501"
+ townName:
+ type: string
+ maxLength: 35
+ example: "Biel"
+ country:
+ type: string
+ maxLength: 2
+ example: "CH"
+ # -----------
+ # ---- Country Code ----
+ country:
+ type: string
+ pattern: '[A-Z]{2}'
+ example: CH
+ description: 2-Letter ISO 3166-2 Country Code
+ # ------------
+ # ---- Error Response (compliant to SIX b.Link)
+ commonErrorResponse:
title: Common Error Response
- description: General error response structure used in different response codes.
type: object
properties:
type:
- $ref: '#/components/schemas/CommonErrorType'
+ $ref: '#/components/schemas/commonErrorType'
title:
type: string
- description: Short name for the problem.
- examples:
- - This is the general problem description
+ example:
+ This is the general problem description
detail:
type: string
- description: More details about the problem.
- examples:
- - Detailed problem description with respect to the current request
+ example:
+ Detailed problem description with respect to the current request
instance:
type: string
- description: Reference to an individual entity or request which caused the problem.
- examples:
- - path/to/corresponding/resource
+ example:
+ path/to/corresponding/resource
- CommonErrorType:
+ commonErrorType:
title: Common Error Type
- description: Error Types for CommonErrorResponse.
+ description: Error Types for commonErrorResponse.
type: string
enum:
- /problems/INVALID_PAYLOAD
@@ -1255,149 +1616,328 @@ components:
- /problems/TECHNICAL_ERROR
- /problems/NOT_IMPLEMENTED
- /problems/SERVICE_UNAVAILABLE
- examples:
- - /problems/TECHNICAL_ERROR
+ example: '/problems/TECHNICAL_ERROR'
+ # ---- End Error Response
+ # ---- End Common Data Model
+ # ---- Global Common Header Parameters ----
parameters:
- path_cardId:
- in: path
- name: cardId
- required: true
+ clientid_in_header:
+ in: header
+ name: X-CorAPI-Client-ID
schema:
- $ref: '#/components/schemas/CardId'
- description: Identifier (technical) for a card for which information is requested.
-
- path_tokenId:
- in: path
- name: tokenId
+ type: string
+ description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
required: true
+
+ correlation_in_header:
+ in: header
+ name: X-Correlation-ID
schema:
- $ref: '#/components/schemas/TokenId'
- description: Identifier (technical) for a token for which information is requested.
-
- path_transactionId:
- in: path
- name: transactionId
+ type: string
+ description: Unique ID (defined by the caller) which will be reflected back in the response.
required: true
+
+ agent_in_header:
+ in: header
+ name: User-Agent
schema:
- $ref: '#/components/schemas/TransactionId'
- description: Identifier (technical) for a transaction for which information is requested.
-
- limit:
+ type: string
+ description: Name and version of the of the Client software
+ required: true
+
+ offset:
+ name: offset
in: query
- name: limit
+ description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
required: false
schema:
type: integer
format: int32
- minimum: 1
- examples:
- - 25
- description: Optional parameter for pagination. Maximum number of entries to be returned.
+ example: 25
+ minimum: 0
+
+ cardConsentId:
+ in: header
+ name: cardConsentId
+ description: Identifier for a consent that must have been given to allow data access.
+ required: true
+ schema:
+ type: string
+
+ cardId:
+ name: cardId
+ in: query
+ required: true
+ schema:
+ type: string
+ format: uuid
+ example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
+ description: Card ID
- offset:
+ cardTokenId:
+ name: cardTokenId
in: query
- name: offset
- required: false
+ required: true
schema:
- type: integer
- format: int32
- minimum: 0
- examples:
- - 25
- description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
+ type: string
+ format: uuid
+ example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
+ description: Card Token ID
+
+ personId:
+ name: personId
+ in: query
+ required: true
+ schema:
+ type: string
+ format: uuid
+ example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
+ description: Person ID
+
+ cardAccountId:
+ name: cardAccountId
+ in: query
+ description: Uuid v4 of a specific existing card account
+ required: true
+ example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
+ schema:
+ type: string
+ format: uuid
- clientid_in_header:
- in: header
- name: X-CorAPI-Client-ID
+ card-accountbundleId:
+ name: card-accountbundleId
+ in: query
required: true
schema:
type: string
- description: ID of the client forwarded to the provider.
+ format: uuid
+ example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
- correlation_in_header:
- in: header
- name: X-Correlation-ID
+ transactionId:
+ name: transactionId
+ in: query
required: true
schema:
- $ref: '#/components/headers/X-Correlation-ID'
- description: Unique ID (defined by the caller) which will be reflected back in the response.
+ type: string
+ format: uuid
+ example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
- agent_in_header:
- in: header
- name: User-Agent
+ statementId:
+ name: statementId
+ in: query
+ required: true
+ schema:
+ type: string
+ format: uuid
+ example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
+
+ cardContractId:
+ name: cardContractId
+ in: query
+ description: Uuid v4 of a specific existing card contract
required: true
+ example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
schema:
type: string
- description: Name and version of the of the Client software.
+ format: uuid
+
+ limit:
+ name: limit
+ in: query
+ description: Optional parameter for pagination. Maximum number of entries to be returned.
+ required: true
+ schema:
+ type: integer
+ format: int32
+ example: 25
+ minimum: 1
- securitySchemes:
- ApiKeyAuth:
- type: apiKey
- in: header
- name: X-API-Key
- OAuth2:
- type: oauth2
- flows:
- authorizationCode:
- authorizationUrl: https://example.com/oauth/authorize
- tokenUrl: https://example.com/oauth/token
- scopes:
- read: Grants read access
- write: Grants write access
+ cursor:
+ name: cursor
+ in: query
+ description: Optional parameter for pagination. An opaque string value used for pagination.
+ required: false
+ schema:
+ type: string
+ example: cursorIDxyz
+ # ---- Responses - Standard Errors Common Data Model v1.2.2----
responses:
standard400:
headers:
Content-Type:
- $ref: '#/components/headers/Content-Type'
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
Content-Language:
- $ref: '#/components/headers/Content-Language'
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
- description: >
- Client Error - The request could not be processed due to a problem in the data provided.
- This could be for any of the reasons of the HTML standard that would result in a 4xx code.
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard401:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard403:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Forbidden - The server understood the request but refuses to authorize it.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard404:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard405:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
standard500:
headers:
Content-Type:
- $ref: '#/components/headers/Content-Type'
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
Content-Language:
- $ref: '#/components/headers/Content-Language'
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
X-Correlation-ID:
- $ref: '#/components/headers/X-Correlation-ID'
- description: >
- Internal Server Error - The request could not be processed due to a problem at the data provider.
- This could be for any of the reasons of the HTML standard that would result in a 5xx code.
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
content:
application/problem+json:
schema:
- $ref: '#/components/schemas/CommonErrorResponse'
-
- headers:
- Content-Language:
- description: Language of provided content.
- schema:
- type: string
- examples:
- - en
-
- Content-Type:
- description: Type of provided content.
- schema:
- type: string
- examples:
- - application/json
- - application/problem+json; charset=utf-8 according to RFC7807
-
- X-Correlation-ID:
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- schema:
- type: string
- examples:
- - f058ebd6-02f7-4d3f-942e-904344e8cde5
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard501:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Not Implemented - The server does not support the functionality required to fulfill the request.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
+ standard503:
+ headers:
+ Content-Type:
+ schema:
+ type: string
+ description: 'application/problem+json; charset=utf-8 according to RFC7807'
+ example: application/problem+json
+ Content-Language:
+ schema:
+ type: string
+ description: 'Response language - always en'
+ example: en
+ X-Correlation-ID:
+ schema:
+ type: string
+ description: Client defined ID from request to correlates HTTP requests between a client and server.
+ example: f058ebd6-02f7-4d3f-942e-904344e8cde5
+ description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
+ content:
+ application/problem+json:
+ schema:
+ $ref: '#/components/schemas/commonErrorResponse'
+ # ---- End Responses - Standard Errors
From 0baa1eb06430e05c8293de1b1d71388b0c82090d Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Tue, 4 Jun 2024 15:52:28 +0200
Subject: [PATCH 23/29] delete old spec
---
cardInfoAPI.yaml | 1943 ----------------------------------------------
1 file changed, 1943 deletions(-)
delete mode 100644 cardInfoAPI.yaml
diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml
deleted file mode 100644
index 8ffe49b..0000000
--- a/cardInfoAPI.yaml
+++ /dev/null
@@ -1,1943 +0,0 @@
-openapi: "3.0.3"
-info:
- version: "0.6"
- title: Common Card Info API (Public)
- description:
- This specification defines a common card info API for payment cards used in Switzerland. The API is supposed to be used to retrieve payment card infos (read only).
- termsOfService: 'Tbd'
- contact:
- email: info@common-api.ch
- license:
- name: Apache 2.0
- url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
-servers:
- - url: https://card.common-api.ch
-externalDocs:
- description: Find out more about SFTI API specifications
- url: 'https://www.common-api.ch'
-security:
- - ApiKeyAuth: []
- - OAuth2:
- - read
- - write
-
-tags:
- - name: cards
- description: Operations related with managing cards
- - name: card-accounts
- description: Operations related with managing card accounts
- - name: statements
- description: Operations related with retrieving card account statements
- - name: transactions
- description: Operations related with retrieving card transactions
- - name: persons
- description: Operations related with managing persons
- - name: card-contracts
- description: Operations related with managing card contracts
- - name: card-accountbundles
- description: --
- - name: card-consents
- description: '[not used] Operations related with managing card consents'
-
-paths:
- /cards:
- get:
- tags:
- - cards
- description: List of cards for the authenticated context including all related information, optional filtered by personId / cardContractId / cardAccountId, sorted by cardId.
- summary: Return the list of all cards for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/transactionId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all cards with all related information sorted by cardId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardList:
- type: array
- items:
- $ref: '#/components/schemas/card'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /cards/card-tokens:
- get:
- tags:
- - card-tokens
- description: Card token (Child card) derived from parent card
- summary: TODO
- parameters:
- - $ref: '#/components/parameters/cardTokenId'
- - name: deviceName
- in: query
- description: Name of device, where token is used
- required: false
- example: apple
- schema:
- type: string
- enum:
- - apple
- - samsung
- - other
- - name: cardLink
- in: query
- description: TODO
- required: true
- example: TODO
- schema:
- type: string
- - name: dpan
- in: query
- description: TODO
- required: true
- example: TODO
- schema:
- type: string
- format: uuid
- - name: statusGeneric
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- - name: walletTypeName
- in: query
- description: Issuer of token card
- required: false
- example: TODO
- schema:
- type: string
- enum:
- - mastercard
- - visa
- - amex
- - dinersclub
- - apple pay
- - google pay
- - other
- - name: provisionDate
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- format: Date
- - name: expireDate
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- format: Date
- - name: schemeTokenId
- in: query
- description: TODO
- required: false
- example: TODO
- schema:
- type: string
- enum:
- - TODO
- - $ref: '#/components/schemas/cardTransaction'
- responses:
- '200':
- description: Paginated list of all token cards with all related information sorted by cardTokenId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardList:
- type: array
- items:
- $ref: '#/components/schemas/cardToken'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-accounts:
- get:
- tags:
- - card-accounts
- description: List of card accounts for the authenticated context including all related information, filtered by query, sorted by cardAccountId.
- summary: Return the list of all card accounts for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/transactionId'
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/statementId'
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/cardContractId'
- - in: query
- name: IBAN
- description: International Bank Account Number that is associated with the payment card account. Note, that one IBAN can be associated to multiple card accounts.
- required: false
- schema:
- type: string
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all card accounts with all related information sorted by cardAccountId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardAccountList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccount'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-accounts/statements:
- get:
- tags:
- - statements
- description: List of card account statements for the authenticated context including all related information, filtered by query, sorted by cardAccountStatementId.
- summary: Return the list of all card account statements for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/cardAccountId'
- - in: query
- name: fromDate
- description: Date from which statement entries should be retrieved
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - in: query
- name: untilDate
- description: Date until which statement entries should be retrieved
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all card account statements with all related information sorted by cardAccountStatementId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardAccountStatementList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccountStatement'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-transactions:
- get:
- tags:
- - transactions
- description: List of card transactions for the authenticated context including all related information, filtered by query, sorted by cardTransactionId.
- summary: Return the list of all card transactions for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/cardAccountId'
- - in: query
- name: inclName
- description: Only retrieve transactions that include this text in as a merchant name
- required: false
- example: Hotel
- schema:
- type: string
- - name: inclLocation
- in: query
- description: Only retrieve transactions that include this text in as a merchant location
- required: false
- example: London
- schema:
- type: string
- - name: inclCountry
- in: query
- description: Only retrieve transactions that include this text in as a merchant country
- required: false
- example: Italien
- schema:
- type: string
- - name: fromDate
- in: query
- description: Only retrieve transactions starting from this date (YYYY-MM-DD)
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - name: untilDate
- in: query
- description: Only retrieve transactions up until this date (YYYY-MM-DD)
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all card transactions with all related information sorted by cardTransactionId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardTransactionList:
- type: array
- items:
- $ref: '#/components/schemas/cardTransaction'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /persons:
- get:
- tags:
- - persons
- description: List of persons for the authenticated context including all related information, filtered by query which also allows searching, sorted by personId.
- summary: Return the list of all persons for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/cardId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/cardContractId'
- - in: query
- name: personSurName
- description: First name of the customer.
- required: false
- schema:
- $ref: '#/components/schemas/personSurName'
- - in: query
- name: personName
- description: Last name of the customer.
- required: false
- schema:
- $ref: '#/components/schemas/personName'
- - in: query
- name: companyName
- description: 'Retrieve a list of customers given the company name.'
- required: false
- schema:
- $ref: '#/components/schemas/entityName'
- - in: query
- name: birthDate
- description: Date of birth of the person.
- required: false
- schema:
- $ref: '#/components/schemas/date'
- - in: query
- name: contractType
- description: Possible values are consumer, business, corporate (if left empty, any will be provided)
- required: false
- schema:
- $ref: '#/components/schemas/contractType'
- - in: query
- name: searchType
- description: Possible values are same, soundex, ccv
- required: false
- schema:
- type: string
- enum:
- - same
- - soundex
- - cvv
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all person with all related information sorted by personId
- content:
- application/json:
- schema:
- type: object
- properties:
- personList:
- type: array
- items:
- $ref: '#/components/schemas/person'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-contracts:
- get:
- tags:
- - card-contracts
- description: List of cards contracts for the authenticated context including all related information, filtered by query, sorted by cardContractId.
- summary: Return the list of all card contracts for the authenticated context (filtered and sorted)
- parameters:
- - $ref: '#/components/parameters/personId'
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: Paginated list of all queried card contracts with all related information sorted by cardContractsId
- content:
- application/json:
- schema:
- type: object
- properties:
- cardContractList:
- type: array
- items:
- $ref: '#/components/schemas/cardContract'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
- /card-accountbundles:
- get:
- tags:
- - card-accountbundles
- description: --
- summary: --
- parameters:
- - $ref: '#/components/parameters/cardAccountId'
- - $ref: '#/components/parameters/card-accountbundleId'
- - $ref: '#/components/parameters/cardContractId'
- - $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- - $ref: '#/components/parameters/clientid_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
- responses:
- '200':
- description: --
- content:
- application/json:
- schema:
- type: object
- properties:
- cardAccountbundleList:
- type: array
- items:
- $ref: '#/components/schemas/cardAccountbundle'
- _links:
- $ref: '#/components/schemas/linksPagination'
- headers:
- X-Correlation-ID:
- schema:
- type: string
- description: Reflects the ID (set by the caller) from the request.
- '400':
- $ref: '#/components/responses/standard400'
- '401':
- $ref: '#/components/responses/standard401'
- '403':
- $ref: '#/components/responses/standard403'
- '404':
- $ref: '#/components/responses/standard404'
- '405':
- $ref: '#/components/responses/standard405'
- '500':
- $ref: '#/components/responses/standard500'
- '501':
- $ref: '#/components/responses/standard501'
- '503':
- $ref: '#/components/responses/standard503'
-
-
-# -------------------------
-# -------- Models ---------
-# -------------------------
-components:
- securitySchemes:
- ApiKeyAuth:
- type: apiKey
- in: header
- name: X-API-Key
-
- OAuth2:
- type: oauth2
- flows:
- authorizationCode:
- authorizationUrl: https://example.com/oauth/authorize
- tokenUrl: https://example.com/oauth/token
- scopes:
- read: Grants read access
- write: Grants write access
-
- schemas:
- # ---- Card Account Object ----
- cardAccount:
- description: The representation of a card account object
- type: object
- required:
- - cardAccountId
- properties:
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- cards:
- type: array
- description: List of card_uids linked to this account
- items:
- $ref: '#/components/schemas/card'
- currency:
- $ref: '#/components/schemas/currency'
- ibanAccount:
- $ref: '#/components/schemas/paymentQrIbanAccount'
- billingCycle:
- type: string
- description: code that determines the billing cycle
- example: monthly
- enum:
- - weekly
- - monthly
- - quarterly
- - halfyearly
- - yearly
- cardAccountStatus:
- $ref: '#/components/schemas/genericStatus'
- cardLoyality:
- $ref: '#/components/schemas/cardLoyality'
- paymentDetails:
- type: object
- properties:
- paymentType:
- $ref: '#/components/schemas/paymentType'
- paymentOption:
- $ref: '#/components/schemas/paymentOption'
- statementDetails:
- type: object
- properties:
- deliveryType:
- type: string
- example: paper
- description: Description of the delivery format of the statement.
- enum:
- - paper
- - paperless
- - estatement
- - other
- activeDeliveryFee:
- type: number
- example: 1.0
- description: Amount charged to the customer for each statement delivery. Typically, paperless is free.
- nextStatementDate:
- $ref: '#/components/schemas/date'
- # ---------
-
- # ---- Card Loyality Object ----
- cardLoyality:
- description: The representation of a card loyality object
- type: object
- required:
- - cardLoyalityId
- properties:
- cardLoyalityId:
- $ref: '#/components/schemas/entityId'
- name:
- type: string
- description: Program name
- example: surprize
- reference:
- type: string
- example: "2501021032295"
- description: Additional reference number if available
- enrollment_date:
- $ref: '#/components/schemas/date'
- # ---------
-
- # ---- Card API Object ----
- cardApi:
- description: List of APIs supported for a API consumer
- type: string
- example: get:cards
- # ---------
-
-
- # ---- Card Consent Object ----
- cardConsent:
- description: The representation of a card consent object
- type: object
- required:
- - cardConsentId
- - cardApiList
- - identificationType
- - identificationValue
- properties:
- cardConsentId:
- $ref: '#/components/schemas/entityId'
- identificationType:
- type: string
- example: card_uid
- description: Audit type field in order to identify the actual user who granted the consent. This field contains the type of identifier.
- identificationValue:
- type: string
- example: 404003004CCL50000
- description: Audit type field in order to identify the actual user who granted the consent. This field contains the actual identifier of the type defined before.
- cardApiList:
- type: array
- description: List of the APIs to which access is requested.
- items:
- $ref: '#/components/schemas/cardApi'
- # ---------
-
- # ---- Card Object ----
- card:
- description: The representation of a card objectw
- type: object
- required:
- - cardId
- properties:
- cardId:
- $ref: '#/components/schemas/entityId'
- personId:
- $ref: '#/components/schemas/entityId'
- contractId:
- $ref: '#/components/schemas/entityId'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- issuingPartnerId:
- $ref: '#/components/schemas/entityIdName'
- issuerId:
- $ref: '#/components/schemas/entityIdName'
- cardDetail:
- type: object
- required:
- - cardNumberCustomer
- properties:
- cardNumber:
- type: string
- example: 4566549683425654
- maxLength: 19
- description: Card number
- cardNumberCustomer:
- type: string
- example: 4566549683425654
- maxLength: 50
- description: Card number
- initialCreationDate:
- $ref: '#/components/schemas/date'
- expiryDate:
- type: string
- example: 05/19
- description: Card expiry date in the format MM/YY
- embossingLine1:
- type: string
- maxLength: 30
- example: FRANZ MUSTERMANN
- description: Embossing Line 1 contains the person name as visible on the card plastic
- embossingLine2:
- type: string
- maxLength: 30
- example: VISECA CARD SERVICES
- description: Embossing Line 2 may contain a person-specified or product-specific value, as visible on the card plastic
- purgedDate:
- $ref: '#/components/schemas/date'
- currency:
- $ref: '#/components/schemas/currency'
- card_scheme:
- type: string
- example: visa
- description: Card payment scheme
- enum:
- - mastercard
- - visa
- - amex
- - dinersclub
- - other
- productId:
- type: string
- example: "1010101"
- description: Issuer identifier of a card product
- productType:
- type: string
- example: prepaid
- description: States if the card is credit or debit. Prepaid cards are labelled as credit in this operation
- enum:
- - credit
- - debit
- - prepaid
- productCategory:
- type: string
- example: gold
- description: 'Product category corresponds to the tier of card: gold, platinum, basic etc.'
- productLine:
- $ref: '#/components/schemas/contractType'
- productName:
- type: string
- maxLength: 50
- example: World Mastercard Gold CHF
- description: Commercial name of the card product as defined by the bank
- cardImage:
- type: string
- example: "https://bank.ch/images/cardImage.png"
- description: URL to the (png) card image corresponding to the card
- cardRelationship:
- type: string
- example: main_card
- description: 'Identifies the nature of the card in regards to the overall account: main card or additional card'
- enum:
- - main_card
- - additional_card
- previousCardId:
- $ref: '#/components/schemas/entityId'
- previousReplacementDate:
- $ref: '#/components/schemas/date'
- replacementReason:
- type: string
- example: other
- description: Reason for the replacement of this card
- nextCardId:
- $ref: '#/components/schemas/entityId'
- nextReplacementDate:
- $ref: '#/components/schemas/date'
- atmDirectDebit:
- type: boolean
- description: A flag indicating if the ATM Direct Debit functionality is enabled
- example: true
- cardStatus:
- $ref: '#/components/schemas/genericStatus'
- # ---------
-
- # TODO: define object with properties
- cardToken:
- description: Card Account Token Information.
- type: object
- required:
- - cardTokenId
- properties:
- cardTokenId:
- type: string
- format: uuid
- description: UUID v4 of the card accountbundle
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
-
- # ---- Card Account Statement ----
- cardAccountStatement:
- description: xy
- type: object
- required:
- - cardAccountStatementId
- properties:
- cardAccountStatementId:
- $ref: '#/components/schemas/entityId'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- statementCreationDate:
- $ref: '#/components/schemas/date'
- statementAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- paymentDueDate:
- $ref: '#/components/schemas/date'
- statementMinimalDueAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- paymentType:
- $ref: '#/components/schemas/paymentType'
- paymentOption:
- $ref: '#/components/schemas/paymentOption'
- # ---------
-
- # ---- Card Transaction ----
- cardTransaction:
- description: Transaction object adapted for card use
- type: object
- required:
- - cardTransactionId
- properties:
- cardTransactionId:
- type: string
- format: uuid
- example: d452083f-8316-410d-a609-d49463687329
- description: Uuid v4 of the specific transaction. Must not change when the status (approved, booked, etc.) is changed.
- approvalCode:
- type: string
- example: Please-Provide-Example-and-MaxLength
- description: Additional transaction identifier provided by schemes or processing system
- transactionTimestamp:
- $ref: '#/components/schemas/dateTime'
- originalCurrencyAmount:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- targetCurrencyAmountt:
- $ref: '#/components/schemas/paymentCurrencyAmount'
- exchangeRate:
- type: string
- example: "0.957"
- pattern: "[0-9][.][0-9]{1,10}"
- maxLength: 12
- exchangeRateDate:
- $ref: '#/components/schemas/date'
- merchant:
- type: object
- description: Merchant information of the card transaction
- properties:
- merchantName:
- type: string
- example: COOP PRONTO
- description: Value that contains the merchant name and location
- merchantLocation:
- type: string
- example: Zurich
- # Please maxLength
- description: Value that contains the merchant name and location
- merchantLocationLatitude:
- type: string
- example: "-35.253252"
- # Please regex
- description: Value that contains the merchant name and location
- merchantLocationLongitude:
- type: string
- example: "174.071674"
- # Please regex
- description: Value that contains the merchant name and location
- merchantCountry:
- $ref: '#/components/schemas/country'
- merchangeCategoryCode:
- type: string
- example: "5411"
- description: Value that contains the merchant category code as defined by ISO 18245
- posEntryMode:
- $ref: '#/components/schemas/posEntryMode'
- terminalId:
- type: string
- description: Identifier of the point of sale terminal
- #Please add example and regex
- channel:
- type: string
- description: Showing if it was a eCommerce transaction or not
- enum:
- - ecom
- - other
- offline:
- type: string
- description: Indicator if the transaction was offline authorized
- #Please add example and regex
- statementDate:
- type: string
- format: date
- example: '2018-08-03'
- description: Settlement date
- fees:
- type: array
- description: |-
- This array shows individual fee objects that are associated with the
- transaction. Please note that multiple fee objects can be transmitted.
- items:
- $ref: '#/components/schemas/cardTransactionFee'
- state:
- type: string
- example: authorised
- description: Used to identify if a transactions has been settled (booked) or just authorised
- transactionCategory:
- type: string
- example: merchant
- description: Transaction type identifying merchant to non-merchant entries
- enum:
- - merchant
- - fee
- - atm
- transactionType:
- $ref: '#/components/schemas/cardTransactionType'
- personId:
- $ref: '#/components/schemas/entityId'
- personName:
- type: object
- description: Name of the person
- properties:
- company:
- $ref: '#/components/schemas/entityName'
- name:
- $ref: '#/components/schemas/personName'
- surName:
- $ref: '#/components/schemas/personSurName'
- cardAccountId:
- $ref: '#/components/schemas/entityId'
- cardId:
- $ref: '#/components/schemas/entityId'
- walletProvider:
- type: string
- example: Apple Pay
- description: Identifier of the wallet provider if transaction was perfomred with a payment token (e.g. mobile payment such as Apple Pay)
- token:
- type: string
- example: "1234"
- maxLength: 4
- description: last 4 digits of the token
- tokenRequestorId:
- type: string
- example: "1234"
- maxLength: 4
- description: last 4 digits of the token
- # Is this a duplicate of token?
- securityLevelIndicator:
- type: string
- # Please provide example and regex
- description: Security Level Indicator provides additional information about 3DS, recurring transactions and other authentication related information
- actionCode:
- type: string
- example: "121"
- description: The Action Code provides information about the why a transaction was approved or declined
- # ---------
-
- # ---- Card Transaction Fee ----
- cardTransactionFee:
- description: Individual fee objects that are associated with the transaction
- type: object
- properties:
- type:
- type: string
- example: Bearbeitungsgebühr 1.75%
- description: Name of the fee
- amount:
- $ref: '#/components/schemas/amount'
- currency:
- $ref: '#/components/schemas/currency'
- # ---------
-
- # ---- Card Transaction Type ----
- cardTransactionType:
- type: object
- properties:
- acquiringType:
- type: string
- # Please provide example
- description: Provides further insight into the interface used
- financialMeaning:
- type: string
- # Please provide example
- description: Additional functional information about a transaction
- transactionReference:
- type: string
- # Please provide example
- description: Provides information about connecting a transaction to a previous occurred transaction. E.g. Storno
- # -------
-
- # ---- Card POS Entry Mode ----
- posEntryMode:
- type: object
- description: The POS Entry Mode object contain multiple fields that further define how the transaction was captured at its point of origin including information about authentication, payment infrastructure and other related topics.
- properties:
- cardDataInputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardCaptureCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- operatingEnvironment:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personPresent:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardPresent:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardDataInputMode:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationMethod:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- personAuthenticationEntity:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- cardDataOutputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- terminalOutputCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
- pinCaptureCapability:
- type: string
- description: Please_Add_Description_and_Example_and_Regex-MaxLength
-
- # ---- Person ----
- person:
- description: Person information .
- type: object
- required:
- - personId
- properties:
- personId:
- $ref: '#/components/schemas/entityId'
- contractId:
- $ref: '#/components/schemas/entityId'
- personType:
- $ref: '#/components/schemas/contractType'
- isMainPerson:
- type: boolean
- description: Flag to identify if the person is a main person
- example: true
- personStatistics:
- type: object
- properties:
- total_accounts:
- type: integer
- example: 1
- description: Total number of accounts of a private customer or a company
- totalActivAccounts:
- type: integer
- description: Total number of active accounts of a private customer or a company
- example: 2
- totalCards:
- type: integer
- example: 1
- description: Total number of cards of a private customer or a company
- totalActiveCards:
- type: integer
- description: Total number of active cards of a private customer or a company
- personDetail:
- type: object
- properties:
- salutation:
- $ref: '#/components/schemas/personSalutation'
- company:
- $ref: '#/components/schemas/entityName'
- name:
- $ref: '#/components/schemas/personName'
- surName:
- $ref: '#/components/schemas/personSurName'
- middleName:
- $ref: '#/components/schemas/personMiddleName'
- address:
- $ref: '#/components/schemas/structuredAddress'
- country:
- $ref: '#/components/schemas/country'
- language:
- $ref: '#/components/schemas/language'
- nationality:
- $ref: '#/components/schemas/country'
- birthDay:
- $ref: '#/components/schemas/date'
- gender:
- $ref: '#/components/schemas/personGender'
- permit:
- $ref: '#/components/schemas/personPermit'
- externalReferenceId:
- type: string
- maxLength: 30
- example: No1
- description: Reference id of company customers (e.g. employee number)
- amloCheck:
- type: boolean
- example: true
- description: Flag to show if the Anti-Money Laundering Ordinance has been already checked for this customer
- adPermission:
- type: boolean
- example: false
- description: Flag to see if the customer give his/her permission to marketing advertisement
- phoneNumber:
- type: array
- description: Phone numbers of the person
- items:
- $ref: '#/components/schemas/personPhoneNumber'
- email:
- type: array
- description: Email addresses of the person
- items:
- $ref: '#/components/schemas/personEmail'
- # ---------
-
- # ---- Card Contract ----
- cardContract:
- description: Card Contract Information .
- type: object
- required:
- - cardContractId
- properties:
- cardContractId:
- type: string
- format: uuid
- description: UUID v4 of the card contract
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
- openingDate:
- description: Date when the card contract was created
- type: string
- format: date
- example: 2018-04-13
- purgedDate:
- description: Date that indicates if and when this card contract was purged in the processor system
- type: string
- format: date
- example: 2018-04-13
- cardAccounts:
- type: array
- items:
- $ref: '#/components/schemas/cardAccount'
- personId:
- $ref: '#/components/schemas/entityId'
- contractType:
- $ref: '#/components/schemas/contractType'
- issuingPartnerId:
- $ref: '#/components/schemas/entityIdName'
- issuerId:
- $ref: '#/components/schemas/entityIdName'
- fulfillEntity:
- $ref: '#/components/schemas/entityName'
- contractStatus:
- $ref: '#/components/schemas/genericStatus'
- # ---------
-
- # TODO: define object with properties
- cardAccountbundle:
- description: Card Accountbundle Information.
- type: object
- required:
- - cardAccountbundleId
- properties:
- cardAccountbundleId:
- type: string
- format: uuid
- description: UUID v4 of the card accountbundle
- example: 576f8de3-6b30-4882-a7af-da2132a456cf
-
- # ---- Card API Model ----
- contractType:
- description: Type of a contract
- type: string
- enum:
- - business
- - corporate
- - consumer
- example: consumer
- entityId:
- type: string
- format: uuid
- description: UUID of an entity
- example: 1b19aeb0-60db-4160-8551-c37de178ca10
- entityName:
- type: string
- maxLength: 70
- description: Name of an entity
- example: Abteilung B
- personSurName:
- type: string
- maxLength: 70
- description: Sur name of person
- example: Muster
- personMiddleName:
- type: string
- maxLength: 70
- description: Middle name of person
- example: Gustav
- personName:
- type: string
- maxLength: 70
- description: Name of person
- example: Max
- personGender:
- type: string
- enum:
- - male
- - female
- - other
- example: female
- description: Gender of the person.
- personSalutation:
- type: string
- enum:
- - none
- - mr
- - mrs
- - company
- - male_academic
- - female_academic
- - male_nobility
- - female_nobility
- - neutral
- example: mrs
- description: Salutation for the person.
- language:
- type: string
- example: fr
- description: Language - for example, preferred contact language
- enum:
- - de
- - fr
- - it
- - en
- personPermit:
- description: Permit of a person
- type: object
- required:
- - permitStatus
- properties:
- permitStatus:
- type: string
- example: B
- description: Permit status
- enum:
- - C
- - B
- - other
- permitSince:
- $ref: '#/components/schemas/date'
- personPhoneNumber:
- description: Phone number of a person
- type: object
- required:
- - phoneNumber
- properties:
- phoneNumberType:
- type: string
- example: mobile
- description: phone number type
- enum:
- - mobile
- - mobile private
- - mobile business
- - fixline
- - fixline private
- - fixline business
- - other
- emailAddress:
- type: string
- maxLength: 30
- example: max.muster@company.ch
- description: Email address
- personEmail:
- description: Email address of a person
- type: object
- required:
- - emailAddress
- properties:
- emailType:
- type: string
- example: personal
- description: Email type
- enum:
- - personal
- - business
- - other
- emailAddress:
- type: string
- maxLength: 30
- example: max.muster@company.ch
- description: Email address
- entityIdName:
- description: Issuing entity of the card
- type: object
- required:
- - issuingEntityId
- properties:
- issuingEntityId:
- $ref: '#/components/schemas/entityId'
- name:
- $ref: '#/components/schemas/entityName'
-
- paymentType:
- type: string
- example: lsv
- description: Identifier of the payment method selected by the person to settle the account.
- enum:
- - lsv
- - debit_direct
- - esr
- - ipi
- - pos
- paymentOption:
- type: string
- example: full
- description: Identifier of the payment plan selected by the person to pay for a bill.
- enum:
- - full
- - instalment
- - revolving
-
- genericStatus:
- description:
- 'Describes the status of a card object.
- Effective: Aggregated effective status on the entity based on directly and inherited status.
- Directly: Directly applied status on the entity. Note: At a contract level effective status and direct status are the same.
- Inherited: Inherited status on the entity. Note: At a contract level there is no inherited status
- Last Change: Date of the last change of the effective status.'
- type: object
- required:
- - effective
- properties:
- effective:
- $ref: '#/components/schemas/genericStatusEnum'
- direct:
- $ref: '#/components/schemas/genericStatusEnum'
- inherited:
- $ref: '#/components/schemas/genericStatusEnum'
- last_change:
- $ref: '#/components/schemas/date'
- genericStatusEnum:
- description: Status element
- type: object
- required:
- - status
- properties:
- status:
- type: string
- enum:
- - ok
- - nok
- - unknown
- - active
- - blocked
- - suspended_by_person
- - suspended_by_bank
- - suspended_by_issuer
- description: Status type
- detail:
- type: string
- description: 'Status detail in custom text'
- # ---------
-
- # ---- Common Data Model v1.2.0
- # ---- Date Formats
- date:
- type: string
- format: date
- example: 2018-04-13
- dateTime:
- type: string
- format: date-time
- example: 2018-04-13T11:11:11Z
- # --------
- # ---- Links for Pagination----
- linksPagination:
- description: Links (or cursors) returned in the answer of an API call.
- type: object
- properties:
- self:
- type: string
- description: Link / cursor to the current result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=75&limit=25
- first:
- type: string
- description: Link / cursor to the first result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=0&limit=25
- previous:
- type: string
- description: Link / cursor to the previous result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=50&limit=25
- next:
- type: string
- description: Link / cursor to the next result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=100&limit=25
- last:
- type: string
- description: Link / cursor to the last result set (based on the submitted pagination approach)
- example: /card-app/api/v1/cards?offset=150&limit=25
- # ---------
-
- # ---- Account objects from payment API ----
- paymentQrIbanAccount:
- title: Payment QR-IBAN Account
- type: object
- required:
- - type
- - identification
- properties:
- type:
- type: string
- description: IBAN or QR-IBAN of the creditor.
- enum:
- - "IBAN"
- - "QR_IBAN"
- identification:
- type: string
- maxLength: 34
- example: "CH9300762011623852957"
- pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}"
- # ---------
-
- # ---- Currency ----
- currency:
- description: ISO 4217 code
- type: string
- pattern: '[A-Z]{3}'
- example: CHF
- # ---------
-
- # ---- Payment Currency Amount compatible to SFTI XS2A API----
- paymentCurrencyAmount:
- title: Payment Currency-Amount
- type: object
- required:
- - currency
- - amount
- properties:
- currency:
- $ref: '#/components/schemas/currency'
- amount:
- $ref: '#/components/schemas/amount'
-
- # ---- Amount ----
- amount:
- type: string
- description: Amount given with fractional digits, the separator is a dot
- pattern: "[0-9]{1,12}([.][0-9]{1,5})?"
- maxLength: 18
- example: "10.25"
- # --------
-
- # ---- Address compliant to payment address (b.Link & ISO20022)----
- structuredAddress:
- title: Structured Address
- type: object
- required:
- - streetName
- - postCode
- - townName
- - country
- properties:
- streetName:
- type: string
- maxLength: 70
- example: "Rue de la gare"
- buildingNumber:
- type: string
- maxLength: 16
- example: "24"
- postCode:
- type: string
- maxLength: 16
- example: "2501"
- townName:
- type: string
- maxLength: 35
- example: "Biel"
- country:
- type: string
- maxLength: 2
- example: "CH"
- # -----------
- # ---- Country Code ----
- country:
- type: string
- pattern: '[A-Z]{2}'
- example: CH
- description: 2-Letter ISO 3166-2 Country Code
- # ------------
- # ---- Error Response (compliant to SIX b.Link)
- commonErrorResponse:
- title: Common Error Response
- type: object
- properties:
- type:
- $ref: '#/components/schemas/commonErrorType'
- title:
- type: string
- example:
- This is the general problem description
- detail:
- type: string
- example:
- Detailed problem description with respect to the current request
- instance:
- type: string
- example:
- path/to/corresponding/resource
-
- commonErrorType:
- title: Common Error Type
- description: Error Types for commonErrorResponse.
- type: string
- enum:
- - /problems/INVALID_PAYLOAD
- - /problems/MALFORMED_PAYLOAD
- - /problems/INVALID_TOKEN
- - /problems/EXPIRED_TOKEN
- - /problems/INSUFFICIENT_PRIVILEGES
- - /problems/NO_ACCESS_TO_RESOURCE
- - /problems/RESOURCE_DOES_NOT_EXIST
- - /problems/RESOURCE_NOT_READY
- - /problems/RESOURCE_TOO_LARGE
- - /problems/WRONG_METHOD
- - /problems/OPERATION_NOT_ALLOWED
- - /problems/TECHNICAL_ERROR
- - /problems/NOT_IMPLEMENTED
- - /problems/SERVICE_UNAVAILABLE
- example: '/problems/TECHNICAL_ERROR'
- # ---- End Error Response
- # ---- End Common Data Model
-
- # ---- Global Common Header Parameters ----
- parameters:
- clientid_in_header:
- in: header
- name: X-CorAPI-Client-ID
- schema:
- type: string
- description: 'ID of the client forwarded to the provider. (SCOPE: FI)'
- required: true
-
- correlation_in_header:
- in: header
- name: X-Correlation-ID
- schema:
- type: string
- description: Unique ID (defined by the caller) which will be reflected back in the response.
- required: true
-
- agent_in_header:
- in: header
- name: User-Agent
- schema:
- type: string
- description: Name and version of the of the Client software
- required: true
-
- offset:
- name: offset
- in: query
- description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
- required: false
- schema:
- type: integer
- format: int32
- example: 25
- minimum: 0
-
- cardConsentId:
- in: header
- name: cardConsentId
- description: Identifier for a consent that must have been given to allow data access.
- required: true
- schema:
- type: string
-
- cardId:
- name: cardId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
- description: Card ID
-
- cardTokenId:
- name: cardTokenId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 7306fd9b-9df5-4f68-9d03-2c3674f48086
- description: Card Token ID
-
- personId:
- name: personId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
- description: Person ID
-
- cardAccountId:
- name: cardAccountId
- in: query
- description: Uuid v4 of a specific existing card account
- required: true
- example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
- schema:
- type: string
- format: uuid
-
- card-accountbundleId:
- name: card-accountbundleId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- transactionId:
- name: transactionId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- statementId:
- name: statementId
- in: query
- required: true
- schema:
- type: string
- format: uuid
- example: 73065f9b-8cf5-4f68-9d03-2c3674f48086
-
- cardContractId:
- name: cardContractId
- in: query
- description: Uuid v4 of a specific existing card contract
- required: true
- example: bcb5d762-8d28-43a2-9398-393b2e8d56ba
- schema:
- type: string
- format: uuid
-
- limit:
- name: limit
- in: query
- description: Optional parameter for pagination. Maximum number of entries to be returned.
- required: true
- schema:
- type: integer
- format: int32
- example: 25
- minimum: 1
-
- cursor:
- name: cursor
- in: query
- description: Optional parameter for pagination. An opaque string value used for pagination.
- required: false
- schema:
- type: string
- example: cursorIDxyz
-
- # ---- Responses - Standard Errors Common Data Model v1.2.2----
- responses:
- standard400:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard401:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Unauthorized - The request has not been applied because it lacks valid authentication credentials for the target resource.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard403:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Forbidden - The server understood the request but refuses to authorize it.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard404:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Not Found - The origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard405:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Method Not Allowed - The method received in the request-line is known by the origin server but not supported by the target resource.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard500:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Internal Server Error - The server encountered an unexpected condition that prevented it from fulfilling the request.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard501:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Not Implemented - The server does not support the functionality required to fulfill the request.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- standard503:
- headers:
- Content-Type:
- schema:
- type: string
- description: 'application/problem+json; charset=utf-8 according to RFC7807'
- example: application/problem+json
- Content-Language:
- schema:
- type: string
- description: 'Response language - always en'
- example: en
- X-Correlation-ID:
- schema:
- type: string
- description: Client defined ID from request to correlates HTTP requests between a client and server.
- example: f058ebd6-02f7-4d3f-942e-904344e8cde5
- description: Service Unavailable. The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
- content:
- application/problem+json:
- schema:
- $ref: '#/components/schemas/commonErrorResponse'
- # ---- End Responses - Standard Errors
From 1aa2f8ad8c82e6b487e9d26768c3838706a327c2 Mon Sep 17 00:00:00 2001
From: christiangmehling <146012642+christiangmehling@users.noreply.github.com>
Date: Tue, 4 Jun 2024 16:58:07 +0200
Subject: [PATCH 24/29] remove cardId query param from card-tokens/tokenId
---
cardInfoAPI-Level1.yaml | 5 -----
1 file changed, 5 deletions(-)
diff --git a/cardInfoAPI-Level1.yaml b/cardInfoAPI-Level1.yaml
index 36bd063..4806f80 100644
--- a/cardInfoAPI-Level1.yaml
+++ b/cardInfoAPI-Level1.yaml
@@ -187,11 +187,6 @@ paths:
- Card-tokens
parameters:
- $ref: '#/components/parameters/path_tokenId'
- - in: query
- name: card_id # TODO should we keep this parameter when it is anyway optional?
- required: false
- schema:
- $ref: '#/components/schemas/CardId'
- $ref: '#/components/parameters/client_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
From e4c51ee6571577e3d0e31406a3160613d643f0f5 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Wed, 5 Jun 2024 16:29:02 +0200
Subject: [PATCH 25/29] add operational Guide
---
operationalGuide.md | 143 ++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 143 insertions(+)
create mode 100644 operationalGuide.md
diff --git a/operationalGuide.md b/operationalGuide.md
new file mode 100644
index 0000000..b68ed34
--- /dev/null
+++ b/operationalGuide.md
@@ -0,0 +1,143 @@
+# Operational Guide
+
+- [Central Design Decisions](#central-design-decisions) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Central-Design-Decisions)
+- [Card API Level 1](#card-api-level-1) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-1)
+- [Card API Level 2](#card-api-level-2) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-2)
+- [Card API Level 3](#card-api-level-3) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-3)
+- [Use of this spec](#use-of-this-spec) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Use-of-this-spec)
+- [Appendix](#appendix) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Appendix)
+
+# Central Design Decisions
+
+## Level concept
+The specification of the Card API is structured in different maturity levels, i.e. from an API modelling point of view, a Matryoshka approach is chosen here. This ensures that different users of the API with different availabilities of information still follow as similar an approach as possible. It also enables a more precise definition of the data model for data providers who do not want to offer all entities. Parties negotiate among themselves which level of the API should be used; ideally, level 3, the most comprehensive level of the API, is aimed for, as this ensures maximum compatibility.
+
+The levels build on each other. This means that level 1 supports the least functionality, but also requires the least information for use. Level 3 offers broader functionality with additional endpoints, but must also be used with complete data on the person/card/account. As the levels build on each other, it is also possible to communicate to lower levels via a proxy that filters the corresponding fields. For example, a data provider can have implemented level 3, but the proxy or end user can only map level 1 information and still receive corresponding responses for level 1.
+
+Please note that the three-tiered approach does not reflect the three card types, but different use cases as described below.
+
+
+
+## Name patterns for parameters
+
+### Differentiation between *code / *reference / *id
+The parameter names allow an easy recognition of the type of underlying identifier. The three following words are used as part of the parameter names for distinction:
+
+* *Id: technical identifier for an instance of a resource, is always in the uuid format; is used for direct access to a resource instance in an API endpoint
+* *Reference: functional identifier for an instance of a resource that can also be known by an end customer, is a generic string without a standardized format
+* *Code: identifier for an instance of a resource, can be mapped to a name in a finite set of values, is a generic string without a standardized format
+
+
+# Card API Level 1
+
+## Model
+
+
+### “cards” resource
+The term “cards” refers to both physical and virtual credit or debit cards issued by banks or financial institutions. Physical cards are the traditional plastic cards that holders carry with them. Virtual cards, on the other hand, only exist in digital form and are often used for online payments. These virtual cards have a card number, expiration date and security code like physical cards.
+### “card-tokens” resource
+The term “card tokens” refers to the DPAN (Digital Primary Account Number) of a credit or debit card that is stored in digital wallets, wearables or with merchants (e.g. for click-to-pay). The “card token” serves as a replacement for the PAN and is used for transactions instead of the real card number. This reduces the risk of data misuse or fraud, as the sensitive card data is not transmitted directly.
+### “transactions” resource
+The term “transactions” refers to payments made with physical or virtual cards or with card tokens. These transactions are displayed on the cardholder's account and include all authorized and recorded payments entered by the cardholder.
+
+Transactions can include various types of payments, such as retail purchases, online payments, transfers between accounts, etc. Each transaction is authorized and recorded, which means that it has been approved by the cardholder and the payment amount has been debited from the cardholder's account.
+
+## Use Cases
+| Identifier | Description |
+| -------- | ------- |
+| PFM/BFM | Aggregation of transactions for cards from different issuers to make evaluations on spending behavior, budget, ecological footprint or more.
Limitation: Account-based transactions are not taken into account.
Challenge with these endpoints: incomplete view of card account transactions. |
+| Card overview| Aggregation of cards and associated tokens from different issuers for display.
Restriction: Structure of cards in an account or customer relationship is not easily traceable. |
+
+## Remarks
+none so far
+
+
+# Card API Level 2
+
+## Model
+
+
+## Use Cases
+| Identifier | Description |
+| -------- | ------- |
+| PFM/BFM | Everything from level 1, plus consideration of account-based transactions. |
+| Card overview | Everything from level 1, plus more extensive information on card account data. |
+| Expense Management | At least for smaller companies / simpler company structures, level 2 should be sufficient to enable this use case. |
+
+## Remarks
+none so far
+
+
+# Card API Level 3
+
+## Model
+
+
+## Use Cases
+| Identifier | Description |
+| -------- | ------- |
+| | All Level 1 + 2 use cases, plus more structuring options, i.e. end customers can map internal structures (organizational units) and contracts, for example. |
+
+## Remarks
+none so far
+
+
+# Use of this spec
+
+## Basics
+For direct communication via the Card API, both parties must negotiate the level of the API used and agree on a level.
+
+## Direct communication
+If only GET requests are used, it is possible that the sender supports a higher level of the API. In this case, the recipient must ignore additional information in the response.
+
+## Communication via proxy
+In practice, communication is often redirected via third parties, so-called proxies. An example of such an implementation would be the bLink platform of SIX. A proxy supports all levels of the API and leaves the selection of the level to the communicating entities. The selection of the level determines the information content of the delivered data.
+In this scenario, it is also possible to communicate via different levels:
+
+* Data provider supports higher level
+ In this case, the proxy filters all undefined fields of the level and the TPP receives all data as defined in its level.
+* Data provider supports lower level
+ In this case, the proxy fills in the missing fields with dummy data. In this way, the TPP receives a data structure with the expected fields. Caution: This response still only contains the information content of the level supported by the data provider.
+
+
+
+
+# Appendix
+
+## Basic understanding of the card business
+This chapter contains a brief description of the most important roles for scheme-based payment cards. More detailed information can be found, for example, in the following source: [https://www.swiss-payment-association.ch/kreditkarten/kreditkartensystem](https://www.swiss-payment-association.ch/kreditkarten/kreditkartensystem)
+
+### Role model for issuing cards
+
+
+Depending on the provider, some roles might be covered by the same organization.
+
+### Cardholder
+* Uses the payment card as payment instrument.
+* Has a contractual relationship with the issuer.
+
+### Distribution Partner
+* Is selling cards legally offered by issuers to cardholders by using his own brand.
+* Does not directly own the data about payment cards and transactions. But access to these data can be possible based on the contractual setup between issuer and cardholder without an explicit consent of the cardholder.
+* Can take over some duties and obligations for the card issuing, depending on the contract with the card issuer.
+
+### Card Issuer
+* Bank or other organization which is legally issuing a payment card under a certain payment scheme (e.g. Mastercard, Visa, American Express, others) to cardholders.
+* Is responsible that payment cards and the issuer-side processing follow the rules of the payment scheme.
+* Manages the payment cards of cardholders, authorizes transactions, and guarantees towards the scheme and acquirer the payment of valid authorizations.
+* Is directly the owner of data about payment cards and transactions.
+* Card issuers in Switzerland are for example banks, Cembra, Swisscard, Viseca Card Services.
+
+### Card Service Provider
+* Is operating the card and transaction processing on behalf of the card issuer.
+* Has a contract with the card issuer.
+* Can cover many parts of scheme and legal regulations as service for the card issuer.
+* Card service providers in Switzerland are for example UBS Card Center, SIX, Viseca Payment Services.
+
+### Processor
+* Provides services for the card service provider related to the card management and transaction processing.
+* Has a contract with the card service provider.
+
+### Embosser
+* Is producing the physical card upon request of the card issuer.
+* Has a contract with the card issuer.
From 59e14814f9778e1751effdea5e72fad7ad22ec23 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Fri, 7 Jun 2024 09:31:04 +0200
Subject: [PATCH 26/29] add scope section
---
operationalGuide.md | 43 +++++++++++++++++++++++++++++++++++++------
1 file changed, 37 insertions(+), 6 deletions(-)
diff --git a/operationalGuide.md b/operationalGuide.md
index b68ed34..2b91da5 100644
--- a/operationalGuide.md
+++ b/operationalGuide.md
@@ -1,11 +1,42 @@
# Operational Guide
-- [Central Design Decisions](#central-design-decisions) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Central-Design-Decisions)
-- [Card API Level 1](#card-api-level-1) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-1)
-- [Card API Level 2](#card-api-level-2) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-2)
-- [Card API Level 3](#card-api-level-3) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-3)
-- [Use of this spec](#use-of-this-spec) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Use-of-this-spec)
-- [Appendix](#appendix) | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Appendix)
+- Scope of the Card API | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Scope-of-the-Card-API)
+- Central Design Decisions | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Central-Design-Decisions)
+- Card API Level 1 | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-1)
+- Card API Level 2 | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-2)
+- Card API Level 3 | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Card-API-Level-3)
+- Use of this spec | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Use-of-this-spec)
+- Appendix | [Card Wiki Page](https://github.com/swissfintechinnovations/ca-card/wiki/Appendix)
+
+# Scope of the Card API
+
+## Card types covered with the Card API
+In scope:
+* Debit
+* Credit
+* Prepaid
+
+Ouf of scope:
+* Deposit cards or non-Scheme-based cards (e.g.loyalty cards)
+
+The focus for creating the Card API specification was on the Mastercard and Visa schemes. However, the standard is open to other schemes as well and feedback that gives hints on necessary adaptations will be implemented.
+
+## Transaction types covered with the Card API
+* All transactions authorized or settled via a payment card (given that the card type is in scope of this API)
+* Card account-based transactions (e.g. fees, deposits, bill payments) are only available from Level 2 upwards.
+* Only financial transactions are covered (i.e., no PIN changes, balance inquiries, or status checks).
+
+Matching transactions retrieved via Card API with debit card transactions which are accessible on the bank account via the XS2A API is not actively supported.
+The Card API only provides card transactions and from Level 2 upwards on the card account as well. Please note that this card account is not equivalent to the bank account.
+
+## Provider and User of the API
+* Provider: All organizations which are able to implement API endpoints which meet the requirements of the Common API Card API specifications (e.g. provide mandatory fields) can act as provider. It is expected that most often Card Service Providers will act at least as technical providers of the Card API.
+* User: The Card API primarily targets Open Finance Use Cases described within each of the foreseen levels (i.e. level 1 to 3). The Card API is suitable for direct integration between Card Service Providers and third parties needing card data to enable new services or further develop existing use cases.
+
+Using the Card API for integrating Card Service Providers with distribution partners or issuers is not the main focus, as more detailed information and further enhanced use cases are usually required.
+
+The contractual and technical requirements for exchanging card data and the allowed uses can be freely agreed upon between Provider and User. The standard does not set any specific rule in this regard.
+
# Central Design Decisions
From 31f7bf6a21fe126bf0c3ed395b96b7655308db61 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 16 Sep 2024 13:04:44 +0200
Subject: [PATCH 27/29] implement feedback from PR review phase
---
cardInfoAPI-Level1.yaml | 185 ++++++++++++----------------------------
1 file changed, 55 insertions(+), 130 deletions(-)
diff --git a/cardInfoAPI-Level1.yaml b/cardInfoAPI-Level1.yaml
index 4806f80..b008386 100644
--- a/cardInfoAPI-Level1.yaml
+++ b/cardInfoAPI-Level1.yaml
@@ -1,6 +1,6 @@
openapi: 3.1.0
info:
- version: 0.7.0
+ version: 0.8.0
title: Common Card API (Public)
description: >
This specification defines a common card API for payment cards used in Switzerland.
@@ -41,38 +41,14 @@ paths:
tags:
- Cards
parameters:
- - in: query
- name: contract_reference
- required: false
- schema:
- $ref: '#/components/schemas/ContractReference'
- description: Retrieves all cards related to a contract. Value has to be a functional reference to the contract that can be known by the end customer.
- - in: query
- name: person_reference
- required: false
- schema:
- $ref: '#/components/schemas/PersonReference'
- description: Retrieves all cards related to an individual person/cardholder. Value has to be a functional reference to the person that can be known by the end customer.
- in: query
name: card_status
required: false
schema:
$ref: '#/components/schemas/CardStatus'
description: Retrieves all cards in a certain status. Only one status can be filtered at a time.
- - in: query
- name: card_account_reference
- required: false
- schema:
- $ref: '#/components/schemas/CardAccountReference'
- description: Retrieves all cards related to a card account (not bank account). Value has to be a functional reference to the account that can be known by the end customer.
- - in: query
- name: bank_account_reference
- required: false
- schema:
- $ref: '#/components/schemas/BankAccountReference'
- description: Retrieves all cards related to a bank account (not card account). Value has to be a functional reference to the account that can be known by the end customer and is usually an IBAN.
+ - $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/client_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
@@ -82,17 +58,19 @@ paths:
headers:
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
+ X-Next-Cursor:
+ $ref: '#/components/headers/X-Next-Cursor'
content:
application/json:
schema:
type: object
+ required:
+ - cards
properties:
- cardList:
+ cards:
type: array
items:
$ref: '#/components/schemas/CardDetails'
- _links:
- $ref: '#/components/schemas/LinksPagination'
'400':
$ref: '#/components/responses/standard400'
'500':
@@ -148,8 +126,8 @@ paths:
schema:
$ref: '#/components/schemas/TokenStatus'
description: Retrieves all tokens in a certain status. Only one status can be filtered at a time.
+ - $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/client_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
@@ -161,17 +139,19 @@ paths:
headers:
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
+ X-Next-Cursor:
+ $ref: '#/components/headers/X-Next-Cursor'
content:
application/json:
schema:
type: object
+ required:
+ - card_tokens
properties:
- cardList:
+ card_tokens:
type: array
items:
$ref: '#/components/schemas/CardTokenDetails'
- _links:
- $ref: '#/components/schemas/LinksPagination'
'400':
$ref: '#/components/responses/standard400'
'500':
@@ -266,8 +246,8 @@ paths:
schema:
$ref: '#/components/schemas/OriginalCurrency'
description: Retrieves all transactions in a certain currency. Filtering is applied on the original_currency attribute.
+ - $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/offset'
- $ref: '#/components/parameters/client_in_header'
- $ref: '#/components/parameters/correlation_in_header'
- $ref: '#/components/parameters/agent_in_header'
@@ -277,12 +257,19 @@ paths:
headers:
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
+ X-Next-Cursor:
+ $ref: '#/components/headers/X-Next-Cursor'
content:
application/json:
schema:
- type: array
- items:
- $ref: '#/components/schemas/TransactionDetails'
+ type: object
+ required:
+ - card-transactions
+ properties:
+ card-transactions:
+ type: array
+ items:
+ $ref: '#/components/schemas/TransactionDetails'
'400':
$ref: '#/components/responses/standard400'
'500':
@@ -1145,15 +1132,16 @@ components:
FeeAmount:
title: Fee amount
- type: number
+ type: string
+ pattern: '^[0-9]{1,12}([.][0-9]{1,5})?$'
examples:
- - 5.00
+ - '5.00'
description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
FeeCurrency:
title: Fee currency
type: string
- pattern: '^[a-zA-Z0-9]{3}$'
+ pattern: '^[A-Z]{3}$'
examples:
- CHF
description: Currency that is used for charging the fee, usually the same as the currency of the card account.
@@ -1179,86 +1167,33 @@ components:
- 2018-04-13T11:11:11Z
description: General date-time that is used for different attributes, format is 'YYYY-MM-DDThh:mm:ssZ'.
- LinksPagination:
- description: Links (or cursors) returned in the answer of an API call.
- type: object
- properties:
- self:
- type: string
- format: uri
- description: Link / cursor to the current result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=75&limit=25
- first:
- type: string
- format: uri
- description: Link / cursor to the first result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=0&limit=25
- previous:
- type: string
- format: uri
- description: Link / cursor to the previous result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=50&limit=25
- next:
- type: string
- format: uri
- description: Link / cursor to the next result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=100&limit=25
- last:
- type: string
- format: uri
- description: Link / cursor to the last result set (based on the submitted pagination approach).
- examples:
- - /card-app/api/v1/products?offset=150&limit=25
-
CommonErrorResponse:
title: Common Error Response
description: General error response structure used in different response codes.
type: object
properties:
type:
- $ref: '#/components/schemas/CommonErrorType'
+ type: string
+ description: |
+ A URI reference that identifies the problem type. When "about:blank" is used, the title SHOULD be the same as the recommended HTTP
+ status phrase for that code (e.g., "Not Found" for 404, and so on)
+ example: about:blank
title:
type: string
- description: Short name for the problem.
+ description: A short, human-readable summary of the problem type.
examples:
- This is the general problem description
detail:
type: string
- description: More details about the problem.
+ description: A human-readable explanation specific to this occurrence of the problem.
examples:
- Detailed problem description with respect to the current request
instance:
type: string
- description: Reference to an individual entity or request which caused the problem.
+ description: A (relative) URI reference that identifies the specific occurrence of the problem.
examples:
- path/to/corresponding/resource
- CommonErrorType:
- title: Common Error Type
- description: Error Types for CommonErrorResponse.
- type: string
- enum:
- - /problems/INVALID_PAYLOAD
- - /problems/MALFORMED_PAYLOAD
- - /problems/INVALID_TOKEN
- - /problems/EXPIRED_TOKEN
- - /problems/INSUFFICIENT_PRIVILEGES
- - /problems/NO_ACCESS_TO_RESOURCE
- - /problems/RESOURCE_DOES_NOT_EXIST
- - /problems/RESOURCE_NOT_READY
- - /problems/RESOURCE_TOO_LARGE
- - /problems/WRONG_METHOD
- - /problems/OPERATION_NOT_ALLOWED
- - /problems/TECHNICAL_ERROR
- - /problems/NOT_IMPLEMENTED
- - /problems/SERVICE_UNAVAILABLE
- examples:
- - /problems/TECHNICAL_ERROR
-
parameters:
path_cardId:
in: path
@@ -1284,34 +1219,30 @@ components:
$ref: '#/components/schemas/TransactionId'
description: Identifier (technical) for a transaction for which information is requested.
- limit:
+ cursor:
+ name: cursor
in: query
- name: limit
+ description: Optional parameter for pagination. An opaque string value used for pagination.
required: false
schema:
- type: integer
- format: int32
- minimum: 1
- examples:
- - 25
- description: Optional parameter for pagination. Maximum number of entries to be returned.
+ type: string
+ example: cursorIDxyz
- offset:
+ limit:
in: query
- name: offset
+ name: limit
required: false
schema:
type: integer
format: int32
- minimum: 0
- examples:
- - 25
- description: Optional parameter for pagination. The number of items to skip before starting to collect the result set.
+ minimum: 1
+ example: 25
+ description: Optional parameter for pagination. Maximum number of entries to be returned.
client_in_header:
in: header
name: X-CorAPI-Client-ID
- required: true
+ required: false
schema:
type: string
description: ID of the client forwarded to the provider.
@@ -1319,7 +1250,7 @@ components:
correlation_in_header:
in: header
name: X-Correlation-ID
- required: true
+ required: false
schema:
$ref: '#/components/schemas/Correlation'
description: Unique ID (defined by the caller) which will be reflected back in the response.
@@ -1327,7 +1258,7 @@ components:
agent_in_header:
in: header
name: User-Agent
- required: true
+ required: false
schema:
type: string
description: Name and version of the of the Client software.
@@ -1350,8 +1281,6 @@ components:
responses:
standard400:
headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
Content-Language:
$ref: '#/components/headers/Content-Language'
X-Correlation-ID:
@@ -1366,8 +1295,6 @@ components:
standard500:
headers:
- Content-Type:
- $ref: '#/components/headers/Content-Type'
Content-Language:
$ref: '#/components/headers/Content-Language'
X-Correlation-ID:
@@ -1388,15 +1315,13 @@ components:
- en
description: Language of provided content.
- Content-Type:
- schema:
- type: string
- examples:
- - application/json
- - application/problem+json; charset=utf-8 according to RFC7807
- description: Type of provided content.
-
X-Correlation-ID:
schema:
$ref: '#/components/schemas/Correlation'
description: Client defined ID from request to correlates HTTP requests between a client and server.
+
+ X-Next-Cursor:
+ description: An opaque string value, or an empty string if there are no more results.
+ schema:
+ type: string
+ example: cursorIDxyz
From a63718b1cb5e6fc514b24dab445018f11ec1e0c4 Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Mon, 16 Sep 2024 13:22:27 +0200
Subject: [PATCH 28/29] fix lint issues
---
cardInfoAPI-Level1.yaml | 114 ++++++++++++++++++++++++----------------
1 file changed, 70 insertions(+), 44 deletions(-)
diff --git a/cardInfoAPI-Level1.yaml b/cardInfoAPI-Level1.yaml
index b008386..4080bfa 100644
--- a/cardInfoAPI-Level1.yaml
+++ b/cardInfoAPI-Level1.yaml
@@ -35,9 +35,10 @@ paths:
get:
summary: Provides a list of cards which match the provided query parameters.
description: >
- This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards.
- In order to prevent API consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included.
- The API consumer is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account number).
+ This operation enables the retrieval of a list of payment cards. Payment cards can be physical or virtual cards. In order to prevent API
+ consumers from having to fulfill PCI DSS requirements, no full PAN or other data relevant for this regulation are included. The API consumer
+ is expected to have a non-card related identifier for the customer for whom data should be returned (e.g. card account number, bank account
+ number).
tags:
- Cards
parameters:
@@ -49,12 +50,14 @@ paths:
description: Retrieves all cards in a certain status. Only one status can be filtered at a time.
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
- description: Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing, an empty list is returned.
+ description: >
+ Payment cards were found which match the query parameters. If no cards matched the parameters or access rights are missing,
+ an empty list is returned.
headers:
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
@@ -86,9 +89,9 @@ paths:
- Cards
parameters:
- $ref: '#/components/parameters/path_cardId'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
description: Single payment card was found. If the cardId was not found, a 400 is returned.
@@ -119,7 +122,9 @@ paths:
required: false
schema:
$ref: '#/components/schemas/CardId'
- description: Retrieves all tokens related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ description: >
+ Retrieves all tokens related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards
+ endpoint.
- in: query
name: token_status
required: false
@@ -128,9 +133,9 @@ paths:
description: Retrieves all tokens in a certain status. Only one status can be filtered at a time.
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
description: >
@@ -167,9 +172,9 @@ paths:
- Card-tokens
parameters:
- $ref: '#/components/parameters/path_tokenId'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
description: Single token was found. If the tokenId was not found, a 400 is returned.
@@ -201,39 +206,48 @@ paths:
schema:
$ref: '#/components/schemas/AuthorizationReference'
description: >
- Retrieves the transaction related to an individual authorization. Parameter can be used to also retrieve the cleared transaction based on the authorization reference.
+ Retrieves the transaction related to an individual authorization. Parameter can be used to also retrieve the cleared transaction based
+ on the authorization reference.
- in: query
name: clearing_reference
required: false
schema:
$ref: '#/components/schemas/ClearingReference'
description: >
- Retrieves the transaction related to an individual clearing.
- Query parameter only returns results for cleared transactions (those booked on the card account for credit and prepaid or bank account for debit cards).
+ Retrieves the transaction related to an individual clearing. Query parameter only returns results for cleared transactions (those
+ booked on the card account for credit and prepaid or bank account for debit cards).
- in: query
name: card_id
required: false
schema:
$ref: '#/components/schemas/CardId'
- description: Retrieves all transactions related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET /cards endpoint.
+ description: >
+ Retrieves all transactions related to a card. Value has to be a technical identifier for the card that can be retrieved with the GET
+ /cards endpoint.
- in: query
name: token_id
required: false
schema:
$ref: '#/components/schemas/TokenId'
- description: Retrieves all transactions related to a token. Value has to be a technical identifier for the card that can be retrieved with the GET /card-tokens endpoint.
+ description: >
+ Retrieves all transactions related to a token. Value has to be a technical identifier for the card that can be retrieved with the GET
+ /card-tokens endpoint.
- in: query
name: from_date
required: false
schema:
$ref: '#/components/schemas/DateTime'
- description: Retrieves all transactions that took place after the provided date time. Filtering is applied on the transaction_date_time attribute.
+ description: >
+ Retrieves all transactions that took place after the provided date time. Filtering is applied on the transaction_date_time
+ attribute.
- in: query
name: to_date
required: false
schema:
$ref: '#/components/schemas/DateTime'
- description: Retrieves all transactions that took place before the provided date time. Filtering is applied on the transaction_date_time attribute.
+ description: >
+ Retrieves all transactions that took place before the provided date time. Filtering is applied on the transaction_date_time
+ attribute.
- in: query
name: status
required: false
@@ -248,12 +262,14 @@ paths:
description: Retrieves all transactions in a certain currency. Filtering is applied on the original_currency attribute.
- $ref: '#/components/parameters/cursor'
- $ref: '#/components/parameters/limit'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
- description: Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing, an empty list is returned.
+ description: >
+ Transactions were found which match the query parameters. If no transactions matched the parameters or access rights are missing,
+ an empty list is returned.
headers:
X-Correlation-ID:
$ref: '#/components/headers/X-Correlation-ID'
@@ -285,9 +301,9 @@ paths:
- Transactions
parameters:
- $ref: '#/components/parameters/path_transactionId'
- - $ref: '#/components/parameters/client_in_header'
- - $ref: '#/components/parameters/correlation_in_header'
- - $ref: '#/components/parameters/agent_in_header'
+ - $ref: '#/components/parameters/optional_client_in_header'
+ - $ref: '#/components/parameters/optional_correlation_in_header'
+ - $ref: '#/components/parameters/optional_agent_in_header'
responses:
'200':
description: Single token was found. If the transactionId was not found, a 400 is returned.
@@ -633,7 +649,9 @@ components:
- additional_card
examples:
- primary_card
- description: Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect of certain lifecycle use cases.
+ description: >
+ Identifies the nature of the card in regards to the overall account; for some issuers the cardCategory has an influence on the effect
+ of certain lifecycle use cases.
IssuingType:
title: Issuing type
@@ -708,7 +726,8 @@ components:
maxLength: 34
examples:
- CH3456789012345678901
- description: Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
+ description: >
+ Functional reference to the bank account linked to a card; mainly relevant for debit cards, can be empty for credit or prepaid cards.
IssuerCode:
title: Issuer code
@@ -826,7 +845,8 @@ components:
maxLength: 100
examples:
- IPHONE
- description: Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
+ description: >
+ Type of the device which is associated to the token, only available for device-based tokens; value defined by the Card Service Provider.
FundingCardId:
title: Funding card id
@@ -886,7 +906,8 @@ components:
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
description: >
- Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or ClearingReference is always present.
+ Unique identifier for authorized transactions; Id does not overlap with ClearingReference; at least one of AuthorizationReference or
+ ClearingReference is always present.
ClearingReference:
title: Clearing reference
@@ -895,7 +916,8 @@ components:
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
description: >
- Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or ClearingReference is always present.
+ Unique identifier for booked transactions; Id does not overlap with AuthorizationReference; at least one of AuthorizationReference or
+ ClearingReference is always present.
TransactionDateTime:
title: Transaction date-time
@@ -910,7 +932,8 @@ components:
StatementDate:
title: Statement date
$ref: '#/components/schemas/Date'
- description: Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
+ description: >
+ Date when the statement is created through which the issuer settles the transaction with the cardholder; only available for credit cards.
TransactionStatus:
title: Transaction status
@@ -976,7 +999,9 @@ components:
Fees:
title: Fees
- description: One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or fee_amount is provided.
+ description: >
+ One or more fees related to a transaction. Depending on the card service provider and the type of fee only the fee_percentage or
+ fee_amount is provided.
type: object
required:
- fee_name
@@ -1110,7 +1135,8 @@ components:
maxLength: 50
examples:
- 9e19df54-47cb-494b-84dc-1c126e95a05c
- description: Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
+ description: >
+ Reference to another transaction or authorization that is linked to the current one, e.g. for separately charged fees, chargeback credits.
FeeName:
title: Fee name
@@ -1220,13 +1246,13 @@ components:
description: Identifier (technical) for a transaction for which information is requested.
cursor:
- name: cursor
in: query
- description: Optional parameter for pagination. An opaque string value used for pagination.
+ name: cursor
required: false
schema:
type: string
example: cursorIDxyz
+ description: Optional parameter for pagination. An opaque string value used for pagination.
limit:
in: query
@@ -1239,7 +1265,7 @@ components:
example: 25
description: Optional parameter for pagination. Maximum number of entries to be returned.
- client_in_header:
+ optional_client_in_header:
in: header
name: X-CorAPI-Client-ID
required: false
@@ -1247,7 +1273,7 @@ components:
type: string
description: ID of the client forwarded to the provider.
- correlation_in_header:
+ optional_correlation_in_header:
in: header
name: X-Correlation-ID
required: false
@@ -1255,7 +1281,7 @@ components:
$ref: '#/components/schemas/Correlation'
description: Unique ID (defined by the caller) which will be reflected back in the response.
- agent_in_header:
+ optional_agent_in_header:
in: header
name: User-Agent
required: false
From a83bdc40178bbbcf8e005bdf17f49f95e9fdd7ec Mon Sep 17 00:00:00 2001
From: dkoeni <116151702+dkoeni@users.noreply.github.com>
Date: Fri, 27 Sep 2024 15:39:11 +0200
Subject: [PATCH 29/29] fix spec based on discussion
---
cardInfoAPI-Level1.yaml | 64 +++++++++++++++++++----------------------
1 file changed, 30 insertions(+), 34 deletions(-)
diff --git a/cardInfoAPI-Level1.yaml b/cardInfoAPI-Level1.yaml
index 4080bfa..233cf29 100644
--- a/cardInfoAPI-Level1.yaml
+++ b/cardInfoAPI-Level1.yaml
@@ -280,9 +280,9 @@ paths:
schema:
type: object
required:
- - card-transactions
+ - card_transactions
properties:
- card-transactions:
+ card_transactions:
type: array
items:
$ref: '#/components/schemas/TransactionDetails'
@@ -366,8 +366,8 @@ components:
$ref: '#/components/schemas/InitialIssuingDate'
card_status:
$ref: '#/components/schemas/CardStatus'
- currency:
- $ref: '#/components/schemas/Currency'
+ card_account_currency:
+ $ref: '#/components/schemas/CardAccountCurrency'
image:
$ref: '#/components/schemas/Image'
product_code:
@@ -599,12 +599,9 @@ components:
- suspended: authorizations are temporarily not possible
- blocked: authorizations are permanently not possible because the card was cancelled or permanently blocked for other reasons
- Currency:
+ CardAccountCurrency:
type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
- - EUR
+ $ref: '#/components/schemas/Amount'
description: Settlement currency of the card / card account in ISO code format.
Image:
@@ -960,41 +957,29 @@ components:
OriginalAmount:
title: Original amount
- type: number
- examples:
- - 2000.05
+ $ref: '#/components/schemas/Amount'
description: Amount of the transaction in the currency used by the merchant.
OriginalCurrency:
title: Original currency
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
+ $ref: '#/components/schemas/Amount'
description: Currency of the card account on which the transaction is charged.
TotalAmount:
title: Total amount
- type: number
- examples:
- - 1957.50
+ $ref: '#/components/schemas/Amount'
description: >
Total amount including fees for the transaction that is charged by the issuer to the card account (sum of transactionAmount and fees);
positive amounts are debit transactions, negative amounts are credit transactions.
TransactionAmount:
title: Transaction amount
- type: number
- examples:
- - 1952.50
+ $ref: '#/components/schemas/Amount'
description: Amount of the transaction (excluding fees) in the currency used by the issuer to settle the charge to the card account.
TransactionCurrency:
title: Transaction currency
- type: string
- pattern: '^[a-zA-Z0-9]{3}$'
- examples:
- - CHF
+ $ref: '#/components/schemas/Amount'
description: Currency of the card account on which the transaction is charged.
Fees:
@@ -1017,9 +1002,10 @@ components:
ExchangeRate:
title: Exchange rate
- type: number
+ type: string
+ pattern: '^[0-9]+[.][0-9]+$'
examples:
- - 1.0485930
+ - '1.0485930'
description: Exchange rate for converting the originalAmount into the transactionAmount.
ExchangeRateDate:
@@ -1149,28 +1135,38 @@ components:
FeePercentage:
title: Fee percentage
- type: number
+ type: string
+ pattern: '^(100([.][0]{1,2})?|[0-9]{1,2}([.][0-9]{1,2})?)$'
examples:
- - 3.5
+ - '3.5'
description: >
Percentage value of the transactionAmount for the fee type; not provided by all Card Service Providers.
Values are provided to be compatible with the % notation. For example a value 3.5 is to be interpreted as 3.5% (= 0.035 as decimal).
FeeAmount:
title: Fee amount
+ $ref: '#/components/schemas/Amount'
+ description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
+
+ FeeCurrency:
+ title: Fee currency
+ $ref: '#/components/schemas/Amount'
+ description: Currency that is used for charging the fee, usually the same as the currency of the card account.
+
+ Amount:
type: string
pattern: '^[0-9]{1,12}([.][0-9]{1,5})?$'
examples:
- '5.00'
- description: Amount of the fee that is charged for the transaction; not provided by all Card Service Providers.
+ description: Amount of money for fees and services.
- FeeCurrency:
- title: Fee currency
+ Currency:
type: string
pattern: '^[A-Z]{3}$'
examples:
- CHF
- description: Currency that is used for charging the fee, usually the same as the currency of the card account.
+ - EUR
+ description: Currency in ISO code format.
Correlation:
type: string