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).

            To access the API, use the URLs defined below.


            | STAGE       | API                                          |
            URL                                                                    
            |

            | ----------- | -------------------------------------------- |
            -----------------------------------------------------------------------
            |

            | Integration | Payment API                                  |
            https://api-integration.ratepay.com/transaction/management             
            |

            | Integration | Dispute API                                  |
            https://api-integration.ratepay.com/dispute/management                 
            |

            | Integration | Webhook Subscriptions                        |
            https://api-integration.ratepay.com/webhook/management                 
            |

            | Integration | Bank Account Management API                  |
            https://api-integration.ratepay.com/shop/consumer/v1                   
            |

            | Integration | Pay Later API                                |
            https://api-integration.ratepay.com/paylater                           
            |

            | Integration | Transaction Status API (For Payment API 1.8) |
            https://api-integration.ratepay.com/order/status/v2/transactions       
            |

            | Integration | Transaction Status API (For Payment API 2.0) |
            https://api-integration.ratepay.com/transaction/status/v2/transactions 
            |

            | Integration | Hosted Payment Page API                      |
            https://payment-integration.ratepay.com                                
            |


            | STAGE       | API                                          |
            URL                                                                    
            |

            | ----------- | -------------------------------------------- |
            -----------------------------------------------------------------------
            |

            | Production  | Payment API                                  |
            https://api.ratepay.com/transaction/management                         
            |

            | Production  | Dispute API                                  |
            https://api.ratepay.com/dispute/management                             
            |

            | Production  | Webhook Subscriptions                        |
            https://api.ratepay.com/webhook/management                             
            |

            | Production  | Bank Account Management API                  |
            https://api.ratepay.com/shop/consumer/v1                               
            |

            | Production  | Pay Later API                                |
            https://api.ratepay.com/paylater                                       
            |  

            | Production  | Transaction Status API (For Payment API 1.8) |
            https://api.ratepay.com/order/status/v2/transactions                   
            |

            | Production  | Transaction Status API (For Payment API 2.0) |
            https://api.ratepay.com/transaction/status/v2/transactions             
            |

            | Production  | Hosted Payment Page API                      |
            https://payment.ratepay.com                                            
            |
          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
