openapi: 3.0.1
info:
  title: NoFraud Portal API
  description: >-
    The NoFraud Portal API includes endpoints to perform actions that would
    otherwise be performed manually in the NoFraud Portal UI.


    The base URL for these requests is
    `https://portal-api.nofraud.com/api/v1/transaction-update/` for both Test
    and Production calls.
paths:
  /customer-code:
    post:
      x-swagger-router-controller: customer-code
      operationId: customer-code
      summary: Submit a customer code
      description: >-
        This process allows your system to automate the method by which phone
        order customer codes are submitted to the NoFraud Portal. 

        For more information on how NoFraud screens phone orders normally,
        please visit our [Phone Order
        Overview](https://help.nofraud.com/s/article/Phone-Orders) or [Phone
        Orders for Developers](guides/phone-orders.md) to find developer
        specific content.
                
        This endpoint uses the Portal API URL. Make POST requests to: 
          
        `https://portal-api.nofraud.com/api/v1/transaction-update/customer-code`
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitCustomerCodeBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 200
                message: customer code created successfully
        '403':
          description: Transaction already canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 403
                message: 'error: customer code has already been added'
        '404':
          description: |-
            Not Found

            Error appears when either API key or customer code is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              examples:
                APIKeyNotFound:
                  value:
                    code: 404
                    message: 'error: api key not found'
                CustomerCodeInvalid:
                  value:
                    code: 404
                    message: 'error: customer code is invalid'
  /report-fraud:
    post:
      x-swagger-router-controller: report-fraud
      operationId: report-fraud
      summary: Report fraud
      description: >-
        After a transaction is screened by NoFraud's API and appears in the
        NoFraud Portal, you have the option of making an API call to NoFraud's
        Portal directly in order to report that a particular order was indeed
        fraudulent. 

        This will trigger an alert for our team of Fraud Analysts to research
        and review the order.


        This action will have the same effect as clicking the "Report Fraud"
        button when viewing a particular transaction in the NoFraud
        Portal.                


        This endpoint uses the Portal API URL. Make POST requests to: 
          
        `https://portal-api.nofraud.com/api/v1/transaction-update/report-fraud`
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalTransactionBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 200
                message: transaction successfully reported as fraudulent
        '403':
          description: >-
            Forbidden


            Error appears if the transaction has already been reported as
            fraudulent or if a transaction covered by chargeback protection has
            not had a chargeback submitted yet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              examples:
                FraudAlreadyReported:
                  value:
                    code: 403
                    message: 'error: transaction has already been repoted as fraudulent'
                MustHaveChargeback:
                  value:
                    code: 403
                    message: 'error: transaction must have a chargeback submitted'
        '404':
          description: |-
            Not Found

            Error appears if either API key or transaction ID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              examples:
                APIKeyNotFound:
                  value:
                    code: 404
                    message: 'error: api key not found'
                TransactionNotFound:
                  value:
                    code: 404
                    message: 'error: transaction not found'
  /cancel-transaction:
    post:
      x-swagger-router-controller: cancel-transaction
      operationId: cancel-transaction
      summary: Cancel a transaction
      description: >-
        After a transaction is screened by NoFraud's API and appears in the
        NoFraud Portal, you have the option of making an API call to NoFraud's
        Portal directly in order to report that a particular order was
        canceled. 

        This will update our system accordingly.


        This action will have the same effect as clicking the "Cancel Order"
        button when viewing a particular transaction in the NoFraud Portal. 

        Transactions can only be marked as canceled within 5 days of the time
        NoFraud initially screened the order.


        This endpoint uses the Portal API URL. Make POST requests to: 
          
        `https://portal-api.nofraud.com/api/v1/transaction-update/cancel-transaction`
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PortalTransactionBody'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 200
                message: transaction successfully marked as canceled
        '403':
          description: Transaction already canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 403
                message: 'error: transaction has already been marked as canceled'
        '404':
          description: |-
            Not Found

            Error appears if either API key or transaction ID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              examples:
                APIKeyNotFound:
                  value:
                    code: 404
                    message: 'error: api key not found'
                TransactionNotFound:
                  value:
                    code: 404
                    message: 'error: transaction not found'
  /submit-chargeback:
    post:
      x-swagger-router-controller: submit-chargeback
      operationId: submit-chargeback
      summary: Submit chargeback
      description: >-
        You can submit a chargeback to NoFraud's system via a request to our
        Portal API for transactions which are covered by Chargeback Protection.
        Only transactions with a current status of either "pass" or "fraudulent"
        can have a chargeback submitted.


        Submitting a chargeback via API is the same as clicking the "Submit
        Chargeback" button and submitting the associated form when viewing a
        particular transaction in the NoFraud Portal.        


        This endpoint uses the Portal API URL. Make POST requests to: 
          
        `https://portal-api.nofraud.com/api/v1/transaction-update/submit-chargeback`
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              allOf:
                - type: object
                  required:
                    - nf_token
                  properties:
                    nf_token:
                      type: string
                      example: NF_prod_eda02a1aa67099c0f30b3ab937bce2a6
                - $ref: '#/components/schemas/Chargeback'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargebackResponse'
        '403':
          description: Transaction not covered by chargeback protection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 403
                message: 'error: transaction is not covered by chargeback protection'
        '404':
          description: |-
            Not Found

            Error appears if either API key or transaction ID is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              examples:
                APIKeyNotFound:
                  value:
                    code: 404
                    message: 'error: api key not found'
                TransactionNotFound:
                  value:
                    code: 404
                    message: 'error: transaction not found'
        '422':
          description: Transaction has already had a chargeback
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PortalAPIResponse'
              example:
                code: 422
                message: 'error: transaction has already had a chargeback'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    SubmitCustomerCodeBody:
      type: object
      required:
        - nf_token
        - customer_code
        - email
      properties:
        nf_token:
          type: string
          example: NF_prod_eda02a1aa67099c0f30b3ab937bce2a6
        customer_code:
          type: string
          example: 123-456-789
        email:
          type: string
          format: email
          example: email@example.com
    Chargeback:
      type: object
      required:
        - transaction_id
        - reason_code
        - due_date
      properties:
        transaction_id:
          type: string
          example: 16f235a0-e4a3-529c-9b83-bd15fe722110
        reason_code:
          description: Chargeback reason code
          type: string
          example: F24
        due_date:
          description: >-
            Last day documentation can be submitted to processor to dispute
            chargeback. Must be formatted as "YYYY-MM-DD"
          type: string
          example: '2025-03-01'
        notice_date:
          description: >-
            Date you were notified about the chargeback. Must be formatted as
            "YYYY-MM-DD"
          type: string
          example: '2025-01-01'
        reference_number:
          description: Chargeback reference number
          type: string
          example: '10003023578'
        carrier:
          description: Shipping Carrier (i.e. "UPS", "FedEx", etc.)
          type: string
          example: USPS
        carrier_tracking_number:
          description: Tracking number of shipment
          type: string
          example: '9114901075742452019146'
        notes:
          description: Additional chargeback notes or information
          type: string
          example: Here is some additional chargeback information.
        inquiry:
          description: >-
            Optional. Must be either "true" or "false". System assumes "false"
            if not present.
          type: string
          example: 'false'
    PortalTransactionBody:
      type: object
      required:
        - nf_token
        - transaction_id
      properties:
        nf_token:
          type: string
          example: NF_prod_eda02a1aa67099c0f30b3ab937bce2a6
        transaction_id:
          type: string
          example: 16f235a0-e4a3-529c-9b83-bd15fe722110
    PortalAPIResponse:
      type: object
      properties:
        code:
          type: string
          description: Response code
        message:
          type: string
          description: Response message
    ChargebackResponse:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: 200
        message:
          type: string
          description: Response message
          example: chargeback successfully reported
        chargeback:
          $ref: '#/components/schemas/Chargeback'
servers:
  - description: Production
    url: https://portal-api.nofraud.com/api/v1/transaction-update/
