From edb45c740c19ebab6a933558a0a4769a6488748a Mon Sep 17 00:00:00 2001 From: dkoeni Date: Tue, 21 Mar 2023 10:41:11 +0100 Subject: [PATCH 1/3] refine response objects --- cardInfoAPI.yaml | 83 ++++++++++++++++++++++++++++-------------------- 1 file changed, 48 insertions(+), 35 deletions(-) diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml index 16363be..9492c3a 100644 --- a/cardInfoAPI.yaml +++ b/cardInfoAPI.yaml @@ -1,6 +1,6 @@ openapi: "3.0.3" info: - version: "0.5" + version: "0.45" 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). @@ -31,7 +31,7 @@ tags: - name: transactions description: Operations related with retrieving card transactions - name: person - description: Operations related with managing cardholders + description: Operations related with managing persons - name: card-contract description: Operations related with managing card contracts - name: card-accountbundle @@ -299,8 +299,8 @@ paths: get: tags: - person - description: List of cardholders for the authenticated context including all related information, filtered by query which also allows searching, sorted by personId. - summary: Return the list of all cardholders for the authenticated context (filtered and sorted) + 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' @@ -325,7 +325,7 @@ paths: $ref: '#/components/schemas/entityName' - in: query name: birthDate - description: Date of birth of the cardholder. + description: Date of birth of the person. required: false schema: $ref: '#/components/schemas/date' @@ -352,16 +352,16 @@ paths: - $ref: '#/components/parameters/agent_in_header' responses: '200': - description: Paginated list of all cardholder with all related information sorted by personId + description: Paginated list of all person with all related information sorted by personId content: application/json: schema: type: object properties: - cardholderList: + personList: type: array items: - $ref: '#/components/schemas/cardholder' + $ref: '#/components/schemas/person' _links: $ref: '#/components/schemas/linksPagination' headers: @@ -460,10 +460,10 @@ paths: schema: type: object properties: - cardContractList: + cardAccountbundleList: type: array items: - $ref: '#/components/schemas/cardContract' + $ref: '#/components/schemas/cardAccountbundle' _links: $ref: '#/components/schemas/linksPagination' headers: @@ -669,12 +669,12 @@ components: type: string maxLength: 30 example: FRANZ MUSTERMANN - description: Embossing Line 1 contains the cardholder name as visible on the card plastic + 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 cardholder-specified or product-specific value, as visible on the card plastic + 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: @@ -869,9 +869,9 @@ components: $ref: '#/components/schemas/cardTransactionType' personId: $ref: '#/components/schemas/entityId' - cardholderName: + personName: type: object - description: Name of the cardholder + description: Name of the person properties: company: $ref: '#/components/schemas/entityName' @@ -948,7 +948,7 @@ components: cardDataInputCapability: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength - cardholderAuthenticationCapability: + personAuthenticationCapability: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength cardCaptureCapability: @@ -957,7 +957,7 @@ components: operatingEnvironment: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength - cardholderPresent: + personPresent: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength cardPresent: @@ -966,10 +966,10 @@ components: cardDataInputMode: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength - cardholderAuthenticationMethod: + personAuthenticationMethod: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength - cardholderAuthenticationEntity: + personAuthenticationEntity: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength cardDataOutputCapability: @@ -982,9 +982,9 @@ components: type: string description: Please_Add_Description_and_Example_and_Regex-MaxLength - # ---- Cardholder ---- - cardholder: - description: Cardholder information . + # ---- Person ---- + person: + description: Person information . type: object required: - personId @@ -993,13 +993,13 @@ components: $ref: '#/components/schemas/entityId' contractId: $ref: '#/components/schemas/entityId' - cardholderType: + personType: $ref: '#/components/schemas/contractType' - isMainCardholder: + isMainPerson: type: boolean - description: Flag to identify if the cardholder is a main cardholder + description: Flag to identify if the person is a main person example: true - cardholderStatistics: + personStatistics: type: object properties: total_accounts: @@ -1017,11 +1017,11 @@ components: totalActiveCards: type: integer description: Total number of active cards of a private customer or a company - cardholderDetail: + personDetail: type: object properties: salutation: - $ref: '#/components/schemas/cardholderSalutation' + $ref: '#/components/schemas/personSalutation' company: $ref: '#/components/schemas/entityName' name: @@ -1059,12 +1059,12 @@ components: description: Flag to see if the customer give his/her permission to marketing advertisement phoneNumber: type: array - description: Phone numbers of the cardholder + description: Phone numbers of the person items: $ref: '#/components/schemas/personPhoneNumber' email: type: array - description: Email addresses of the cardholder + description: Email addresses of the person items: $ref: '#/components/schemas/personEmail' # --------- @@ -1108,6 +1108,19 @@ components: $ref: '#/components/schemas/genericStatus' # --------- + # TODO: define object + 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 @@ -1149,8 +1162,8 @@ components: - female - other example: female - description: Gender of the cardholder. - cardholderSalutation: + description: Gender of the person. + personSalutation: type: string enum: - none @@ -1163,7 +1176,7 @@ components: - female_nobility - neutral example: mrs - description: Salutation for the cardholder. + description: Salutation for the person. language: type: string example: fr @@ -1245,7 +1258,7 @@ components: paymentType: type: string example: lsv - description: Identifier of the payment method selected by the cardholder to settle the account. + description: Identifier of the payment method selected by the person to settle the account. enum: - lsv - debit_direct @@ -1255,7 +1268,7 @@ components: paymentOption: type: string example: full - description: Identifier of the payment plan selected by the cardholder to pay for a bill. + description: Identifier of the payment plan selected by the person to pay for a bill. enum: - full - instalment @@ -1294,7 +1307,7 @@ components: - unknown - active - blocked - - suspended_by_cardholder + - suspended_by_person - suspended_by_bank - suspended_by_issuer description: Status type From 2828aec5413bafe73d0b37c27aa58ee3427ba174 Mon Sep 17 00:00:00 2001 From: dkoeni Date: Tue, 21 Mar 2023 10:43:07 +0100 Subject: [PATCH 2/3] fix version --- cardInfoAPI.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml index 9492c3a..bc8c70d 100644 --- a/cardInfoAPI.yaml +++ b/cardInfoAPI.yaml @@ -1,6 +1,6 @@ openapi: "3.0.3" info: - version: "0.45" + version: "0.51" 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). From 33ecb6a7152223d06f744b9e14cce994137dd920 Mon Sep 17 00:00:00 2001 From: dkoeni Date: Mon, 27 Mar 2023 11:09:13 +0200 Subject: [PATCH 3/3] added card-tokens endpoint --- cardInfoAPI.yaml | 210 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 178 insertions(+), 32 deletions(-) diff --git a/cardInfoAPI.yaml b/cardInfoAPI.yaml index bc8c70d..8ffe49b 100644 --- a/cardInfoAPI.yaml +++ b/cardInfoAPI.yaml @@ -1,6 +1,6 @@ openapi: "3.0.3" info: - version: "0.51" + 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). @@ -30,11 +30,11 @@ tags: description: Operations related with retrieving card account statements - name: transactions description: Operations related with retrieving card transactions - - name: person + - name: persons description: Operations related with managing persons - - name: card-contract + - name: card-contracts description: Operations related with managing card contracts - - name: card-accountbundle + - name: card-accountbundles description: -- - name: card-consents description: '[not used] Operations related with managing card consents' @@ -91,6 +91,124 @@ paths: '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: @@ -295,10 +413,10 @@ paths: '503': $ref: '#/components/responses/standard503' - /person: + /persons: get: tags: - - person + - 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: @@ -386,10 +504,10 @@ paths: '503': $ref: '#/components/responses/standard503' - /card-contract: + /card-contracts: get: tags: - - card-contract + - 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: @@ -437,10 +555,10 @@ paths: '503': $ref: '#/components/responses/standard503' - /card-accountbundle: + /card-accountbundles: get: tags: - - card-accountbundle + - card-accountbundles description: -- summary: -- parameters: @@ -637,13 +755,13 @@ components: personId: $ref: '#/components/schemas/entityId' contractId: - $ref: '#/components/schemas/entityId' + $ref: '#/components/schemas/entityId' cardAccountId: - $ref: '#/components/schemas/entityId' + $ref: '#/components/schemas/entityId' issuingPartnerId: - $ref: '#/components/schemas/entityIdName' + $ref: '#/components/schemas/entityIdName' issuerId: - $ref: '#/components/schemas/entityIdName' + $ref: '#/components/schemas/entityIdName' cardDetail: type: object required: @@ -743,6 +861,19 @@ components: $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 @@ -751,22 +882,23 @@ components: - cardAccountStatementId properties: cardAccountStatementId: - $ref: '#/components/schemas/entityId' + $ref: '#/components/schemas/entityId' cardAccountId: - $ref: '#/components/schemas/entityId' + $ref: '#/components/schemas/entityId' statementCreationDate: - $ref: '#/components/schemas/date' + $ref: '#/components/schemas/date' statementAmount: - $ref: '#/components/schemas/paymentCurrencyAmount' + $ref: '#/components/schemas/paymentCurrencyAmount' paymentDueDate: - $ref: '#/components/schemas/date' + $ref: '#/components/schemas/date' statementMinimalDueAmount: - $ref: '#/components/schemas/paymentCurrencyAmount' + $ref: '#/components/schemas/paymentCurrencyAmount' paymentType: - $ref: '#/components/schemas/paymentType' + $ref: '#/components/schemas/paymentType' paymentOption: - $ref: '#/components/schemas/paymentOption' + $ref: '#/components/schemas/paymentOption' # --------- + # ---- Card Transaction ---- cardTransaction: description: Transaction object adapted for card use @@ -906,8 +1038,8 @@ components: 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 @@ -922,6 +1054,7 @@ components: currency: $ref: '#/components/schemas/currency' # --------- + # ---- Card Transaction Type ---- cardTransactionType: type: object @@ -1068,6 +1201,7 @@ components: items: $ref: '#/components/schemas/personEmail' # --------- + # ---- Card Contract ---- cardContract: description: Card Contract Information . @@ -1108,7 +1242,7 @@ components: $ref: '#/components/schemas/genericStatus' # --------- - # TODO: define object + # TODO: define object with properties cardAccountbundle: description: Card Accountbundle Information. type: object @@ -1534,17 +1668,27 @@ components: cardId: name: cardId in: query - required: false + 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: false + required: true schema: type: string format: uuid @@ -1555,7 +1699,7 @@ components: name: cardAccountId in: query description: Uuid v4 of a specific existing card account - required: false + required: true example: bcb5d762-8d28-43a2-9398-393b2e8d56ba schema: type: string @@ -1564,7 +1708,7 @@ components: card-accountbundleId: name: card-accountbundleId in: query - required: false + required: true schema: type: string format: uuid @@ -1573,7 +1717,7 @@ components: transactionId: name: transactionId in: query - required: false + required: true schema: type: string format: uuid @@ -1582,7 +1726,7 @@ components: statementId: name: statementId in: query - required: false + required: true schema: type: string format: uuid @@ -1592,7 +1736,7 @@ components: name: cardContractId in: query description: Uuid v4 of a specific existing card contract - required: false + required: true example: bcb5d762-8d28-43a2-9398-393b2e8d56ba schema: type: string @@ -1602,12 +1746,13 @@ components: name: limit in: query description: Optional parameter for pagination. Maximum number of entries to be returned. - required: false + required: true schema: type: integer format: int32 example: 25 minimum: 1 + cursor: name: cursor in: query @@ -1616,6 +1761,7 @@ components: schema: type: string example: cursorIDxyz + # ---- Responses - Standard Errors Common Data Model v1.2.2---- responses: standard400: