{
  "openapi": "3.0.1",
  "info": {
    "title": "Authentication OpenAPI specification",
    "description": "This is the documentation for the Ratepay authorization server. The API uses the OAuth 2.0 protocol with JSON Web Tokens (JWT) for authentication and authorization.",
    "contact": {
      "name": "Ratepay",
      "url": "https://www.ratepay.com/",
      "email": "info@ratepay.com"
    },
    "version": "version 1"
  },
  "servers": [
    {
      "url": "https://oauth.ratepay.com",
      "description": "Ratepay Authorization Server"
    }
  ],
  "paths": {
    "/oauth/token": {
      "post": {
        "summary": "Request OAuth token",
        "description": "Request an OAuth token from the Ratepay authorization server.",
        "operationId": "createOAuthToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Request"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successfully created an access token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseGranted"
                }
              }
            }
          },
          "401": {
            "description": "Invalid credentials.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResponseDenied"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Request": {
        "required": [
          "client_id",
          "client_secret",
          "audience",
          "grant_type"
        ],
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string",
            "description": "Client ID provided by Ratepay.",
            "example": "your-client-id"
          },
          "client_secret": {
            "type": "string",
            "description": "Client secret provided by Ratepay.",
            "example": "your-client-secret"
          },
          "audience": {
            "type": "string",
            "description": "Specific resources and scope (environment).\nTo access the API, use the URLs defined below.\n\n| STAGE       | API                                          | URL                                                                     |\n| ----------- | -------------------------------------------- | ----------------------------------------------------------------------- |\n| Integration | Payment API                                  | https://api-integration.ratepay.com/transaction/management              |\n| Integration | Dispute API                                  | https://api-integration.ratepay.com/dispute/management                  |\n| Integration | Webhook Subscriptions                        | https://api-integration.ratepay.com/webhook/management                  |\n| Integration | Bank Account Management API                  | https://api-integration.ratepay.com/shop/consumer/v1                    |\n| Integration | Pay Later API                                | https://api-integration.ratepay.com/paylater                            |\n| Integration | Transaction Status API (For Payment API 1.8) | https://api-integration.ratepay.com/order/status/v2/transactions        |\n| Integration | Transaction Status API (For Payment API 2.0) | https://api-integration.ratepay.com/transaction/status/v2/transactions  |\n| Integration | Hosted Payment Page API                      | https://payment-integration.ratepay.com                                 |\n\n| STAGE       | API                                          | URL                                                                     |\n| ----------- | -------------------------------------------- | ----------------------------------------------------------------------- |\n| Production  | Payment API                                  | https://api.ratepay.com/transaction/management                          |\n| Production  | Dispute API                                  | https://api.ratepay.com/dispute/management                              |\n| Production  | Webhook Subscriptions                        | https://api.ratepay.com/webhook/management                              |\n| Production  | Bank Account Management API                  | https://api.ratepay.com/shop/consumer/v1                                |\n| Production  | Pay Later API                                | https://api.ratepay.com/paylater                                        |  \n| Production  | Transaction Status API (For Payment API 1.8) | https://api.ratepay.com/order/status/v2/transactions                    |\n| Production  | Transaction Status API (For Payment API 2.0) | https://api.ratepay.com/transaction/status/v2/transactions              |\n| Production  | Hosted Payment Page API                      | https://payment.ratepay.com                                             |\n",
            "example": "https://api.ratepay.com/transaction/management"
          },
          "grant_type": {
            "type": "string",
            "description": "The type of grant presented in the exchange. Use `client_credentials`.",
            "example": "client_credentials"
          }
        }
      },
      "ResponseGranted": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string",
            "example": "ey..."
          },
          "expires_in": {
            "type": "number",
            "example": 1800
          },
          "token_type": {
            "type": "string",
            "example": "Bearer"
          }
        }
      },
      "ResponseDenied": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "example": "access_denied"
          },
          "error_description": {
            "type": "string",
            "example": "Unauthorized"
          }
        }
      }
    }
  }
}