openapi: 3.2.0
info:
  version: '46'
  x-publicVersion: true
  title: Adyen Stored Value Check Balance API
  description: A set of API endpoints to manage stored value products.
  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://pal-test.adyen.com/pal/servlet/StoredValue/v46
tags:
- name: Check Balance
paths:
  /checkBalance:
    post:
      tags:
      - Check Balance
      summary: Adyen Checks the Balance
      description: Checks the balance of the provided payment method.
      operationId: post-checkBalance
      x-groupName: General
      x-sortIndex: 0
      x-methodName: checkBalance
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StoredValueBalanceCheckRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredValueBalanceCheckResponse'
              examples:
                post-checkBalance200Example:
                  summary: Default post-checkBalance 200 response
                  x-microcks-default: true
                  value:
                    currentBalance: example_value
                    pspReference: REF-001
                    refusalReason: REF-001
                    resultCode: Success
                    thirdPartyRefusalReason: REF-001
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-checkBalance400Example:
                  summary: Default post-checkBalance 400 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-checkBalance401Example:
                  summary: Default post-checkBalance 401 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-checkBalance403Example:
                  summary: Default post-checkBalance 403 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-checkBalance500Example:
                  summary: Default post-checkBalance 500 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    StoredValueBalanceCheckRequest:
      properties:
        amount:
          description: The amount information for the transaction.
          $ref: '#/components/schemas/Amount'
        merchantAccount:
          description: The merchant account identifier, with which you want to process the transaction.
          type: string
        paymentMethod:
          additionalProperties:
            type: string
          description: The collection that contains the type of the payment method and its specific information if available
          type: object
        recurringDetailReference:
          type: string
        reference:
          description: 'The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.

            If you need to provide multiple references for a transaction, separate them with hyphens ("-").

            Maximum length: 80 characters.'
          type: string
        shopperInteraction:
          description: 'Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer.

            For the web service API, Adyen assumes Ecommerce shopper interaction by default.


            This field has the following possible values:

            * `Ecommerce` - Online transactions where the cardholder is present (online). For better authorisation rates, we recommend sending the card security code (CSC) along with the request.

            * `ContAuth` - Card on file and/or subscription transactions, where the cardholder is known to the merchant (returning customer). If the shopper is present (online), you can supply also the CSC to improve authorisation (one-click payment).

            * `Moto` - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone.

            * `POS` - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal.'
          enum:
          - Ecommerce
          - ContAuth
          - Moto
          - POS
          type: string
        shopperReference:
          type: string
        store:
          description: The physical store, for which this payment is processed.
          maxLength: 16
          minLength: 1
          type: string
      required:
      - merchantAccount
      - reference
      - paymentMethod
      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
    ServiceError:
      properties:
        additionalData:
          x-addedInVersion: '46'
          additionalProperties:
            type: string
          description: Contains additional information about the payment. Some data fields are included only if you select them first. Go to **Customer Area** > **Developers** > **Additional data**.
          type: object
        errorCode:
          description: The error code mapped to the error message.
          type: string
        errorType:
          description: The category of the error.
          type: string
        message:
          description: A short explanation of the issue.
          type: string
        pspReference:
          description: The PSP reference of the payment.
          type: string
        status:
          description: The HTTP response status.
          format: int32
          type: integer
      type: object
    StoredValueBalanceCheckResponse:
      properties:
        currentBalance:
          description: The balance currently on the payment method.
          $ref: '#/components/schemas/Amount'
        pspReference:
          description: Adyen's 16-character string reference associated with the transaction/request. This value is globally unique; quote it when communicating with us about this request.
          type: string
        refusalReason:
          description: 'If the transaction is refused or an error occurs, this field holds Adyen''s mapped reason for the refusal or a description of the error.


            When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values.'
          type: string
        resultCode:
          description: "The result of the payment. Possible values:\n\n* **Success** – The operation has been completed successfully. \n* **Refused** – The operation was refused. The reason is given in the `refusalReason` field. \n* **Error** – There was an error when the operation was processed. The reason is given in the `refusalReason` field. \n* **NotEnoughBalance** – The amount on the payment method is lower than the amount given in the request. Only applicable to balance checks. \n"
          enum:
          - Success
          - Refused
          - Error
          - NotEnoughBalance
          type: string
        thirdPartyRefusalReason:
          description: Raw refusal reason received from the third party, where available
          type: string
      type: object
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
x-groups:
- General