Modern Treasury Reversal API

openapi: 3.2.0
info:
  title: Modern Treasury AccountCapability Reversal API
  version: v1
  contact:
    name: Modern Treasury Engineering Team
    url: https://moderntreasury.com
  description: The Modern Treasury REST API. Please see https://docs.moderntreasury.com for more details.
servers:
- url: http://localhost:3000
- url: https://app.moderntreasury.com
tags:
- name: Reversal
paths:
  /api/payment_orders/{payment_order_id}/reversals:
    get:
      summary: list reversals
      tags:
      - Reversal
      description: Get a list of all reversals of a payment order.
      operationId: listReversals
      security:
      - basic_auth: []
      parameters:
      - name: payment_order_id
        in: path
        schema:
          type: string
        description: The ID of the relevant Payment Order.
        required: true
      - name: after_cursor
        in: query
        schema:
          type:
          - string
          - 'null'
        required: false
      - name: per_page
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: successful
          headers:
            X-After-Cursor:
              schema:
                type:
                - string
                - 'null'
              required: false
              description: The cursor for the next page. Including this in a call as `after_cursor` will return the next page.
            X-Per-Page:
              schema:
                type:
                - integer
                - 'null'
              description: The current `per_page`.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/reversal'
    post:
      summary: create reversal
      tags:
      - Reversal
      description: Create a reversal for a payment order.
      operationId: createReversal
      security:
      - basic_auth: []
      parameters:
      - name: Idempotency-Key
        in: header
        required: false
        description: This key should be something unique, preferably something like an UUID.
        schema:
          type: string
      - name: payment_order_id
        in: path
        schema:
          type: string
          description: The id of the payment order being reversed.
        description: The ID of the relevant Payment Order.
        required: true
      responses:
        '201':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reversal'
        '404':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
        '422':
          description: unsuccessful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/reversal_create_request'
  /api/payment_orders/{payment_order_id}/reversals/{reversal_id}:
    parameters:
    - name: payment_order_id
      in: path
      schema:
        type: string
      description: The id of the payment order being reversed.
      required: true
    - name: reversal_id
      in: path
      schema:
        type: string
      description: The ID of the reversal.
      required: true
    get:
      summary: show reversal
      tags:
      - Reversal
      description: Get details on a single reversal of a payment order.
      operationId: getReversal
      security:
      - basic_auth: []
      responses:
        '200':
          description: successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reversal'
        '404':
          description: not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_message'
components:
  schemas:
    ledger_transaction_create_request:
      type: object
      properties:
        description:
          type:
          - string
          - 'null'
          description: An optional description for internal use.
        status:
          type: string
          enum:
          - archived
          - pending
          - posted
          description: To post a ledger transaction at creation, use `posted`.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        effective_date:
          type: string
          format: date
          description: The date (YYYY-MM-DD) on which the ledger transaction happened for reporting purposes.
        ledger_entries:
          type: array
          items:
            $ref: '#/components/schemas/ledger_entry_create_request'
          description: An array of ledger entry objects.
        external_id:
          type: string
          description: A unique string to represent the ledger transaction. Only one pending or posted ledger transaction may have this ID in the ledger.
        ledgerable_type:
          type: string
          enum:
          - expected_payment
          - incoming_payment_detail
          - payment_order
          - return
          - reversal
          description: If the ledger transaction can be reconciled to another object in Modern Treasury, the type will be populated here, otherwise null. This can be one of payment_order, incoming_payment_detail, expected_payment, return, or reversal.
        ledgerable_id:
          type: string
          format: uuid
          description: If the ledger transaction can be reconciled to another object in Modern Treasury, the id will be populated here, otherwise null.
      required:
      - ledger_entries
    reversal_create_request:
      type: object
      properties:
        reason:
          type: string
          enum:
          - duplicate
          - incorrect_amount
          - incorrect_receiving_account
          - date_earlier_than_intended
          - date_later_than_intended
          description: The reason for the reversal. Must be one of `duplicate`, `incorrect_amount`, `incorrect_receiving_account`, `date_earlier_than_intended`, `date_later_than_intended`.
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
        ledger_transaction:
          $ref: '#/components/schemas/ledger_transaction_create_request'
          description: Specifies a ledger transaction object that will be created with the reversal. If the ledger transaction cannot be created, then the reversal creation will fail. The resulting ledger transaction will mirror the status of the reversal.
      required:
      - reason
    reversal:
      type: object
      properties:
        id:
          type: string
          format: uuid
        object:
          type: string
        live_mode:
          type: boolean
          description: This field will be true if this object exists in the live environment or false if it exists in the test environment.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - cancelled
          - completed
          - failed
          - pending
          - processing
          - returned
          - sent
          description: The current status of the reversal.
        payment_order_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the relevant Payment Order.
        transaction_ids:
          type: array
          items:
            type:
            - string
            - 'null'
            format: uuid
            description: The ID of the relevant Transaction or `null`.
        ledger_transaction_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the ledger transaction linked to the reversal.
        metadata:
          type: object
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
        reason:
          type: string
          enum:
          - duplicate
          - incorrect_amount
          - incorrect_receiving_account
          - date_earlier_than_intended
          - date_later_than_intended
          description: The reason for the reversal.
        internal_account_id:
          type:
          - string
          - 'null'
          format: uuid
          description: The ID of the relevant Internal Account.
        reconciliation_status:
          type: string
          enum:
          - unreconciled
          - tentatively_reconciled
          - reconciled
          description: One of `unreconciled`, `tentatively_reconciled` or `reconciled`.
      additionalProperties: false
      minProperties: 13
      required:
      - id
      - object
      - live_mode
      - created_at
      - updated_at
      - status
      - payment_order_id
      - transaction_ids
      - ledger_transaction_id
      - metadata
      - reason
      - internal_account_id
      - reconciliation_status
    error_message:
      type: object
      properties:
        errors:
          type: object
          properties:
            code:
              type: string
              enum:
              - parameter_invalid
              - parameter_missing
              - resource_not_found
              - not_found
              - forbidden
              - invalid_ip
              - invalid_key
              - header_invalid
              - expired_key
              - conflict
              - too_many_requests
            message:
              type: string
            parameter:
              type: string
      required:
      - errors
    ledger_entry_create_request:
      type: object
      properties:
        amount:
          type: integer
          description: Value in specified currency's smallest unit. e.g. $10 would be represented as 1000. Can be any integer up to 36 digits.
        effective_at:
          type: string
          format: date-time
          description: The timestamp (ISO8601 format) at which the ledger transaction happened for reporting purposes.
        direction:
          type: string
          enum:
          - credit
          - debit
          description: One of `credit`, `debit`. Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that wire, rtp, and check payments will always be `credit`.
          _x-stainless-modelDefPath: $shared.transaction_direction
        ledger_account_id:
          type: string
          format: uuid
          description: The ledger account that this ledger entry is associated with.
        lock_version:
          type:
          - integer
          - 'null'
          description: Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See our post about Designing the Ledgers API with Optimistic Locking for more details.
        pending_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s pending balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        posted_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s posted balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        available_balance_amount:
          type:
          - object
          - 'null'
          additionalProperties:
            type: integer
          description: Use `gt` (>), `gte` (>=), `lt` (<), `lte` (<=), or `eq` (=) to lock on the account’s available balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422.
        show_resulting_ledger_account_balances:
          type:
          - boolean
          - 'null'
          description: If true, response will include the balance of the associated ledger account for the entry.
        metadata:
          type: object
          description: Additional data represented as key-value pairs. Both the key and value must be strings.
          additionalProperties:
            type: string
          example:
            key: value
            foo: bar
            modern: treasury
      required:
      - amount
      - direction
      - ledger_account_id
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic