AbstractPaymentTransaction:
  description: |
    A basic abstract representation of the consumer's payment transaction or a request to create a new payment transaction.
    Please note that an instance of this class will never be returned but only one of its child entities.
  type: object
  properties:
    correlation_id:
      description: |
        The merchant's unique id with which the payment transaction is associated.
      type: string
      minLength: 1
      maxLength: 40
      example: TP-103645
    statement_text:
      description: |
        Text of ASCII printable characters that will be printed on consumer's statement if supported by the payment method.
        May not be all digits, all same character, or all sequential characters (e.g. "abc").
        The text will overwrite the statement text provided for the payment session.
      $ref: '../../common/statement-text/statement-text_v1.yaml#/StatementText'
    labels:
      description: |
        Set of key-value pairs that will be attached to the payment transaction.
        This can be useful for storing additional information about the payment transaction in a structured format.
      type: string
      additionalProperties:
        type: string
    merchant_variables:
      description: |
        Set of key-value pairs that will be included in all status notifications sent for the payment transaction.
        This can be useful for storing additional information about the payment transaction in a structured format that will be passed back to the merchant.
      type: string
      additionalProperties:
        type: string
  
CreatePaymentTransactionRequest:
  description: A representation of the consumer's payment transaction
  type: object
  required:
    - amount
  properties:
    amount:
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
  allOf:
    - $ref: '#/AbstractPaymentTransaction'

CreatePaymentTransactionResponse:
  description: A simplified representation of the created payment transaction
  type: object
  required:
    - id
    - session_id
    - ip
    - port
  properties:
    id:
      description: The payment gateway's unique ID for the created payment transaction
      $ref: '../../common/record-entity-id/record-entity-id_v1.yaml#/RecordEntityId'
    session_id:
      description: The payment gateway's unique ID for the payment session the created payment transaction is part of
      $ref: '../../common/record-entity-id/record-entity-id_v1.yaml#/RecordEntityId'
    ip:
      description: The source IP address from which the payment transaction was created
      type: string
      format: ipv4
      example: 80.52.87.56
    port:
      description: The source port from which the payment transaction was created
      type: integer
      format: int32
      example: 37570

PaymentTransaction:
  description: A complete representation of the consumer's payment transaction
  type: object
  required:
    - total_amount
    - authorized_amount
    - captured_amount
    - refunded_amount
    - cancelled_amount
    - amounts
    - statuses
    - labels
    - merchant_variables
    - created
    - modified
  properties:
    payment_method_id:
      description: The unique id for the payment method that the consumer selected to create the payment transaction
      $ref: '../payment-method/payment-method-id_v1.yaml#/PAYMENT_METHOD_ID'
      example: 200
    payment_instrument_id:
      description: |
        The unique id for the payment instrument that the consumer selected from the wallet or secure vault.  
        The value will generally match `payment_method_id` for payments authorized with the consumer entering the card details
        and will always be different for payments authorized using a stored card or a valuable from the consumer's wallet.
      $ref: '../payment-method/payment-method-id_v1.yaml#/PAYMENT_METHOD_ID'
      example: 103
    authentication_provider_id:
      description: The unique id for the upstream provider that authenticated the consumer for the payment transaction
      $ref: '../../common/system-entity-id/system-entity-id_v1.yaml#/SystemEntityId'
      example: 2
    initialization_id:
      description: The transaction id returned by an upstream 3rd party provider, such as Apple Pay or MobilePay, upon initializing the payment for the payment transaction.
      type: string
      minLength: 1
      maxLength: 40
      example: d8df6e3b-f012-4417-a1de-3e038b72c551
    authentication_id:
      description: The universally unique transaction identifier assigned by the 3DS Server or MPI to identify a single transaction.
      type: string
      minLength: 1
      maxLength: 40
      example: d8df6e3b-f012-4417-a1de-3e038b72c551
    payment_provider_id:
      description: The unique id for the upstream provider that authorized the payment for the payment transaction.
      $ref: '../../common/system-entity-id/system-entity-id_v1.yaml#/SystemEntityId'
      example: 1
    authorization_code:
      description: The universally unique transaction identifier assigned by the upstream payment provider to identify a single authorization.
      type: string
      minLength: 1
      maxLength: 40
      example: d8df6e3b-f012-4417-a1de-3e038b72c551
    total_amount:
      description: The total amount for the payment transaction
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
    authorized_amount:
      description: The amount authorized for the payment transaction.
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
    captured_amount:
      description: The total amount captured for the payment transaction
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
    refunded_amount:
      description: The total amount refunded for the payment transaction
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
    cancelled_amount:
      description: The part of the authorized amount that has been cancelled for the payment transaction
      $ref: '../../common/amount/amount_v1.yaml#/Amount'
    amounts:
      description: The list of amounts (of any type) that have been posted for the payment transaction
      type: array
      items:
        $ref: '../../common/amount/posted-amount_v1.yaml#/PostedAmount'
      minItems: 1
    statuses:
      description: The list of payment statuses that have been posted to the payment transaction
      type: array
      items:
        $ref: '../payment-status/posted-payment-status_v1.yaml#/PostedPaymentStatus'
      minItems: 1
    fingerprint:
      $ref: '../../common/payment-method-fingerprint/payment-method-fingerprint_v1.yaml#/PaymentMethodFingerprint'
    created:
      description: Timestamp specifying when the payment transaction was created
      type: string
      format: date-time
      example: 2017-07-21T17:32:28Z
    modified:
      description: Timestamp specifying when the payment transaction was last modified
      type: string
      format: date-time
      example: 2017-07-21T17:32:28Z
  allOf:
    - $ref: '#/AbstractPaymentTransaction'
    - $ref: '#/CreatePaymentTransactionResponse'