Adyen notifyShopper API

openapi: 3.2.0
info:
  version: '68'
  x-publicVersion: true
  title: Adyen Recurring Notify Shopper API
  description: "The Recurring APIs allow you to manage and remove your tokens or saved payment details. Tokens should be created with validation during a payment request.\n\nFor more information, refer to our [Tokenization documentation](https://docs.adyen.com/online-payments/tokenization).\n## Authentication\nYou need an [API credential](https://docs.adyen.com/development-resources/api-credentials) to authenticate to the API.\n\nIf using an API key, 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@Company.YOUR_COMPANY_ACCOUNT\":\"YOUR_BASIC_AUTHENTICATION_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\n\n## Versioning\nRecurring 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://pal-test.adyen.com/pal/servlet/Recurring/v68/disable\n```\n\n## Going live\n\nTo authenticate to the live endpoints, you need an [API credential](https://docs.adyen.com/development-resources/api-credentials) from your live Customer Area.\n\nThe live endpoint URLs contain a prefix which is unique to your company account:\n```\n\nhttps://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Recurring/v68/disable\n```\n\nGet your `{PREFIX}` from your live Customer Area under **Developers** > **API URLs** > **Prefix**."
  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/Recurring/v68
tags:
- name: notifyShopper
paths:
  /notifyShopper:
    post:
      tags:
      - notifyShopper
      summary: Adyen Ask Issuer to Notify the Shopper
      description: Sends a request to the issuer so they can inform the shopper about the upcoming recurring payment. This endpoint is used only for local acquiring in India. For more information, refer to [Recurring card payments in India](https://docs.adyen.com/payment-methods/cards/cards-recurring-india).
      operationId: post-notifyShopper
      x-sortIndex: 4
      x-methodName: notifyShopper
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              notifyShopperOfUpcomingRecurringPayment:
                $ref: '#/components/examples/post-notifyShopper-notifyShopperOfUpcomingRecurringPayment'
            schema:
              $ref: '#/components/schemas/NotifyShopperRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                notifyShopperOfUpcomingRecurringPayment:
                  $ref: '#/components/examples/post-notifyShopper-notifyShopperOfUpcomingRecurringPayment-200'
              schema:
                $ref: '#/components/schemas/NotifyShopperResult'
          description: OK - the request has succeeded.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-notifyShopper400Example:
                  summary: Default post-notifyShopper 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-notifyShopper401Example:
                  summary: Default post-notifyShopper 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-notifyShopper403Example:
                  summary: Default post-notifyShopper 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.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-notifyShopper422Example:
                  summary: Default post-notifyShopper 422 response
                  x-microcks-default: true
                  value:
                    additionalData: {}
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-notifyShopper500Example:
                  summary: Default post-notifyShopper 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:
    NotifyShopperResult:
      properties:
        displayedReference:
          description: Reference of Pre-debit notification that is displayed to the shopper
          type: string
        message:
          description: A simple description of the `resultCode`.
          type: string
        pspReference:
          description: The unique reference that is associated with the request.
          type: string
        reference:
          description: Reference of Pre-debit notification sent in my the merchant
          type: string
        resultCode:
          description: The code indicating the status of notification.
          type: string
        shopperNotificationReference:
          description: The unique reference for the request sent downstream.
          type: string
        storedPaymentMethodId:
          description: This is the recurringDetailReference returned in the response when token was created
          type: string
      type: object
    NotifyShopperRequest:
      properties:
        amount:
          description: The amount of the upcoming payment.
          $ref: '#/components/schemas/Amount'
        billingDate:
          description: Date on which the subscription amount will be debited from the shopper. In YYYY-MM-DD format
          type: string
        billingSequenceNumber:
          description: Sequence of the debit. Depends on Frequency and Billing Attempts Rule.
          type: string
        displayedReference:
          description: Reference of Pre-debit notification that is displayed to the shopper. Optional field. Maps to reference if missing
          type: string
        merchantAccount:
          description: The merchant account identifier with which you want to process the transaction.
          type: string
        recurringDetailReference:
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string
        reference:
          description: Pre-debit notification reference sent by the merchant. This is a mandatory field
          type: string
        shopperReference:
          description: 'The ID that uniquely identifies the shopper.


            This `shopperReference` must be the same as the `shopperReference` used in the initial payment.'
          type: string
        storedPaymentMethodId:
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string
      required:
      - merchantAccount
      - shopperReference
      - amount
      - reference
      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
    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-notifyShopper-notifyShopperOfUpcomingRecurringPayment-200:
      summary: Example response for request 'notifyShopper'
      value:
        message: Request Processed Successfully
        resultCode: Success
        shopperNotificationReference: '9915003646742627'
        storedPaymentMethodId: '8415995487234100'
        pspReference: M5N7TQ4TG5PFWR50
        reference: Example reference
        displayedReference: exampleDisplayedReference
    post-notifyShopper-notifyShopperOfUpcomingRecurringPayment:
      summary: Request issuer to notify shopper of upcoming recurring payment
      value:
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        storedPaymentMethodId: '8415995487234100'
        shopperReference: YOUR_SHOPPER_REFERENCE
        amount:
          currency: INR
          value: 1000
        billingDate: '2021-03-16'
        reference: Example reference
        displayedReference: exampleDisplayedReference
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http