pAPI-swagger.yaml

basePath: /v1
consumes: [application/vnd.api+json]
definitions:
  AccountNumber:
    description: Account number
    example: "71268996"
    type: string
  Amount:
    description: Amount of money. Requires 1 to 2 decimal places.
    example: "10.00"
    pattern: ^[0-9.]{0,20}$
    type: string
  ApiError:
    properties:
      error_code: { format: uuid, type: string }
      error_message: { type: string }
    type: object
  BankId:
    description: Financial institution identification
    example: "333333"
    type: string
  BankIdCode:
    description:
      The type of identification provided at `bank_id` attribute. Must
      be ISO code as listed in the [External Code Sets spreadsheet](https://www.iso20022.org/external_code_list.page)
    enum:
      [SWBIC, GBDSC, BE, FR, DEBLZ, GRBIC, ITNCC, PLKNR, PTNCC, ESNCC, CHBCC]
    example: GBDSC
    type: string
  ChargesInformation:
    properties:
      bearer_code:
        description:
          Specifies which party/parties will bear the charges associated
          with the processing of the payment transaction.
        enum: [DEBT, CRED, SHAR, SLEV]
        example: SLEV
        type: string
      receiver_charges_amount:
        description: Transaction charges due to the receiver of the transaction.
        $ref: "#/definitions/Amount"
      receiver_charges_currency:
        $ref: "#/definitions/Currency"
      sender_charges:
        items:
          description: List of transaction charges due to the sender of the transaction
          properties:
            amount:
              description:
                Amount of each transaction charge due to the sender of
                the transaction.
              $ref: "#/definitions/Amount"
            currency:
              $ref: "#/definitions/Currency"
          type: object
        type: array
    type: object
  Currency:
    description: Currency code as defined in [ISO 4217](http://www.iso.org/iso/home/standards/currency_codes.htm).
    example: EUR
    pattern: "^[A-Z]{3}$"
    type: string
  Links:
    properties:
      first:
        description: Link to the first resource in the list
        example: "https://api.test.example.com/v1/api_name/resource_type"
        type: string
      last:
        description: Link to the last resource in the list
        example: "https://api.test.example.com/v1/api_name/resource_type"
        type: string
      next:
        description: Link to the next resource in the list
        example: "https://api.test.example.com/v1/api_name/resource_type"
        type: string
      prev:
        description: Link to the previous resource in the list
        example: "https://api.test.example.com/v1/api_name/resource_type"
        type: string
      self:
        description: Link to this resource type
        example: "https://api.test.example.com/v1/api_name/resource_type"
        type: string
    type: object
  Payment:
    properties:
      attributes:
        properties:
          amount:
            description:
              Amount of money moved between the instructing agent and instructed
              agent
            $ref: "#/definitions/Amount"
          beneficiary_party:
            $ref: "#/definitions/PaymentParty"
          charges_information:
            $ref: "#/definitions/ChargesInformation"
          currency:
            $ref: "#/definitions/Currency"
          debtor_party:
            $ref: "#/definitions/PaymentParty"
          end_to_end_reference:
            description:
              Unique identification, as assigned by the initiating party,
              to unambiguously identify the transaction. This identification is passed
              on, unchanged, throughout the entire end-to-end chain.
            example: "PAYMENT REF: 20094"
            type: string
          fx:
            properties:
              contract_reference:
                description:
                  Reference to the foreign exchange contract associated
                  with the transaction
                example: FXCONTRACT/REF/123567
                type: string
              exchange_rate:
                description:
                  Factor used to convert an amount from the instructed currency
                  into the transaction currency. Decimal value, represented as
                  a string, maximum length 12. Must be > 0.
                example: "0.13343"
                type: string
              original_amount:
                description:
                  Amount of money to be moved between the debtor and creditor,
                  before deduction of charges, expressed in the currency as instructed
                  by the initiating party. Decimal value. Must be > 0.
                $ref: "#/definitions/Amount"
              original_currency:
                description: Currency of `orginal_amount`.
                $ref: "#/definitions/Currency"
            type: object
          numeric_reference:
            description:
              Numeric reference field, see scheme specific descriptions
              for usage
            example: "0001"
            type: string
          payment_id:
            description: Payment identification (legacy?)
            example: "123456789012345678"
            type: string
          payment_purpose:
            description: Purpose of the payment in a proprietary form
            example: "Paying for goods/services"
            type: string
          payment_scheme:
            description:
              Clearing infrastructure through which the payment instruction
              is to be processed. Default for given organisation ID is used if left
              empty. Currently only FPS is supported.
            enum: [FPS]
            example: FPS
            type: string
          payment_type:
            enum: [Credit]
            type: string
          processing_date:
            description:
              Date on which the payment is to be debited from the debtor
              account. Formatted according to ISO 8601 format YYYY-MM-DD.
            example: "2015-02-12"
            format: date
            type: string
          reference:
            description: Payment reference for beneficiary use
            example: rent for oct
            type: string
          scheme_payment_sub_type:
            description: The scheme specific payment sub type
            enum:
              [
                TelephoneBanking,
                InternetBanking,
                BranchInstruction,
                Letter,
                Email,
                MobilePaymentsService,
              ]
            example: TelephoneBanking
            type: string
          scheme_payment_type:
            description: The scheme-specific payment type
            enum: [ImmediatePayment, ForwardDatedPayment, StandingOrder]
            example: ImmediatePayment
            type: string
          sponsor_party:
            description: Sponsor party
            properties:
              account_number:
                $ref: "#/definitions/AccountNumber"
              bank_id:
                $ref: "#/definitions/BankId"
              bank_id_code:
                $ref: "#/definitions/BankIdCode"
            type: object
        type: object
      id:
        description: Unique resource ID
        example: 4ee3a8d8-ca7b-4290-a52c-dd5b6165ec43
        format: uuid
        type: string
      organisation_id:
        description: Unique ID of the organisation this resource is created by
        example: 743d5b63-8e6f-432e-a8fa-c5d8d2ee5fcb
        format: uuid
        type: string
      type:
        description: Name of the resource type
        example: Payment
        pattern: "^[A-Za-z_]*$"
        type: string
      version:
        description: Version number
        example: 0
        minimum: 0
        type: integer
    required: [id, organisation_id, attributes]
    type: object
  PaymentCreationRequest:
    properties:
      data:
        $ref: "#/definitions/Payment"
    required:
      - data
    type: object
  PaymentCreationResponse:
    properties:
      data:
        $ref: "#/definitions/Payment"
      links:
        $ref: "#/definitions/Links"
    required:
      - data
    type: object
  PaymentDetailsListResponse:
    properties:
      data:
        items:
          $ref: "#/definitions/Payment"
        type: array
      links:
        $ref: "#/definitions/Links"
    type: object
  PaymentDetailsResponse:
    properties:
      data:
        $ref: "#/definitions/Payment"
      links:
        $ref: "#/definitions/Links"
    type: object
  PaymentParty:
    properties:
      account_name:
        description: Name of beneficiary/debtor as given with account
        example: James Bond
        type: string
      account_number:
        $ref: "#/definitions/AccountNumber"
      account_number_code:
        description: The type of identification given at `account_number` attribute
        enum: [IBAN, BBAN]
        example: IBAN
        type: string
      account_type:
        description: The type of the account given with account_number. Single
          digit number. Only required if requested by the beneficiary
          party. Defaults to 0.
        example: 0
        type: integer
      address:
        description: Beneficiary/debtor address
        example: 1 Clarence Mew, Horsforth, Leeds Ls18 4EP
        type: string
      bank_id:
        $ref: "#/definitions/BankId"
      bank_id_code:
        $ref: "#/definitions/BankIdCode"
      name:
        description: Beneficiary/debtor name
        example: Norman Smith
        type: string
    type: object
  PaymentUpdateRequest:
    properties:
      data:
        $ref: "#/definitions/Payment"
    required:
      - data
    type: object
  PaymentUpdateResponse:
    properties:
      data:
        $ref: "#/definitions/Payment"
      links:
        $ref: "#/definitions/Links"
    required:
      - data
    type: object
host: api.example.com
info:
  description: Payments API as specified in Form3 take home test
  title: Payments API
  version: "1"
paths:
  /payments:
    get:
      operationId: listPayments
      parameters:
        - description: Which page to select
          in: query
          minimum: 0
          default: 0
          name: "page[number]"
          required: false
          type: integer
        - description: Number of items per page
          in: query
          maximum: 100
          minimum: 1
          default: 10
          name: "page[size]"
          required: false
          type: integer
      responses:
        200:
          description: List of payment details
          schema:
            $ref: "#/definitions/PaymentDetailsListResponse"
        404:
          description: The query returned no payments
          schema:
            $ref: "#/definitions/ApiError"
        429:
          description: Too Many Requests
        500:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/ApiError"
      summary: List payments
      tags: [Payments]
    post:
      operationId: createPayment
      parameters:
        - in: body
          name: Payment creation request
          schema:
            $ref: "#/definitions/PaymentCreationRequest"
      responses:
        201:
          description: Payment created successfully
          schema:
            $ref: "#/definitions/PaymentCreationResponse"
        409:
          description: A payment with the given ID already exists
          schema:
            $ref: "#/definitions/ApiError"
        429:
          description: Too Many Requests
        500:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/ApiError"
      summary: Create payment
      tags: [Payments]
  /payments/{id}:
    delete:
      operationId: deletePayment
      parameters:
        - description: ID of payment to delete
          format: uuid
          in: path
          name: id
          required: true
          type: string
      responses:
        204:
          description: Payment deleted OK. No body content will be returned
        404:
          description: Payment Not Found
          schema:
            $ref: "#/definitions/ApiError"
        429:
          description: Too Many Requests
        500:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/ApiError"
      summary: Deletes a payment resource
      tags: [Payments]
    get:
      operationId: getPayment
      parameters:
        - description: ID of payment to fetch
          format: uuid
          in: path
          name: id
          required: true
          type: string
      responses:
        200:
          description: Payment details
          schema:
            $ref: "#/definitions/PaymentDetailsResponse"
        404:
          description: Payment Not Found
          schema:
            $ref: "#/definitions/ApiError"
        429:
          description: Too Many Requests
        500:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/ApiError"
      summary: Fetch payment
      tags: [Payments]
    put:
      operationId: updatePayment
      parameters:
        - description: ID of payment to update
          format: uuid
          in: path
          name: id
          required: true
          type: string
        - description: New payment details
          in: body
          name: Payment update request
          schema:
            $ref: "#/definitions/PaymentUpdateRequest"
      responses:
        200:
          description: Payment details
          schema:
            $ref: "#/definitions/PaymentUpdateResponse"
        404:
          description: Payment Not Found
          schema:
            $ref: "#/definitions/ApiError"
        429:
          description: Too Many Requests
        500:
          description: Internal Server Error
          schema:
            $ref: "#/definitions/ApiError"
      summary: Update payment details
      tags: [Payments]
produces: [application/vnd.api+json]
schemes: [http]
swagger: "2.0"