openapi: "3.0.0" info: version: 0.9.6 title: Common Payment API description: This specification defines a simple payment API for payment types used in Switzerland. The API is supposed to be used by customers who want to initiate a payment at their bank. Note that, consents and SCA will be handled in a dedicated specification file. This specification uses schema definitions from the Common Data Model v1.2.1. 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: payment.common-api.ch externalDocs: description: Find out more about SFTI API specifications url: 'https://www.common-api.ch' security: - OAuth2: - read - write paths: /payments: post: tags: - Payments submissions summary: Initiate new payments submission description: Create new payments submission operationId: submitPaymentsSubmissionUsingPOST requestBody: description: Details of payments submission to be added required: true content: application/json: schema: $ref: '#/components/schemas/paymentSubmissionRequest' responses: '201': description: created headers: location: schema: type: string format: uri description: Link to the created resource /payments/{submissionId}: get: tags: - Payments submissions description: Retrieve a specific payment submission summary: Get a specific payment submission parameters: - name: submissionId in: path description: ID of payment submission to be retrieved required: true schema: type: integer format: int64 responses: '200': description: The original payment submission content: application/json: schema: $ref: '#/components/schemas/paymentSubmissionRequest' /payments/{submissionId}/status: get: tags: - Payments submissions description: Retrieve a specific payment submission's status summary: Get status information for the specific payment submission parameters: - name: submissionId in: path description: ID of chosen payment submission required: true schema: type: integer format: int64 responses: '200': description: Status information for the specific payment submission content: application/json: schema: $ref: '#/components/schemas/paymentSubmissionStatus' /iso20022/payments: post: tags: - iso20022 summary: Submit ISO20022 XML payment instruction (PAIN.001) description: Submit an XML PAIN.001 payment instruction according to the ISO20022 specification. requestBody: description: The XML PAIN.001 required: true content: application/xml: schema: type: string responses: '201': description: created headers: location: schema: type: string format: uri description: link to the created resource '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' /iso20022/payments/{submissionId}: get: tags: - iso20022 summary: Retrieve a submitted ISO20022 XML PAIN.001 message. parameters: - in: path name: submissionId schema: type: string required: true description: Unique ID of the ISO20022 payment instruction responses: '200': description: Returns the requested ISO20022 XML PAIN.001 message content: application/xml: schema: type: string '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' /iso20022/payments/{submissionId}/status: get: tags: - iso20022 summary: Get the ISO20022 XML status report (PAIN.002) for a specific payment instruction description: The status report for the requested XML ISO20022 payment instruction (PAIN.002) parameters: - in: path name: submissionId schema: type: string required: true description: Unique ID of the ISO20022 payment instruction responses: '200': description: Returns the requested ISO20022 XML PAIN.002 message content: application/xml: schema: type: string '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' /iso20022/statements: get: tags: - iso20022 summary: Get list of resource links to account statements (CAMT.053) description: The resources links to available account statements (CAMT.053) responses: '200': description: Returns a list of resource links to ISO20022 XML CAMT.053 messages content: application/json: schema: type: object properties: conditionList: type: array items: $ref: '#/components/schemas/iso20022ReportReference' '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' /iso20022/statements/{reportId}: get: tags: - iso20022 summary: Retrieves a specifically requested ISO20022 XML CAMT.053 document parameters: - in: path name: reportId schema: type: string required: true description: Unique ID of the requested ISO20022 XML CAMT.053 document responses: '200': description: Returns the requested ISO20022 XML CAMT.053 message content: application/xml: schema: type: string '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: 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: # ---- From SIX ---- paymentSubmissionRequest: title: Payment Submission Request type: object required: - messageId - initiatingPartyId - debtorAccount - bookingInstruction - transactions - requestedExecutionDate properties: messageId: type: string maxLength: 35 example: "eb6305c91f7f49deaed016487c27b42d" initiatingPartyId: type: string maxLength: 32 example: "TPP01746" requestedExecutionDate: type: string format: date example: "2018-04-07" debtorAccount: $ref: '#/components/schemas/paymentIbanAccount' bookingInstruction: $ref: '#/components/schemas/paymentBookingInstruction' transactions: type: array items: $ref: '#/components/schemas/paymentInstructionItem' paymentIbanAccount: title: Payment IBAN Account type: object required: - type - identification properties: type: type: string description: The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN. enum: - "IBAN" identification: type: string maxLength: 34 example: "CH9300762011623852957" pattern: "[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}" paymentQrIbanAccount: title: Payment QR-IBAN Account type: object required: - type - identification properties: type: type: string description: IBAN or QR-IBAN of the creditor, only IBANs with CH or LI country code permitted. 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}" paymentOtherAccount: title: Payment Other Account type: object required: - type - identification properties: "type": type: string description: The allowed account identification type for the creditor account depends on the payment type. The debtor account must always be an IBAN. enum: - "OTHER" identification: type: string maxLength: 34 example: "01-39139-1" paymentBookingInstruction: title: Payment Booking Instruction type: string enum: - "SINGLEBOOKING_SIA" - "SINGLEBOOKING_NOA" - "BATCHBOOKING_SALA_NOA" - "BATCHBOOKING_SALA_CND" - "BATCHBOOKING_NOA" - "BATCHBOOKING_CND" - "BATCHBOOKING_CWD" example: "BATCHBOOKING_SALA_CND" paymentInstructionItem: title: Payment Instruction Item type: object required: - instructionId - endToEndId - instructedAmount properties: instructionId: type: string maxLength: 35 example: "INSTR-001" endToEndId: type: string maxLength: 35 example: "ENDTOENDID-001" instructedAmount: $ref: '#/components/schemas/paymentCurrencyAmount' ibanDetails: $ref: '#/components/schemas/paymentIBANDetail' isrDetails: $ref: '#/components/schemas/paymentISRDetail' otherDetails: $ref: '#/components/schemas/paymentOtherDetail' qrDetails: $ref: '#/components/schemas/paymentQRDetail' paymentCurrencyAmount: title: Payment Currency-Amount type: object required: - currency - amount properties: currency: type: string maxLength: 3 minLength: 3 example: "CHF" amount: type: string pattern: "[0-9]{1,12}([.][0-9]{1,5})?" maxLength: 18 example: "10.25" paymentIBANDetail: title: Payment IBAN Detail type: object required: - creditorAccount - creditor properties: sepaIndicator: type: boolean example: true creditorAccount: $ref: '#/components/schemas/paymentIbanAccount' creditorAgent: $ref: '#/components/schemas/paymentCreditorAgent' creditor: $ref: '#/components/schemas/paymentCreditor' chargeBearer: $ref: '#/components/schemas/paymentChargeBearerMethod' remittanceReference: $ref: '#/components/schemas/paymentIbanRemittanceReference' remittanceInformation: $ref: '#/components/schemas/paymentRemittanceInformation' paymentISRDetail: title: Payment ISR Detail type: object required: - remittanceReference properties: creditorAccount: $ref: '#/components/schemas/paymentOtherAccount' creditor: $ref: '#/components/schemas/paymentCreditor' remittanceReference: $ref: '#/components/schemas/paymentIsrRemittanceReference' paymentOtherDetail: title: Payment Other Detail type: object required: - creditorAccount - creditorAgent - creditor properties: creditorAccount: $ref: '#/components/schemas/paymentOtherAccount' creditorAgent: $ref: '#/components/schemas/paymentCreditorAgent' creditor: $ref: '#/components/schemas/paymentCreditor' chargeBearer: $ref: '#/components/schemas/paymentChargeBearerMethod' remittanceReference: $ref: '#/components/schemas/paymentOtherRemittanceReference' paymentQRDetail: title: Payment QR Detail type: object required: - creditor - creditorAccount properties: creditorAccount: $ref: '#/components/schemas/paymentQrIbanAccount' creditor: $ref: '#/components/schemas/paymentCreditor' ultimateCreditor: $ref: '#/components/schemas/paymentCreditor' ultimateDebtor: $ref: '#/components/schemas/paymentDebtor' remittanceReference: $ref: '#/components/schemas/paymentIbanRemittanceReference' remittanceInformation: $ref: '#/components/schemas/paymentRemittanceInformation' paymentCreditorAgent: type: object properties: bic: type: string maxLength: 11 example: "BDEMMXMM" clearingSystemMemberIdentification: $ref: '#/components/schemas/commonClearingSystemMemberIdentification' commonClearingSystemMemberIdentification: title: Common Clearing System Member Identification type: object required: - code - memberId properties: code: type: string maxLength: 5 example: "CHBCC" memberId: type: string maxLength: 35 example: "00230" paymentCreditor: title: Payment Creditor type: object required: - name - postalAddress properties: name: type: string maxLength: 140 postalAddress: $ref: '#/components/schemas/paymentStructuredOrUnstructuredAddress' paymentDebtor: title: Payment Debtor type: object required: - name - postalAddress properties: name: type: string postalAddress: $ref: '#/components/schemas/paymentStructuredOrUnstructuredAddress' paymentChargeBearerMethod: title: Payment Charge Bearer Method type: string enum: - "DEBT" - "CRED" - "SHAR" - "SLEV" example: "SHAR" paymentIbanRemittanceReference: title: Payment Remittance Reference description: either remittanceReference or remittanceInformation must be set type: object properties: type: type: string enum: - SCOR - QRR reference: type: string maxLength: 35 example: "210000000003139471430009017" paymentIsrRemittanceReference: title: Payment Remittance Reference description: either remittanceReference or remittanceInformation must be set type: object properties: type: type: string enum: - ISR reference: type: string maxLength: 35 example: "210000000003139471430009017" paymentOtherRemittanceReference: title: Payment Remittance Reference description: either remittanceReference or remittanceInformation must be set type: object properties: type: type: string enum: - SCOR reference: type: string maxLength: 35 example: "210000000003139471430009017" paymentRemittanceInformation: title: Payment Remittance Information description: either remittanceReference or remittanceInformation must be set type: string maxLength: 140 example: "Rechnung Nr. 408" paymentStructuredAddress: title: Structured Address for Payments 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" paymentUnstructuredAddress: title: Unstructured Address for Payments type: object required: - addressLines - country properties: addressLines: type: array description: max 2 lines of 70 characters maxLength: 2 example: ["Robert Schneider SA", "Rue de la gare 24"] items: type: string maxLength: 70 country: type: string maxLength: 2 example: "CH" paymentStructuredOrUnstructuredAddress: title: Payment Structured or Unstructured Address description: Either structured or unstructered must be set type: object properties: structured: $ref: '#/components/schemas/paymentStructuredAddress' unstructured: $ref: '#/components/schemas/paymentUnstructuredAddress' paymentSubmissionStatus: title: Payment Submission Status type: object required: - statusCode properties: messageId: type: string example: "eb6305c91f7f49deaed016487c27b42d" statusCode: type: string enum: - ACCP - RJCT - PART example: "PART" transactions: type: array items: $ref: '#/components/schemas/paymentInstructionItemStatus' paymentInstructionItemStatus: title: Payment Instruction Item Status type: object required: - instructionId - statusCode properties: instructionId: type: string maxLength: 35 example: "DNCS-20180322-IXN0-TXN0" statusCode: type: string enum: - ACCP - RJCT example: "RJCT" reasonCode: type: string example: "CURR" reasonInformation: type: string maxLength: 105 example: "currency USD not allowed for payment type ISR" iso20022ReportReference: title: ISO 20022 Report Reference type: object properties: name: type: string description: type: string type: type: string enum: - CAMT53 id: type: string # --- End SIX ----- # ---- 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 ---- Links: description: links returned in the answer of an API call type: object properties: self: type: string first: type: string previous: type: string next: type: string last: type: string # --------- # ---- Currency ---- Currency: description: ISO 4217 code type: string pattern: '[A-Z]{3}' # --------- # ---- Amount ---- Amount: description: amount with currency type: object required: - currency - content properties: currency: $ref: '#/components/schemas/Currency' content: description: amount given with fractional digits, the separator is a dot type: string pattern: '-?\d{1,14}(?:\.\d{1,3})?' # -------- # ---- 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 # ---- Responses - Standard Errors Common Data Model v1.2.1---- responses: standard400: headers: Content-Type: schema: type: string description: 'application/problem+json; charset=utf-8 according to RFC7807' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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' Content-Language: schema: type: string description: 'Response language - always en' X-Correlation-ID: schema: type: string description: Client defined ID from request to correlates HTTP requests between a client and server. 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