Weavr Step up API

openapi: 3.2.0
info:
  version: v1
  title: Weavr Embedded Payment Run Step up API
  license:
    name: private
    url: https://weavr.io
  x-logo:
    url: https://weavr-cdn.s3.eu-central-1.amazonaws.com/weavr-payment-run-logo.png
    backgroundColor: '#FFFFFF'
    altText: Weavr
  description: Weavr Payment Run Plug-in API provides a simple and flexible way for Embedders to add payment execution capabilities in their application.
servers:
- url: https://sandbox.weavr.io/payment-run
  description: Sandbox
security:
- apiKey: []
  authToken: []
tags:
- name: Step up
paths:
  /v1/stepup/challenges/otp/{channel}:
    post:
      operationId: stepupSCAChallenge
      description: 'Initiates the step-up token process by sending an SMS with an one-time-password to a device belonging to the logged-in user that was previously enrolled through `/authentication_factors/otp/{channel}` endpoint.


        This process is required for endpoints that require a step-up token to complete the call.


        _Note that on the Sandbox Environment, text messages are not sent and the one-time-password is always \"123456\"._'
      summary: Issue a one-time password that can be used to step-up a token
      tags:
      - Step up
      parameters:
      - name: channel
        in: path
        required: true
        description: The unique identifier for the channel.
        schema:
          type: string
          enum:
          - SMS
          description: '- "SMS": The one-time-password is sent as a text message'
      - in: header
        name: idempotency-ref
        description: A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.
        required: false
        schema:
          type: string
      responses:
        '204':
          description: Success - No Content.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '400':
          description: Bad Request Error - Your request is invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    maxLength: 255
                    type: string
                    description: When present helps to identify and fix the problem.
                  syntaxErrors:
                    type: object
                    description: Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.
                    properties:
                      invalidFields:
                        type: array
                        items:
                          type: object
                          properties:
                            params:
                              type: array
                              items:
                                type: string
                            fieldName:
                              type: string
                            error:
                              type: string
                              enum:
                              - REQUIRED
                              - HAS_TEXT
                              - REQUIRES
                              - SIZE
                              - RANGE
                              - IN
                              - NOT_IN
                              - REGEX
                              - EXACTLY
                              - AT_LEAST
                              - AT_MOST
                              - ALL_OR_NONE
        '401':
          description: Unauthorized - Your credentials or access token are invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '403':
          description: Forbidden - Access to the requested resource or action is forbidden.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    enum:
                    - INSUFFICIENT_PERMISSIONS
        '404':
          description: Not found - The requested resource couldn't be found.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    enum:
                    - CHANNEL_NOT_SUPPORTED
                    - CHANNEL_NOT_REGISTERED
                    - MOBILE_NUMBER_INVALID
                    - RETRY_IN_15SEC
                    - IDEMPOTENT_REQUEST_IN_PROGRESS
        '413':
          description: Content Too Large
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '422':
          description: Unprocessable Entity
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '429':
          description: Too many requests.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
            x-ratelimit-limit:
              description: 'Example: `20, 10;w=60, 20;w=3600, 200;w=86400`

                The first number (20) is the limit that has been exceeded.

                The remaining numbers are the limits that are in force, with ''w'' meaning ''window in seconds''. In this example `20;w=3600` was exceeded. 20 calls in 3600secs (1hr)

                '
              required: true
              schema:
                type: string
            x-ratelimit-reset:
              description: The number of seconds until the window is reset.
              required: true
              schema:
                minimum: 0
                type: integer
                format: int32
        '500':
          description: Internal Server Error - There is a problem with the server. Please try again later.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '503':
          description: Service Unavailable - We're temporarily offline for maintenance. Please try again later.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        default:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
  /v1/stepup/challenges/otp/{channel}/verify:
    post:
      operationId: stepupSCAVerify
      description: 'Completes the verification process for a step up token.


        _Note that on the Sandbox Environment, text messages are not sent and the `verificationCode` is always \"123456\"._'
      summary: Verify a step-up token using a one-time password
      tags:
      - Step up
      parameters:
      - name: channel
        in: path
        required: true
        description: The unique identifier for the channel.
        schema:
          type: string
          enum:
          - SMS
          description: '- "SMS": The one-time-password is sent as a text message'
      - in: header
        name: idempotency-ref
        description: A unique call reference generated by the caller that, taking into consideration the payload as well as the operation itself, helps avoid duplicate operations. Idempotency reference uniqueness is maintained for at least 24 hours.
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verificationCode
              properties:
                verificationCode:
                  type: string
                  description: The code received by the user on the device.
                  minLength: 6
                  maxLength: 6
                  pattern: ^[0-9]*$
      responses:
        '204':
          description: Success - No Content.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '400':
          description: Bad Request Error - Your request is invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    maxLength: 255
                    type: string
                    description: When present helps to identify and fix the problem.
                  syntaxErrors:
                    type: object
                    description: Is returned as part of an HTTP error response whenever a syntax error is detected. A list of the fields together with their syntax error will be provided.
                    properties:
                      invalidFields:
                        type: array
                        items:
                          type: object
                          properties:
                            params:
                              type: array
                              items:
                                type: string
                            fieldName:
                              type: string
                            error:
                              type: string
                              enum:
                              - REQUIRED
                              - HAS_TEXT
                              - REQUIRES
                              - SIZE
                              - RANGE
                              - IN
                              - NOT_IN
                              - REGEX
                              - EXACTLY
                              - AT_LEAST
                              - AT_MOST
                              - ALL_OR_NONE
        '401':
          description: Unauthorized - Your credentials or access token are invalid.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '403':
          description: Forbidden - Access to the requested resource or action is forbidden.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    enum:
                    - INSUFFICIENT_PERMISSIONS
        '404':
          description: Not found - The requested resource couldn't be found.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                type: object
                properties:
                  errorCode:
                    type: string
                    enum:
                    - STATE_INVALID
                    - VERIFICATION_CODE_EXPIRED
                    - VERIFICATION_CODE_INVALID
                    - CHANNEL_NOT_SUPPORTED
                    - CHANNEL_NOT_REGISTERED
                    - ONE_CHALLENGE_LIMIT_REMAINING
                    - CHALLENGE_LIMIT_EXCEEDED
                    - IDEMPOTENT_REQUEST_IN_PROGRESS
        '413':
          description: Content Too Large
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '422':
          description: Unprocessable Entity
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '429':
          description: Too many requests.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
            x-ratelimit-limit:
              description: 'Example: `20, 10;w=60, 20;w=3600, 200;w=86400`

                The first number (20) is the limit that has been exceeded.

                The remaining numbers are the limits that are in force, with ''w'' meaning ''window in seconds''. In this example `20;w=3600` was exceeded. 20 calls in 3600secs (1hr)

                '
              required: true
              schema:
                type: string
            x-ratelimit-reset:
              description: The number of seconds until the window is reset.
              required: true
              schema:
                minimum: 0
                type: integer
                format: int32
        '500':
          description: Internal Server Error - There is a problem with the server. Please try again later.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        '503':
          description: Service Unavailable - We're temporarily offline for maintenance. Please try again later.
          headers:
            request-ref:
              description: A request identifier. Providing this reference when contacting our support team will help us investigate your query.
              required: true
              schema:
                type: string
        default:
          description: Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
components:
  securitySchemes:
    apiKey:
      name: api-key
      type: apiKey
      in: header
      description: The API Key representing your Weavr account. You can find your API Key in your Weavr Portal in the API Credentials page.
    authToken:
      type: http
      description: The authentication token representing the user. This will be included in the login response object.
      scheme: bearer
      bearerFormat: JWT
  parameters:
    signature:
      name: signature
      in: header
      description: The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `published-timestamp` using your API key.
      required: true
      style: simple
      explode: false
      deprecated: true
      schema:
        type: string
    signature-v2:
      name: signature-v2
      in: header
      description: The signature to verify the authenticity of this request.  This is the base64 hash (HmacSHA256) of the `call-ref + payload + published-timestamp` using your API key.
      required: true
      style: simple
      explode: false
      schema:
        type: string
    call-ref:
      description: A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255
      in: header
      name: call-ref
      required: false
      schema:
        type: string
    published-timestamp:
      name: published-timestamp
      in: header
      description: The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.
      required: true
      style: simple
      explode: false
      schema:
        type: integer
        format: int64
  schemas:
    CredentialId:
      required:
      - type
      - id
      type: object
      properties:
        type:
          maxLength: 50
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
          enum:
          - ROOT
          - USER
          - API_CLIENT
          description: The type of user.
        id:
          type: string
          pattern: ^[0-9]+$
          description: The identifier of the user.
    StepupEvent:
      required:
      - challengeId
      - credential
      - identity
      - publishedTimestamp
      - status
      - type
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/CredentialId'
        identity:
          $ref: '#/components/schemas/StringWrappedTypeId'
        challengeId:
          type: string
          pattern: ^[0-9]+$
        type:
          type: string
        status:
          $ref: '#/components/schemas/StepupEventEventStatus'
        publishedTimestamp:
          type: string
          pattern: ^[0-9]+$
          description: Epoch timestamp using millisecond precision.
        authToken:
          type: string
    StepupEventEventStatus:
      type: string
      enum:
      - VERIFIED
      - DECLINED
      - EXPIRED
    StringWrappedTypeId:
      required:
      - type
      - id
      type: object
      properties:
        type:
          maxLength: 50
          pattern: ^[a-zA-Z0-9_-]+$
          type: string
        id:
          type: string
          pattern: ^[0-9]+$
x-tagGroups:
- name: Authentication
  tags:
  - Tokens
  - Passwords
- name: Authorisation
  tags:
  - Additional Factors
  - Step up
- name: Identities
  tags:
  - Buyers
  - Buyer Authorised Users
- name: Payment runs
  tags:
  - Payment runs
- name: Instruments
  tags:
  - Linked Accounts
- name: Institutions
  tags:
  - Institutions
- name: Simulators
  tags:
  - Simulator
- name: Events
  tags:
  - Buyers Webhooks
  - Payment runs Webhooks
  - Linked Accounts Webhooks
  - Tokens Webhooks
  - Stepup Webhooks
  - Authentication Factors Webhooks
  - Transactions Webhooks
webhooks:
  /stepup/watch:
    post:
      tags:
      - Step up
      summary: Step-up status
      description: Notification that a step-up has been completed or declined.
      operationId: stepup_watch
      parameters:
      - $ref: '#/components/parameters/call-ref'
      - $ref: '#/components/parameters/published-timestamp'
      - $ref: '#/components/parameters/signature'
      - $ref: '#/components/parameters/signature-v2'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StepupEvent'
        required: true
      responses:
        '204':
          description: Success - No Content