Fifth Third Bancorp Returns API

openapi: 3.2.0
info:
  title: Newline Platform Returns API
  version: 1.0.0
  description: Welcome!
servers:
- url: https://sandbox.newline53.com/api/v1
security:
- ApiKeyAuth: []
tags:
- name: Returns
  description: The Returns endpoints help initiate, track, and manage returns of received and originated payments.
paths:
  /returns:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    get:
      tags:
      - Returns
      summary: List Returns
      description: Retrieves a list of return transactions. You can filter the results based on parameters such as status, date, and transaction type. This endpoint is available in Sandbox and Production environments.
      parameters:
      - name: customer_uid
        in: query
        schema:
          type: string
          description: The UID of the customer requesting a return.
          example: Trzqy9t6j6tFGoG3
      - name: requestor_type
        in: query
        schema:
          type: string
          description: Type of the customer requesting a return.
          example: customer
          enum:
          - customer
          - subclient
      responses:
        '200':
          description: A list of Returns is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  created_at:
                    type: string
                    description: The DateTime at which this Return was created.
                    example: null
                  external_uid:
                    $ref: '#/paths/~1returns/post/requestBody/content/application~1json/schema/properties/external_uid'
                  original_transaction_uid:
                    $ref: '#/paths/~1returns/post/requestBody/content/application~1json/schema/properties/original_transaction_uid'
                  customer_uid:
                    $ref: '#/paths/~1returns/get/parameters/0/schema'
                  requestor_type:
                    $ref: '#/paths/~1returns/get/parameters/1/schema'
                  return_reason:
                    $ref: '#/paths/~1returns/post/requestBody/content/application~1json/schema/properties/return_reason'
                  return_transaction_uid:
                    type: string
                    description: The transaction returning the funds.
                    example: SMwKC1osz77DTEiu
                  status:
                    type: string
                    description: 'A value indicating the overall status of the Return.

                      '
                    enum:
                    - canceled
                    - queued
                    - pending
                    - settled
                    - failed
                    readOnly: true
                    example: pending
                  uid:
                    type: string
                    description: Unique identifier for the Return
                    example: dYTG8WAWAh5UyvY7
              examples:
                returns_list:
                  value:
                    total_count: 4
                    count: 2
                    limit: 2
                    offset: 0
                    data:
                    - created_at: '2024-05-01T00:00:00.000Z'
                      external_uid: null,
                      original_transaction_uid: nwXnpBbX3A5sTki3
                      customer_uid: Trzqy9t6j6tFGoG3
                      requestor_type: customer
                      return_reason: RLYGR8CO RMA Z452208-13
                      return_transaction_uid: upKspzfHgAh47pHf
                      status: settled
                      uid: 9ZZ87saSFLkkDG7z
                    - created_at: '2024-05-01T15:53:13.591Z'
                      external_uid: partner-created-id,
                      original_transaction_uid: DbxJUHVuqt3C7hGK
                      customer_uid: EhrQZJNjCd79LLYq
                      requestor_type: subclient
                      return_reason: Insufficient Funds
                      return_transaction_uid: 7UvkHn3Ss9AbWe2c
                      status: pending
                      uid: o1gSDeWvEt45Yuaa
        '403':
          description: Denied access to Returns
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: integer
                          description: Code provided by Newline for reference
                          example: 1234
                        title:
                          type: string
                          description: Title of Error Code
                          example: Sorry, something went wrong
                        detail:
                          type: string
                          description: Description of Error Code
                          example: Details about it here.
                        occurred_at:
                          type: string
                          description: Error Timestamp
                          example: '2022-10-21T18:22:22.300Z'
                        extra:
                          type: string
                          description: Included based on Error Code; Additional context to help users self-solve the error
                          example: Extra details are sometimes provided here.
                  status:
                    type: integer
                    description: HTTP Status Code
              examples:
                access_to_returns:
                  value:
                    errors:
                    - code: 18007
                      title: Returns not enabled
                      detail: Returns are not enabled for this program.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 403
        '422':
          description: Failed to retrieve Returns
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                failed_to_retrieve_returns:
                  value:
                    errors:
                    - code: 31001
                      title: Failed to retrieve Returns
                      detail: An exception occurred while retrieving Returns
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
      operationId: getReturns
      x-operation-id-source: derived
    post:
      tags:
      - Returns
      summary: Create a new Return
      description: 'Initiates a Return of an ACH or wire payment.

        A full ACH addenda is not available for ACH returns because an addenda record is used for the return itself; the `addenda_info` field contains the remaining available space.

        For wire returns, the `wire_instruction` field is limited to 70 characters because Newline prefixes the instructions with the original wire transaction identifier (e.g., IMAD).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                external_uid:
                  type: string
                  description: Client supplied unique identifier. It must be unique within the customer. If the same value is given, no new resource will be created.
                  example: YrfDrfVRgpPgnhF5
                original_transaction_uid:
                  type: string
                  description: The transaction to be returned.
                  example: nwXnpBbX3A5sTki3
                requesting_customer_uid:
                  $ref: '#/paths/~1returns/get/parameters/0/schema'
                requestor_type:
                  $ref: '#/paths/~1returns/get/parameters/1/schema'
                return_reason:
                  type: string
                  maxLength: 140
                  description: 'Freeform text (up to 140 characters) documenting the reason for return. For wire returns, this value will be sent to the other bank.

                    '
                  example: Insufficient Funds
                ach:
                  type: object
                  properties:
                    ach_return_code:
                      type: string
                      description: 'The reason an ACH payment is being returned. Required if returning an RDFI transaction. Optional if reversing an ODFI transaction.

                        '
                      example: R02
                      enum:
                      - R01
                      - R02
                      - R03
                      - R04
                      - R06
                      - R09
                      - R10
                      - R16
                      - R17
                      - R20
                      - R23
                      - R29
                      - R31
                    addenda_info:
                      type: string
                      description: Freeform text (up to 44 characters) to attach a memo to return.
                      maxLength: 44
                      example: TXN0055BADD1E cancelled
                wire:
                  type: object
                  properties:
                    wire_instructions:
                      type: string
                      maxLength: 140
                      description: 'DEPRECATED. Use `return_reason` instead. Wire information for the return transaction (up to 140 characters).

                        '
                      example: ORDER 5555555555
              required:
              - original_transaction_uid
              - requesting_customer_uid
              - requestor_type
              - return_reason
            examples:
              ach:
                value:
                  original_transaction_uid: nwXnpBbX3A5sTki3
                  requesting_customer_uid: Trzqy9t6j6tFGoG3
                  requestor_type: customer
                  return_reason: RLYGR8CO RMA Z452208-13
                  ach:
                    ach_return_code: R02
                    addenda_info: TXN0055BADD1E cancelled
              wire:
                value:
                  original_transaction_uid: DbxJUHVuqt3C7hGK
                  requesting_customer_uid: EhrQZJNjCd79LLYq
                  requestor_type: customer
                  return_reason: 'Refund issued by Bruno''s Boxing for Order #5555555555'
                  wire:
                    wire_instructions: ORDER 5555555555
      responses:
        '201':
          description: A single registered Return is returned.
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/paths/~1returns/get/responses/200/content/application~1json/schema'
                - type: object
                  properties:
                    ach:
                      $ref: '#/paths/~1returns/post/requestBody/content/application~1json/schema/properties/ach'
                    wire:
                      $ref: '#/paths/~1returns/post/requestBody/content/application~1json/schema/properties/wire'
              examples:
                created_return:
                  value:
                    '<<':
                      created_at: '2024-05-01T00:00:00.000Z'
                      external_uid: null,
                      original_transaction_uid: nwXnpBbX3A5sTki3
                      customer_uid: Trzqy9t6j6tFGoG3
                      requestor_type: customer
                      return_reason: RLYGR8CO RMA Z452208-13
                      return_transaction_uid: upKspzfHgAh47pHf
                      status: settled
                      uid: 9ZZ87saSFLkkDG7z
                    ach:
                      ach_return_code: R02
                      addenda_info: TXN0055BADD1E cancelled
        '400':
          description: Creation Error
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_requestor_type:
                  value:
                    errors:
                    - code: 31003
                      title: Unknown Requestor Type
                      detail: The requestor type is not recognized
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                bad_original_transaction_status:
                  value:
                    errors:
                    - code: 31005
                      title: Cannot Initiate Return
                      detail: The given Transaction must be settled to issue Return
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                unsupported_return:
                  value:
                    errors:
                    - code: 31006
                      title: Unsupported Return
                      detail: Returns are not supported for the given Transaction type
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                expired_return_window:
                  value:
                    errors:
                    - code: 31007
                      title: Expired Transaction
                      detail: A Return can not be issued as specified; too much time has elapsed
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                network_code_unsupported:
                  value:
                    errors:
                    - code: 31008
                      title: Network code unsupported
                      detail: Returns are not supported for Wires with UETR numbers
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                unsupported_original_transaction_code:
                  value:
                    errors:
                    - code: 31012
                      title: Unsupported Transaction Code
                      detail: Returns are not supported for the original transaction code
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                cannot_return_a_return_transaction:
                  value:
                    errors:
                    - code: 31013
                      title: Cannot return a return
                      detail: A return transaction cannot be returned.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
                cannot_return_an_ineligible_transaction:
                  value:
                    errors:
                    - code: 31014
                      title: Ineligible transaction
                      detail: This transaction is not eligible to be returned.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 400
        '403':
          description: Denied access to Returns
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                access_to_returns:
                  $ref: '#/paths/~1returns/get/responses/403/content/application~1json/examples/access_to_returns'
        '422':
          description: Creation Error
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                return_creation_error:
                  value:
                    errors:
                    - code: 31002
                      title: Could not create Return
                      detail: An exception occurred while creating a Return
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
                return_already_exists:
                  value:
                    errors:
                    - code: 31004
                      title: Return Already Exists
                      detail: A Return already exists for the given Transaction
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
                extraneous_payment_rail_info_for_return:
                  value:
                    errors:
                    - code: 31009
                      title: Extra payment information
                      detail: Payment information was provided that is not required for this return.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
                information_unavailable_for_return:
                  value:
                    errors:
                    - code: 31010
                      title: Insufficient information for return.
                      detail: The original transaction data required to submit a return is not available.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
                insufficient_time_to_process_return:
                  value:
                    errors:
                    - code: 31011
                      title: Insufficient time to process return.
                      detail: The return cannot be processed because there is insufficient time remaining to process and submit the return to the appropriate institution.
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 422
      operationId: postReturns
      x-operation-id-source: derived
  /returns/{uid}:
    parameters:
    - $ref: '#/paths/~1auth/parameters/0'
    - $ref: '#/paths/~1pools~1%7Buid%7D/parameters/1'
    get:
      tags:
      - Returns
      summary: Get a single Return
      description: Retrieves details about a specific return transaction, including its status, original transaction reference, and any associated metadata.
      responses:
        '200':
          description: A single Return is returned
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/post/responses/201/content/application~1json/schema'
              examples:
                single_return:
                  $ref: '#/paths/~1returns/post/responses/201/content/application~1json/examples/created_return'
        '403':
          description: Denied access to Returns
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/200/content/application~1json/schema'
              examples:
                access_to_returns:
                  $ref: '#/paths/~1returns/get/responses/403/content/application~1json/examples/access_to_returns'
        '404':
          description: Unknown Return
          headers:
            x-trace-id:
              $ref: '#/paths/~1auth/post/responses/201/headers/x-trace-id'
          content:
            application/json:
              schema:
                $ref: '#/paths/~1returns/get/responses/403/content/application~1json/schema'
              examples:
                unknown_return_uid:
                  value:
                    errors:
                    - code: 31000
                      title: Unknown Return
                      detail: Could not find Return with the given uid
                      occurred_at: '2023-05-04T13:23:04.345Z'
                    status: 404
      operationId: getReturnsByUid
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Access token signed with shared HMAC
x-explorer-enabled: false