> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Request a capability

> Asks for a capability that reads `ready`. Safe to repeat: one already `in_review` or `active` answers 200 with the capability, and so does `pay_by_bank_uk_eu`, which a merchant has once Quidkey signs off. An agreement it requires is accepted first as an `agreement_acceptance`. `CAPABILITY_NOT_READY` lists what is missing in `details`, as `required_actions` codes. One not offered to the merchant answers `CAPABILITY_UNAVAILABLE`, and `pay_by_bank_us`, which is requested another way for now, `CAPABILITY_NOT_REQUESTABLE`. While another request for the capability is going through, and once this one runs out of time, it answers 503 `SERVICE_UNAVAILABLE`: the request goes on, so repeat it to see where it stands. `OUTCOME_UNKNOWN` means it may have gone through without saying so: Quidkey checks, and until then every request for the capability answers `OUTCOME_UNKNOWN` again, so contact Quidkey. A merchant the credential can't reach answers 404, and a merchant's own credential gets 403.

Credentials: `partner`

Permission: `capabilities:request`



## OpenAPI

````yaml /api-reference/v1/openapi.json post /merchants/{id}/capabilities/{capability_id}:request
openapi: 3.1.0
info:
  title: Quidkey API
  version: 1.0.0
  description: >-
    The Quidkey public API.


    Within a version, a response can carry what this document doesn't list yet:
    a new field, a new value of an enum, a new error code. Handle a value you
    don't recognise rather than refusing the response. A client generated from
    this document turns an `enum` into a closed type unless told otherwise, so
    turn on its option for unknown values, such as openapi-generator's
    `enumUnknownDefaultCase`. A request is held to what's listed: a value it
    doesn't list is refused.
  contact:
    name: Quidkey
    url: https://docs.quidkey.com
servers:
  - url: https://api.quidkey.com/v1
security:
  - bearer: []
tags:
  - name: account_owner
  - name: agreement
  - name: agreement_acceptance
  - name: api_key
  - name: bank
  - name: bank_account
  - name: capability
  - name: country
  - name: identity_verification
  - name: legal_entity
  - name: merchant
  - name: party
  - name: payment_link
  - name: payout
  - name: transaction
  - name: webhook_endpoint
paths:
  /merchants/{id}/capabilities/{capability_id}:request:
    post:
      tags:
        - capability
      summary: Request a capability
      description: >-
        Asks for a capability that reads `ready`. Safe to repeat: one already
        `in_review` or `active` answers 200 with the capability, and so does
        `pay_by_bank_uk_eu`, which a merchant has once Quidkey signs off. An
        agreement it requires is accepted first as an `agreement_acceptance`.
        `CAPABILITY_NOT_READY` lists what is missing in `details`, as
        `required_actions` codes. One not offered to the merchant answers
        `CAPABILITY_UNAVAILABLE`, and `pay_by_bank_us`, which is requested
        another way for now, `CAPABILITY_NOT_REQUESTABLE`. While another request
        for the capability is going through, and once this one runs out of time,
        it answers 503 `SERVICE_UNAVAILABLE`: the request goes on, so repeat it
        to see where it stands. `OUTCOME_UNKNOWN` means it may have gone through
        without saying so: Quidkey checks, and until then every request for the
        capability answers `OUTCOME_UNKNOWN` again, so contact Quidkey. A
        merchant the credential can't reach answers 404, and a merchant's own
        credential gets 403.


        Credentials: `partner`


        Permission: `capabilities:request`
      operationId: capability.request
      parameters:
        - name: id
          in: path
          required: true
          schema:
            minLength: 1
            type: string
        - name: capability_id
          in: path
          required: true
          schema:
            type: string
            enum:
              - pay_by_bank_uk_eu
              - pay_by_bank_us
              - payto_au
              - virtual_accounts
      responses:
        '200':
          description: The capability, in the full view.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                additionalProperties: false
                type: object
                required:
                  - result
                  - entities
                  - not_included
                properties:
                  result:
                    $ref: '#/components/schemas/CapabilityFull'
                  entities:
                    additionalProperties: false
                    description: Nothing can be included here.
                    type: object
                    properties: {}
                  not_included:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotIncludedEntry'
        '400':
          description: '`VALIDATION_FAILED`: The request is malformed or failed validation.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - VALIDATION_FAILED
        '401':
          description: '`UNAUTHENTICATED`: A valid bearer token is required.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - UNAUTHENTICATED
        '403':
          description: >-
            `FORBIDDEN`: This credential doesn't have permission for this
            endpoint.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - FORBIDDEN
        '404':
          description: '`NOT_FOUND`: Not found.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_FOUND
        '406':
          description: '`NOT_ACCEPTABLE`: This endpoint doesn''t offer the format in Accept.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - NOT_ACCEPTABLE
        '409':
          description: '`CAPABILITY_NOT_READY`: This capability can''t be requested yet.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - CAPABILITY_NOT_READY
        '422':
          description: >-
            `CAPABILITY_NOT_REQUESTABLE`: This capability is requested another
            way for now. Contact Quidkey to request it.


            `CAPABILITY_UNAVAILABLE`: This capability isn't offered to this
            merchant.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - CAPABILITY_NOT_REQUESTABLE
            - CAPABILITY_UNAVAILABLE
        '429':
          description: '`RATE_LIMITED`: Too many requests.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - RATE_LIMITED
        '500':
          description: '`INTERNAL_ERROR`: Something went wrong on our side.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - INTERNAL_ERROR
        '502':
          description: >-
            `CAPABILITY_REQUEST_FAILED`: The request didn't go through. Read the
            capability, then retry if it still reads ready.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - CAPABILITY_REQUEST_FAILED
        '503':
          description: >-
            `OUTCOME_UNKNOWN`: The request may have taken effect. Read the
            resource before trying again.


            `SERVICE_UNAVAILABLE`: The service is busy. Try again shortly.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
              description: How many seconds to wait before retrying `SERVICE_UNAVAILABLE`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          x-error-codes:
            - OUTCOME_UNKNOWN
            - SERVICE_UNAVAILABLE
components:
  headers:
    RequestId:
      description: Identifies this request. Quote it to support.
      schema:
        type: string
    RetryAfter:
      description: How many seconds to wait before retrying.
      schema:
        minimum: 0
        type: integer
  schemas:
    CapabilityFull:
      additionalProperties: false
      type: object
      required:
        - _type
        - _uri
        - _view
        - id
        - created_at
        - updated_at
        - category
        - markets
        - description
        - status
        - required_actions
        - required_agreements
        - merchant
      properties:
        _type:
          const: capability
          type: string
        _uri:
          pattern: ^/
          description: The canonical URI, relative to the version root.
          type: string
        _view:
          const: full
          type: string
        id:
          type: string
          enum:
            - pay_by_bank_uk_eu
            - pay_by_bank_us
            - payto_au
            - virtual_accounts
          description: >-
            Which capability this is. Unique only within its merchant, since
            every merchant has the same set. A new value comes with notice.
        created_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        updated_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
        category:
          type: string
          enum:
            - payments
            - payouts_and_refunds
        markets:
          type: array
          items:
            type: string
            enum:
              - uk
              - eu
              - us
              - au
        description:
          type: string
        status:
          type: string
          enum:
            - unavailable
            - not_ready
            - ready
            - in_review
            - active
          description: >-
            Where it stands.


            - `unavailable`: Not offered to this merchant.

            - `not_ready`: Something is missing, and `required_actions` says
            what.

            - `ready`: It can be requested.

            - `in_review`: With a provider or Quidkey: requested, being set up,
            or done while the merchant isn't `active`, suspended included.

            - `active`: Done, and the merchant is `active`, so it can be used. A
            live payment transaction can still be refused, as `merchant.status`
            says of an `active` merchant.
        required_actions:
          type: array
          items:
            $ref: '#/components/schemas/RequiredAction'
          description: >-
            What holds it back: what's missing while it's `not_ready`, including
            what `onboarding` also reports, and Quidkey's part while it's
            `in_review`. Empty otherwise. It uses the codes on `onboarding`'s
            `required_actions`, and these.


            - `LEGAL_ENTITY_INCOMPLETE`: Actor `api`. The legal entity is
            missing the details this capability needs, which `fields` names.

            - `LEGAL_ENTITY_COMPLETION_PENDING`: Actor `quidkey`. The legal
            entity is missing details this capability needs that the legal
            entity's fields don't hold, so Quidkey has to complete them.

            - `PARTY_REQUIRED`: Actor `api`. Add the owner or director this
            capability needs.

            - `MERCHANT_WEBSITE_REQUIRED`: Actor `api`. Set the merchant's
            `website_url`.

            - `MERCHANT_CATEGORY_NOT_ACCEPTED`: Actor `api`. This capability
            doesn't accept the merchant's `category_code`.

            - `BANK_ACCOUNT_REQUIRED`: Actor `api`. Add an active `owned`
            account with the role `payout`.

            - `AGREEMENT_ACCEPTANCE_REQUIRED`: Actor `api`. `target` is the
            agreement version an `agreement_acceptance` must name.

            - `CAPABILITY_REQUEST_REQUIRED`: Actor `api`. `target` is the
            `virtual_accounts` capability, which has to be requested first.

            - `ONBOARDING_INCOMPLETE`: Actor `api`. It waits on Quidkey's
            sign-off of the merchant, and the merchant's onboarding has steps
            left before Quidkey reviews it. `target` is the onboarding, whose
            `required_actions` lists them.

            - `QUIDKEY_REVIEW_PENDING`: Actor `quidkey`. It waits on Quidkey's
            review and sign-off of the merchant, whose onboarding is with
            Quidkey, as `onboarding` follows.

            - `QUIDKEY_SETUP_PENDING`: Actor `quidkey`. Quidkey is completing
            setup it needs: before it can be requested, or once it has been.

            - `QUIDKEY_ACTIVATION_PENDING`: Actor `quidkey`. It is done, and
            Quidkey has yet to put the merchant live or to reinstate it.
        required_agreements:
          maxItems: 10
          type: array
          items:
            $ref: '#/components/schemas/AgreementLink'
          description: >-
            The current version of each agreement it requires, accepted or not.
            What an `agreement_acceptance` must name.
        merchant:
          $ref: '#/components/schemas/MerchantLink'
    NotIncludedEntry:
      additionalProperties: false
      type: object
      required:
        - link
        - reason
      properties:
        link:
          $ref: '#/components/schemas/AnyLink'
        reason:
          type: string
          enum:
            - no_permission
            - not_published
          description: >-
            Why this link has no entity.


            - `no_permission`: This credential can't read it. Fetching it
            answers 403, or 404 where a 403 would reveal that it exists.

            - `not_published`: The API doesn't show it: a type it doesn't
            publish, or a record it doesn't show on a type it does, such as a
            failed payout. Fetching it, where it has a URI, answers 404.
    Error:
      additionalProperties: false
      type: object
      required:
        - error
      properties:
        error:
          additionalProperties: false
          type: object
          required:
            - code
            - message
            - details
            - retryable
            - request_id
          properties:
            code:
              description: Branch on this. New codes can appear.
              type: string
            message:
              description: For people. It can change.
              type: string
            details:
              type: array
              items:
                $ref: '#/components/schemas/ErrorDetail'
            retryable:
              description: >-
                Whether sending the same request again unchanged, after a wait,
                can succeed with nothing else changing.
              type: boolean
            request_id:
              description: Quote this to support.
              type: string
    RequiredAction:
      description: Something that has to happen before a resource can move on.
      additionalProperties: false
      type: object
      required:
        - code
        - message
        - actor
        - target
        - fields
        - hosted_link
      properties:
        code:
          description: >-
            Public and stable, and listed on the field that holds it. New codes
            can appear, so handle any you don't recognise.
          type: string
        message:
          type: string
        actor:
          type: string
          enum:
            - api
            - person
            - quidkey
          description: >-
            Who resolves it. `api`: your integration makes the API call the code
            names. `person`: someone acts, in Console or on the page in
            `hosted_link`. `quidkey`: there's nothing for you to do, because
            Quidkey retries it or its staff handle it.
        target:
          anyOf:
            - $ref: '#/components/schemas/AnyLink'
            - type: 'null'
        fields:
          type: array
          items:
            type: string
          description: >-
            The public fields of `target` it's about, with dotted paths into an
            address, such as `registered_address.city`. `[]` unless the code
            names fields.
        hosted_link:
          anyOf:
            - $ref: '#/components/schemas/HostedLink'
            - type: 'null'
    AgreementLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: agreement
          type: string
        id:
          type: string
      x-link-target:
        resource: agreement
        kind: resource
        is_published: true
        views:
          - full
    MerchantLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: merchant
          type: string
        id:
          type: string
      x-link-target:
        resource: merchant
        kind: resource
        is_published: true
        views:
          - full
    AnyLink:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - _link
            - _type
            - id
          properties:
            _link:
              pattern: ^/
              type: string
            _type:
              type: string
            id:
              type: string
        - additionalProperties: false
          type: object
          required:
            - _type
            - id
          properties:
            _type:
              type: string
            id:
              type: string
      x-link-target:
        resource: any
        kind: any
        is_published: true
    ErrorDetail:
      anyOf:
        - additionalProperties: false
          type: object
          required:
            - field
            - message
          properties:
            field:
              type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - required_actions
            - message
          properties:
            required_actions:
              description: The `required_actions` codes holding this back.
              type: array
              items:
                type: string
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - available_percent
            - message
          properties:
            available_percent:
              $ref: '#/components/schemas/Percent'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - agreement
            - current_agreement
            - message
          properties:
            agreement:
              $ref: '#/components/schemas/AgreementLink'
            current_agreement:
              $ref: '#/components/schemas/AgreementLink'
            message:
              type: string
        - additionalProperties: false
          type: object
          required:
            - legal_entity
            - message
          properties:
            legal_entity:
              $ref: '#/components/schemas/LegalEntityLink'
            message:
              type: string
    HostedLink:
      description: >-
        A page a person opens, on HTTPS in production. Its URL can carry a
        token, so treat it as a secret.
      additionalProperties: false
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          format: uri
          type: string
        expires_at:
          anyOf:
            - format: date-time
              pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$
              type: string
            - type: 'null'
    Percent:
      pattern: ^\d+(\.\d+)?$
      description: 'A percentage as a decimal string: `"25.00"` is 25%.'
      type: string
    LegalEntityLink:
      additionalProperties: false
      type: object
      required:
        - _link
        - _type
        - id
      properties:
        _link:
          pattern: ^/
          type: string
        _type:
          const: legal_entity
          type: string
        id:
          type: string
      x-link-target:
        resource: legal_entity
        kind: resource
        is_published: true
        views:
          - full
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.