# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Storefront API V1 Paymentauthentication API
  version: 1.0.0
extends: openapi/optimizely-paymentauthentication-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/api/v1/paymentauthentication'].post
  update:
    x-apievangelist-phrasing:
      intent: Start payment authentication for a card
      effect: write
      questions:
      - How do I run payment authentication on a card before placing a storefront order?
      - Can I authenticate a saved payment profile instead of a newly entered card?
      - What card and cart details does the payment authentication request expect?
      instructions:
      - text: Authenticate card {cardNumber} expiring {expirationMonth}/{expirationYear} for {orderAmount} {currency} on cart {cartId}.
        slots:
          cardNumber: requestBody.cardNumber
          expirationMonth: requestBody.expirationMonth
          expirationYear: requestBody.expirationYear
          orderAmount: requestBody.orderAmount
          currency: requestBody.currency
          cartId: requestBody.cartId
      - text: Resume 3-D Secure authentication for web order {webOrderNumber} and return to {returnUrl}.
        slots:
          webOrderNumber: requestBody.webOrderNumber
          returnUrl: requestBody.returnUrl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/threedsnotify'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a 3-D Secure notification
      effect: write
      questions:
      - Where does the storefront receive the 3-D Secure notify post after a card check?
      - Which endpoint handles the 3DS notification step of payment authentication?
      instructions:
      - text: Post the 3-D Secure notification back to the storefront.
      - text: Deliver the 3DS notify message to complete the card check.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/adyenwebhook'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive a payment gateway webhook notification
      effect: write
      questions:
      - Which endpoint accepts the payment gateway's webhook notifications for the storefront?
      - Does the gateway webhook receiver distinguish live notifications from test ones?
      instructions:
      - text: Forward gateway notification items {notificationItems} to the storefront webhook.
        slots:
          notificationItems: requestBody.notificationItems
      - text: Send a payment gateway webhook batch flagged live as {live}.
        slots:
          live: requestBody.live
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/adyenpaymentdetails'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit additional gateway payment details
      effect: write
      questions:
      - How do I pass the extra details the gateway asks for after the first payment step?
      - Can I submit follow-up payment details to finish a gateway payment?
      instructions:
      - text: Submit gateway payment details {details}.
        slots:
          details: requestBody.details
      - text: Send the follow-up payment details {details} so the gateway can complete the payment.
        slots:
          details: requestBody.details
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/adyenpayment'].post
  update:
    x-apievangelist-phrasing:
      intent: Make a payment through the payment gateway
      effect: write
      questions:
      - Which endpoint starts a new payment through the storefront's payment gateway integration?
      - Can the storefront create a gateway payment directly through this API?
      instructions:
      - text: Create a gateway payment for the current checkout.
      - text: Start a new payment through the payment gateway integration.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/adyenrefund'].post
  update:
    x-apievangelist-phrasing:
      intent: Refund a gateway payment
      effect: destructive
      questions:
      - How do I refund an order that was paid through the payment gateway?
      - Can I refund a specific amount against a PSP reference?
      instructions:
      - text: Refund {amount} on payment {pspReference} for order {orderNumber}.
        slots:
          amount: requestBody.amount
          pspReference: requestBody.pspReference
          orderNumber: requestBody.orderNumber
      - text: Issue a gateway refund for order {orderNumber}.
        slots:
          orderNumber: requestBody.orderNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/threedschallengeresponse'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a 3-D Secure challenge response
      effect: write
      questions:
      - Where does the shopper's answer to a 3-D Secure challenge get posted?
      - Which endpoint receives the 3DS challenge response?
      instructions:
      - text: Post the shopper's 3-D Secure challenge response.
      - text: Submit the completed 3DS challenge result for verification.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/threedscallback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle a 3-D Secure callback
      effect: write
      questions:
      - Which URL handles the 3-D Secure callback after the issuer finishes?
      - Is there a separate callback endpoint for 3DS besides the challenge response?
      instructions:
      - text: Send the 3-D Secure callback to the storefront.
      - text: Deliver the issuer's 3DS callback to finish authentication.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/paymentauthentication/bnplcallback'].post
  update:
    x-apievangelist-phrasing:
      intent: Handle a buy now, pay later callback
      effect: write
      questions:
      - Where does the storefront receive buy now, pay later payment callbacks?
      - Which endpoint handles the BNPL callback after a shopper finishes checkout?
      instructions:
      - text: Post the buy now, pay later callback to the storefront.
      - text: Deliver the BNPL provider's callback for the current payment.
      method: generated
      generated: '2026-09-26'