Adyen Grants API

openapi: 3.2.0
info:
  version: '4'
  x-publicVersion: true
  title: Adyen Transfers Grants API
  description: ">Versions 1 and 2 of the Transfers API are deprecated. If you are just starting your implementation, use the latest version.\n\nThis API provides endpoints that you can use to transfer funds, whether when [paying out to a transfer instrument](https://docs.adyen.com/marketplaces-and-platforms/payout-to-users/on-demand-payouts), [sending funds to third parties](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/send-receive-funds) for users with business bank accounts, or to [request a payout for a grant offer](https://docs.adyen.com/marketplaces-and-platforms/capital). The API also supports use cases for [getting transactions for business bank accounts](https://docs.adyen.com/marketplaces-and-platforms/business-accounts/transactions-api) and getting [grants and its outstanding balances](https://docs.adyen.com/marketplaces-and-platforms/capital#get-balances). .\n\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-H \"Content-Type: application/json\" \\\n-U \"ws@BalancePlatform.YOUR_BALANCE_PLATFORM\":\"YOUR_WS_PASSWORD\" \\\n...\n```\n## Roles and permissions\nTo use the Transfers API, you need an additional role for your API credential. Transfers must also be enabled for the source balance account. Your Adyen contact will set up the roles and permissions for you.\n## Versioning\nThe Transfers API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://balanceplatform-api-test.adyen.com/btl/v4/transfers\n```\n## Going live\nWhen going live, your Adyen contact will provide your API credential for the live environment. You can then use the username and password to send requests to `https://balanceplatform-api-live.adyen.com/btl/v4`.\n\n"
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://balanceplatform-api-test.adyen.com/btl/v4
tags:
- name: Grants
paths:
  /grants:
    get:
      tags:
      - Grants
      summary: Adyen Get a Capital Account
      description: Returns a list of grants with status and outstanding balances.
      x-addedInVersion: '3'
      operationId: get-grants
      x-sortIndex: 2
      x-methodName: getCapitalAccount
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The counterparty account holder id.
        name: counterpartyAccountHolderId
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapitalGrants'
              examples:
                get-grants200Example:
                  summary: Default get-grants 200 response
                  x-microcks-default: true
                  value:
                    grants:
                    - example_value
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants400Example:
                  summary: Default get-grants 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants401Example:
                  summary: Default get-grants 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants403Example:
                  summary: Default get-grants 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants404Example:
                  summary: Default get-grants 404 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Not Found - the payment was not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants422Example:
                  summary: Default get-grants 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants500Example:
                  summary: Default get-grants 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      tags:
      - Grants
      summary: Adyen Request a Grant Payout
      description: Requests the payout of the selected grant offer.
      x-addedInVersion: '3'
      operationId: post-grants
      x-sortIndex: 1
      x-methodName: requestGrantPayout
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              requestGrant:
                $ref: '#/components/examples/post-grants-requestGrant'
            schema:
              $ref: '#/components/schemas/CapitalGrantInfo'
      responses:
        '200':
          content:
            application/json:
              examples:
                requestGrant:
                  $ref: '#/components/examples/post-grants-requestGrant-200'
              schema:
                $ref: '#/components/schemas/CapitalGrant'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants400Example:
                  summary: Default post-grants 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants401Example:
                  summary: Default post-grants 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants403Example:
                  summary: Default post-grants 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants404Example:
                  summary: Default post-grants 404 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Not Found - the payment was not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants422Example:
                  summary: Default post-grants 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                post-grants500Example:
                  summary: Default post-grants 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /grants/{id}:
    get:
      tags:
      - Grants
      summary: Adyen Get Grant Reference Details
      description: Returns the details of a capital account specified in the path.
      x-addedInVersion: '3'
      operationId: get-grants-id
      x-sortIndex: 3
      x-methodName: getGrantReferenceDetails
      security:
      - clientKey: []
      - BasicAuth: []
      - ApiKeyAuth: []
      parameters:
      - description: The unique identifier of the grant.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CapitalGrant'
              examples:
                get-grants-id200Example:
                  summary: Default get-grants-id 200 response
                  x-microcks-default: true
                  value:
                    amount: 1000
                    balances: example_value
                    counterparty: example_value
                    fee: example_value
                    grantAccountId: '500123'
                    grantOfferId: '500123'
                    id: '500123'
                    repayment: example_value
                    status: Pending
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id400Example:
                  summary: Default get-grants-id 400 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id401Example:
                  summary: Default get-grants-id 401 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id403Example:
                  summary: Default get-grants-id 403 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Forbidden - insufficient permissions to process the request.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id404Example:
                  summary: Default get-grants-id 404 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Not Found - the payment was not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id422Example:
                  summary: Default get-grants-id 422 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
              examples:
                get-grants-id500Example:
                  summary: Default get-grants-id 500 response
                  x-microcks-default: true
                  value:
                    detail: example_value
                    errorCode: CODE123
                    instance: example_value
                    invalidFields:
                    - example_value
                    requestId: '500123'
                    response: example_value
                    status: 500
                    title: example_value
                    type: standard
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Fee:
      properties:
        amount:
          description: An object containing the fee amount.
          $ref: '#/components/schemas/Amount'
      required:
      - amount
      type: object
    Counterparty:
      properties:
        accountHolderId:
          description: The identifier of the receiving account holder. The payout will default to the primary balance account of this account holder if no `balanceAccountId` is provided.
          type: string
        balanceAccountId:
          description: The identifier of the balance account that belongs to the receiving account holder.
          type: string
        transferInstrumentId:
          description: The identifier of the transfer instrument that belongs to the legal entity of the account holder.
          type: string
      type: object
    CapitalGrantInfo:
      properties:
        counterparty:
          description: An object containing the details of the receiving party of the grant. Setting either an `accountHolderId`, `balanceAccountId`, or both is required.
          $ref: '#/components/schemas/Counterparty'
        grantAccountId:
          description: The identifier of the grant account used for the grant.
          type: string
        grantOfferId:
          description: The identifier of the grant offer that has been selected and from which the grant details will be used.
          type: string
      required:
      - grantAccountId
      - grantOfferId
      type: object
    CapitalGrants:
      properties:
        grants:
          description: The unique identifier of the grant.
          items:
            $ref: '#/components/schemas/CapitalGrant'
          type: array
      required:
      - grants
      type: object
    Repayment:
      properties:
        basisPoints:
          description: The repayment that is deducted daily from incoming net volume, in [basis points](https://www.investopedia.com/terms/b/basispoint.asp).
          format: int32
          type: integer
        term:
          description: An object containing the details of the configuration for repayment term.
          $ref: '#/components/schemas/RepaymentTerm'
        threshold:
          description: An object containing the details of the 30-day repayment threshold.
          $ref: '#/components/schemas/ThresholdRepayment'
      required:
      - basisPoints
      type: object
    InvalidField:
      properties:
        message:
          description: Description of the validation error.
          type: string
        name:
          description: The field that has an invalid value.
          type: string
        value:
          description: The invalid value.
          type: string
      required:
      - name
      - value
      - message
      type: object
    CapitalGrant:
      properties:
        amount:
          description: An object containing the amount of the grant, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          $ref: '#/components/schemas/Amount'
        balances:
          description: An object containing the details of the existing grant.
          $ref: '#/components/schemas/CapitalBalance'
        counterparty:
          description: An object containing the details of the receiving party of the grant. Setting either an `accountHolderId`, `balanceAccountId`, or both is required.
          $ref: '#/components/schemas/Counterparty'
        fee:
          description: An object containing the fee currency and value, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          $ref: '#/components/schemas/Fee'
        grantAccountId:
          description: The identifier of the grant account used for the grant.
          type: string
        grantOfferId:
          description: The identifier of the grant offer that has been selected and from which the grant details will be used.
          type: string
        id:
          description: The identifier of the grant reference.
          type: string
        repayment:
          description: An object containing the details of the 30-day repayment threshold.
          $ref: '#/components/schemas/Repayment'
        status:
          description: 'The current status of the grant. Possible values: **Pending**, **Active**, **Repaid**.'
          enum:
          - Pending
          - Active
          - Repaid
          type: string
      required:
      - grantAccountId
      - grantOfferId
      - id
      - status
      - balances
      type: object
    RestServiceError:
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        errorCode:
          description: A code that identifies the problem type.
          type: string
        instance:
          description: A unique URI that identifies the specific occurrence of the problem.
          type: string
        invalidFields:
          description: Detailed explanation of each validation error, when applicable.
          items:
            $ref: '#/components/schemas/InvalidField'
          type: array
        requestId:
          description: A unique reference for the request, essentially the same as `pspReference`.
          type: string
        response:
          description: JSON response payload.
          $ref: '#/components/schemas/JSONObject'
        status:
          description: The HTTP status code.
          format: int32
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
          type: string
      required:
      - type
      - errorCode
      - title
      - detail
      - status
      type: object
    ThresholdRepayment:
      properties:
        amount:
          description: The amount to be repaid on a 30-day basis.
          $ref: '#/components/schemas/Amount'
      required:
      - amount
      type: object
    RepaymentTerm:
      properties:
        estimatedDays:
          description: The estimated term for repaying the grant, in days.
          format: int32
          type: integer
        maximumDays:
          description: The maximum term for repaying the grant, in days. Only applies when `contractType` is **loan**.
          format: int32
          type: integer
      required:
      - estimatedDays
      type: object
    CapitalBalance:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          type: string
        fee:
          description: Fee amount.
          format: int64
          type: integer
        principal:
          description: Principal amount.
          format: int64
          type: integer
        total:
          description: Total amount. A sum of principal amount and fee amount.
          format: int64
          type: integer
      required:
      - principal
      - fee
      - total
      - currency
      type: object
    JSONObject:
      type: object
    Amount:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
  examples:
    post-grants-requestGrant-200:
      summary: Grant payout requested
      description: Example response for requesting grant payout
      value:
        id: GR00000000000000000000001
        grantAccountId: CG00000000000000000000001
        grantOfferId: '0000000000000001'
        counterparty:
          accountHolderId: AH00000000000000000000001
          balanceAccountId: BA00000000000000000000001
        amount:
          currency: EUR
          value: 1000000
        fee:
          amount:
            value: 120000
            currency: EUR
        balances:
          currency: EUR
          fee: 120000
          principal: 1000000
          total: 1120000
        repayment:
          basisPoints: 1400
        status: Pending
    post-grants-requestGrant:
      summary: Request grant payout to a balance account
      description: Example request for grant payout
      value:
        grantAccountId: CG00000000000000000000001
        grantOfferId: '0000000000000001'
        counterparty:
          accountHolderId: AH00000000000000000000001
          balanceAccountId: BA00000000000000000000001
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
    clientKey:
      in: query
      name: clientKey
      type: apiKey