openapi: 3.0.2
info:
  x-logo:
    url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
  title: Primer Webhooks
  version: '2.4'
  description: Webhooks specifications for Primer API v2.4
servers:
  - url: https://api.sandbox.primer.io
  - url: https://api.primer.io
paths:
  /payment-status:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Payment Webhooks
      summary: Payment Status Update
      description: |
        Primer notifies you with a `PAYMENT.STATUS` webhook when a payment's status
        has been updated. This is especially useful for asyncronous processor Connections,
        which do not respond with an upfront authorization.

        The webhook events will arrive in the order that the payment status changes,
        for example you should expect a status of `PENDING`, then `AUTHORIZED`, then
        `SETTLED` (depending on how your workflow is set up).

        The webhook body contains the full payment object.
      operationId: payment_status_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              allOf:
                - $ref: '#/components/schemas/PaymentStatusWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: true
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: true
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

  /payment-refund:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Payment Webhooks
      summary: Payment Refund
      description: |
        Primer notifies you with a `PAYMENT.REFUND` Webhook when a refund request has been fully processed by a payment processor and the refund has reached a final state.

        Check the transaction with the most recent `transactionType: "REFUND"` in the `transactions` array:
        - if `processorStatus` is `SETTLED`, the refund was successful and the funds have been returned to the customer
        - if `processorStatus` is `FAILED`, the refund was unsuccessful

        Learn more about [how Primer handles webhooks](/docs/api-reference/get-started/configure-webhooks).

      operationId: payment_refund_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              allOf:
                - $ref: '#/components/schemas/PaymentRefundWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: true
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: true
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

  /workflow-run-failed:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Workflow Webhooks
      summary: Workflow Run Failed
      description: |
        Primer notifies you with a `WORKFLOW_RUN.FAILED` webhook when a workflow run does not complete successfully.

        This webhook is recommended if you use Capture or Cancel via Workflows. A workflow failure does not necessarily fail the payment or update the payment status, so this webhook is the signal you need to keep your own systems in sync when an automated capture or cancel does not succeed.

        For payment workflows, the payload does not contain payment data — only the Payment ID in the `triggerEventId` field. Use the [Payments API](/api-reference/v2.4/api-reference/payments-api/get-a-payment) to retrieve the latest status and payment data for the payment linked to this ID.

        Learn more about [Workflow Run failed webhooks](/workflows/monitor-workflows/workflow-run-failed-webhook) and [how Primer handles webhooks](/api-reference/get-started/configure-webhooks).
      operationId: workflow_run_failed_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              allOf:
                - $ref: '#/components/schemas/WorkflowRunFailedWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: false
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string. Only present when webhook signing is enabled
            in the dashboard.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: false
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

  /payment-operation-failure:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Payment Webhooks
      summary: Payment Operation Failure
      description: |
        Every operation you trigger on a payment deserves a clear answer. These webhooks deliver one instantly - so you can act before a missed capture or failed refund becomes a problem you discover too late.

        Primer notifies you with a failure webhook whenever a payment operation attempt does not succeed and the payment status has not changed as a result. The following event types are supported:
        - `PAYMENT.CAPTURE.FAILED` - a capture attempt did not succeed
        - `PAYMENT.REFUND.FAILED` - a refund attempt did not succeed
        - `PAYMENT.CANCELLATION.FAILED` - a cancellation attempt did not succeed
        - `PAYMENT.AUTHORIZATION_ADJUSTMENT.FAILED` - an authorization adjustment attempt did not succeed

        These events are operational signals, not status changes. Receiving a `PAYMENT.CAPTURE.FAILED` event, for example, means the capture attempt was unsuccessful - it does not mean the payment has failed or that the authorization has been lost.

        **When does a failure webhook fire?** Common scenarios include:
        - **Amount mismatch** - you attempt to capture £100, but the remaining authorised amount is only £80
        - **PSP-side error** - the processor returns a technical error or the request times out before a response is received

        > **Particularly useful with Primer Workflows.** If you trigger captures or refunds automatically through a Workflow, failure webhooks are the signal you need to keep your own systems in sync. Because the action happened upstream, your backend won't know it failed unless Primer tells you - these events close that gap.

        A **webhook is emitted for every individual failed attempt**. If the same operation fails multiple times, you will receive a separate event each time.

        The webhook payload is intentionally minimal. To **retrieve the full context** - including the error reason, timeline, and processor response - **call** `GET /payments/{id}?expand=transactions.events` after receiving the event.

        **What to do when you receive a failure event**

        The right action depends on the failure type: for amount mismatches, you may want to retry the capture with a corrected amount; for PSP errors or timeouts, a retry after a short delay is often appropriate. In all cases, make sure your internal systems reflect the outcome - update your order management, notify your operations team if needed, and avoid leaving the payment in an ambiguous state on your end.

        **Testing failure webhooks in sandbox**

        The easiest way to trigger each failure event in your sandbox environment is to force a condition that will cause the processor to reject the operation. Because the failures are real processor responses, no special flags or mock modes are needed — you just need to engineer the right conditions.
        - **`PAYMENT.CAPTURE.FAILED`** — Authorise a payment, then attempt to capture an amount larger than what was authorised. The processor will reject the capture and the event will fire immediately.
        - **`PAYMENT.REFUND.FAILED`** — Capture a payment, then refund it directly through your processor's dashboard before sending the refund request to Primer. Since the funds have already been returned at the processor level, Primer's refund attempt will fail and the event will fire.
        - **`PAYMENT.CANCELLATION.FAILED`** — Authorise a payment, then capture it directly through your processor's dashboard (outside of Primer). When you then send a cancel request through Primer, the processor will reject it since the payment is no longer in a cancellable state, since the capture already happened.

        In all cases, once you receive the webhook, you can retrieve the full error detail by calling `GET /payments/{id}?expand=transactions.events`. The `transactionEvent.id` in the webhook payload corresponds directly to the event entry in the response, where you will find the processor status reason and the full operation timeline.

      operationId: payment_operation_failed_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentOperationFailedWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: true
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: true
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

  /dispute-opened:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Dispute & Chargebacks Webhooks
      summary: Dispute Open
      description: |
        Primer notifies you with a `DISPUTE.OPENED` webhook on newly opened disputes or chargebacks. This notification is unified across all processors.

        Learn more about [how Primer handles webhooks](/docs/api-reference/get-started/configure-webhooks).

      operationId: dispute_open_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              allOf:
                - $ref: '#/components/schemas/DisputeOpenWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: true
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: true
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

  /dispute-status:
    post:
      x-excluded: true  # Exclude from autogeneration. Can be removed once migrated to OAS 3.1
      tags:
        - Dispute & Chargebacks Webhooks
      summary: Dispute Status
      description: |
        Primer notifies you with a `DISPUTE.STATUS` webhook that will provide information on retrievals, disputes (also known as chargebacks), and preabritration filings.

        This notification is supported for processors Adyen, Braintree, Checkout.com & PayPal.

        The `DISPUTE.STATUS` event can be used to proactively communicate with customers, issue refunds, send disputes to risk tools, or to proactively defend disputes.

        The `DISPUTE.STATUS` event is currently in an open beta stage, as we continue to add more processors.

        Learn more about [managing disputes at Primer](/docs/disputes/manage-disputes).

      operationId: dispute_status_webhook_event
      requestBody:
        content:
          application/json:
            schema:
              title: Request
              allOf:
                - $ref: '#/components/schemas/DisputeStatusWebhookPayload'
      parameters:
        - in: header
          name: X-Signature-Primary
          schema:
            type: string
          required: true
          description: >-
            An [HMAC signature](https://en.wikipedia.org/wiki/HMAC) generated using
            the webhook payload and a shared signing secret. This is then converted
            to a base64 encoded string.
        - in: header
          name: X-Signature-Secondary
          schema:
            type: string
          required: true
          description: >-
            A secondary signature that is added when you have rotated your secret
            within the past 24 hours.
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received successfully

components:
  schemas:
    AccountFundingTypeEnum:
      title: AccountFundingTypeEnum
      enum:
        - CREDIT
        - DEBIT
        - PREPAID
        - CHARGE
        - DEFERRED_DEBIT
        - UNKNOWN
      type: string
      description: An enumeration.

    ApayaCustomerTokenAPISchema:
      title: ApayaCustomerTokenAPISchema
      required:
        - mx
      type: object
      properties:
        mx:
          title: Mx
          type: string
        mnc:
          title: Mnc
          type: integer
        mcc:
          title: Mcc
          type: integer

    BinDataAPISchema:
      title: BinDataAPISchema
      required:
        - network
        - regionalRestriction
        - accountNumberType
        - accountFundingType
        - prepaidReloadableIndicator
        - productUsageType
        - productCode
        - productName
      type: object
      properties:
        network:
          $ref: '#/components/schemas/CardNetworkEnum'
        issuerCountryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
        issuerName:
          title: Issuername
          type: string
        issuerCurrencyCode:
          $ref: '#/components/schemas/Currency'
        regionalRestriction:
          $ref: '#/components/schemas/CardRegionRestrictionEnum'
        accountNumberType:
          $ref: '#/components/schemas/CardAccountNumberTypeEnum'
        accountFundingType:
          $ref: '#/components/schemas/AccountFundingTypeEnum'
        prepaidReloadableIndicator:
          $ref: '#/components/schemas/PrepaidReloadableEnum'
        productUsageType:
          $ref: '#/components/schemas/CardProductTypeEnum'
        productCode:
          title: Productcode
          type: string
        productName:
          title: Productname
          type: string

    CardAccountNumberTypeEnum:
      title: CardAccountNumberTypeEnum
      enum:
        - PRIMARY_ACCOUNT_NUMBER
        - NETWORK_TOKEN
        - UNKNOWN
      type: string
      description: An enumeration.

    CardNetworkEnum:
      title: CardNetworkEnum
      type: string
      enum:
        - AMEX
        - DANKORT
        - DINERS_CLUB
        - DISCOVER
        - ENROUTE
        - ELO
        - HIPER
        - INTERAC
        - JCB
        - MAESTRO
        - MASTERCARD
        - MIR
        - PRIVATE_LABEL
        - UNIONPAY
        - VISA
        - CARTES_BANCAIRES
        - OTHER
      description: |
        The list of available card networks.

    CardProductTypeEnum:
      title: CardProductTypeEnum
      enum:
        - CONSUMER
        - BUSINESS
        - GOVERNMENT
        - UNKNOWN
      type: string
      description: An enumeration.

    CardRegionRestrictionEnum:
      title: CardRegionRestrictionEnum
      enum:
        - DOMESTIC_USE_ONLY
        - NONE
        - UNKNOWN
      type: string
      description: An enumeration.

    PaymentResponsePaymentMethodOptionsAPISchema:
      title: PaymentResponsePaymentMethodOptionsAPISchema
      type: object
      properties:
        descriptor:
          title: Payment descriptor
          type: string
          description: >-
            The description of the payment, as it would typically appear on a bank
            statement.
        paymentType:
          allOf:
            - $ref: '#/components/schemas/RecurringPaymentTypeSchema'
        paymentMethodToken:
          title: Payment Method Token
          type: string
          description: The payment method token used to authorize the 
            transaction.
        isVaulted:
          title: >-
            Boolean flag indicating if a payment method token was vaulted
          type: boolean
          description: >-
            If the payment method token was vaulted, this is set to `true`. Use this
            token for recurring payments.
        analyticsId:
          title: Unique analytics ID
          type: string
          description: >-
            Unique analytics identifier corresponding to a payment method
        paymentMethodType:
          title: Payment method type
          allOf:
            - $ref: '#/components/schemas/PaymentMethodTypeEnum'
          description: Payment method type
        paymentMethodData:
          title: Payment method data
          anyOf:
            - $ref: '#/components/schemas/PaymentCardTokenAPISchema'
            - $ref: '#/components/schemas/PayPalOrderTokenAPISchema'
            - $ref: '#/components/schemas/PayPalBillingAgreementAPISchema'
            - $ref: '#/components/schemas/GoCardlessMandateAPISchema'
            - $ref: '#/components/schemas/KlarnaPaymentSessionAPISchema'
            - $ref: '#/components/schemas/KlarnaCustomerTokenAPISchema'
            - $ref: '#/components/schemas/IdealPayNLTokenAPISchema'
            - $ref: '#/components/schemas/ApayaCustomerTokenAPISchema'
          description: Payment method data
        threeDSecureAuthentication:
          title: Threedsecureauthentication
          allOf:
            - $ref: '#/components/schemas/ThreeDSecureAuthenticationAPISchema'
          default:
            responseCode: NOT_PERFORMED

    CountryCodeEnum:
      title: CountryCodeEnum
      enum:
        - AW
        - AF
        - AO
        - AI
        - AX
        - AL
        - AD
        - AE
        - AR
        - AM
        - AS
        - AQ
        - TF
        - AG
        - AU
        - AT
        - AZ
        - BI
        - BE
        - BJ
        - BQ
        - BF
        - BD
        - BG
        - BH
        - BS
        - BA
        - BL
        - BY
        - BZ
        - BM
        - BO
        - BR
        - BB
        - BN
        - BT
        - BV
        - BW
        - CF
        - CA
        - CC
        - CH
        - CL
        - CN
        - CI
        - CM
        - CD
        - CG
        - CK
        - CO
        - KM
        - CV
        - CR
        - CU
        - CW
        - CX
        - KY
        - CY
        - CZ
        - DE
        - DJ
        - DM
        - DK
        - DO
        - DZ
        - EC
        - EG
        - ER
        - EH
        - ES
        - EE
        - ET
        - FI
        - FJ
        - FK
        - FR
        - FO
        - FM
        - GA
        - GB
        - GE
        - GG
        - GH
        - GI
        - GN
        - GP
        - GM
        - GW
        - GQ
        - GR
        - GD
        - GL
        - GT
        - GF
        - GU
        - GY
        - HK
        - HM
        - HN
        - HR
        - HT
        - HU
        - ID
        - IM
        - IN
        - IO
        - IE
        - IR
        - IQ
        - IS
        - IL
        - IT
        - JM
        - JE
        - JO
        - JP
        - KZ
        - KE
        - KG
        - KH
        - KI
        - KN
        - KR
        - KW
        - LA
        - LB
        - LR
        - LY
        - LC
        - LI
        - LK
        - LS
        - LT
        - LU
        - LV
        - MO
        - MF
        - MA
        - MC
        - MD
        - MG
        - MV
        - MX
        - MH
        - MK
        - ML
        - MT
        - MM
        - ME
        - MN
        - MP
        - MZ
        - MR
        - MS
        - MQ
        - MU
        - MW
        - MY
        - YT
        - NA
        - NC
        - NE
        - NF
        - NG
        - NI
        - NU
        - NL
        - 'NO'
        - NP
        - NR
        - NZ
        - OM
        - PK
        - PA
        - PN
        - PE
        - PH
        - PW
        - PG
        - PL
        - PR
        - KP
        - PT
        - PY
        - PS
        - PF
        - QA
        - RE
        - RO
        - RU
        - RW
        - SA
        - SD
        - SN
        - SG
        - GS
        - SH
        - SJ
        - SB
        - SL
        - SV
        - SM
        - SO
        - PM
        - RS
        - SS
        - ST
        - SR
        - SK
        - SI
        - SE
        - SZ
        - SX
        - SC
        - SY
        - TC
        - TD
        - TG
        - TH
        - TJ
        - TK
        - TM
        - TL
        - TO
        - TT
        - TN
        - TR
        - TV
        - TW
        - TZ
        - UG
        - UA
        - UM
        - UY
        - US
        - UZ
        - VA
        - VC
        - VE
        - VG
        - VI
        - VN
        - VU
        - WF
        - WS
        - YE
        - ZA
        - ZM
        - ZW
      description: An enumeration.

    Currency:
      title: Currency
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYR
        - BYN
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LYD
        - MAD
        - MDL
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SOS
        - SRD
        - SSP
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - UYU
        - UZS
        - VND
        - VUV
        - WST
        - XAF
        - XAG
        - XAU
        - XBA
        - XBB
        - XBC
        - XBD
        - XCD
        - XDR
        - XFU
        - XOF
        - XPD
        - XPF
        - XPT
        - XSU
        - XTS
        - XUA
        - YER
        - ZAR
        - ZMW
        - ZWL
      description: Enumerates all supported currencies

    PaymentResponseProcessorAPISchema:
      title: PaymentResponseProcessorAPISchema
      type: object
      properties:
        name:
          title: Processor Name
          type: string
          description: The payment processor used for this payment.
        processorMerchantId:
          title: Processor Merchant ID
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this payment.
        amountCaptured:
          title: Amount captured
          type: integer
          format: int64
          description: |
            If no capture was performed, this value will be set to `0`.

            If one or more partial captures were performed, this value will be a sum
            of all partial capture amounts.
        amountRefunded:
          title: Amount refunded
          type: integer
          format: int64
          description: |
            If no refund was performed, this value will be set to `0`.

            If one or more partial refunds were performed, this value will be a sum
            of all partial refund amounts.

    GoCardlessMandateAPISchema:
      title: GoCardlessMandateAPISchema
      required:
        - gocardlessMandateId
      type: object
      properties:
        gocardlessMandateId:
          title: Mandate agreement ID
          type: string
          description: Unique identifier of a GoCardless mandate agreement
    IdealPayNLTokenAPISchema:
      title: IdealPayNLTokenAPISchema
      required:
        - paymentMethodConfigId
      type: object
      properties:
        paymentMethodConfigId:
          title: Paymentmethodconfigid
          type: string
          format: uuid
    KlarnaAddressAPISchema:
      title: KlarnaAddressAPISchema
      type: object
      properties:
        title:
          title: Title
          type: string
        firstName:
          title: Firstname
          type: string
        lastName:
          title: Lastname
          type: string
        email:
          title: Email
          type: string
        phoneNumber:
          title: Phonenumber
          type: string
        addressLine1:
          title: Addressline1
          type: string
        addressLine2:
          title: Addressline2
          type: string
        addressLine3:
          title: Addressline3
          type: string
        city:
          title: City
          type: string
        state:
          title: State
          type: string
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
        postalCode:
          title: Postalcode
          type: string
    KlarnaCustomerTokenAPISchema:
      title: KlarnaCustomerTokenAPISchema
      required:
        - klarnaCustomerToken
        - sessionData
      type: object
      properties:
        klarnaCustomerToken:
          title: Klarnacustomertoken
          type: string
        sessionData:
          $ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
    KlarnaPaymentSessionAPISchema:
      title: KlarnaPaymentSessionAPISchema
      required:
        - klarnaAuthorizationToken
        - sessionData
      type: object
      properties:
        klarnaAuthorizationToken:
          title: Klarnaauthorizationtoken
          type: string
        sessionData:
          $ref: '#/components/schemas/KlarnaSessionDetailsAPISchema'
    KlarnaSessionDetailsAPISchema:
      title: KlarnaSessionDetailsAPISchema
      required:
        - billingAddress
        - purchaseCountry
        - purchaseCurrency
        - locale
        - orderLines
      type: object
      properties:
        recurringDescription:
          title: Recurringdescription
          type: string
        billingAddress:
          $ref: '#/components/schemas/KlarnaAddressAPISchema'
        shippingAddress:
          $ref: '#/components/schemas/KlarnaAddressAPISchema'
        purchaseCountry:
          title: Purchasecountry
          type: string
        purchaseCurrency:
          title: Purchasecurrency
          type: string
        locale:
          title: Locale
          type: string
        orderLines:
          title: Orderlines
          type: array
          items: {}
        tokenDetails:
          $ref: '#/components/schemas/KlarnaTokenDetails'
    KlarnaTokenDetails:
      title: KlarnaTokenDetails
      required:
        - type
      type: object
      properties:
        type:
          title: Type
          type: string
        brand:
          title: Brand
          type: string
        masked_number:
          title: Masked Number
          type: string
        expiry_date:
          title: Expiry Date
          type: string
    PayPalBillingAgreementAPISchema:
      title: PayPalBillingAgreementAPISchema
      required:
        - paypalBillingAgreementId
      type: object
      properties:
        paypalBillingAgreementId:
          title: Paypalbillingagreementid
          type: string
        externalPayerInfo:
          title: Payer Info
          allOf:
            - $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
          description: Information about the PayPal customer
        shippingAddress:
          title: Shipping address
          allOf:
            - $ref: '#/components/schemas/AddressAPISchema'
          description: The PayPal customer's shipping address
        paypalStatus:
          title: PayPal order status
          type: string
    PayPalExternalPayerInfoAPISchema:
      title: PayPalExternalPayerInfoAPISchema
      type: object
      properties:
        externalPayerId:
          title: Externalpayerid
          type: string
        email:
          title: Email
          type: string
        firstName:
          title: Firstname
          type: string
        lastName:
          title: Lastname
          type: string
    PayPalOrderTokenAPISchema:
      title: PayPalOrderTokenAPISchema
      required:
        - paypalOrderId
      type: object
      properties:
        paypalOrderId:
          title: PayPal order identifier
          type: string
        externalPayerInfo:
          title: Payer Info
          allOf:
            - $ref: '#/components/schemas/PayPalExternalPayerInfoAPISchema'
          description: Information about the PayPal customer
        paypalStatus:
          title: PayPal order status
          type: string

    PaymentStatusWebhookPayload:
      title: PaymentStatusWebhookPayload
      type: object
      required:
        - eventType
        - date
        - signedAt
        - notificationConfig
        - payment
      properties:
        eventType:
          title: Event Type
          type: string
          description: >-
            The type of the webhook raised. `PAYMENT.STATUS` in this case.
        date:
          title: Date
          type: string
          description: The date-time that the webhook was sent.
          format: date-time
        signedAt:
          title: Signed At
          type: string
          description: The Unix timestamp at which the webhook payload was 
            signed.
          example: '1689221338'
        notificationConfig:
          title: Notification Config
          type: object
          required:
            - id
            - description
          description: The notification configuration details.
          properties:
            id:
              title: ID
              type: string
              description: The notification configuration ID.
              format: uuid
            description:
              title: Description
              type: string
              description: The notification configuration description.
        version:
          title: Version
          type: string
          description: The payload version
          example: '2.4'
        payment:
          title: Payment Details
          type: object
          required:
            - id
            - date
            - dateUpdated
            - amount
            - currencyCode
            - orderId
            - status
            - paymentMethod
            - transactions
          properties:
            id:
              title: Payment identifier
              type: string
              description: |
                The unique payment ID.

                You can use this ID to retrieve the payment details, or perform downstream operations.
            date:
              title: Payment date
              type: string
              description: >-
                The date and time at which the payment was created in UTC format.
              format: date-time
            dateUpdated:
              title: Date Updated
              type: string
              description: >-
                The date-time that the update related to the webhook has happened.
              format: date-time
            status:
              title: Current status
              allOf:
                - $ref: '#/components/schemas/PaymentStatus'
              description: >-
                See the payment [status table](../docs#payment-status) for more information.
            orderId:
              title: Order ID
              type: string
              description: Your reference for the payment.
            currencyCode:
              title: Currency
              type: string
              description: |
                The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
                e.g. use `USD` for US dollars.
            amount:
              title: Payment amount
              minimum: 0.0
              type: integer
              format: int64
              description: The amount you charged the customer, in minor units.
            customerId:
              title: The ID of the customer using the checkout
              type: string
              description: The unique identifier for your customer.
            metadata:
              title: Payment Metadata
              type: object
              description: |
                Additional data to be used throughout the payment lifecycle.
            customer:
              title: customer
              type: object
              properties:
                emailAddress:
                  title: Email Address
                  type: string
                  description: |
                    Customer email address.
                  format: email
                mobileNumber:
                  title: Mobile Number
                  type: string
                  description: The customer's mobile number
                  minLength: 1
                  maxLength: 255
                firstName:
                  title: First Name
                  type: string
                  description: The customer's first name
                  minLength: 1
                  maxLength: 255
                lastName:
                  title: Last Name
                  type: string
                  description: The customer's last name
                  minLength: 1
                  maxLength: 255
                billingAddress:
                  $ref: '#/components/schemas/OptionalAddressAPISchema'
                  title: Billing Address
                  description: |
                    Customer billing address.
                shippingAddress:
                  $ref: '#/components/schemas/OptionalAddressAPISchema'
                  title: Shipping Address
                  description: Customer shipping address
                taxId:
                  title: Tax ID
                  type: string
                  description: The customer's tax id number for tax exemptions
                  maxLength: 255
                nationalDocumentId:
                  title: National Document ID
                  type: string
                  description: The customer's national identification number
                  maxLength: 255
            paymentMethod:
              title: Payment Method Options
              allOf:
                - $ref: >-
                    #/components/schemas/PaymentResponsePaymentMethodOptionsAPISchema
              description: >-
                The payment method options provided in the request, as well as the
                token used to process the payment.
            processor:
              title: Processor Information
              allOf:
                - $ref: '#/components/schemas/PaymentResponseProcessorAPISchema'
              description: >-
                More information associated with the payment processor, including
                the processor name.
            statusReason:
              title: Status Reason
              allOf:
                - $ref: '#/components/schemas/StatusReasonAPISchema'
              description: |
                Check this field for more information regarding the payment's status. This is especially useful when the status is `DECLINED` or `FAILED`.
            transactions:
              title: Transactions
              type: array
              items:
                $ref: '#/components/schemas/TransactionOverviewAPISchema'
              description: >-
                A list summarizing the transactions that occurred while processing
                the payment.

                Note: a refund is a separate transaction and so will appear in this
                `transactions` list if a refund was performed.
            riskData:
              $ref: '#/components/schemas/RiskDataAPISchema'
              title: Risk Data

    PaymentRefundWebhookPayload:
      title: PaymentRefundWebhookPayload
      type: object
      required:
        - eventType
        - date
        - signedAt
        - notificationConfig
        - payment
      properties:
        eventType:
          title: Event Type
          type: string
          description: >-
            The type of the webhook raised. `PAYMENT.REFUND` in this case.
        date:
          title: Date
          type: string
          description: The date-time that the webhook was sent.
          format: date-time
        signedAt:
          title: Signed At
          type: string
          description: The Unix timestamp at which the webhook payload was 
            signed.
          example: '1689221338'
        notificationConfig:
          title: Notification Config
          type: object
          required:
            - id
            - description
          description: The notification configuration details.
          properties:
            id:
              title: ID
              type: string
              description: The notification configuration ID.
              format: uuid
            description:
              title: Description
              type: string
              description: The notification configuration description.
        version:
          title: Version
          type: string
          description: The payload version
          example: '2.4'
        payment:
          title: Payment Details
          type: object
          required:
            - id
            - date
            - dateUpdated
            - amount
            - currencyCode
            - orderId
            - status
            - paymentMethod
            - transactions
          properties:
            id:
              title: Payment identifier
              type: string
              description: |
                The unique payment ID.

                You can use this ID to retrieve the payment details, or perform downstream operations.
            date:
              title: Payment date
              type: string
              description: >-
                The date and time at which the payment was created in UTC format.
              format: date-time
            dateUpdated:
              title: Date Updated
              type: string
              description: >-
                The date-time that the update related to the webhook has happened.
              format: date-time
            status:
              title: Current status
              allOf:
                - $ref: '#/components/schemas/PaymentStatus'
              description: >-
                See the payment [status table](../docs#payment-status) for more information.
            orderId:
              title: Order ID
              type: string
              description: Your reference for the payment.
            currencyCode:
              title: Currency
              type: string
              description: |
                The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
                e.g. use `USD` for US dollars.
            amount:
              title: Payment amount
              minimum: 0.0
              type: integer
              format: int64
              description: The amount you charged the customer, in minor units.
            customerId:
              title: The ID of the customer using the checkout
              type: string
              description: The unique identifier for your customer.
            metadata:
              title: Payment Metadata
              type: object
              description: |
                Additional data to be used throughout the payment lifecycle.
            customer:
              title: customer
              type: object
              properties:
                emailAddress:
                  title: Email Address
                  type: string
                  description: |
                    Customer email address.
                  format: email
                mobileNumber:
                  title: Mobile Number
                  type: string
                  description: The customer's mobile number
                  minLength: 1
                  maxLength: 255
                firstName:
                  title: First Name
                  type: string
                  description: The customer's first name
                  minLength: 1
                  maxLength: 255
                lastName:
                  title: Last Name
                  type: string
                  description: The customer's last name
                  minLength: 1
                  maxLength: 255
                billingAddress:
                  $ref: '#/components/schemas/OptionalAddressAPISchema'
                  title: Billing Address
                  description: |
                    Customer billing address.
                shippingAddress:
                  $ref: '#/components/schemas/OptionalAddressAPISchema'
                  title: Shipping Address
                  description: Customer shipping address
                taxId:
                  title: Tax ID
                  type: string
                  description: The customer's tax id number for tax exemptions
                  maxLength: 255
                nationalDocumentId:
                  title: National Document ID
                  type: string
                  description: The customer's national identification number
                  maxLength: 255
            paymentMethod:
              title: Payment Method Options
              allOf:
                - $ref: >-
                    #/components/schemas/PaymentResponsePaymentMethodOptionsAPISchema
              description: >-
                The payment method options provided in the request, as well as the
                token used to process the payment.
            processor:
              title: Processor Information
              allOf:
                - $ref: '#/components/schemas/PaymentResponseProcessorAPISchema'
              description: >-
                More information associated with the payment processor, including
                the processor name.
            statusReason:
              title: Status Reason
              allOf:
                - $ref: '#/components/schemas/StatusReasonAPISchema'
              description: |
                Check this field for more information regarding the payment's status. This is especially useful when the status is `DECLINED` or `FAILED`.
            transactions:
              title: Transactions
              type: array
              items:
                $ref: '#/components/schemas/TransactionOverviewAPISchema'
              description: >-
                A list summarizing the transactions that occurred while processing
                the payment.

                Note: a refund is a separate transaction and so will appear in this
                `transactions` list if a refund was performed.
            riskData:
              $ref: '#/components/schemas/RiskDataAPISchema'
              title: Risk Data

    WorkflowRunFailedWebhookPayload:
      title: WorkflowRunFailedWebhookPayload
      type: object
      required:
        - eventType
        - version
        - date
        - primerAccountId
        - workflow
        - run
      properties:
        eventType:
          title: Event Type
          type: string
          enum:
            - WORKFLOW_RUN.FAILED
          description: >-
            The type of the webhook raised. `WORKFLOW_RUN.FAILED` for failed
            workflow runs. Additional types may be supported in the future.
        version:
          title: Version
          type: string
          description: The payload version for this `eventType`.
          example: '1.0'
        date:
          title: Date
          type: string
          description: The date and time when the webhook event was sent.
          example: '2024-02-21 15:36:16.167687'
        primerAccountId:
          title: Primer Account ID
          type: string
          format: uuid
          description: >-
            The Primer Account ID of the account that owns the failed workflow
            run.
        triggerEventId:
          title: Trigger Event ID
          type: string
          nullable: true
          description: >-
            An optional ID passed with the trigger to identify the origin of the
            event that started the workflow. For payment workflows this is the
            payment ID; other triggers may not set an event ID, in which case
            this value will be `null`.
        workflow:
          title: Workflow
          type: object
          required:
            - id
            - name
            - version
          description: Details of the workflow that had a failed run.
          properties:
            id:
              title: Workflow ID
              type: string
              format: uuid
              description: The ID of the workflow that had a failed run.
            name:
              title: Workflow Name
              type: string
              description: The name of the workflow that had a failed run.
            version:
              title: Workflow Version
              type: integer
              description: The version of the workflow that had a failed run.
        run:
          title: Run
          type: object
          required:
            - timestamp
            - id
            - status
            - lastError
          description: Details of the workflow run that failed.
          properties:
            timestamp:
              title: Timestamp
              type: string
              format: date-time
              description: The date and time when the workflow run failed.
            id:
              title: Run ID
              type: string
              format: uuid
              description: >-
                The ID of the workflow run that failed. Use this to locate the
                run in the dashboard.
            status:
              title: Status
              type: string
              enum:
                - FAILED
              description: >-
                The workflow run status. Currently always `FAILED`. In the
                future, additional statuses such as `COMPLETED` may be supported
                for Workflow Run webhooks.
            lastError:
              title: Last Error
              type: object
              description: >-
                Details about the error that caused the workflow run to fail.
              properties:
                applicationId:
                  title: Application ID
                  type: string
                  nullable: true
                  description: >-
                    The application used for the block that led to the workflow
                    run failure. Values depend on the applications used within
                    workflows, e.g. `SLACK`, `ONFIDO`, `PRIMER_PAYMENTS`.
                actionId:
                  title: Action ID
                  type: string
                  nullable: true
                  description: >-
                    The ID of the action used for the block that led to the
                    workflow run failure. Values depend on the actions used
                    within workflows, e.g. `send_message`, `capture_payment`,
                    `create_ticket`.
                diagnosticsId:
                  title: Diagnostics ID
                  type: string
                  nullable: true
                  description: >-
                    A diagnostics ID to help Primer debug traces when needed.
                message:
                  title: Message
                  type: string
                  nullable: true
                  description: >-
                    The error message as also displayed in the Workflow Run
                    Timeline.

    PaymentOperationFailedWebhookPayload:
      title: PaymentOperationFailedWebhookPayload
      type: object
      required:
        - eventType
        - date
        - signedAt
        - notificationConfig
        - payment
        - transactionEvent
      properties:
        eventType:
          title: Event Type
          type: string
          enum:
            - PAYMENT.CAPTURE.FAILED
            - PAYMENT.CANCELLATION.FAILED
            - PAYMENT.AUTHORIZATION_ADJUSTMENT.FAILED
            - PAYMENT.REFUND.FAILED
          description: The type of the webhook raised.
        date:
          title: Date
          type: string
          format: date-time
          description: The date-time that the webhook was sent.
        signedAt:
          title: Signed At
          type: string
          description: >-
            The Unix timestamp at which the webhook payload was signed.
          example: '1689221338'
        notificationConfig:
          title: Notification Config
          type: object
          required:
            - id
            - description
          description: The notification configuration details.
          properties:
            id:
              title: ID
              type: string
              format: uuid
              description: The notification configuration ID.
            description:
              title: Description
              type: string
              description: The notification configuration description.
        version:
          title: Version
          type: string
          description: The payload version.
          example: '2.4'
        payment:
          title: Payment Details
          type: object
          required:
            - id
            - amount
            - currencyCode
            - orderId
          properties:
            id:
              title: Payment identifier
              type: string
              description: |
                The unique payment ID.

                You can use this ID to retrieve the payment details, or perform downstream operations.
            amount:
              title: Payment amount
              type: integer
              format: int64
              description: The amount you charged the customer, in minor units.
            currencyCode:
              title: Currency
              type: string
              description: |
                The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
                e.g. use `USD` for US dollars.
            orderId:
              title: Order ID
              type: string
              description: Your reference for the payment.
        transactionEvent:
          title: Transaction Event
          type: object
          required:
            - id
          properties:
            id:
              title: Transaction Event ID
              type: string
              format: uuid
              description: >-
                The unique identifier for the transaction event associated
                with the failed operation.
        requestAmount:
          title: Request Amount
          type: integer
          format: int64
          description: >-
            The requested amount for the operation in minor units.
            Present for capture, refund, and authorization adjustment events.
            Not applicable for cancellation events.

    DisputeOpenWebhookPayload:
      title: DisputeOpenWebhookPayload
      type: object
      required:
        - eventType
        - processorId
        - processorDisputeId
        - paymentId
        - transactionId
        - orderId
        - primerAccountId
      properties:
        eventType:
          title: Event Type
          type: string
          description: >-
            The type of the webhook raised. `DISPUTE.OPENED` in this case.
        processorId:
          title: Processor ID
          type: string
          description: The name of the processor that generated the dispute.
        processorDisputeId:
          title: Processor Dispute ID
          type: string
          description: >-
            A unique identifier for the corresponding connection dispute.
        paymentId:
          title: Payment ID
          type: string
          description: >-
            A unique identifier for the Primer payment corresponding to this dispute.
        transactionId:
          title: Transaction ID
          type: string
          description: >-
            A unique identifier for the Primer transaction corresponding to this dispute.
        orderId:
          title: Order ID
          type: string
          description: >-
            Your reference for the sale transaction that the dispute relates to.
        primerAccountId:
          title: Primer Account ID
          type: string
          description: A unique identifier for your Primer merchant account.

    DisputeStatusWebhookPayload:
      title: DisputeStatusWebhookPayload
      type: object
      required:
        - eventType
        - type
        - status
        - primerAccountId
        - orderId
        - paymentId
        - paymentMethod
        - processor
        - processorDisputeId
        - receivedAt
        - challengeRequiredBy
        - reasonCode
        - amount
        - currency
      properties:
        eventType:
          title: Event Type
          type: string
          description: |
            The type of event that triggered the webhook. This will have the value `DISPUTE.STATUS`. This indicates that a dispute notification was issued through a configured connection.

            Use these notifications to proactively communicate with your customer, issue refunds, or submit evidence to challenge disputes.
        version:
          title: Version
          type: string
          description: The payload version
          example: '2.4'
        type:
          title: Type
          type: string
          enum:
            - RETRIEVAL
            - DISPUTE
            - PREARBITRATION
          description: |
            The type of dispute event. More information on what the `type` field represents can be found in [Manage disputes](/docs/disputes/manage-disputes)
        status:
          title: Status
          type: string
          enum:
            - OPEN
            - ACCEPTED
            - CHALLENGED
            - EXPIRED
            - CANCELLED
            - WON
            - LOST
          description: |
            To see which statuses are applicable for a dispute `type`, and how we map `status`, please see [Manage disputes](/docs/disputes/manage-disputes).
        primerAccountId:
          title: Primer Account ID
          type: string
          description: A unique identifier for your Primer merchant account.
        transactionId:
          title: Transaction ID
          type: string
          description: >-
            A unique identifier for the Primer transaction corresponding to this dispute.
        orderId:
          title: Order ID
          type: string
          description: >-
            Your reference for the sale transaction that the dispute relates to.
        paymentId:
          title: Payment ID
          type: string
          description: >-
            A unique identifier for the Primer payment corresponding to this dispute.
        paymentMethod:
          title: Payment Method Information
          description: >-
            The payment method information for the payment that is now disputed.
          type: object
          properties:
            paymentMethodType:
              $ref: '#/components/schemas/PaymentMethodTypeEnum'
            paymentMethodData:
              title: Payment method data
              type: object
              properties:
                network:
                  $ref: '#/components/schemas/CardNetworkEnum'
        processor:
          title: Processor
          type: string
          enum:
            - ADYEN
            - BRAINTREE
          description: >-
            The payment processor that you submitted a payment to, and received a
            dispute notification from.
        processorDisputeId:
          title: Processor Dispute ID
          type: string
          description: |
            An identifier for this dispute provided by the processor. This is shared across multiple dispute `type` and `status` relating to the same payment.

            e.g. as an `open` dispute that is later challenged will share a `proccessorDisputeId`.
        receivedAt:
          title: Received date
          type: string
          format: date-time
          description: >-
            Date and time at which Primer received the processor's dispute event.
            Provided as an ISO timestamp in UTC.
        challengeRequiredBy:
          title: Challenge Required date
          type: string
          format: date-time
          description: >-
            Time by which the merchant must challenge a dispute. This is provided
            by the processor, where available.
        reason:
          title: Reason
          type: string
          description: >-
            Primer's unified reason that explains why the dispute was raised. This
            should not vary across processors for the same dispute `reasonCode`, unlike
            the `processorReason`.
        reasonCode:
          title: Reason Code
          type: string
          description: >-
            The dispute reason code for a dispute. This will be the same code provided
            by the card schemes.
        processorReason:
          title: Processor Reason
          type: string
          description: >-
            The dispute reason provided by the processor. This can vary across processors
            for the same dispute `reasonCode`, which is why we provide a unified field
            - `reason`.
        amount:
          title: Amount
          type: integer
          format: int64
          description: |
            The disputed amount. Note: this is not always the same as the payment amount.

            This will be displayed in minor units.

            e.g. for $7, use `700`. Some currencies, such as Japanese Yen, do not have minor units. In this case you should use the value as it is, without any formatting. For example for ¥100, use `100`.
        currency:
          title: Currency
          type: string
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        merchantId:
          title: Merchant ID
          type: string
          description: >-
            The merchant ID registered at the payment processor used for this dispute.

    PaymentCardTokenAPISchema:
      title: PaymentCardTokenAPISchema
      required:
        - last4Digits
        - expirationMonth
        - expirationYear
      type: object
      properties:
        first6Digits:
          title: Payment card's first six digits
          maxLength: 6
          minLength: 6
          type: string
        last4Digits:
          title: Payment card's last four digits
          maxLength: 4
          minLength: 4
          type: string
        expirationMonth:
          title: Expiration month
          maxLength: 2
          minLength: 2
          type: string
        expirationYear:
          title: Expiration year
          maxLength: 4
          minLength: 4
          type: string
        cardholderName:
          title: Cardholder's name
          type: string
        network:
          title: Card network
          type: string
        isNetworkTokenized:
          title: Is represented by a digital PAN
          type: boolean
          default: false
        binData:
          $ref: '#/components/schemas/BinDataAPISchema'

    StatusReasonAPISchema:
      title: StatusReasonAPISchema
      required:
        - type
      type: object
      properties:
        type:
          title: Payment status type
          allOf:
            - $ref: '#/components/schemas/PaymentStatusTypeEnum'
          description: |
            The status reason type for the payment, providing more information on the error.
            `APPLICATION_ERROR` indicates something went wrong internally within primer's system. 
            `GATEWAY_REJECTED` indicates that request was rejected on the third-party.
            `GATEWAY_TIMEOUT` indicates the timeout limit on the third party request was exceeded. 
            `ISSUER_DECLINED` indicates a legitimate decline that is not due to a timeout.
        declineType:
          title: Decline Type
          allOf:
            - $ref: '#/components/schemas/DeclineTypeEnum'
          description: |
            If the error is of type `ISSUER_DECLINED` this will be returned.

            Declines of type `SOFT_DECLINE` may be retried,
            whereas declines of type `HARD_DECLINE` should not be retried.
        code:
          title: Payment status code
          allOf:
            - $ref: '#/components/schemas/TransactionDeclineReasonV2Enum'
          description: >-
            If the error is of type `ISSUER_DECLINED`, this will be returned.
        message:
          title: Processor message
          type: string
          description: >-
            In case of an error on the processor's part, we will return the message
            returned by the processor. This is usually a human readable error.
        paymentMethodResultCode:
          title: Payment Method Result Code
          type: string
          description: |
            The result code returned by the payment method or card network. This code is unified across all supported processors.

            _e.g. Code `46` refers to the message "Closed account" for Visa across all supported processors._
        paymentMethodResultMessage:
          title: Payment Method Result Message
          type: string
          description: |
            Human-readable version of the Payment Method Result Code. This message is unified across all supported processors.

            _e.g. Code `46` refers to the message "Closed account" for Visa across all supported processors._
        paymentMethodAdviceCode:
          title: Payment Method Advice Code
          type: string
          description: |
            The advice code returned by the payment method or card network. This code is unified across all supported processors.

            _For payments made with Mastercard, this represents the Merchant Advice Code (MAC)._

            _e.g. Code `24` refers to the message "Retry after 1 hour" for Mastercard across all supported processors._
        paymentMethodAdviceMessage:
          title: Payment Method Advice Message
          type: string
          description: |
            Human-readable version of the Payment Method Advice Code. This message is unified across all supported processors.

            _For payments made with Mastercard, this represents the message of the Merchant Advice Code (MAC)._

            _e.g. Code `24` refers to the message "Retry after 1 hour" for Mastercard across all supported processors._
        advisedAction:
          title: Advised Action
          $ref: '#/components/schemas/AdvisedActionEnum'

    RiskDataAPISchema:
      title: RiskDataAPISchema
      description: |
        Risk data associated with this payment.
      type: object
      properties:
        fraudChecks:
          title: Fraud Checks
          $ref: '#/components/schemas/FraudCheckAPISchema'
        cvvCheck:
          title: CVV Check
          $ref: '#/components/schemas/CVVCheckAPISchema'
        avsCheck:
          title: AVS Check
          $ref: '#/components/schemas/AVSCheckAPISchema'

    FraudCheckAPISchema:
      title: FraudCheckAPISchema
      description: |
        Results of the pre-authorization and post-authorization fraud checks.
      type: object
      properties:
        source:
          type: string
          example: FRAUD_PROVIDER
        preAuthorizationResult:
          $ref: '#/components/schemas/PreAuthFraudDecisionTypeEnum'
          example: THREE_DS
        preAuthorizationRecommendation:
          $ref: '#/components/schemas/PreAuthorizationRecommendationEnum'
          example: TRANSACTION_RISK_ANALYSIS
        postAuthorizationResult:
          $ref: '#/components/schemas/PostAuthFraudDecisionTypeEnum'
          example: ACCEPT

    PreAuthFraudDecisionTypeEnum:
      title: PreAuthFraudDecisionTypeEnum
      enum:
        - ACCEPT
        - REFUSE
        - FAILED
        - THREE_DS
        - THREE_DS_EXEMPTION
      type: string
      description: Possible pre-authorization fraud check outcomes.

    PostAuthFraudDecisionTypeEnum:
      title: PostAuthFraudDecisionTypeEnum
      enum:
        - ACCEPT
        - REFUSE
        - FAILED
        - THREE_DS
      type: string
      description: Possible post-authorization fraud check outcomes.

    PreAuthorizationRecommendationEnum:
      title: PreAuthorizationRecommendationEnum
      enum:
        - TRANSACTION_RISK_ANALYSIS
      type: string
      description: |
        Pre-authorization recommendation indicating the SCA exemption or risk assessment path taken. Only present when `preAuthorizationResult` is `THREE_DS_EXEMPTION`.

        Values:
        - `TRANSACTION_RISK_ANALYSIS`: Indicates that the fraud check deemed the transaction low risk and recommends applying a Transaction Risk Analysis (TRA) exemption to bypass Strong Customer Authentication (SCA) under PSD2, reducing friction for users.

    CVVCheckAPISchema:
      title: CVVCheckAPISchema
      description: |
        Results of any external CVV check performed on this payment.
      type: object
      properties:
        source:
          type: string
          example: PROCESSOR
        result:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: MATCHED

    AVSCheckAPISchema:
      title: AVSCheckAPISchema
      description: |
        Results of any external AVS check performed on this payment.
      type: object
      properties:
        source:
          type: string
          example: PROCESSOR
        result:
          $ref: '#/components/schemas/AVSRiskAssessmentValues'

    AVSRiskAssessmentValues:
      title: AVSRiskAssessmentValues
      type: object
      properties:
        streetAddress:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: NOT_MATCHED
        postalCode:
          $ref: '#/components/schemas/RiskAssessmentStatusEnum'
          example: NOT_VERIFIED

    RiskAssessmentStatusEnum:
      title: RiskAssessmentStatusEnum
      enum:
        - MATCHED
        - NOT_MATCHED
        - NOT_VERIFIED
        - NOT_PROVIDED
        - NOT_APPLICABLE
        - SKIPPED
      type: string
      description: Possible risk assessment values for CVV and AVS checks.

    PaymentMethodTypeEnum:
      title: PaymentMethodTypeEnum
      type: string
      description: |
        [The list of available payment methods and their `PAYMENT_METHOD_TYPE` can be found here.](https://primer.io/docs/connections/payment-methods/available-payment-methods)

    PrepaidReloadableEnum:
      title: PrepaidReloadableEnum
      enum:
        - RELOADABLE
        - NON_RELOADABLE
        - NOT_APPLICABLE
        - UNKNOWN
      type: string
      description: An enumeration.

    ThreeDSecureAuthResponseCodeEnum:
      title: ThreeDSecureAuthResponseCodeEnum
      enum:
        - NOT_PERFORMED
        - SKIPPED
        - AUTH_SUCCESS
        - AUTH_FAILED
        - CHALLENGE
        - METHOD
      type: string
      description: An enumeration.

    ThreeDSecureAuthenticationAPISchema:
      title: ThreeDSecureAuthenticationAPISchema
      required:
        - responseCode
      type: object
      properties:
        responseCode:
          $ref: '#/components/schemas/ThreeDSecureAuthResponseCodeEnum'
        reasonCode:
          title: Reasoncode
          anyOf:
            - $ref: '#/components/schemas/ThreeDSecureSkippedReasonCodeEnum'
            - $ref: '#/components/schemas/ThreeDSecureFailedReasonCodeEnum'
        reasonText:
          title: Reasontext
          type: string
        protocolVersion:
          title: Protocolversion
          type: string
        challengeIssued:
          title: Challengeissued
          type: boolean

    ThreeDSecureFailedReasonCodeEnum:
      title: ThreeDSecureFailedReasonCodeEnum
      enum:
        - UNKNOWN
        - REJECTED_BY_ISSUER
        - CARD_AUTHENTICATION_FAILED
        - UNKNOWN_DEVICE
        - UNSUPPORTED_DEVICE
        - EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT
        - EXPIRED_CARD
        - INVALID_CARD_NUMBER
        - INVALID_TRANSACTION
        - NO_CARD_RECORD
        - SECURITY_FAILURE
        - STOLEN_CARD
        - SUSPECTED_FRAUD
        - TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER
        - CARDHOLDER_NOT_ENROLLED_IN_SERVICE
        - TRANSACTION_TIMED_OUT_AT_THE_ACS
        - LOW_CONFIDENCE
        - MEDIUM_CONFIDENCE
        - HIGH_CONFIDENCE
        - VERY_HIGH_CONFIDENCE
        - EXCEEDS_ACS_MAXIMUM_CHALLENGES
        - NON_PAYMENT_NOT_SUPPORTED
        - THREE_RI_NOT_SUPPORTED
        - ACS_TECHNICAL_ISSUE
        - DECOUPLED_REQUIRED_BY_ACS
        - DECOUPLED_MAX_EXPIRY_EXCEEDED
        - DECOUPLED_AUTHENTICATION_INSUFFICIENT_TIME
        - AUTHENTICATION_ATTEMPTED_BUT_NOT_PERFORMED_BY_CARDHOLDER
        - ACS_TIMED_OUT
        - INVALID_ACS_RESPONSE
        - ACS_SYSTEM_ERROR_RESPONSE
        - ERROR_GENERATING_CAVV
        - PROTOCOL_VERSION_NOT_SUPPORTED
        - TRANSACTION_EXCLUDED_FROM_ATTEMPTS_PROCESSING
        - REQUESTED_PROGRAM_NOT_SUPPORTED
      type: string
      description: >-
        This enum is derived from the `transStatusReason` on page 218 of the

        [EMV Co 3DS protocol specification](https://www.emvco.com/terms-of-use/?u=/wp-content/uploads/documents/EMVCo_3DS_Spec_v220_122018.pdf)


        | Code | Description                             |

        |------|-----------------------------------------|

        | 01   | Card authentication failed              |

        | 02   | Unknown Device                          |

        | 03   | Unsupported Device                      |

        | 04   | Exceeds authentication frequency limit  |

        | 05   | Expired card                            |

        | 06   | Invalid card number                     |

        | 07   | Invalid transaction                     |

        | 08   | No Card record                          |

        | 09   | Security failure                        |

        | 10   | Stolen card                             |

        | 11   | Suspected fraud                         |

        | 12   | Transaction not permitted to cardholder |

        | 13   | Cardholder not enrolled in service      |

        | 14   | Transaction timed out at the ACS        |

        | 15   | Low confidence                          |

        | 16   | Medium confidence                       |

    ThreeDSecureSkippedReasonCodeEnum:
      title: ThreeDSecureSkippedReasonCodeEnum
      enum:
        - GATEWAY_UNAVAILABLE
        - DISABLED_BY_MERCHANT
        - NOT_SUPPORTED_BY_ISSUER
        - FAILED_TO_NEGOTIATE
        - UNKNOWN_ACS_RESPONSE
        - 3DS_SERVER_ERROR
        - ACQUIRER_NOT_CONFIGURED
        - ACQUIRER_NOT_PARTICIPATING
        - EXEMPTION_ACCEPTED
      type: string
      description: An enumeration.

    DeclineTypeEnum:
      title: DeclineTypeEnum
      enum:
        - SOFT_DECLINE
        - HARD_DECLINE
      type: string
      description: An enumeration.

    TransactionDeclineReasonV2Enum:
      title: TransactionDeclineReasonV2Enum
      enum:
        - ERROR
        - INVALID_CARD_NUMBER
        - EXPIRED_CARD
        - LOST_OR_STOLEN_CARD
        - SUSPECTED_FRAUD
        - UNKNOWN
        - DECLINED
        - REFER_TO_CARD_ISSUER
        - DO_NOT_HONOR
        - INSUFFICIENT_FUNDS
        - WITHDRAWAL_LIMIT_EXCEEDED
        - ISSUER_TEMPORARILY_UNAVAILABLE
        - AUTHENTICATION_REQUIRED
      type: string
      description: An enumeration.

    AdvisedActionEnum:
      title: AdvisedActionEnum
      enum:
        - RETRY_LATER
        - UPDATE_DATA
        - DO_NOT_RETRY
        - STOP_ALL_PAYMENTS
      type: string
      description: |
        The Primer-recommended action to take based on the underlying decline reason and advice code. This advised action is unified across all supported processors and payment methods.

        - `RETRY_LATER`: The payment was likely declined due to a temporary issue (e.g. Insufficient funds). The payment can be retried immediately or at a later date. 
        - `UPDATE_DATA`: The payment was likely declined because critical data was missing or out-of-date. Please ensure you use the most up-to-date payment information and customer details before retrying the payment.
        - `DO_NOT_RETRY`: The payment was declined and should not be retried. You can still charge this payment method for future orders or installments.
        - `STOP_ALL_PAYMENTS`: The processor or payment method explicitly informs you to stop making any payment requests with this payment method. Please use another payment method to charge this customer.
        - `null`: Primer is unable to determine a recommended action. 

    TransactionOverviewAPISchema:
      title: TransactionOverviewAPISchema
      required:
        - date
        - amount
        - currencyCode
        - transactionType
        - processorName
        - processorMerchantId
        - processorStatus
      type: object
      properties:
        date:
          title: Creation date
          type: string
          description: Date & time of the transaction (UTC)
          format: date-time
        amount:
          minimum: 0.0
          type: integer
          format: int64
          description: Transaction amount in minor units
        currencyCode:
          $ref: '#/components/schemas/Currency'
          title: Currency
          description: >
            The 3-letter currency code in [ISO 4217 format](https://en.wikipedia.org/wiki/ISO_4217#Active_codes).
            e.g. use `USD` for US dollars.
        orderId:
          title: Order ID
          type: string
          description: The reference submitted on payment creation or refund.
        transactionType:
          $ref: '#/components/schemas/TransactionTypeEnum'
          title: Transaction type
        processorTransactionId:
          title: Processor's transaction ID
          type: string
          description: Processor's unique identifier for the transaction
        authorizationCode:
          title: Authorization code
          type: string
          description: >-
            The authorization code returned by the processor on a successful
            authorization. For transactions that were subsequently
            auth-adjusted, this is the latest code. Useful for chargeback
            matching and bank reconciliation. Not guaranteed to be present;
            availability depends on the processor.
        processorName:
          title: Processor Name
          type: string
          description: An identifier of a processor.
        processorMerchantId:
          title: Processor master account identifier
          type: string
          description: |
            Processor's main account identifier.

            * Adyen: Account code
            * Braintree: Merchant ID
            * Stripe: Account ID"
        processorStatus:
          title: Processor Transaction status
          allOf:
            - $ref: '#/components/schemas/PaymentStatus'
          description: >-
            Transaction status, please refer to the [Transaction Status Codes](#section/API-Usage-Guide/Payment-Status)
            table for more information
        processorStatusReason:
          title: Payment error
          allOf:
            - $ref: '#/components/schemas/StatusReasonAPISchema'
          description: |
            If the transaction has a declined or failed status.

            Only if the status is `DECLINED` or `FAILED`, otherwise `null`.
        reason:
          title: Reason
          type: string
          description: |
            The reason for a cancel or refund request on this transaction, if any.
          example: Item returned.

    PaymentStatus:
      title: PaymentStatus
      enum:
        - PENDING
        - FAILED
        - AUTHORIZED
        - SETTLING
        - PARTIALLY_SETTLED
        - SETTLED
        - DECLINED
        - CANCELLED
      type: string
      description: An enumeration.

    PaymentStatusTypeEnum:
      title: PaymentStatusTypeEnum
      enum:
        - APPLICATION_ERROR
        - GATEWAY_REJECTED
        - ISSUER_DECLINED
        - GATEWAY_TIMEOUT
      type: string
      description: An enumeration.

    TransactionTypeEnum:
      title: TransactionTypeEnum
      enum:
        - SALE
        - REFUND
      type: string
      description: An enumeration.

    AddressAPISchema:
      title: AddressAPISchema
      required:
        - addressLine1
        - city
        - countryCode
      type: object
      properties:
        firstName:
          title: First Name
          type: string
        lastName:
          title: Last Name
          type: string
        addressLine1:
          title: Address Line 1
          type: string
          description: Street name, Company name or PO Box
        addressLine2:
          title: Address Line 2
          type: string
          description: Apartment, Unit or Building number
        city:
          title: City
          type: string
          description: Name of the city, district, town or village
        state:
          title: State
          type: string
          description: State, County or Province
        countryCode:
          title: Country Code
          allOf:
            - $ref: '#/components/schemas/CountryCodeEnum'
          description: Two letter ISO country code
        postalCode:
          title: Postal Code
          type: string
          description: Postal or ZIP code

    RecurringPaymentTypeSchema:
      title: Recurring Payment Type
      type: string
      enum:
        - FIRST_PAYMENT
        - ECOMMERCE
        - SUBSCRIPTION
        - UNSCHEDULED
      description: >-
        Payment types, primarily to be used for recurring payments. See the table
        below for all possible values.

        Note: if no field is set, we will return a blank value and make a best effort
        to calculate the downstream fields required for processing the payment.


        | paymentType | Use case |

        | --- | --- |

        | `FIRST_PAYMENT` | a customer-initiated payment which is the first in a series
        of recurring payments or subscription, or a card on file scenario.

        | `ECOMMERCE` | a customer-initiated payment using stored payment details
        where the cardholder is present.

        | `SUBSCRIPTION` | a merchant-initiated payment as part of a series of payments
        on a fixed schedule and a set amount.

        | `UNSCHEDULED` | a merchant-initiated payment using stored payment details
        with no fixed schedule or amount.

    OptionalAddressAPISchema:
      title: OptionalAddressAPISchema
      type: object
      properties:
        firstName:
          title: First Name
          type: string
          minLength: 1
          maxLength: 255
        lastName:
          title: Last Name
          type: string
          minLength: 1
          maxLength: 255
        addressLine1:
          title: Address Line 1
          type: string
          description: Street name, Company name or PO Box
          minLength: 1
          maxLength: 255
        addressLine2:
          title: Address Line 2
          type: string
          description: Apartment, Unit or Building number
          maxLength: 255
        city:
          title: City
          type: string
          description: Name of the city, district, town or village
          minLength: 1
          maxLength: 255
        state:
          title: State
          type: string
          description: State, County or Province
          minLength: 1
          maxLength: 255
        countryCode:
          $ref: '#/components/schemas/CountryCodeEnum'
          title: Country Code
          description: Two letter ISO country code
        postalCode:
          title: Postal Code
          type: string
          description: Postal or ZIP code
          minLength: 1
          maxLength: 255
