AccessToken-2021-03-22.v1.yaml

openapi: 3.0.3
info:
  version: 2021 03 22
  title: Access Token
  description: 'Access Tokens are required to execute all API actions, you can use this resource to obtain one. The authority of the bearer token; the actions it can execute, is determined by the associated Merchant ID, Accounts and Permissions of the app used to create it.'
  contact:
    name: API Integrations
    url: 'https://developer.globalpay.com/?gp-api=true'
    email: api.integrations@globalpay.com
servers:
  - url: 'https://apis.sandbox.globalpay.com/ucp'
    description: Sandbox Environment
  - url: 'https://apis.globalpay.com/ucp'
    description: Production Environment
paths:
  /accesstoken:
    post:
      tags:
        - Create Access Token
      summary: Create a bearer access token.
      description: 'Using your app credentials, send a request to create a bearer access token that can be used to execute subsequent API actions. The actions  that the token can execute are determined by the permissions the app has.'
      operationId: getAccessToken
      parameters:
        - $ref: '#/components/parameters/Content-type'
        - $ref: '#/components/parameters/X-GP-Version'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/request'
            examples:
              Get Access Token:
                value:
                  app_id: i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR
                  nonce: random_string
                  secret: e776ce1d9e94d5072ee132258e446cd92668d7c28b2e475a345319b475ba601956c16e3983926ce279db6301d78b7f47cfb729e41b4169814e373f0a0bf38716
                  grant_type: client_credentials
              Get Access Token - Set Permissions:
                value:
                  app_id: i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR
                  nonce: random_string
                  secret: e776ce1d9e94d5072ee132258e446cd92668d7c28b2e475a345319b475ba601956c16e3983926ce279db6301d78b7f47cfb729e41b4169814e373f0a0bf38716
                  grant_type: client_credentials
                  seconds_to_expire: 6400
                  permissions:
                    - TRN_POST_Authorize
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/response'
        '400':
          $ref: '#/components/responses/RequestInvalid_400'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid_401'
        '403':
          $ref: '#/components/responses/NotAuthorized_403'
        '404':
          description: Resource Not Found
        '500':
          $ref: '#/components/responses/ServerError_500'
        '501':
          $ref: '#/components/responses/UnknownServerError_501'
        '502':
          $ref: '#/components/responses/UnknownPlatformError_502'
        '504':
          $ref: '#/components/responses/ServerTimeout_504'
      servers:
        - url: 'https://apis.sandbox.globalpay.com/ucp'
          description: Sandbox Environment
        - url: 'https://apis.globalpay.com/ucp'
          description: Production Environment
tags:
  - name: Create Access Token
    description: Authenticate using app credentials to use GP API.
    externalDocs:
      url: 'https://developer.globalpay.com/authentication'
components:
  parameters:
    Content-type:
      name: Content-type
      in: header
      description: Format of the message body.
      required: true
      schema:
        type: string
        default: application/json
        example: application/json
    X-GP-Version:
      name: X-GP-Version
      in: header
      description: The version of the API to execute the request.
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        default: '2021-03-22'
        example: '2021-03-22'
  responses:
    RequestInvalid_400:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/objRequestInvalid_400'
    AuthenticationInvalid_401:
      description: Not Authenticated
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthenticationInvalid_401'
    NotAuthorized_403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotAuthorized_403'
    ServerError_500:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerError_500'
    UnknownServerError_501:
      description: Not implemented
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnknownServerError_501'
    UnknownPlatformError_502:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnknownPlatformError_502'
    ServerTimeout_504:
      description: Timeout
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServerTimeout_504'
  schemas:
    request:
      type: object
      properties:
        app_id:
          $ref: '#/components/schemas/app_id_ACCESS_TOKENS.app_id'
        nonce:
          $ref: '#/components/schemas/nonce_ACCESS_TOKENS.nonce'
        secret:
          $ref: '#/components/schemas/secret_ACCESS_TOKENS.secret'
        grant_type:
          $ref: '#/components/schemas/grant_type_ACCESS_TOKENS.grant_type'
        seconds_to_expire:
          $ref: '#/components/schemas/seconds_to_expire_ACCESS_TOKENS.seconds_to_expire'
        interval_to_expire:
          $ref: '#/components/schemas/interval_to_expire_ACCESS_TOKENS.interval_to_expire'
        permissions:
          $ref: '#/components/schemas/permissions_ACCESS_TOKENS.scope.accounts.permissions'
      required:
        - app_id
        - nonce
        - secret
        - grant_type
      x-examples: {}
    app_id_ACCESS_TOKENS.app_id:
      type: string
      description: The id of the app that was used to create the token.
      minLength: 1
      maxLength: 50
      example: uzFr7t4VOqxdLDI44hHmXIjHtOOE8d
    nonce_ACCESS_TOKENS.nonce:
      type: string
      description: A unique random value used to create the secret. The integrator must ensure this is unique and different for every request to create an access token.
      minLength: 1
      maxLength: 50
      example: random_string
    secret_ACCESS_TOKENS.secret:
      type: string
      description: A unique string created using the nonce and app-key. This value is used to further authenticate the request. Created as follows - SHA512(NONCEAPP-KEY
      minLength: 1
      maxLength: 200
      example: e776ce1d9e94d5072ee13225
    grant_type_ACCESS_TOKENS.grant_type:
      type: string
      enum:
        - client_credentials
      description: |
        This is an Oauth specific field that must be set to client_credentials. This indicates to the platform to give access to the apps own resources.
          * `client_credentials` 
      minLength: 1
      maxLength: 50
      example: client_credentials
    seconds_to_expire_ACCESS_TOKENS.seconds_to_expire:
      type: number
      description: The time in seconds that the access token will expire and can no longer be used.
    interval_to_expire_ACCESS_TOKENS.interval_to_expire:
      type: string
      enum:
        - WEEK
        - DAY
        - 12_HOURS
        - 6_HOURS
        - 3_HOURS
        - 1_HOUR
        - 30_MINUTES
        - 10_MINUTES
        - 5_MINUTES
      description: |
        The time interval set for when the token will expire.
          * `WEEK`
          * `DAY`
          * `12_HOURS`
          * `6_HOURS`
          * `3_HOURS`
          * `1_HOUR`
          * `30_MINUTES`
          * `10_MINUTES`
          * `5_MINUTES`
      example: 1_HOUR
    permissions_ACCESS_TOKENS.scope.accounts.permissions:
      type: array
      description: All of the permissions or activites that may be performed by the account.
      items:
        type: string
        enum:
          - TRN_POST_Authorize
          - TRN_POST_Refund
          - TRN_POST_Capture
          - TRN_POST_Reverse
          - VER_POST_Verify
          - TRN_GET_Single
          - TRN_GET_List
          - AUT_POST_Initiate
          - AUT_POST_Results
          - AUT_POST_Check_Availability
      example:
        - TRN_POST_Authorize
    response:
      type: object
      properties:
        token:
          $ref: '#/components/schemas/token_ACCESS_TOKENS.token'
        type:
          $ref: '#/components/schemas/type_ACCESS_TOKENS.type'
        scope:
          type: object
          properties:
            merchant_id:
              $ref: '#/components/schemas/merchant_id_ACCESS_TOKENS.scope.merchant_id'
            merchant_name:
              $ref: '#/components/schemas/merchant_name_ACCESS_TOKENS.scope.merchant_name'
            accounts:
              type: array
              items:
                type: object
                properties:
                  id:
                    $ref: '#/components/schemas/id_ACCESS_TOKENS.scope.accounts.id'
                  name:
                    $ref: '#/components/schemas/name_ACCESS_TOKENS.scope.accounts.name'
                  permissions:
                    $ref: '#/components/schemas/permissions_ACCESS_TOKENS.scope.accounts.permissions'
        app_id:
          $ref: '#/components/schemas/app_id_ACCESS_TOKENS.app_id'
        app_name:
          $ref: '#/components/schemas/app_name_ACCESS_TOKENS.app_name'
        time_created:
          $ref: '#/components/schemas/time_created_ACCESS_TOKENS.time_created'
        seconds_to_expire:
          $ref: '#/components/schemas/seconds_to_expire_ACCESS_TOKENS.seconds_to_expire'
        interval_to_expire:
          $ref: '#/components/schemas/interval_to_expire_ACCESS_TOKENS.interval_to_expire'
        email:
          $ref: '#/components/schemas/email_ACCESS_TOKENS.email'
    token_ACCESS_TOKENS.token:
      type: string
      description: The access token that can be used to execute API actions. A unique identifier generated by Global Payments to identify the merchant.
      minLength: 1
      maxLength: 50
      example: AEI2ptJfKM1Wb5TFZxBDWFZA7Se7
    type_ACCESS_TOKENS.type:
      type: string
      enum:
        - Bearer
      description: |
        The type of token created. minLength:
          * `Bearer` - Indicates that the holder or bearer of this access token can access the API.
      minLength: 1
      maxLength: 50
      example: Bearer
    merchant_id_ACCESS_TOKENS.scope.merchant_id:
      type: string
      description: 'A unique identifier that is used to identify and reference an instance of this resource. This id is used when actioning or referencing a specific merchant. Begins with the three letters, MER.'
      minLength: 1
      maxLength: 50
      example: MER_A6A1EC44522F96630ABEA17A
    merchant_name_ACCESS_TOKENS.scope.merchant_name:
      type: string
      description: A meaningful label that better identifes the merchant.
      minLength: 1
      maxLength: 50
      example: ABC INDUSTRIES
    id_ACCESS_TOKENS.scope.accounts.id:
      type: string
      description: |
        A unique identifier that is used to identify and reference an instance of this resource. It can begin with one of the following the three letters combinations. Each one representing a different account type and capability.

          TRA - Transaction Processing
          TKA - Tokenization
          DIA - Dispute Management
          DAA - Data Services
          MMA - Merchant Management
          FPA - File Processing
          FMA - Funds Management
          RAA - Risk Assessment
      minLength: 1
      maxLength: 50
      example: TRA_be83259a-455e-4ce6-a53a-6d5d31c79d41
    name_ACCESS_TOKENS.scope.accounts.name:
      type: string
      description: A understandable name associated with an account.
      minLength: 1
      maxLength: 50
      example: North American Website
    app_name_ACCESS_TOKENS.app_name:
      type: string
      description: The name of the app the user gave to the application.
      minLength: 1
      maxLength: 50
      example: my_lovely_app
    time_created_ACCESS_TOKENS.time_created:
      type: string
      description: Global Payments time indicating when the object was created in ISO-8601 format.
      example: '2021-05-03T21:23:39.718Z'
    email_ACCESS_TOKENS.email:
      type: string
      description: Email registered with the application that was used to access this token
      minLength: 1
      maxLength: 50
      example: james.mason@example.com
    objRequestInvalid_400:
      type: object
      description: Bad Request
      properties:
        error_code:
          type: string
          enum:
            - DUPLICATE_TRANSACTION
            - INVALID_BATCH_ACTION
            - INVALID_REQUEST_DATA
            - INVALID_TRANSACTION_ACTION
            - MANDATORY_DATA_MISSING
            - TRANSACTION_NOT_FOUND
          description: This indicates an issue with the API request.
          example: MANDATORY_DATA_MISSING
        detailed_error_code:
          type: string
          enum:
            - '40016'
          description: Unique reference to identify the error.
          example: '40016'
        detailed_error_description:
          type: string
          description: Unique Text describing the specific error.
          example: Bad track data
    AuthenticationInvalid_401:
      type: object
      description: Not Authenticated
      properties:
        error_code:
          type: string
          enum:
            - NOT_AUTHENTICATED
          description: This action failed as token in the request is not valid.
          example: NOT_AUTHENTICATED
        detailed_error_code:
          type: string
          enum:
            - '40001'
            - '40002'
          description: Unique reference to identify the error.
          example: '40001'
        detailed_error_description:
          type: string
          description: Unique Text describing the specific error.
          example: Invalid Access Token
    NotAuthorized_403:
      type: object
      description: Forbidden
      properties:
        error_code:
          type: string
          enum:
            - ACTION_NOT_AUTHORIZED
          description: This action is not authorized with the credentials being used.
          example: ACTION_NOT_AUTHORIZED
        detailed_error_code:
          type: string
          enum:
            - '40003'
            - '40004'
          description: Unique reference to identify the error.
          example: '40003'
        detailed_error_description:
          type: string
          description: Unique Text describing the specific error.
          example: Permission not enabled to execute action
    ServerError_500:
      type: object
      description: Internal Server Error
      properties:
        error_code:
          type: string
          enum:
            - SYSTEM_ERROR_DOWNSTREAM
          description: This indicates an unexpected issue occurred on the Global Payments system.
          example: SYSTEM_ERROR_DOWNSTREAM
        detailed_error_code:
          type: string
          enum:
            - '50011'
          description: Unique reference to identify the error.
          example: '50011'
        detailed_error_description:
          type: string
          description: Unique Text describing the specific error.
          example: Processor Configuration error
    UnknownServerError_501:
      type: object
      description: Not implemented
      properties:
        error_code:
          type: string
          enum:
            - UNKNOWN_RESPONSE
          description: This is an error not yet handled or mapped properly.
          example: UNKNOWN_RESPONSE
        detailed_error_code:
          type: string
          enum:
            - '50012'
          description: Unique reference to identify the error.
          example: '50012'
        detailed_error_description:
          type: string
          description: 'Unique Text describing the specific error not yet handled.      '
    UnknownPlatformError_502:
      type: object
      description: Bad Gateway
      properties:
        error_code:
          type: string
          enum:
            - UNAUTHORIZED_DOWNSTREAM
          description: This is an error indicating there was an issue connecting to a partner system..
          example: UNAUTHORIZED_DOWNSTREAM
        detailed_error_code:
          type: string
          enum:
            - '50002'
          description: Unique reference to identify the error.
          example: '50002'
        detailed_error_description:
          type: string
          description: Authentication error—Verify and correct credentials.
    ServerTimeout_504:
      type: object
      description: Timeout
      properties:
        error_code:
          type: string
          enum:
            - TIMEOUT_DOWNSTREAM
          description: This is an error indicating there was a timeout issue to another  system.
          example: TIMEOUT_DOWNSTREAM
        detailed_error_code:
          type: string
          enum:
            - '50008'
          description: Unique reference to identify the error.
          example: '50008'
        detailed_error_description:
          type: string
          description: No response from payment method provider.