Conversation
87466e5 to
f644c76
Compare
2ee48c8 to
a7645eb
Compare
Added latest version of Wiki pages as per 30th June 2026 for review of level 2
There was a problem hiding this comment.
Dear Reviewer
thank you for your valuable feedback. Please provide your feedback on the corresponding line in this file and include your feedback in the follow structure:
- Title:
- Question/Feedback:
- Suggestion for improvement:
Please start with describing your feedback or asking your question regarding a specific component in the spec. For overall questions or remarks please use the comment function for the whole file. Make sure your feedback is not collected already, if so, please like the feedback or add further issues or clarifications as reply to the comment.
It might be very helpful if you suggest improvements for the core team to elaborate your feedback. Thus we ask you to share all your relevant thoughts on this topic and feel free to share any solutions to your issue. This will improve further discussion and allow people to refactor your suggestions. The core team will come back to your feedback as needed.
| $ref: '#/components/schemas/MerchantCountry' | ||
| merchant_name: | ||
| $ref: '#/components/schemas/MerchantName' | ||
| person_id: |
There was a problem hiding this comment.
Title: Link person to Transaction
Question/Feedback: With the Card Api Level 2 a new entity, person has been introduced. personId /person_reference have been added to the transaction. This could create ambiguity about the source of truth for the person information and the relationship between personId, cardId, and the transaction. In the domain model the transaction is linked to a card and the card is owned by a person (cardholder)
Suggestion for improvement: Clarify whether it is a justified need to store personId directly on the transaction. If personId is required, suggest to document the rules for consistency (e.g., personId must match the owner of the referenced card).
| description: | | ||
| Technical reference to a person/cardholder, used as unique identifier for API calls to retrieve person details. | ||
| type: string | ||
| format: uuid |
There was a problem hiding this comment.
Title: Reconsider strict UUID requirement for IDs
Question/Feedback: Nearly all IDs in the spec are defined as UUIDs. For payment integrations, this can be challenging because some underlying payment systems use different identifier formats (e.g., numeric or proprietary IDs), which may require additional mapping, transformation, or storage logic on the integrating systems.
Suggestion for improvement: Please clarify whether UUIDs are strictly required at the API boundary or if alternative ID formats are allowed with clear constraints (e.g. leght restriction / alphanumeric only). If UUIDs must be used, consider stating how systems that do not natively support UUIDs should handle this requirement.
| in: query | ||
| name: external_reference | ||
| description: | | ||
| Filters resources to return only those related tothe specified external reference. |
There was a problem hiding this comment.
Title: Fix typo external_reference description
Question/Feedback: "tothe" is a typo.
Suggestion for improvement: introduce blank space
[Feedback captured on behalf of core working group]
There was a problem hiding this comment.
Feedback implemented as suggested after discussion in the core working group.
| maximum: 31 | ||
| examples: | ||
| - 15 | ||
| BillingCycleRhythm: |
There was a problem hiding this comment.
Title: BillingCycleRhythm obsolete
Question/Feedback: Attribute can be obsolete when the enum contains always the same value.
Suggestion for improvement: Delete attribute and enhance description of BillingCycleDay that it is always monthly rhythm.
[Feedback captured on behalf of core working group]
There was a problem hiding this comment.
Feedback implemented as suggested after discussion in the core working group.
| operationId: listCardTransactions | ||
| tags: | ||
| - Transactions | ||
| parameters: |
There was a problem hiding this comment.
Title: Amount filter
Question/Feedback: It would be helpful to filter also based on the transaction amounts to narrow down the search if a user doesn't remember when he did a certain transaction or when he wants to identify all high-value transactions.
Suggestion for improvement: Add filters for amounts.
[Feedback captured on behalf of a non-registered reviewer]
There was a problem hiding this comment.
Discussed in the core working group and agreed that filters for original_amount and total_amount will be added.
This change adds transaction query filters for original and total amount ranges and corrects the external reference description wording. It also updates billing cycle documentation to clarify that only monthly billing cycles are currently supported and removes the deprecated billing_cycle_rhythm field from CardAccountDetails.
Removes a trailing space in the billing cycle day description and keeps the multi-line wording formatting consistent.
4 participants
Goal
In this Pull Request all feedback to the proposed Level 2 of the SFTI Common API Card API is collected. When all feedback is incorporated, a version 2.0 of the standard will be published.
Note that the pull request contains also changes to the Level 1 schemas and endpoints defined in version 1.0 of the standard.
Instructions
There are three files that you can review (links lead to the Diff View):
Contains the full specification of the Level 1 Card API.
The Diff for the Level 1 file, will show the comparison of the released version 1 and the newly proposed version 2 of the Level 1.
Contains the full specification of the Level 2 Card API.
The Diff for the Level 2 file, will show the comparison between the newly proposed version 2 of the Level 1 and the Level 2. We find this the more useful comparison than the Level 2 file itself because it is completely new.
Contains a snapshot of the Wiki pages that already reflects the Level 2 design proposed with the pull request.
The Diff shows the comparison to the Wiki pages of the released version 1.
For easier readability of the yaml files, you can follow the link to the Swagger Editor or open the files with the OpenAPI viewer of your choice.
To make your comment as valuable as possible, please follow the structure of the sample comment on the file cardInfoAPI-level1.yaml.
Note that you can also vote and react to existing comments. Please use this functionality to make it easier for the core team to consolidate the feedback.
For users new to GitHub, please follow the general GitHub instructions here: GitHub Docs - Review proposed changes
You might also be interested in the GitHub Docs section about Comment on a PR or View a PR review.
Every user with a GitHub login can comment, no special access rights are needed.
Timeline
The review is open until 21st August. The Card API core team will review the received feedback afterwards and seek alignment with individual reviewers where needed.