openapi: 3.2.0 info: title: Payment Orders Client Approve API description: Provides access to querying, initiating, approving and managing (recurring) payment orders, payment order drafts and batch payments. version: 2.0.0 servers: - url: http://localhost:4010 description: mock-api-server - url: http://localhost:8080 description: Springboot default port - url: https://localhost:8081 description: 'Best practice: use https' tags: - name: approve description: Payment approval API. paths: /client-api/v2/payment-orders/{paymentOrderId}/approvals: summary: Approvals description: Performs an approval operation on the given payment order put: tags: - approve description: Approves or rejects a given payment order operationId: putApprovalsByPaymentOrderId parameters: - name: paymentOrderId in: path description: Payment Order ID required: true style: simple explode: false schema: maxLength: 36 type: string requestBody: description: Approves or rejects a given payment order content: application/json: schema: $ref: '#/components/schemas/PaymentOrderApprovalPutRequest' example: $ref: '#/components/examples/payment-orders-approval-payment-order-approval-put-request' required: true responses: '202': description: PaymentOrderAccepted content: application/json: schema: $ref: '#/components/schemas/PaymentOrdersPostResponse' examples: simple: $ref: '#/components/examples/simple-1' approved: $ref: '#/components/examples/approved-1' '403': description: BreachReportError content: application/json: schema: $ref: '#/components/schemas/BreachReportError' example: $ref: '#/components/examples/error-breach-report-error' '500': description: InternalServer content: application/json: schema: $ref: '#/components/schemas/internal-server-error' example: $ref: '#/components/examples/lib-internal-server-error' '400': description: BadRequest content: application/json: schema: $ref: '#/components/schemas/bad-request-error' example: $ref: '#/components/examples/lib-bad-request-validation-error' x-BbAccessControl-resource: Payments x-BbAccessControl-function: Different functions per payment type, eg 'SEPA CT', 'US Domestic Wire', etc x-BbAccessControl-privilege: view,approve summary: Put approvals by payment order id x-summary-source: derived components: schemas: Schedule: required: - every - 'on' - startDate - transferFrequency type: object properties: nonWorkingDayExecutionStrategy: type: string description: Strategy for executing payments on non-working days enum: - BEFORE - AFTER - NONE transferFrequency: type: string description: Denotes how frequently the transfer should be made enum: - ONCE - DAILY - WEEKLY - BIWEEKLY - MONTHLY - QUARTERLY - YEARLY 'on': type: integer description: Denotes day on which transfer should be executed. For WEEKLY transferFrequency it will be 1..7 indicating weekday. For BIWEEKLY it will be 1..14 indicating the day of the two week period. For MONTHLY it will be 1..31 indicating day of month. For YEARLY it will be 1..12 indicating month of the year. format: int32 startDate: type: string description: When to start executing the schedule. First transfer will be executed on first calculated date by schedule after this date. format: date endDate: type: string description: When to stop transfers. Transfers will not be executed after this date. Only one of endDate and repeat is possible. If neither repeat nor endDate is provided transfer will be executed until canceled format: date repeat: type: integer description: Number of transfer to be executed. Only one of endDate and repeat is possible. If neither repeat nor endDate is provided transfer will be executed until canceled format: int32 every: type: integer description: Indicates skip interval of transfer. 1 would mean execute every time, 2 - every other time format: int32 enum: - 1 - 2 nextExecutionDate: type: string description: Date when the next payment will be executed, taking in consideration bank holidays and cut-off times. It will be only retrieved when getting payments, it will be dismissed when creating or updating. format: date description: Schedule for recurring transfer. Mandatory if paymentMode is RECURRING TimeFrame: required: - endTime - period - startTime type: object properties: period: type: string startTime: type: string format: date-time endTime: type: string format: date-time IdentifiedTransaction: required: - counterparty - counterpartyAccount - instructedAmount type: object properties: counterparty: $ref: '#/components/schemas/InvolvedParty' counterpartyAccount: $ref: '#/components/schemas/CounterpartyAccount' counterpartyBank: $ref: '#/components/schemas/Bank' instructedAmount: $ref: '#/components/schemas/Currency' correspondentBank: $ref: '#/components/schemas/Bank' intermediaryBank: $ref: '#/components/schemas/Bank' messageToBank: maxLength: 140 type: string description: The message to the bank used for US domestic wire payments targetCurrency: pattern: ^[A-Z]{3}$ type: string description: The alpha-3 code (complying with ISO 4217) of the currency remittanceInformation: $ref: '#/components/schemas/RemittanceInformation' endToEndIdentification: maxLength: 35 type: string mandateIdentifier: maxLength: 15 type: string description: The mandate identifier, of the counter party, giving permission for the debit order. chargeBearer: type: string description: 'Indicated who pays the fees for an international transfer. Possible values: OUR(originator), BEN(beneficiary or SHA(shared).' enum: - OUR - BEN - SHA transferFee: $ref: '#/components/schemas/Currency' exchangeRateInformation: $ref: '#/components/schemas/ExchangeRateInformation' description: The object defining the identified transaction, which means the counterparty will have a arrangementId where applicable. EntityDescription: required: - description - ref - type type: object properties: ref: type: string type: type: string description: type: string ExchangeRateInformation: type: object properties: currencyCode: pattern: ^[A-Z]{3}$ type: string description: Currency in which the rate of exchange is expressed in a currency exchange. rate: maximum: 1.0e+18 minimum: -1.0e+18 type: string description: The factor used for conversion of an amount from one currency to another. rateType: type: string description: Specifies the type used to complete the currency exchange. enum: - ACTUAL - INDICATIVE - AGREED contractIdentification: maxLength: 256 type: string description: Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent. description: The detailed information on the exchange rate that has been used in the payment transaction. BreachReportError: required: - message type: object properties: message: type: string payment: $ref: '#/components/schemas/IdentifiedPaymentOrder' checkTime: type: string format: date-time breachReport: type: array items: $ref: '#/components/schemas/BreachReportItem' internal-server-error: title: InternalServerError type: object properties: message: type: string description: Further Information description: Represents HTTP 500 Internal Server Error PostalAddress: type: object properties: addressLine1: maxLength: 70 type: string addressLine2: maxLength: 70 type: string streetName: maxLength: 70 type: string postCode: maxLength: 16 type: string town: maxLength: 35 type: string countrySubDivision: maxLength: 35 type: string country: maxLength: 2 type: string description: Postal address object with fields OriginatorAccount: required: - arrangementId - identification properties: arrangementId: maxLength: 36 minLength: 1 type: string description: The unique arrangement id. externalArrangementId: maxLength: 70 minLength: 1 type: string description: The external unique arrangement id. identification: $ref: '#/components/schemas/Identification' name: maxLength: 140 type: string description: This is the name of the account, and not the name of the account holder. description: The product identification of the originator PaymentOrderApprovalPutRequest: title: ApprovalStatusPutRequest required: - approvalStatus type: object properties: approvalStatus: type: string description: The options for approval. enum: - APPROVED - REJECTED comment: maxLength: 140 type: string description: When approving or rejecting, the user can add comments which would explain the reason for the action. error-item: title: ErrorItem type: object properties: message: type: string description: Any further information. key: type: string description: '{capability-name}.api.{api-key-name}. For generated validation errors this is the path in the document the error resolves to. e.g. object name + ''.'' + field' context: type: object additionalProperties: type: string description: Context can be anything used to construct localised messages. ContextualInformation: required: - externalUserId - origin - serviceAgreementId type: object properties: externalUserId: maxLength: 64 type: string description: The (unique and human readable) external user id of the user. internalUserId: maxLength: 36 minLength: 1 type: string description: General purpose identifier. Can be UUID but does not have to. serviceAgreementId: maxLength: 36 minLength: 1 type: string description: General purpose identifier. Can be UUID but does not have to. legalEntityId: maxLength: 36 minLength: 1 type: string description: General purpose identifier. Can be UUID but does not have to. origin: maxLength: 200 minLength: 1 type: string description: Name the system where endpoint is calling from Identification: required: - identification - schemeName type: object properties: identification: maxLength: 36 type: string description: The identifier of the account. Can be a regular account number, or an ID. schemeName: type: string description: This describes the type of the account identifier. ID will mean it refers to an account known within DBS. enum: - IBAN - BBAN - ID - EXTERNAL_ID BreachInfo: required: - breachType - currentConsumption - currentThreshold type: object properties: breachType: type: string enum: - THRESHOLD - CONSUMPTION breachedLimitType: type: string enum: - PERIODIC - TRANSACTIONAL timeframe: $ref: '#/components/schemas/TimeFrame' currentConsumption: type: string description: The amount in the specified currency currentThreshold: type: string description: The amount in the specified currency PaymentOrdersPostResponse: title: PaymentOrdersPostResponse required: - id - status type: object properties: id: type: string status: type: string description: The internal DBS status of the payment order.. enum: - DRAFT - ENTERED - READY - ACCEPTED - PROCESSED - REJECTED - CANCELLED - CANCELLATION_PENDING - CONFIRMATION_PENDING - CONFIRMATION_DECLINED bankStatus: maxLength: 35 type: string description: Internal status of the payment or batch order in the core banking system. reasonCode: maxLength: 4 type: string description: Reason code the core banking system accepted/rejected the payment or batch. reasonText: maxLength: 35 type: string description: Human readable reason the core banking system accepted/rejected the payment or batch. errorDescription: maxLength: 105 type: string description: Additional information from the core banking system on why the payment was refused. nextExecutionDate: type: string description: The execution date of the payment that the core system calculated. format: date paymentSetupId: maxLength: 128 type: string description: Generated when the PISP sets up the payments before the Backbase authorization flow. paymentSubmissionId: maxLength: 128 type: string description: Generated when the PISP submits the payment which is after the Backbase authorization flow. approvalStatus: maxLength: 70 type: string description: The status as returned by the approval service. transferFee: $ref: '#/components/schemas/Currency' exchangeRateInformation: $ref: '#/components/schemas/ExchangeRateInformation' additions: type: object additionalProperties: type: string CounterpartyAccount: required: - identification properties: accountType: maxLength: 10 type: string description: The type of the account, e.g. for ACH we have CHECKING/SAVINGS arrangementId: maxLength: 36 minLength: 1 type: string description: The unique arrangement id. externalArrangementId: maxLength: 70 minLength: 1 type: string description: The external unique arrangement id. identification: $ref: '#/components/schemas/Identification' name: maxLength: 140 type: string description: Default name field used in DBS description: The counterparty Account is the original account identification plus the arrangement if applicable. BreachReportItem: required: - breachInfo type: object properties: limitedEntity: type: array description: When not set, user-BBID must be set items: $ref: '#/components/schemas/EntityDescription' shadow: type: boolean description: Shadow limit flag. Applicable for certain entity-types currency: type: string description: Currency code user-BBID: type: string description: BBID of the user for whom the personal limit is assigned breachInfo: type: array description: List of breached periodic limits related to a particular limitable entity items: $ref: '#/components/schemas/BreachInfo' currency: title: Currency required: - amount - currencyCode type: object properties: amount: maximum: 1.0e+18 minimum: -1.0e+18 type: string description: The amount in the specified currency currencyCode: pattern: ^[A-Z]{3}$ type: string description: The alpha-3 code (complying with ISO 4217) of the currency that qualifies the amount additions: type: object additionalProperties: type: string description: Additional properties bad-request-error: title: BadRequestError required: - message type: object properties: message: type: string description: Any further information errors: type: array description: Detailed error information items: $ref: '#/components/schemas/error-item' RemittanceInformation: required: - content - type type: object properties: type: type: string description: When type is structured it consists of some XML tags used when the transaction was uploaded. enum: - STRUCTURED - UNSTRUCTURED content: maxLength: 140 type: string description: The content of the remittance information. description: This is the object representation of the remittance info and can contain different types of remittance info. It is only used in responses, not for input requests! Bank: type: object properties: bankBranchCode: maxLength: 11 type: string description: Some code to identify a bank office, p.e. ABA routing transit number (9) or Swift BIC code (11) name: maxLength: 140 type: string description: The name of a bank postalAddress: $ref: '#/components/schemas/PostalAddress' bic: pattern: ^([A-Z0-9]){4}([A-Z]){2}([A-Z0-9]){2}([A-Z0-9]{3})?$ type: string description: Business identifier code as specified by ISO 9362:2014 description: This object is used to identify the counterparty or correspondent bank. Actions: type: array description: An array of actions that could be performed on a payment order. Actions that can be done are dependant on the payment itself. items: type: string description: The actions that can be performed by the user (with the current context). This field is not evaluated when payment is requested by support employee on behalf of another user. enum: - APPROVE - FINAL_APPROVE - REJECT - CANCEL - DELETE Currency: $ref: '#/components/schemas/currency' InvolvedParty: required: - name type: object properties: name: maxLength: 140 type: string role: type: string description: These are the possible values the role of an involved party can have. enum: - CREDITOR - DEBTOR postalAddress: $ref: '#/components/schemas/PostalAddress' recipientId: maxLength: 15 type: string description: Used for ACH Credit to indicate the id of the recipient description: This object is a common denominator for the debtor or creditor party. IdentifiedPaymentOrder: required: - id - status - version properties: id: pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string description: Unique identification of the payment order. approvalId: pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$ type: string description: The id of the approval request that is or was used to get this item approved. status: type: string description: The internal DBS status of the payment order.. enum: - DRAFT - ENTERED - READY - ACCEPTED - PROCESSED - REJECTED - CANCELLED - CANCELLATION_PENDING - CONFIRMATION_PENDING - CONFIRMATION_DECLINED bankStatus: maxLength: 35 type: string description: Internal status of the payment or batch order in the core banking system. reasonCode: maxLength: 4 type: string description: Reason code the core banking system accepted/rejected the payment or batch. reasonText: maxLength: 35 type: string description: Human readable reason the core banking system accepted/rejected the payment or batch. errorDescription: maxLength: 105 type: string description: Additional information from the core banking system on why the payment was refused. createdBy: maxLength: 128 type: string description: Creator user info. createdAt: type: string description: Date and time indicating when the payment was created format: date-time updatedBy: maxLength: 128 type: string description: Updater user info. updatedAt: type: string description: Date and time indicating when the payment was updated format: date-time actions: $ref: '#/components/schemas/Actions' version: type: integer description: Indication of what version the payment order currently has format: int32 contextualInformation: $ref: '#/components/schemas/ContextualInformation' intraLegalEntity: type: boolean description: Indication if this payment was an intra-company payment. originatorAccountCurrency: pattern: ^[A-Z]{3}$ type: string description: Currency code of the payment order originating account confirmationId: maxLength: 36 minLength: 1 type: string description: The confirmation id for transaction signing. paymentSetupId: maxLength: 128 type: string description: Generated when the PISP sets up the payments before the Backbase authorization flow. paymentSubmissionId: maxLength: 128 type: string description: Generated when the PISP submits the payment which is after the Backbase authorization flow. originator: $ref: '#/components/schemas/InvolvedParty' originatorAccount: $ref: '#/components/schemas/OriginatorAccount' batchBooking: type: boolean description: Indicate whenever there should be only one debit posting for the whole set of instructions instructionPriority: type: string description: Specify the priority of execution of the payment order. enum: - NORM - HIGH requestedExecutionDate: type: string description: The preferred date for the payment order to be executed. format: date paymentMode: type: string description: Denotes whether payment will be single or will be recurring enum: - SINGLE - RECURRING paymentType: maxLength: 22 minLength: 1 type: string description: The type of payment. entryClass: maxLength: 3 type: string description: Used for ACH Standard Entry Class (SEC) Code to designate how the transaction was authorized by the originator. schedule: $ref: '#/components/schemas/Schedule' transferTransactionInformation: $ref: '#/components/schemas/IdentifiedTransaction' totalAmount: $ref: '#/components/schemas/Currency' additions: type: object additionalProperties: type: string examples: payment-orders-approval-payment-order-approval-put-request: summary: payment-orders-approval-payment-order-approval-put-request value: approvalStatus: APPROVED lib-internal-server-error: summary: lib-internal-server-error value: message: Description of error simple-1: summary: simple-1 value: id: af2599ef-759a-4b78-8e67-4949055a532b status: ENTERED approved-1: summary: approved-1 value: id: af2599ef-759a-4b78-8e67-4949055a532b status: ENTERED approvalStatus: APPROVED lib-bad-request-validation-error: summary: lib-bad-request-validation-error value: message: Bad Request errors: - message: Value Exceeded. Must be between {min} and {max}. key: common.api.shoesize context: max: '50' min: '1' error-breach-report-error: summary: error-breach-report-error value: message: Limits has been breached, check the report for more details payment: id: 7d341c28-6714-11e7-907b-a6006ad3dba0 status: ENTERED originatorAccount: arrangementId: 729190df-a421-4937-94fd-5e1a3da132cc identification: identification: NL53RABO0309349755 schemeName: IBAN instructionPriority: NORM requestedExecutionDate: 2017-07-16 transferTransactionInformation: name: Jack Jackson instructedAmount: amount: '5000.55' currencyCode: EUR counterpartyAccount: identification: identification: FR708933019952AUNHQNQ0KZ schemeName: IBAN arrangementId: fe9d66ae-b927-4ac7-8799-c5a38a596ff2 counterparty: name: Backbase postalAddress: addressLine1: Jacob Bontiusplaats 9 zipcode: 1018LL city: Amsterdam country: NL remittanceInformation: type: UNSTRUCTURED content: Return a debt version: 0 checkTime: 2017-01-31 12:12:12+00:00 breachReport: - limitedEntity: - ref: 1234567-12312-123123 type: Service Agreement description: Kuhic, Gislason and Kemmer. SERVICE AGREEMENT shadow: false currency: EUR user-BBID: oleksii breachInfo: - breachType: THRESHOLD breachedLimitType: PERIODIC timeframe: period: daily startTime: 2017-01-31 00:00:00+00:00 endTime: 2017-01-31 23:59:59+00:00 currentConsumption: '250.0' currentThreshold: '499.9' - breachType: CONSUMPTION timeframe: period: monthly startTime: 2017-01-01 00:00:00+00:00 endTime: 2017-01-31 23:59:59+00:00 currentConsumption: '9950.0' currentThreshold: '10000.0' - user-BBID: oleksii shadow: false currency: EUR breachInfo: - breachType: CONSUMPTION timeframe: period: daily startTime: 2017-01-31 00:00:00+00:00 endTime: 2017-01-31 23:59:59+00:00 currentConsumption: '500.0' currentThreshold: '1000.0' - limitedEntity: - ref: 1234567-12312-123123 type: Function Access Group description: Payments approvers - ref: 1234567-12312-123123 type: Function description: Domestic payments - ref: Approve type: Privilege description: Approve shadow: false currency: EUR breachInfo: - breachType: THRESHOLD timeframe: period: daily startTime: 2017-01-31 00:00:00+00:00 endTime: 2017-01-31 23:59:59+00:00 currentConsumption: '250.0' currentThreshold: '499.9' - limitedEntity: - ref: 1234567-12312-123123 type: Legal Entity description: Kuhic, Gislason and Kemmer shadow: false currency: EUR breachInfo: - breachType: CONSUMPTION timeframe: period: quarterly startTime: 2017-01-01 00:00:00+00:00 endTime: 2017-03-31 23:59:59+00:00 currentConsumption: '99950.0' currentThreshold: '100000.0'