Adyen Loyalty API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute Loyalty API
  description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\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-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account 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://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
  x-timestamp: '2023-05-30T15:27:20Z'
  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://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Loyalty
paths:
  /loyalty:
    post:
      description: It conveys Information related to the Loyalty transaction to process. Content of the Loyalty Request message.
      summary: Adyen Loyalty Request
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoyaltyRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoyaltyResponse'
              examples:
                operation200Example:
                  summary: Default operation 200 response
                  x-microcks-default: true
                  value:
                    Response: example_value
                    SaleData: example_value
                    POIData: example_value
                    LoyaltyResult:
                    - example_value
                    PaymentReceipt:
                    - example_value
          description: It conveys Information related to the Loyalty transaction processed by the POI System. Content of the Loyalty Response message.
      tags:
      - Loyalty
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    POIData:
      type: object
      description: In the Message Response, identification of the POI transaction. Data related to the POI System.
      properties:
        POITransactionID:
          $ref: '#/components/schemas/TransactionIDType'
        POIReconciliationID:
          type: integer
          description: If Result is Success.
      required:
      - POITransactionID
    LoyaltyTransaction:
      type: object
      properties:
        LoyaltyTransactionType:
          $ref: '#/components/schemas/LoyaltyTransactionType'
        Currency:
          type: string
          pattern: ^[A-Z]{3,3}$
        TotalAmount:
          type: number
          maximum: 99999999.999999
          minimum: 0
        OriginalPOITransaction:
          $ref: '#/components/schemas/OriginalPOITransaction'
        TransactionConditions:
          $ref: '#/components/schemas/TransactionConditions'
        SaleItem:
          type: array
          items:
            $ref: '#/components/schemas/SaleItem'
      required:
      - LoyaltyTransactionType
    LoyaltyAccountID:
      type: object
      description: In the Payment or the Loyalty Request message, it allows to identify the loyalty account by the Sale Terminal instead of the POI Terminal (e.g. because the account identification is a bar-code read by the Cashier on a scanner device). Identification of a Loyalty account.
      properties:
        EntryMode:
          $ref: '#/components/schemas/EntryMode'
        IdentificationType:
          $ref: '#/components/schemas/IdentificationType'
        IdentificationSupport:
          $ref: '#/components/schemas/IdentificationSupport'
        LoyaltyID:
          type: string
      required:
      - EntryMode
      - IdentificationType
      - LoyaltyID
    ErrorCondition:
      type: string
      enum:
      - Aborted
      - Busy
      - Cancel
      - DeviceOut
      - InProgress
      - InsertedCard
      - InvalidCard
      - LoggedOut
      - MessageFormat
      - NotAllowed
      - NotFound
      - PaymentRestriction
      - Refusal
      - UnavailableDevice
      - UnavailableService
      - UnreachableHost
      - WrongPIN
    TransactionConditions:
      type: object
      description: Conditions on which the transaction must be processed.
      properties:
        AllowedPaymentBrand:
          type: array
          items:
            type: string
            pattern: ^.+$
            description: Restrict brand if data sent.
        AcquirerID:
          type: array
          items:
            type: integer
            description: Restrict to these Acquirer if present.
        DebitPreferredFlag:
          type: boolean
          description: The preferred type of payment is a debit transaction rather a credit transaction.
        AllowedLoyaltyBrand:
          type: array
          items:
            type: string
            pattern: ^.+$
            description: Restrict brand if data sent.
        LoyaltyHandling:
          $ref: '#/components/schemas/LoyaltyHandling'
        CustomerLanguage:
          type: string
          pattern: ^[a-z]{2,2}$
          description: If the language is selected by the Sale System before the request to the POI.
        ForceOnlineFlag:
          type: boolean
          default: false
          description: Go online if data sent.
        ForceEntryMode:
          $ref: '#/components/schemas/ForceEntryMode'
        MerchantCategoryCode:
          type: string
          pattern: ^.{3,4}$
          description: The payment implies a specific MCC.
    EntryMode:
      type: array
      items:
        type: string
        enum:
        - Contactless
        - File
        - ICC
        - Keyed
        - MagStripe
        - Manual
        - Mobile
        - RFID
        - Scanned
        - SynchronousICC
        - Tapped
    LoyaltyUnit:
      type: string
      enum:
      - Monetary
      - Point
    Rebates:
      type: object
      properties:
        TotalRebate:
          type: number
          maximum: 99999999.999999
          minimum: 0
        RebateLabel:
          type: string
          pattern: ^.+$
        SaleItemRebate:
          type: array
          items:
            $ref: '#/components/schemas/SaleItemRebate'
    Response:
      type: object
      description: If Result is Success, ErrorCondition is absent or not used in the processing of the message. In the other cases, the ErrorCondition has to be present and can refine the processing of the message response. AdditionalResponse gives more information about the success or the failure of the message request processing, for logging without real time involvements. Result of a message request processing.
      properties:
        Result:
          $ref: '#/components/schemas/Result'
        ErrorCondition:
          $ref: '#/components/schemas/ErrorCondition'
        AdditionalResponse:
          type: string
          pattern: ^.+$
          description: If present, the POI logs it for further examination.
      required:
      - Result
    TransactionIDType:
      type: object
      description: Identification of a transaction for the Sale System or the POI System.
      properties:
        TransactionID:
          type: string
          pattern: ^.+$
        TimeStamp:
          type: string
          format: date-time
      required:
      - TransactionID
      - TimeStamp
    Result:
      type: string
      enum:
      - Failure
      - Partial
      - Success
    SaleItem:
      type: object
      description: In loyalty or value added payment card transaction, the items of the sale are entering in the processing of the transaction. Sale items of a transaction.
      properties:
        ItemID:
          type: integer
          description: Item identification inside a transaction (0 to n).
        ProductCode:
          type: integer
          minimum: 1
          maximum: 20
          description: Product code of item purchased with the transaction.
        EanUpc:
          type: integer
          description: If data sent, POI has to store it and send it if the host protocol allows it.
        UnitOfMeasure:
          $ref: '#/components/schemas/UnitOfMeasure'
        Quantity:
          type: string
          description: If data sent, POI has to store it and send it if the host protocol allows it.
        UnitPrice:
          type: number
          maximum: 99999999.999999
          minimum: 0
          description: if Quantity present.
        ItemAmount:
          type: number
          maximum: 99999999.999999
          minimum: 0
          description: Total amount of the item line.
        TaxCode:
          type: integer
          description: If data sent, POI has to store it and send it if the host protocol allows it.
        SaleChannel:
          type: integer
          description: If data sent, POI has to store it and send it if the host protocol allows it.
        ProductLabel:
          type: string
          pattern: ^.+$
        AdditionalProductInfo:
          type: string
          pattern: ^.+$
          description: If data sent, POI has to store it and send it if the host protocol allows it.
      required:
      - ItemID
      - ProductCode
      - ItemAmount
    CharacterWidth:
      type: string
      enum:
      - DoubleWidth
      - SingleWidth
    OutputContent:
      type: object
      description: This is a sequence of elements if they have different formats. Content to display or print.
      properties:
        OutputFormat:
          $ref: '#/components/schemas/OutputFormat'
        PredefinedContent:
          $ref: '#/components/schemas/PredefinedContent'
        OutputText:
          type: array
          items:
            $ref: '#/components/schemas/OutputText'
        OutputXHTML:
          type: string
          format: byte
          pattern: ^.{0,262144}$
          description: Mandatory, if OutputFormat is XHTML, not allowed otherwise.
        OutputBarcode:
          $ref: '#/components/schemas/OutputBarcode'
      required:
      - OutputFormat
    IdentificationType:
      type: string
      enum:
      - AccountNumber
      - BarCode
      - ISOTrack2
      - PAN
      - PhoneNumber
    BarcodeType:
      type: string
      enum:
      - Code128
      - Code25
      - EAN13
      - EAN8
      - PDF417
      - QRCode
      - UPCA
    Color:
      type: string
      enum:
      - Black
      - Blue
      - Cyan
      - Green
      - Magenta
      - Red
      - White
      - Yellow
    Alignment:
      type: string
      enum:
      - Centred
      - Justified
      - Left
      - Right
    SaleItemRebate:
      type: object
      description: To be differentiated from the award which is the amount or quantity earned on the loyalty account. The awarded amount that is attached to an item as a rebate.
      properties:
        ItemID:
          type: integer
          description: Item identification inside a transaction (0 to n).
        ProductCode:
          type: integer
          minimum: 1
          maximum: 20
          description: Product code of item purchased with the transaction.
        EanUpc:
          type: integer
        UnitOfMeasure:
          $ref: '#/components/schemas/UnitOfMeasure'
        Quantity:
          type: string
          description: if rebate is additional units.
        ItemAmount:
          type: number
          maximum: 99999999.999999
          minimum: 0
          description: if rebate on the line item amount.
        RebateLabel:
          type: string
          pattern: ^.+$
          description: If provided by the Acquirer.
      required:
      - ItemID
      - ProductCode
    OutputFormat:
      type: string
      enum:
      - BarCode
      - MessageRef
      - Text
      - XHTML
    SaleData:
      type: object
      description: Data associated to the Sale System, with a particular value during the processing of the payment by the POI, including the cards acquisition. Data related to the Sale System.
      properties:
        OperatorID:
          type: string
          pattern: ^.+$
        OperatorLanguage:
          type: string
          pattern: ^[a-z]{2,2}$
          description: if different from the Login.
        ShiftNumber:
          type: string
          pattern: ^.+$
          description: if different from the Login and  see Login .SaleData.
        SaleTransactionID:
          $ref: '#/components/schemas/TransactionIDType'
        SaleReferenceID:
          type: string
          pattern: ^.+$
          description: If payment reservation.
        SaleTerminalData:
          $ref: '#/components/schemas/SaleTerminalData'
        TokenRequestedType:
          $ref: '#/components/schemas/TokenRequestedType'
        CustomerOrderID:
          type: string
          pattern: ^.+$
          description: Additional and optional identification of a customer order.
        CustomerOrderReq:
          $ref: '#/components/schemas/CustomerOrderReq'
        SaleToPOIData:
          type: string
          pattern: ^.+$
          description: Stored with the transaction.
        SaleToAcquirerData:
          type: string
          pattern: ^.+$
          description: Send to the Acquirer if present.
        SaleToIssuerData:
          $ref: '#/components/schemas/SaleToIssuerData'
      required:
      - SaleTransactionID
    CharacterStyle:
      type: string
      enum:
      - Bold
      - Italic
      - Normal
      - Underline
    UnitOfMeasure:
      type: string
      enum:
      - Case
      - Centilitre
      - Centimetre
      - Foot
      - Gram
      - Inch
      - Kilogram
      - Kilometre
      - Litre
      - Meter
      - Mile
      - Other
      - Ounce
      - Pint
      - Pound
      - Quart
      - UKGallon
      - USGallon
      - Yard
    CharacterHeight:
      type: string
      enum:
      - DoubleHeight
      - HalfHeight
      - SingleHeight
    LoyaltyResult:
      type: object
      description: In the Message Response, the result of each loyalty brand transaction. Data related to the result of a processed loyalty transaction.
      properties:
        LoyaltyAccount:
          $ref: '#/components/schemas/LoyaltyAccount'
        CurrentBalance:
          type: number
          maximum: 99999999.999999
          minimum: 0
          description: if known (provided by the card or an external host).
        LoyaltyAmount:
          $ref: '#/components/schemas/LoyaltyAmount'
        LoyaltyAcquirerData:
          $ref: '#/components/schemas/LoyaltyAcquirerData'
        Rebates:
          $ref: '#/components/schemas/Rebates'
      required:
      - LoyaltyAccount
    LoyaltyData:
      type: object
      description: In the Payment, Loyalty or Balance Inquiry Request message, it allows the Sale Terminal to send the identification of the loyalty account or an awarded amount or an amount to redeem to the loyalty account. Data related to a Loyalty program or account.
      properties:
        CardAcquisitionReference:
          $ref: '#/components/schemas/TransactionIDType'
        LoyaltyAccountID:
          $ref: '#/components/schemas/LoyaltyAccountID'
        LoyaltyAmount:
          $ref: '#/components/schemas/LoyaltyAmount'
    OutputBarcode:
      type: object
      properties:
        BarcodeType:
          $ref: '#/components/schemas/BarcodeType'
        BarcodeValue:
          type: string
          pattern: ^.+$
      required:
      - BarcodeValue
    ForceEntryMode:
      type: array
      items:
        type: string
        enum:
        - CheckReader
        - Contactless
        - File
        - ICC
        - Keyed
        - MagStripe
        - Manual
        - RFID
        - Scanned
        - SynchronousICC
        - Tapped
    OutputText:
      type: object
      description: It conveys Information related to the content of the text message and its format. All the data elements related to the format of the text to display or print are parameters valid for the whole Text content. Content of text message to display or print.
      properties:
        Text:
          type: string
        CharacterSet:
          type: integer
        Font:
          type: string
          pattern: ^.+$
        StartRow:
          type: integer
          minimum: 1
          maximum: 500
        StartColumn:
          type: integer
          minimum: 1
          maximum: 500
        Color:
          $ref: '#/components/schemas/Color'
        CharacterWidth:
          $ref: '#/components/schemas/CharacterWidth'
        CharacterHeight:
          $ref: '#/components/schemas/CharacterHeight'
        CharacterStyle:
          $ref: '#/components/schemas/CharacterStyle'
        Alignment:
          $ref: '#/components/schemas/Alignment'
        EndOfLineFlag:
          type: boolean
          default: true
      required:
      - Text
    DocumentQualifier:
      type: string
      enum:
      - CashierReceipt
      - CustomerReceipt
      - Document
      - Journal
      - SaleReceipt
      - Voucher
    PaymentReceipt:
      type: object
      description: If the payment receipts are printed by the Sale system and the POI or the Sale does not implement the Print exchange (Basic profile). Customer or Merchant payment receipt.
      properties:
        DocumentQualifier:
          $ref: '#/components/schemas/DocumentQualifier'
        IntegratedPrintFlag:
          type: boolean
          description: Type of the print integrated to other prints.
        RequiredSignatureFlag:
          type: boolean
          default: false
          description: Indicate that the cardholder payment receipt requires a physical signature by the Customer.
        OutputContent:
          $ref: '#/components/schemas/OutputContent'
      required:
      - DocumentQualifier
      - OutputContent
    TokenRequestedType:
      type: string
      enum:
      - Customer
      - Transaction
    LoyaltyTransactionType:
      type: string
      enum:
      - Award
      - AwardRefund
      - Rebate
      - RebateRefund
      - Redemption
      - RedemptionRefund
    LoyaltyRequest:
      type: object
      description: It conveys Information related to the Loyalty transaction to process. Content of the Loyalty Request message.
      properties:
        SaleData:
          $ref: '#/components/schemas/SaleData'
        LoyaltyTransaction:
          $ref: '#/components/schemas/LoyaltyTransaction'
        LoyaltyData:
          $ref: '#/components/schemas/LoyaltyData'
      required:
      - SaleData
      - LoyaltyTransaction
      - LoyaltyData
    LoyaltyAcquirerData:
      type: object
      properties:
        LoyaltyAcquirerID:
          type: string
          pattern: ^.+$
        ApprovalCode:
          type: string
          pattern: ^.+$
        LoyaltyTransactionID:
          $ref: '#/components/schemas/TransactionIDType'
        HostReconciliationID:
          type: string
          pattern: ^.+$
    OriginalPOITransaction:
      type: object
      description: In the Payment or the Loyalty Request message, it allows using the card of a previous CardAcquisition or Payment/Loyalty request. Identification of a previous POI transaction.
      properties:
        SaleID:
          type: string
          pattern: ^.+$
          description: Identification of a Sale System or a Sale Terminal for the Sale to POI protocol.
        POIID:
          type: string
          pattern: ^.+$
          description: If original transaction is coming from another POI.
        POITransactionID:
          $ref: '#/components/schemas/TransactionIDType'
        ReuseCardDataFlag:
          type: boolean
          default: true
          description: Indicate if the card data has to be got from a previous transaction.
        ApprovalCode:
          type: string
          pattern: ^.+$
          description: If referral.
        CustomerLanguage:
          type: string
          pattern: ^[a-z]{2,2}$
          description: If the language is selected by the Sale System before the request to the POI.
        AcquirerID:
          type: integer
          description: Restrict to these Acquirer if present.
        AmountValue:
          type: number
          maximum: 99999999.999999
          minimum: 0
        HostTransactionID:
          $ref: '#/components/schemas/TransactionIDType'
    PredefinedContent:
      type: object
      description: It conveys Information related to the predefined message. Reference of a predefined message to display or print.
      properties:
        ReferenceID:
          type: string
          pattern: ^.+$
          description: Identification of a predefined message to display or print.
        Language:
          type: string
          pattern: ^[a-z]{2,2}$
          description: Identification of a language.
      required:
      - ReferenceID
    SaleTerminalData:
      type: object
      description: In the Login Request, if a Sale Terminal is involved in the login. In other messages, when a logical device is out of order (SaleCapabilites), or when the other data have changed since or were not in the Login. Information related to the software and hardware feature of the Sale Terminal.
      properties:
        TotalsGroupID:
          type: string
          pattern: ^.{1,16}$
          description: If present, default value for all transaction.
    CustomerOrderReq:
      type: array
      items:
        type: string
        enum:
        - Both
        - Closed
        - Open
    SaleToIssuerData:
      type: object
      description: The POI System receives this information and sends it to the Acquirer for the Issuer without any change. Sale information intended for the Issuer.
      properties:
        StatementReference:
          type: string
          pattern: ^.+$
          description: Information to print on the bank statement.
    LoyaltyHandling:
      type: string
      enum:
      - Allowed
      - Forbidden
      - Processed
      - Proposed
      - Required
    IdentificationSupport:
      type: string
      enum:
      - HybridCard
      - LinkedCard
      - LoyaltyCard
      - NoCard
    LoyaltyResponse:
      type: object
      description: It conveys Information related to the Loyalty transaction processed by the POI System. Content of the Loyalty Response message.
      properties:
        Response:
          $ref: '#/components/schemas/Response'
        SaleData:
          $ref: '#/components/schemas/SaleData'
        POIData:
          $ref: '#/components/schemas/POIData'
        LoyaltyResult:
          type: array
          items:
            $ref: '#/components/schemas/LoyaltyResult'
        PaymentReceipt:
          type: array
          items:
            $ref: '#/components/schemas/PaymentReceipt'
      required:
      - Response
      - SaleData
      - POIData
    LoyaltyAccount:
      type: object
      description: This data structure conveys the identification of the account and the associated loyalty brand. Data related to a loyalty account processed in the transaction.
      properties:
        LoyaltyAccountID:
          $ref: '#/components/schemas/LoyaltyAccountID'
        LoyaltyBrand:
          type: string
          pattern: ^.+$
          description: If a card is analysed.
      required:
      - LoyaltyAccountID
    LoyaltyAmount:
      type: object
      description: An awarded amount or an amount to redeem to the loyalty account might be sent in the Payment request message. Amount of a loyalty account.
      properties:
        LoyaltyUnit:
          $ref: '#/components/schemas/LoyaltyUnit'
        Currency:
          type: string
          pattern: ^[A-Z]{3,3}$
        AmountValue:
          type: number
          maximum: 99999999.999999
          minimum: 0
      required:
      - AmountValue
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
x-groups:
- Account holders
- Accounts
- Verification