Two API Key API

openapi: 3.2.0
info:
  title: Two Order API Key API
  version: '1.0'
  description: 'This API is for creating orders connected to an online purchase through your solution.

    The API also functions as a central building block when using other Two APIs, e.g. Marketplace API, and Trade Account Onboarding API.


    Specifically, the API enables you to:


    - Check whether a buyer is accepted for credit before placing the order (Order intent)

    - Create orders

    - Fulfil orders (Send invoice from Two)

    - Edit orders

    - Cancel orders

    - Refund orders (Send credit note)

    - Download invoice


    Below you will find a description of a typical flow of how the different endpoints are called. However, you might want to deviate from this order depending on your setup.


    ### Step 0: Use the Two Company Search API to find the company

    By using the Two Company Search API, you ensure that the user places an order on behalf of the correct organization. It enables an improved user experience and lowers the friction.


    **Using Canonical IDs (Recommended):** The Company Search API returns a `canonical_id` for each company. You can use this canonical_id when creating orders and order intents instead of providing full company details. This ensures data accuracy and simplifies integration.


    Example:

    ```json

    {

    "buyer": {

    "company": {

    "company_canonical_id": "abc123def456"

    },

    "representative": { ... }

    }

    }

    ```


    ### Step 1: Check whether a buyer will be accepted for credit during checkout (Order intent)

    Use `POST /v1/order_intent` to credit check your buyers during the checkout. Only enable Two as the payment option if the credit check is approved.

    Collect the `tracking_id` from the response of the order intent in order to connect the order_intent with the actual order being placed by the buyer.


    ### Step 2: Create order

    Create an order by building a request body containing all required elements and call the `POST /v1/order` endpoint.

    1. Read the state and status of the order response.

    2. Check if the status is `APPROVED`.

    3. Check if the state is `UNVERIFIED`, and redirect the user to the `payment_url`.


    After completing the verfication, the user is redirected back to your order confirmation page.


    ### Step 3: Confirm order

    On the order confirmation page use the `POST /v1/order//confirm` endpoint to confirm that the user has arrived at the order confirmation page.


    ### Step 4: Handling orders


    #### Cancel order

    Use `POST /v1/order//cancel` to cancel a specific order.


    #### Edit order

    Use `PUT /v1/order/` with a specified request body to edit an order.


    #### Fulfil order

    Use `POST /v1/order//fulfilled` with a specified request body to fulfil all line items of an order.


    Note: Include a request body in order to do a partial fulfillment.


    #### Refund order

    Use `POST /v1/order//refund` to refund a specific order.


    Note: Include a request body in order to do a partial refund.


    ## Environments


    ### Testing


    https://api.sandbox.two.inc


    Note: Read about our sandbox environment specific behaviour.


    ### Production


    https://api.two.inc'
servers:
- url: https://api.sandbox.two.inc
  description: Testing
- url: https://api.two.inc
  description: Production
security: []
tags:
- name: API Key
paths:
  /v1/merchant/{merchant_id}/api_key:
    post:
      summary: Create API key
      operationId: create_merchant_api_key_handler.post
      description: Create a new API key. An existing API key is required to authenticate the request. If you do not have an API key yet, this can be obtained from the merchant portal integration panel. Note that production API key is only available after a manual review once onboarding and integration is complete. The existing key will remain valid until it is revoked.
      tags:
      - API Key
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
        description: Merchant ID
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '201':
          description: API key schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMerchantAPIKeyResponseSchema'
        '403':
          description: Access denied
        '404':
          description: Merchant not found
      security:
      - X-Api-Key: []
    get:
      summary: Retrieve API keys
      operationId: retrieve_merchant_api_keys_handler.get
      description: Retrieve a list of metadata associated with active API keys.
      tags:
      - API Key
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
        description: Merchant ID
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: List of API key metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantAPIKeyResponseSchemaList'
        '404':
          description: Merchant not found
      security:
      - X-Api-Key: []
  /v1/merchant/{merchant_id}/api_key/{api_key_id}:
    get:
      summary: Retrieve API key
      operationId: retrieve_merchant_api_key_handler.get
      description: Retrieve metadata related to an active API key.
      tags:
      - API Key
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
        description: Merchant ID
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
        description: API Key ID
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: API key metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MerchantAPIKeyResponseSchema'
        '404':
          description: Merchant or API key not found
      security:
      - X-Api-Key: []
    delete:
      summary: Revoke API key
      operationId: revoke_merchant_api_key_handler.delete
      description: Revoke an existing API key. Once revoked, the key will stop working for subsequent requests.
      tags:
      - API Key
      parameters:
      - name: merchant_id
        in: path
        required: true
        schema:
          type: string
        description: Merchant ID
      - name: api_key_id
        in: path
        required: true
        schema:
          type: string
        description: API Key ID
      responses:
        default:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '200':
          description: API key deleted successfully
        '403':
          description: Access denied
        '404':
          description: Merchant not found
      security:
      - X-Api-Key: []
components:
  schemas:
    MerchantAPIKeyResponseSchemaList:
      items:
        $ref: '#/components/schemas/MerchantAPIKeyResponseSchema'
      title: MerchantAPIKeyResponseSchemaList
      type: array
    ErrorResponse:
      properties:
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: An error code related to the error.
          title: Error Code
        error_details:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A detailed description of the error when available.
          title: Error Details
        error_message:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A short description of the error.
          title: Error Message
        error_json:
          anyOf:
          - items:
              $ref: '#/components/schemas/ErrorJSON'
            type: array
          - type: 'null'
          default: null
          description: A list of errors when available.
          title: Error Json
        error_trace_id:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: A unique trace ID for the request that generated the error. Please quote this trace ID in any support requests.
          title: Error Trace Id
      title: ErrorResponse
      type: object
    ErrorJSON:
      properties:
        loc:
          anyOf:
          - items:
              anyOf:
              - type: string
              - type: integer
            type: array
          - type: 'null'
          default: null
          description: Error location.
          title: Loc
        msg:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Error message.
          title: Msg
        type:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Error type.
          title: Type
        ctx:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          description: Error context information.
          title: Ctx
      title: ErrorJSON
      type: object
    CreateMerchantAPIKeyResponseSchema:
      properties:
        id:
          description: Unique identifier of the API key
          format: uuid
          title: Id
          type: string
        hint:
          description: Hint for the API key (last 4 characters)
          title: Hint
          type: string
        label:
          description: Label for the API key (e.g. how it was created)
          title: Label
          type: string
        issued_by:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Immutable record of how the API key was created (read-only)
          title: Issued By
        date_created:
          description: Date that the API key was created (UTC)
          format: date-time
          title: Date Created
          type: string
        date_last_used:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Date that the API key was last used (UTC)
          title: Date Last Used
        date_expiry:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Date that the API key expires (UTC)
          title: Date Expiry
        usage_count:
          description: Number of times the API key has been used
          title: Usage Count
          type: integer
        merchant_id:
          description: Unique identifier of the merchant
          format: uuid
          title: Merchant Id
          type: string
        api_key:
          description: Newly created API key to pass with X-Api-Key header
          title: Api Key
          type: string
      required:
      - id
      - hint
      - label
      - date_created
      - usage_count
      - merchant_id
      - api_key
      title: CreateMerchantAPIKeyResponseSchema
      type: object
    MerchantAPIKeyResponseSchema:
      properties:
        id:
          description: Unique identifier of the API key
          format: uuid
          title: Id
          type: string
        hint:
          description: Hint for the API key (last 4 characters)
          title: Hint
          type: string
        label:
          description: Label for the API key (e.g. how it was created)
          title: Label
          type: string
        issued_by:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: Immutable record of how the API key was created (read-only)
          title: Issued By
        date_created:
          description: Date that the API key was created (UTC)
          format: date-time
          title: Date Created
          type: string
        date_last_used:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Date that the API key was last used (UTC)
          title: Date Last Used
        date_expiry:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: Date that the API key expires (UTC)
          title: Date Expiry
        usage_count:
          description: Number of times the API key has been used
          title: Usage Count
          type: integer
        merchant_id:
          description: Unique identifier of the merchant
          format: uuid
          title: Merchant Id
          type: string
      required:
      - id
      - hint
      - label
      - date_created
      - usage_count
      - merchant_id
      title: MerchantAPIKeyResponseSchema
      type: object
  securitySchemes:
    X-Api-Key:
      type: apiKey
      description: 'For instructions on how to obtain API keys, visit [this page](/docs/guides/getting-api-keys-page/).

        You will obtain two different keys, an initial one for testing in our sandbox environment and once ready, for production.

        Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe.

        Your API key is not to be shared with anyone, including in your version control system, client-side code, in public chatrooms and so on.

        The API key is applied in the request header. For example:

        ```

        GET /something

        X-Api-Key: secret_test_aabbccddeeff0123456789

        ```


        API Keys have the following structure: `secret_<env>_<key>` where:

        - `env` is determined by the environment (`prod` for production, `test` for test environments)

        - `key` is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.'
      name: X-Api-Key
      in: header