--- swagger: "2.0" info: x-ibm-name: psd2-pis-api title: PIS API version: 1.0.0 contact: name: Postbank email: api@postbank.bg url: https://www.postbank.bg description: Payment Initiation Service Provider API schemes: - https consumes: - application/json produces: - application/json securityDefinitions: OAuth2: type: oauth2 description: "" flow: accessCode scopes: pis: "" authorizationUrl: https://gate.postbank.bg/postbank/psd2/oauth2/authorize tokenUrl: https://gate.postbank.bg/postbank/psd2/oauth2/token x-tokenIntrospect: url: "" clientIdHeader: type: apiKey in: header name: X-IBM-Client-Id security: - clientIdHeader: [] OAuth2: - pis x-ibm-configuration: testable: true enforced: true phase: realized paths: /payments/{payment-product}: post: tags: - payments summary: "This method to initiate a payment initiation at the Postbank can be sent with a JSON body depending on the payment product in the path. There are the following payment products: \n* bgn-credit-transfers-credit payment (local in BGN) \n* bgn-budget-transfers-payment to the BG budget \n* sepa-credit-transfers \n* cross-border-transfers\n\nExample request body definitions: \n* pisRequestBodyBGNCreditTransfer \n* pisRequestBodyBGNBudgetTransfer \n* pisRequestBodySEPACreditTransfer \n* pisRequestBodyCrossBorderTransfer\n\nIn the test tool is used only general request body with all parameters `paymentInitiationServiceRequestBody`\n" description: Creates a payment initiation resource addressable under {paymentId} with all data relevant for the corresponding payment product. This is the first step in the API to initiate the related payment operationId: Creates a payment initiation request at the ASPSP consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/payment-product' - name: Content-Type in: header type: string description: Content type is JSON enum: - application/json required: true - name: X-Request-ID in: header type: string description: ID of the request, unique to the call, as determined by the initiating party. required: true - name: PSU-IP-Address type: string pattern: ^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ required: true in: header description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. - name: TPP-Redirect-URI in: header type: string description: URI of the TPP, where the transaction flow shall be redirected to after a Redirect required: true - name: PSU-User-Agent in: header type: string description: The forwarded Agent header field of the http request between PSU and TPP, if available. required: false - name: PSU-IP-Port in: header type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available. required: false - name: PSU-Geo-Location in: header type: string description: The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available. required: false - name: PSU-Accept type: string required: false in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. - name: PSU-Accept-Charset type: string required: false in: header - name: PSU-Accept-Encoding type: string required: false in: header - name: PSU-Accept-Language type: string required: false in: header - name: PSU-Http-Method type: string enum: - GET - POST - PUT - PATCH - DELETE required: false in: header description: | HTTP method used at the PSU – TPP interface, if available. Valid values are\: * GET * POST * PUT * PATCH * DELETE - name: PSU-Device-ID type: string required: false in: header description: UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. - name: PISBody required: true in: body schema: $ref: '#/definitions/paymentInitiationServiceRequestBody' responses: 201: description: Created schema: type: object required: - transactionStatus - paymentId - _links properties: transactionStatus: $ref: '#/definitions/TransactionStatus' paymentId: type: string description: resource identification of the generated payment initiation resource. transactionFees: $ref: '#/definitions/Amount' description: Can be used by the Postbank to transport transaction fees relevant for the underlying payments. transactionFeeIndicator: type: boolean description: If equals “true”, the transaction will involve specific transaction cost as shown by the Postbank in their public price list or as agreed between Postbank and PSU. If equals “false”, the transaction will not involve additional specific transaction costs to the PSU. _links: $ref: '#/definitions/Links' psuMessage: type: string description: Text to be displayed to the PSU X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. tppMessages: type: array items: type: string description: Messages to the TPP example: transactionStatus: RCVD paymentId: 135797531 _links: scaRedirect: href: https://www.postbank.bg/authentication/135797531 self: href: /v1/payments/bgn-credit-transfers/135797531 headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. Location: type: string description: Location of the created resource (if created). ASPSP-SCA-Approach: type: string description: Possible values is REDIRECT. 400: description: Bad Request schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 401: description: Unauthorized schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 403: description: Forbidden schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 500: description: Internal Server Error schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. /payments/{payment-product}/{paymentId}: get: tags: - payment summary: Returns the content of a payment object parameters: - $ref: '#/parameters/payment-product' - $ref: '#/parameters/paymentId' - name: X-Request-ID type: string required: true in: header description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address type: string pattern: ^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ required: false in: header description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. - name: PSU-User-Agent in: header type: string description: The forwarded Agent header field of the http request between PSU and TPP, if available. required: false - name: PSU-IP-Port in: header type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available. required: false - name: PSU-Geo-Location in: header type: string description: The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available. required: false - name: PSU-Accept type: string required: false in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. - name: PSU-Accept-Charset type: string required: false in: header - name: PSU-Accept-Encoding type: string required: false in: header - name: PSU-Accept-Language type: string required: false in: header - name: PSU-Http-Method type: string enum: - GET - POST - PUT - PATCH - DELETE required: false in: header description: | HTTP method used at the PSU – TPP interface, if available. Valid values are\: * GET * POST * PUT * PATCH * DELETE - name: PSU-Device-ID type: string required: false in: header description: UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. operationId: getPaymentByPaymentId consumes: - application/json produces: - application/json responses: 200: description: OK /payments/{payment-product}/{paymentId}/status: get: tags: - payments summary: Payment initiation status request description: Reads the transaction status of the payment operationId: getPaymentStatusByPaymentId consumes: - application/json produces: - application/json parameters: - $ref: '#/parameters/payment-product' - $ref: '#/parameters/paymentId' - name: X-Request-ID in: header type: string required: true description: ID of the request, unique to the call, as determined by the initiating party. - name: PSU-IP-Address type: string pattern: ^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ required: false in: header description: The forwarded IP Address header field consists of the corresponding HTTP request IP Address field between PSU and TPP. - name: PSU-User-Agent in: header type: string description: The forwarded Agent header field of the http request between PSU and TPP, if available. required: false - name: PSU-IP-Port in: header type: string description: The forwarded IP Address header field consists of the corresponding http request IP Address field between PSU and TPP, if available. required: false - name: PSU-Geo-Location in: header type: string description: The forwarded Geo Location header field of the corresponding http request between PSU and TPP if available. required: false - name: PSU-Accept type: string required: false in: header description: The forwarded IP Accept header fields consist of the corresponding HTTP request Accept header fields between PSU and TPP, if available. - name: PSU-Accept-Charset type: string required: false in: header - name: PSU-Accept-Encoding type: string required: false in: header - name: PSU-Accept-Language type: string required: false in: header - name: PSU-Http-Method type: string enum: - GET - POST - PUT - PATCH - DELETE required: false in: header description: | HTTP method used at the PSU – TPP interface, if available. Valid values are\: * GET * POST * PUT * PATCH * DELETE - name: PSU-Device-ID type: string required: false in: header description: UUID (Universally Unique Identifier) for a device, which is used by the PSU, if available. responses: 200: description: OK schema: type: object properties: transactionStatus: $ref: '#/definitions/TransactionStatus' example: transactionStatus: RCVD headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 400: description: Bad Request schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 401: description: Unauthorized schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 403: description: Forbidden schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. 500: description: Internal Server Error schema: $ref: '#/definitions/ErrorModel' headers: X-Request-ID: type: string description: ID of the request, unique to the call, as determined by the initiating party. parameters: payment-product: name: payment-product in: path description: | The choosen payment product in initiating payment call\: * bgn-credit-transfers * bgn-budget-transfers * sepa-credit-transfers * cross-border-transfers required: true type: string enum: - bgn-credit-transfers - bgn-budget-transfers - sepa-credit-transfers - cross-border-transfers paymentId: name: paymentId in: path description: Resource identification of the generated payment initiation resource. required: true type: string definitions: Amount: type: object required: - currency - amount properties: currency: type: string description: ISO 4217 Alpha 3 currency code pattern: '[A-Z]{3}' default: BGN amount: type: string default: "88.55" Address: type: object required: - country properties: street: type: string maxLength: 70 buildingNumber: type: string city: type: string postalCode: type: string country: type: string description: ISO 3166 ALPHA2 country code example: SE pattern: '[A-Z]{2}' PaymentType: type: object properties: serviceLevel: $ref: '#/definitions/ServiceLevelCode' ServiceLevelCode: type: string description: |- - SEPA - Used for SEPA payment - URGP - Used for payments through RTGS System - SDVA - Used for Cross border CT. Payment must be executed with same day value to the creditor - NEXT - Used for Cross border CT. Payment must be executed with next working day value to the creditor - SPOT - Used for Cross border CT. Payment must be executed with spot working day value to the creditor example: SEPA enum: - SEPA - URGP - SDVA - NEXT - SPOT PurposeCode: type: string enum: - GOVT description: GOVT - Constant marked budget payment ChargeBearerCode: type: string description: |- - DEBT – Borne By Debtor - CRED – Borne By Creditor - SHAR – Shared in Credit Transfer context - SLEV – Usefully in SEPA payments example: DEBT enum: - DEBT - CRED - SHAR - SLEV BudgetPaymentDetails: type: object required: - regulatoryReportType properties: regulatoryReportType: description: Regulatory Report Type – 1 digit code $ref: '#/definitions/RegulatoryReportType' documentNumber: description: Document Number issued by Government authority type: string documentDate: description: Document Date issued by Government authority type: string format: ISODate pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) example: "2018-03-17" taxId: type: string pattern: ^[0-9]{1,10}$ maxLength: 10 taxTp: description: Tax Type – 3 CAP letters code $ref: '#/definitions/TaxTypeCode' paymentCategory: description: Payment Category – 6 digit code $ref: '#/definitions/PaymentCategoryCode' fromDate: description: From Date – start of period date type: string format: ISODate pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) example: "2019-02-10" endDate: description: End Date – end of period date type: string format: ISODate pattern: ([12]\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])) example: "2019-08-10" RegulatoryReportType: type: integer description: |- - 1 – Declaration - 2 – Inspection ACt - 3 – Penalty Decree - 4 – advance payment - 5 – batch property number - 6 – enforces collection order - 9 – others enum: - 1 - 2 - 3 - 4 - 5 - 6 - 9 TaxTypeCode: type: string description: |- - EGN – Personal ID - EIK – Corporate ID - PNF – Foreign Person ID enum: - EGN - EIK - PNF maxLength: 3 PaymentCategoryCode: type: string description: |- - 110000 - НАП (NRA) - 551111 - НОИ (NSSI) - 561111 - НЗОК (NHIF) - 581111 - ДЗПО (SCPI) enum: - 110000 - 551111 - 561111 - 581111 maxLength: 6 Links: type: object properties: scaRedirect: type: string description: A link to a Postbank site where SCA is performed within the Redirect SCA approach. self: type: string description: The link to the payment initiation resource created by the request itself. This link can be used later to retrieve the transaction status of the payment initiation. status: type: string description: The link to retrieve the transaction status of the payment initiation. TransactionStatus: type: string description: The transaction status is filled with codes of the ISO 20022 data table. enum: - ACSC - ACSP - ACTC - RCVD - RJCT ErrorModel: type: object properties: tppMessages: type: array items: type: object properties: category: type: string code: type: string text: type: string paymentInitiationServiceRequestBody: type: object required: - instructedAmount - debtorAccount - creditorName - creditorAccount properties: endToEndIdentification: type: string maxLength: 35 debtorAccount: $ref: '#/definitions/AccountReference' ultimateDebtor: type: string maxLength: 70 description: 'Mandatory for: bgn-budget-transfers. N.A. for: bgn-credit-transfers, sepa-credit-transfers, cross-border-transfers.' instructedAmount: $ref: '#/definitions/Amount' creditorAccount: $ref: '#/definitions/AccountReference' creditorAgent: type: string default: AAAADEBBXXX pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' creditorAgentName: type: string description: 'Mandatory for creditorAccount when payment is cross-border-transfers - If no IBAN used for creditorAccount. N.A. for: bgn-credit-transfers, bgn-budget-transfers, sepa-credit-transfers.' maxLength: 70 creditorAgentAddress: description: 'Mandatory for creditorAccount when payment is cross-border-transfers - If no IBAN used for creditorAccount. N.A. for: bgn-credit-transfers, bgn-budget-transfers, sepa-credit-transfers.' $ref: '#/definitions/Address' creditorName: type: string description: Creditor Name default: Търговец ЕООД maxLength: 35 creditorAddress: description: 'Mandatory for: cross-border-transfers. Optional for: bgn-credit-transfers, bgn-budget-transfers, sepa-credit-transfers. ' $ref: '#/definitions/Address' purposeCode: description: 'Mandatory for: bgn-budget-transfers. N.A. for: bgn-credit-transfers, cross-border-transfers, sepa-credit-transfers.' $ref: '#/definitions/PurposeCode' chargeBearer: description: 'Mandatory for: cross-border-transfers. Optional for: sepa-credit-transfers. N.A. for: bgn-credit-transfers, bgn-budget-transfers.' $ref: '#/definitions/ChargeBearerCode' remittanceInformationUnstructured: type: string description: 'Mandatory for: bgn-credit-transfers, bgn-budget-transfers. Optional for: sepa-credit-transfers, cross-border-transfers.' default: Ref Number Merchant maxLength: 140 paymentType: description: 'Mandatory for: sepa-credit-transfers, cross-border-transfers. Optional for: bgn-credit-transfers, bgn-budget-transfers.' $ref: '#/definitions/PaymentType' budgetPaymentDetails: description: 'Mandatory for: bgn-budget-transfers. N.A. for: bgn-credit-transfers, sepa-credit-transfers, cross-border-transfers.' $ref: '#/definitions/BudgetPaymentDetails' pisRequestBodySEPACreditTransfer: type: object required: - instructedAmount - debtorAccount - creditorName - creditorAccount - paymentType properties: endToEndIdentification: type: string maxLength: 35 debtorAccount: $ref: '#/definitions/AccountReference' instructedAmount: $ref: '#/definitions/Amount' creditorAccount: $ref: '#/definitions/AccountReference' creditorAgent: type: string default: AAAADEBBXXX pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' creditorName: type: string description: Creditor Name default: Търговец ЕООД maxLength: 35 creditorAddress: $ref: '#/definitions/Address' remittanceInformationUnstructured: type: string default: Ref Number Merchant maxLength: 140 paymentType: $ref: '#/definitions/PaymentType' pisRequestBodyBGNBudgetTransfer: type: object required: - instructedAmount - debtorAccount - ultimateDebtor - creditorName - creditorAccount - purposeCode - remittanceInformationUnstructured - budgetPaymentDetails properties: endToEndIdentification: type: string maxLength: 35 debtorAccount: $ref: '#/definitions/AccountReference' ultimateDebtor: type: string maxLength: 70 instructedAmount: $ref: '#/definitions/Amount' creditorAccount: $ref: '#/definitions/AccountReference' creditorAgent: type: string default: AAAADEBBXXX pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' creditorName: type: string description: Creditor Name default: Търговец ЕООД maxLength: 35 creditorAddress: $ref: '#/definitions/Address' purposeCode: $ref: '#/definitions/PurposeCode' remittanceInformationUnstructured: type: string default: Ref Number Merchant maxLength: 140 paymentType: $ref: '#/definitions/PaymentType' budgetPaymentDetails: $ref: '#/definitions/BudgetPaymentDetails' pisRequestBodyBGNCreditTransfer: type: object required: - instructedAmount - debtorAccount - creditorName - creditorAccount - remittanceInformationUnstructured properties: endToEndIdentification: type: string maxLength: 35 debtorAccount: $ref: '#/definitions/AccountReference' instructedAmount: $ref: '#/definitions/Amount' creditorAccount: $ref: '#/definitions/AccountReference' creditorAgent: type: string default: AAAADEBBXXX pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' creditorName: type: string description: Creditor Name default: Търговец ЕООД maxLength: 35 creditorAddress: $ref: '#/definitions/Address' remittanceInformationUnstructured: type: string default: Ref Number Merchant maxLength: 140 paymentType: $ref: '#/definitions/PaymentType' pisRequestBodyCrossBorderTransfer: type: object required: - instructedAmount - debtorAccount - creditorName - creditorAccount - creditorAddress - chargeBearer - paymentType properties: endToEndIdentification: type: string maxLength: 35 debtorAccount: $ref: '#/definitions/AccountReference' instructedAmount: $ref: '#/definitions/Amount' creditorAccount: $ref: '#/definitions/AccountReference' creditorAgent: type: string default: AAAADEBBXXX pattern: '[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}' creditorAgentName: type: string description: Mandatory, if no IBAN used for creditorAccount. maxLength: 70 creditorAgentAddress: description: Mandatory, if no IBAN used for creditorAccount. $ref: '#/definitions/Address' creditorName: type: string description: Creditor Name default: Търговец ЕООД maxLength: 35 creditorAddress: $ref: '#/definitions/Address' chargeBearer: $ref: '#/definitions/ChargeBearerCode' remittanceInformationUnstructured: type: string default: Ref Number Merchant maxLength: 140 paymentType: $ref: '#/definitions/PaymentType' example: SPOT AccountReference: type: object properties: iban: type: string description: 'IBAN of account, mandatory for debtorAccount for all payments and mandatory for creditorAccount when payment is: bgn-credit-transfers, bgn-budget-transfers, sepa-credit-transfers. Optional for creditorAccount when payment is cross-border-transfers. If no IBAN used then "creditorAgentName" and "creditorAgentAddress" have to be filled.' pattern: '[A-Z]{2,2}[0-9]{2,2}[a-zA-Z0-9]{1,30}' default: BG77BPBI000001 tags: [] externalDocs: description: Latest update is published here url: https://www.postbank.bg basePath: /v1 x-ibm-endpoints: - endpointUrl: https://gate.postbank.bg/postbank/psd2 type: - production - development ...