openapi: 3.0.0
info:
  title: Dime API Documentation - Orders
  description: >-
    This API supports functionalities for managing orders within the Dime
    payment system.
  version: 1.0.0
servers:
  - url: https://api.dimepay.app/dapi/v1
    description: Production server
  - url: https://sandbox.api.dimepay.app/dapi/v1
    description: Sandbox server for testing
paths:
  /orders:
    post:
      summary: Create a new order
      operationId: createApiOrder
      parameters:
        - name: client_key
          in: header
          required: true
          schema:
            type: string
            example: abcd12345
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                lang:
                  type: string
                  description: The language that should be used
                  example: en
                data:
                  type: string
                  description: >-
                    A signed JWT containing the order input details. **Fields to
                    include in the JWT payload:**


                    - `currency`: Currency of the order.

                    - `id`: Unique order identifier.

                    - `subtotal`: Subtotal of the order.

                    - `total`: Total amount of the order.

                    - `email`: Customer's email.

                    - `tax`: Tax applied to the order.

                    - `ipAddress`: IP address of the customer.

                    - `fulfillmentStatus`: Order's fulfillment status.

                    - `orderComments`: Any comments about the order.

                    - `discount`: Discount applied to the order.

                    - `items`: Array of items in the order.

                    - `billingPerson`: Billing address details.

                    - `shippingPerson`: Shipping address details.

                    - `referenceTransactionId`: Reference to a transaction ID.

                    - `taxes`: Array of tax details.


                    **Example of unsigned payload:**

                    ```json

                    {
                      "currency": "USD",
                      "id": "XJ12H",
                      "subtotal": 1076.64,
                      "total": 2014.97,
                      "email": "mscott@gmail.com",
                      "tax": 488.48,
                      "ipAddress": "195.151.247.241",
                      "fulfillmentStatus": "AWAITING_PROCESSING",
                      "orderComments": "555",
                      "discount": 4,
                      "items": [
                        {
                          "id": "xxxx-xxxx-xxxx-xxxx",
                          "price": 1060,
                          "sku": "ABCA-IAC",
                          "quantity": 1,
                          "shortDescription": "",
                          "name": "iMac",
                          "imageUrl": "https://example.com/images/xxxxxx.jpg",
                          "selectedOptions": [
                            {
                              "name": "Color",
                              "value": "red",
                              "type": "CHOICE"
                            }
                          ]
                        }
                      ],
                      "billingPerson": {
                        "name": "Michael Scott",
                        "companyName": "",
                        "street": "555 Lackawanna Ave",
                        "city": "Scranton",
                        "countryCode": "US",
                        "countryName": "United States",
                        "postalCode": "18508",
                        "stateOrProvinceCode": "PA",
                        "stateOrProvinceName": "Pennsylvania",
                        "phone": ""
                      },
                      "shippingPerson": {
                        "name": "Michael Scott",
                        "companyName": "",
                        "street": "555 Lackawanna Ave",
                        "city": "Scranton",
                        "countryCode": "US",
                        "countryName": "United States",
                        "postalCode": "18508",
                        "stateOrProvinceCode": "PA",
                        "stateOrProvinceName": "Pennsylvania",
                        "phone": ""
                      },
                      "referenceTransactionId": "transaction_65306446",
                      "taxes": [
                        {
                          "name": "New Tax 2",
                          "value": 12,
                          "total": 57.1
                        }
                      ]
                    }

                    ```

                    **Example of signing the payload:**

                    ```javascript

                    const jwt = require('jsonwebtoken');

                    const payload = { /* fields above */ };

                    const signedData = jwt.sign(payload, 'your_secret_key');

                    ```


                    **Final request payload:**

                    ```json

                    {
                      "lang": "en",
                      "data": "<signed_jwt_token>"
                    }

                    ```
                  example: >-
                    eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXJyZW5jeSI6IlVTRCIsImlkIjoiWEoxMkgifQ.nR2Gh18rL9E7E
              required:
                - lang
                - data
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_url:
                    type: string
                    description: URL of the created order
                    example: https://sandbox.dimepay.app/e-order/abcd1234
  /orders/{token}:
    get:
      summary: Retrieve an order by token
      operationId: getApiOrder
      parameters:
        - name: client_key
          in: header
          required: true
          schema:
            type: string
            example: abcd1234
        - name: token
          in: path
          required: true
          schema:
            type: string
            description: >-
              A signed JWT containing the order token. **Fields to include in
              the JWT payload:**


              - `token`: The order's unique token.


              **Example of unsigned payload:**
               "order_123abc456xyz" 
              **Example of signing the payload:**

              ```javascript

              const jwt = require('jsonwebtoken');

              const payload = 'order_123abc456xyz';

              const signedData = jwt.sign(payload, 'your_secret_key');

              ```


              **Final request URL:**

              `/orders/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94`
            example: >-
              https://sandbox.api.dimepay.app/orders/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbiI6ImNhcmRfMTIzYWJjNDU2eHl6In0.7W3ISpqFnINqpm6QX-8oOn-d5M6ixJHiTTk6W0U_e94
      responses:
        '200':
          description: Order retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Primary key, unique ID for the order
                    example: 550e8400-e29b-41d4-a716-446655440000
                  token:
                    type: string
                    description: Unique token for the order
                    example: order_123abc456xyz
                  customer_id:
                    type: string
                    format: uuid
                    nullable: true
                    description: Customer ID associated with the order
                    example: 7db04ed8-cffc-4577-8b50-d3e4c95692aa
                  customer:
                    type: object
                    description: Customer details as JSON
                    example:
                      name: John Doe
                      email: johndoe@example.com
                      phone: '+1234567890'
                  status:
                    type: string
                    enum:
                      - COMPLETE
                      - PENDING
                      - FAILED
                      - REFUNDED
                      - VOIDED
                    description: Current status of the order
                    example: COMPLETE
                  origin_type:
                    type: string
                    enum:
                      - API
                    description: Origin of the order
                    example: API
                  origin_id:
                    type: string
                    nullable: true
                    description: ID of the origin
                    example: orig_987xyz654abc
                  currency:
                    type: string
                    description: Currency for the order
                    example: USD
                  products:
                    type: array
                    description: Products in the order
                    items:
                      type: object
                      example:
                        id: prod_12345
                        name: Laptop
                        price: 1200.5
                        quantity: 1
                  payment_source:
                    type: object
                    description: Payment source details
                    example:
                      method: CARD
                      last4: '4242'
                      brand: Visa
                  fees:
                    type: object
                    description: Fee details
                    example:
                      transaction_fee: 15
                      service_fee: 5
                  total:
                    type: number
                    format: double
                    description: Total amount of the order
                    example: 1250.5
                  subtotal:
                    type: number
                    format: double
                    description: Subtotal amount of the order
                    example: 1200.5
                  shipping:
                    type: number
                    format: double
                    nullable: true
                    description: Shipping cost for the order
                    example: 50
                  tax:
                    type: number
                    format: double
                    nullable: true
                    description: Tax amount for the order
                    example: 30
                  taxValue:
                    type: number
                    format: double
                    nullable: true
                    description: Tax value for the order
                    example: 25
                  consumer_fee:
                    type: number
                    format: double
                    nullable: true
                    description: Consumer fee for the order
                    example: 5
                  enable_notes:
                    type: boolean
                    description: Whether notes are enabled for the order
                    example: true
                  fulfilled:
                    type: boolean
                    description: Whether the order has been fulfilled
                    example: false
                  notes:
                    type: string
                    nullable: true
                    description: Notes about the order
                    example: Please deliver by Friday.
                  metadata:
                    type: object
                    description: Metadata for the order
                    example:
                      custom_field: Custom data here
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: client_key
      in: header
security:
  - ApiKeyAuth: []
