openapi: 3.0.3
info:
  version: v1
  title: Nopan API
  description: >-
    Download Nopan Postman collection:
    [Download](/postman/nopan-api-collection.zip)
servers:
  - url: https://api.nopan.com
tags:
  - name: Authentication APIs
    description: >-
      This section covers the endpoints required for securely obtaining OAuth
      2.0 access tokens to interact with the Nopan API. These APIs support
      machine-to-machine (M2M) authentication using mutual TLS (mTLS) and client
      credentials. A valid access token is required to authorize all subsequent
      requests to protected resources.
  - name: Payment Processing APIs
    description: >-
      This section provides a set of operations for initiating and managing
      payments through the Nopan API. These endpoints enable clients to request
      payments, handle SCA, and track the status of transactions in real time.
      Designed for seamless integration, the APIs support secure and compliant
      payment workflows for a variety of use cases including e-commerce,
      invoicing, and in-app purchases.
  - name: Testing APIs
    description: >-
      The Nopan API includes a sandbox environment and test endpoints to help
      developers safely simulate, mock and validate payment flows without
      processing real transactions. These testing APIs mirror the behavior of
      the live endpoints, allowing you to initiate payments, trigger SCA flows,
      and verify callbacks using predefined test data. This environment is ideal
      for integration testing, QA workflows, and development staging before
      going live.
  - name: Webhooks
    description: >-
      API of the webhooks notifications Nopan will send if configured in the
      portal.
paths:
  /auth/token:
    post:
      tags:
        - Authentication APIs
      operationId: getAccessToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema: &ref_20
              type: object
              required:
                - grant_type
                - processing_account_id
              properties:
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: >-
                    OAuth2 grant type. Must be set to
                    <code>client_credentials</code> to indicate
                    machine-to-machine authentication using client
                    credentials.<br/><small>Example:
                    <i>client_credentials</i></small>
                processing_account_id:
                  type: string
                  description: >-
                    Unique organization account ID issued to the client during
                    onboarding. Used to identify the merchant or integration
                    making the request.<br/><small>Example:
                    <i>merchant-abc123</i></small>
                scope:
                  type: string
                  description: >-
                    Optional space-delimited list of scopes the client is
                    requesting access to. Used to limit the access token's
                    permissions. Default is
                    <code>payments:read</code><br/><small>Example:
                    <i>payments:read payments:process</i></small>
              additionalProperties: false
            examples:
              GetAccessToken:
                summary: Get Access Token
                description: Get access token via OAuth2 by submitting form
                value: >-
                  grant_type=client_credentials&processing_account_id=your-organization-id&scope=payments:process
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: &ref_21
                type: object
                required:
                  - access_token
                  - token_type
                  - expires_in
                properties:
                  access_token:
                    type: string
                    description: >-
                      Short-lived Bearer token used to authorize subsequent API
                      requests. Encoded as a JWT (JSON Web
                      Token).<br/><small>Example:
                      <i>eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...</i></small>
                  token_type:
                    type: string
                    description: >-
                      Indicates the type of token issued. Always `Bearer` for
                      Nopan APIs.<br/><small>Example: <i>Bearer</i></small>
                  expires_in:
                    type: integer
                    description: >-
                      Lifetime of the access token in seconds. After this
                      period, the token expires and must be
                      re-requested.<br/><small>Example: <i>7200</i></small>
                  refresh_expires_in:
                    type: integer
                    description: >-
                      Lifetime of the associated refresh token in seconds. If
                      refresh tokens are not issued, this is 0.
                  not-before-policy:
                    type: integer
                    description: >-
                      The time before which the token must not be accepted.
                      Mostly internal and set to 0 unless otherwise specified.
                  scope:
                    type: string
                    description: >-
                      A space-separated list of scopes that the access token
                      grants access to. Reflects the permissions
                      approved.<br/><small>Example: <i>payments:read</i></small>
                additionalProperties: false
              examples:
                Access Token:
                  summary: Short lived access token
                  description: >-
                    Access token itself, how long it is valid for in seconds and
                    other information
                  value:
                    access_token: header.payload.signature
                    expires_in: 7200
                    refresh_expires_in: 0
                    token_type: Bearer
                    not-before-policy: 0
                    scope: payments:read
        '400':
          description: Bad Request
          content:
            application/json:
              schema: &ref_0
                type: object
                properties:
                  callId:
                    type: string
                    description: The request tracing ID
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                  statusInfo: &ref_22
                    type: object
                    properties:
                      reasonCode:
                        type: string
                        description: >-
                          Code of the status response<br/><small>Example:
                          <i>-1</i></small>
                      message:
                        type: string
                        description: >-
                          Description of the current status
                          response<br/><small>Example: <i>Awaiting user
                          consent</i></small>
                    description: The information about the status of the request
                additionalProperties: false
              examples:
                ValidationFailure:
                  summary: Validation failure
                  description: >-
                    The payload was incomplete or didn’t pass schema validation.
                    Check required fields and formats.
                  value:
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4980'
                      message: Certificate error
                    callId: dccdf12110264f4c-a19b2c
        '403':
          description: Forbidden error
          content:
            application/json:
              schema: *ref_0
              examples:
                ForbiddenError:
                  summary: Forbidden error
                  description: Authorization has failed
                  value: &ref_3
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4971'
                      message: 'Authorization error: Resource is not allowed'
                    callId: 0dbad1cf74de4f76-31bc1e
      summary: Get access token
      description: Get an access token via OAuth2
  /payments/initiate:
    post:
      tags:
        - Payment Processing APIs
      operationId: initiatePayment
      requestBody:
        content:
          application/json:
            schema: &ref_30
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                clientTransactionId:
                  type: string
                  minLength: 1
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                returnUrl:
                  type: string
                  minLength: 1
                  description: >-
                    The client's redirect destination after SCA
                    completion<br/><small>Example:
                    <i>https://api.merchant.com/callback?ref=order1234</i></small>
                transactionType:
                  type: string
                  enum:
                    - ONE_TIME
                    - RECURRING
                    - TOKENIZED
                  description: >-
                    Requesting transaction type<br/><small>• <b> ONE_TIME</b>
                    One time payment without storing payment information
                    (COF)</small><br/><small>• <b> RECURRING</b> For recurring
                    payments. Requires mandate details.</small><br/><small>• <b>
                    TOKENIZED</b> Securely stores payment information (COF).
                    Auto capture is not allowed.</small>
                paymentDetails: &ref_32
                  type: object
                  properties:
                    amount:
                      type: integer
                      format: int64
                      minimum: 1
                      description: >-
                        Total payment amount in minor units<br/><small>Example:
                        <i>200</i></small>
                    currency:
                      type: string
                      minLength: 1
                      description: >-
                        Currency code (ISO 4217)<br/><small>Example:
                        <i>EUR</i></small>
                    country:
                      type: string
                      minLength: 1
                      description: >-
                        Country code (ISO 3166-1)<br/><small>Example:
                        <i>DE</i></small>
                    description:
                      type: string
                      minLength: 1
                      description: >-
                        Transaction summary<br/><small>Example: <i>Purchase
                        request of order 1234</i></small>
                    autoCapture:
                      type: boolean
                      description: >-
                        If set to false the payment will require a manual
                        capture after finalization<br/><small>Example:
                        <i>false</i></small>
                  required:
                    - country
                    - currency
                    - description
                  description: Monetary details of the transaction
                providerDetails: &ref_33
                  type: object
                  properties:
                    providerId:
                      type: string
                      enum:
                        - WERO
                        - BLIK
                        - BIZUM
                        - SATISPAY
                        - IRIS
                      description: >-
                        The payment scheme provider ID<br/><small>• <b> WERO</b>
                        New EU digital wallet and instant payment
                        scheme</small><br/><small>• <b> BLIK</b> Polish mobile
                        payments system used for online and in-store
                        transfers</small><br/><small>• <b> BIZUM</b> Spanish
                        real-time mobile payment solution linked to bank
                        accounts</small><br/><small>• <b> SATISPAY</b>
                        Independent Italian mobile money app for everyday
                        payments</small><br/><small>• <b> IRIS</b> Greek instant
                        account-to-account payment system</small>
                  required:
                    - providerId
                  description: Payment scheme provider details
                payerDetails: &ref_31
                  type: object
                  properties:
                    payerId:
                      type: string
                      minLength: 1
                      description: >-
                        The payer's ID provided by the
                        client<br/><small>Example: <i>shopper-1234</i></small>
                    oneTimeCode:
                      type: string
                      description: >-
                        One time code before SCA<br/><small>Example:
                        <i>123456</i></small>
                    phone: &ref_4
                      type: object
                      properties:
                        countryCode:
                          type: string
                          minLength: 1
                          pattern: ^\+\d{1,4}$
                          description: >-
                            The payer's phone country code<br/><small>Example:
                            <i>+34</i></small>
                        number:
                          type: string
                          minLength: 1
                          pattern: ^\d{6,10}$
                          description: >-
                            The payer's phone number<br/><small>Example:
                            <i>644786335</i></small>
                      required:
                        - countryCode
                        - number
                      description: The payer's phone
                  required:
                    - payerId
                  description: Payer identity information
                requestContext: &ref_17
                  type: object
                  properties:
                    ipAddress:
                      type: string
                      description: >-
                        Requester’s IP address on IPv4/6
                        format<br/><small>Example: <i>203.0.113.45</i></small>
                    userAgent:
                      type: string
                      description: >-
                        Device/browser identifier<br/><small>Example:
                        <i>Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                        AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3.1
                        Safari/605.1.15</i></small>
                    channel:
                      type: string
                      enum:
                        - WEB
                        - APP
                        - SYSTEM
                      description: >-
                        Request access channel<br/><small>• <b> WEB</b> Payment
                        initiated through an online browser
                        channel</small><br/><small>• <b> APP</b> Payment
                        initiated via a mobile or desktop
                        application</small><br/><small>• <b> SYSTEM</b>  Payment
                        triggered automatically by a backend or integrated
                        system</small>
                    deviceId:
                      type: string
                      description: >-
                        App/device identifier<br/><small>Example:
                        <i>device_xyz123</i></small>
                    locale:
                      type: string
                      description: >-
                        Locale on ISO 639 format<br/><small>Example:
                        <i>es-ES</i></small>
                  description: Information about where the transaction was requested
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Free map of tags set by the
                    client<br/><small>Example</small><pre><code>{
                      "key": "value",
                      "experiment": "checkout_A",
                      "promo_code": "SPRING2025"
                    }</code></pre>
              required:
                - clientTransactionId
                - payerDetails
                - paymentDetails
                - processingAccountId
                - providerDetails
                - returnUrl
                - transactionType
              additionalProperties: false
            examples:
              Blik:
                summary: Blik
                description: Initiates a Blik payment request
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: ONE_TIME
                  paymentDetails:
                    amount: 100
                    currency: PLN
                    country: PL
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: BLIK
                  payerDetails:
                    payerId: payerUUID
                    oneTimeCode: '123456'
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: >-
                      Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                      AppleWebKit/537.36
                    channel: WEB
                    deviceId: device-12345
                    locale: pl-PL
                  metadata:
                    orderId: '12345'
                    customerId: cust-789
                    productCategory: electronics
              Bizum:
                summary: Bizum
                description: Initiates a Bizum payment request
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: ONE_TIME
                  paymentDetails:
                    amount: 50
                    currency: EUR
                    country: ES
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: BIZUM
                  payerDetails:
                    payerId: payerUUID
                    phone:
                      number: '633782248'
                      countryCode: '+34'
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: >-
                      Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X)
                      AppleWebKit/605.1.15
                    channel: WEB
                    deviceId: device-67890
                    locale: es-ES
                  metadata:
                    orderId: '12345'
                    customerId: cust-789
                    campaign: summer2025
              Wero:
                summary: Wero
                description: Initiates a Wero payment request
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: ONE_TIME
                  paymentDetails:
                    amount: 75
                    currency: EUR
                    country: DE
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: WERO
                  payerDetails:
                    payerId: payerUUID
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: >-
                      Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                      AppleWebKit/537.36
                    channel: WEB
                    deviceId: device-11223
                    locale: de-DE
                  metadata:
                    orderId: '12345'
                    customerId: cust-789
                    checkoutVersion: v2.1
              SatispayRecurring:
                summary: Satispay recurring
                description: Initiates a Satispay recurring payment
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: RECURRING
                  paymentDetails:
                    amount: 200
                    currency: EUR
                    country: IT
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: SATISPAY
                  payerDetails:
                    payerId: payerUUID
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36
                    channel: WEB
                    deviceId: device-99001
                    locale: it-IT
                  metadata:
                    subscriptionId: sub-456
                    customerId: cust-789
                    billingCycle: monthly
              SatispayOneTime:
                summary: Satispay one time
                description: Initiates a Satispay one time payment
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: ONE_TIME
                  paymentDetails:
                    amount: 200
                    currency: EUR
                    country: IT
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: SATISPAY
                  payerDetails:
                    payerId: payerUUID
                    phone:
                      countryCode: '+39'
                      number: '3121111111'
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: Mozilla/5.0 (Linux; Android 13) AppleWebKit/537.36
                    channel: APP
                    deviceId: device-44556
                    locale: it-IT
                  metadata:
                    orderId: '12345'
                    customerId: cust-789
                    storeName: Milano Store
              SatispayOneTimeRedirect:
                summary: Satispay redirect
                description: Initiates a Satispay payment with redirect
                value:
                  processingAccountId: merchant
                  clientTransactionId: order123
                  returnUrl: https://api.merchant.callback?ref=order123
                  transactionType: ONE_TIME
                  paymentDetails:
                    amount: 200
                    currency: EUR
                    country: IT
                    description: Product ID 1234 purchase
                  providerDetails:
                    providerId: SATISPAY
                  payerDetails:
                    payerId: payerUUID
                  requestContext:
                    ipAddress: 203.0.113.45
                    userAgent: >-
                      Mozilla/5.0 (Windows NT 10.0; Win64; x64)
                      AppleWebKit/537.36
                    channel: WEB
                    deviceId: device-77889
                    locale: it-IT
                  metadata:
                    orderId: '12345'
                    customerId: cust-789
                    redirectFlow: 'true'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: &ref_34
                type: object
                properties:
                  processingAccountId:
                    type: string
                    description: >-
                      The organization account ID provided at
                      onboarding<br/><small>Example:
                      <i>merchant-1234</i></small>
                  transactionId:
                    type: string
                    description: >-
                      Nopan's transaction ID<br/><small>Example:
                      <i>ee2anef9bt</i></small>
                  clientTransactionId:
                    type: string
                    description: >-
                      The unique client's internal transaction
                      ID<br/><small>Example: <i>order11234</i></small>
                  returnUrl:
                    type: string
                    description: >-
                      The client's redirect destination after SCA
                      completion<br/><small>Example:
                      <i>https://api.merchant.com/callback?ref=order1234</i></small>
                  providerDetails: &ref_35
                    type: object
                    properties:
                      providerId:
                        type: string
                        enum:
                          - WERO
                          - BLIK
                          - BIZUM
                          - SATISPAY
                          - IRIS
                        description: >-
                          The payment scheme provider ID<br/><small>• <b>
                          WERO</b> New EU digital wallet and instant payment
                          scheme</small><br/><small>• <b> BLIK</b> Polish mobile
                          payments system used for online and in-store
                          transfers</small><br/><small>• <b> BIZUM</b> Spanish
                          real-time mobile payment solution linked to bank
                          accounts</small><br/><small>• <b> SATISPAY</b>
                          Independent Italian mobile money app for everyday
                          payments</small><br/><small>• <b> IRIS</b> Greek
                          instant account-to-account payment system</small>
                      providerTransactionId:
                        type: string
                        description: >-
                          Transaction reference returned by the
                          provider<br/><small>Example: <i>wero-1234</i></small>
                      redirectUrl:
                        type: string
                        description: >-
                          The URL where the payer should perform
                          SCA<br/><small>Example:
                          <i>https://auth.merchant.com/token=consent_1234</i></small>
                      registeredAt:
                        type: string
                        format: date-time
                        description: >-
                          Timestamp when the transaction was registered in the
                          provider<br/><small>Example: <i>1748699594</i></small>
                      expiresAt:
                        type: string
                        format: date-time
                        description: >-
                          Timestamp when the redirect URL
                          expires<br/><small>Example: <i>1748622594</i></small>
                    description: Payment scheme provider details
                  metadata:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      Free map of tags set by the
                      client<br/><small>Example</small><pre><code>{
                        "key": "value",
                        "experiment": "checkout_A",
                        "promo_code": "SPRING2025"
                      }</code></pre>
                  step:
                    type: string
                    enum:
                      - INITIATE
                      - FINALIZE
                      - CAPTURE
                      - REFUND
                      - CHARGE
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                  statusInfo: &ref_1
                    type: object
                    properties:
                      reasonCode:
                        type: string
                        description: >-
                          Code of the status response<br/><small>Example:
                          <i>-1</i></small>
                      message:
                        type: string
                        description: >-
                          Description of the current status
                          response<br/><small>Example: <i>Awaiting user
                          consent</i></small>
                    description: The information about the status of the request
                additionalProperties: false
              examples:
                ApprovalPending:
                  summary: Approval pending
                  description: The request has been accepted and awaits for SCA
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order123
                    returnUrl: https://api.merchant.callback?ref=order123
                    providerDetails:
                      providerId: WERO
                      providerTransactionId: 9c82132e-eb2a-491c-970d-47260d4122b0
                      redirectUrl: https://merchant.callback.com
                      registeredAt: '2026-01-19T14:32:05.987654Z'
                      expiresAt: '2026-01-19T14:32:05.987654Z'
                    status: PENDING
                    step: INITIATE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema: &ref_7
                type: object
                properties:
                  statusInfo: *ref_1
                  callId:
                    type: string
                    description: The request tracing ID
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                  fields:
                    type: object
                    additionalProperties:
                      type: string
                    description: A map of fields that have failed validation
                additionalProperties: false
              examples:
                MalformedJson:
                  summary: Malformed JSON
                  description: The JSON is not properly formatted
                  value: &ref_8
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4000'
                      message: >-
                        The payload was incomplete or didn't pass schema
                        validation. Check required fields and formats.
                    callId: a3c8cdef0a134df4-2e31b1
                ValidationFailure:
                  summary: Validation failure
                  description: The client ID and payment amount are invalid
                  value: &ref_19
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4000'
                      message: Invalid input
                    fields:
                      processingAccountId: Processing Account ID is required
                      paymentDetails.amount: Amount is required
                    callId: 678c62b0177e4bc3-a12309
                SignatureError:
                  summary: Signature error
                  description: There was an error signing the signature
                  value: &ref_9
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4990'
                      message: Signature error
                    callId: 0af7a364bc7745f2-b823fc
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: &ref_2
                type: object
                properties:
                  statusInfo: *ref_1
                  callId:
                    type: string
                    description: The request tracing ID
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                additionalProperties: false
              examples:
                InvalidSignature:
                  summary: Invalid signature
                  description: The signature is not valid
                  value: &ref_10
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4991'
                      message: Error validating the signature
                    callId: a3c8cdef0a134df4-2e31b1
                TokenExpired:
                  summary: Token expired
                  description: Token is expired
                  value: &ref_11
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4061'
                      message: Token is expired
                    callId: c84b0b9f91714d4e-5d2311
                UnauthorizedError:
                  summary: Unauthorized error
                  description: Unable to authorize user
                  value: &ref_12
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4970'
                      message: Authentication error
                    callId: be1d37ab317e4b2d-a8f9d4
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
              examples:
                ForbiddenError:
                  summary: Forbidden error
                  description: Authorization has failed
                  value: *ref_3
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
              examples:
                ConflictError:
                  summary: Conflict error
                  description: Payment transaction is already created
                  value: &ref_13
                    status: DECLINED
                    statusInfo:
                      reasonCode: '4010'
                      message: Payment already exists
                    callId: 9cf37980efdc4316-01a4bc
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
              examples:
                RateLimitError:
                  summary: Rate limit error
                  description: The rate limit has been exceeded
                  value: &ref_14
                    status: DECLINED
                    statusInfo:
                      reasonCode: '3000'
                      message: Rate limit exceeded
                    callId: 4a9137cf2ccf4c19-00982e
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
              examples:
                InternalServerError:
                  summary: Internal server error
                  description: An unexpected error has happened
                  value: &ref_15
                    status: DECLINED
                    statusInfo:
                      reasonCode: '9999'
                      message: Internal Server Error
                    callId: e147c3ba09cd496f-bd02e7
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
              examples:
                BadGatewayError:
                  summary: Bad gateway error
                  description: Unable to reach the provider
                  value: &ref_16
                    status: DECLINED
                    statusInfo:
                      reasonCode: '8003'
                      message: Provider Error
                    callId: 0af7a364bc7745f2-b823fc
      summary: Initiate payment
      description: >-
        Starts a new payment flow. The client provides payment details, and the
        response includes a redirect URL for the payer's SCA.
  /payments/finalize:
    post:
      tags:
        - Payment Processing APIs
      operationId: finalizePayment
      requestBody:
        content:
          application/json:
            schema: &ref_36
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                transactionId:
                  type: string
                  minLength: 1
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
              required:
                - processingAccountId
                - transactionId
              additionalProperties: false
            examples:
              Finalize:
                summary: Finalize
                description: Finalizes a payment
                value:
                  processingAccountId: merchant
                  transactionId: ee2anef9bt
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: &ref_18
                type: object
                properties:
                  transactionId:
                    type: string
                    description: >-
                      Nopan's transaction ID<br/><small>Example:
                      <i>ee2anef9bt</i></small>
                  processingAccountId:
                    type: string
                    description: >-
                      The organization account ID provided at
                      onboarding<br/><small>Example:
                      <i>merchant-1234</i></small>
                  clientTransactionId:
                    type: string
                    description: >-
                      The unique client's internal transaction
                      ID<br/><small>Example: <i>order11234</i></small>
                  providerDetails: &ref_29
                    type: object
                    properties:
                      providerId:
                        type: string
                        enum:
                          - WERO
                          - BLIK
                          - BIZUM
                          - SATISPAY
                          - IRIS
                        description: >-
                          The payment scheme provider ID<br/><small>• <b>
                          WERO</b> New EU digital wallet and instant payment
                          scheme</small><br/><small>• <b> BLIK</b> Polish mobile
                          payments system used for online and in-store
                          transfers</small><br/><small>• <b> BIZUM</b> Spanish
                          real-time mobile payment solution linked to bank
                          accounts</small><br/><small>• <b> SATISPAY</b>
                          Independent Italian mobile money app for everyday
                          payments</small><br/><small>• <b> IRIS</b> Greek
                          instant account-to-account payment system</small>
                      providerTransactionId:
                        type: string
                        description: >-
                          Transaction reference returned by the
                          provider<br/><small>Example: <i>wero-1234</i></small>
                      redirectUrl:
                        type: string
                        description: >-
                          The URL where the payer should perform
                          SCA<br/><small>Example:
                          <i>https://auth.merchant.com/token=consent_1234</i></small>
                      registeredAt:
                        type: integer
                        format: int64
                        description: >-
                          Timestamp when the transaction was registered in the
                          provider<br/><small>Example: <i>1748699594</i></small>
                      expiresAt:
                        type: integer
                        format: int64
                        description: >-
                          Timestamp when the redirect URL
                          expires<br/><small>Example: <i>1748622594</i></small>
                    description: Payment scheme provider details
                  payerDetails: &ref_25
                    type: object
                    properties:
                      payerId:
                        type: string
                        description: >-
                          The payer's ID provided by the
                          client<br/><small>Example: <i>shopper-1234</i></small>
                      phone: *ref_4
                      oneTimeCode:
                        type: string
                        description: >-
                          One time code before SCA<br/><small>Example:
                          <i>123456</i></small>
                      paymentToken:
                        type: string
                        description: >-
                          The payment token of the payer<br/><small>Example:
                          <i>eyJraWQiOiI5MDU5OGE2NC1jZWNlLTQ1YzItOGUzMy02OTAzODA5OTBlYjgiLCJhbGciOiJSUzI1NiJ9...</i></small>
                    description: Payer identity information
                  paymentDetails: &ref_26
                    type: object
                    properties:
                      amount:
                        type: integer
                        format: int64
                        description: >-
                          Total payment amount in minor
                          units<br/><small>Example: <i>200</i></small>
                      capturedAmount:
                        type: integer
                        format: int64
                        description: >-
                          Total captured amount in minor units so
                          far<br/><small>Example: <i>200</i></small>
                      refundedAmount:
                        type: integer
                        format: int64
                        description: >-
                          Total refunded amount in minor units so
                          far<br/><small>Example: <i>100</i></small>
                      currency:
                        type: string
                        description: >-
                          Currency code (ISO 4217)<br/><small>Example:
                          <i>EUR</i></small>
                      country:
                        type: string
                        description: >-
                          Country code (ISO 3166-1)<br/><small>Example:
                          <i>DE</i></small>
                      description:
                        type: string
                        description: >-
                          Transaction summary<br/><small>Example: <i>Purchase
                          request of order 1234</i></small>
                      autoCapture:
                        type: boolean
                        description: >-
                          If set to false the payment will require a manual
                          capture after finalization<br/><small>Example:
                          <i>false</i></small>
                      captures:
                        type: array
                        items: &ref_27
                          type: object
                          properties:
                            clientTransactionId:
                              type: string
                              description: >-
                                The unique client's internal transaction
                                ID<br/><small>Example: <i>order11234</i></small>
                            paymentDetails: &ref_5
                              type: object
                              properties:
                                amount:
                                  type: integer
                                  format: int64
                              description: Monetary details of the transaction
                            providerDetails: &ref_6
                              type: object
                              properties:
                                providerOperationId:
                                  type: string
                                registeredAt:
                                  type: string
                                  format: date-time
                              description: Payment scheme provider details
                            status:
                              type: string
                              enum:
                                - APPROVED
                                - DECLINED
                              description: >-
                                The current state of the capture<br/><small>•
                                <b> APPROVED</b> Capture successfully executed
                                and funds collected</small><br/><small>• <b>
                                DECLINED</b> Capture request rejected and funds
                                were not collected</small>
                            statusInfo: *ref_1
                            timestamp:
                              type: string
                              format: date-time
                        description: >-
                          Collection of records for each capture attempted
                          and/or performed on the payment
                      refunds:
                        type: array
                        items: &ref_28
                          type: object
                          properties:
                            clientTransactionId:
                              type: string
                              description: >-
                                The unique client's internal transaction
                                ID<br/><small>Example: <i>order11234</i></small>
                            paymentDetails: *ref_5
                            providerDetails: *ref_6
                            status:
                              type: string
                              enum:
                                - ACCEPTED
                                - APPROVED
                                - DECLINED
                              description: >-
                                The current state of the refund<br/><small>• <b>
                                ACCEPTED</b> Refund request received and
                                awaiting processing</small><br/><small>• <b>
                                APPROVED</b> Refund successfully executed and
                                funds returned</small><br/><small>• <b>
                                DECLINED</b> Refund request rejected and will
                                not proceed</small>
                            statusInfo: *ref_1
                            timestamp:
                              type: string
                              format: date-time
                        description: >-
                          Collection of records for each refund attempted and/or
                          performed on the payment
                    description: Monetary details of the transaction
                  metadata:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      Free map of tags set by the
                      client<br/><small>Example</small><pre><code>{
                        "key": "value",
                        "experiment": "checkout_A",
                        "promo_code": "SPRING2025"
                      }</code></pre>
                  step:
                    type: string
                    enum:
                      - INITIATE
                      - FINALIZE
                      - CAPTURE
                      - REFUND
                      - CHARGE
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                  statusInfo: *ref_1
                additionalProperties: false
              examples:
                Approved:
                  summary: Payment approved
                  description: The payment has been approved and ready for capture
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order123
                    paymentDetails:
                      amount: 75
                      capturedAmount: 0
                      currency: EUR
                      country: DE
                      description: Product ID 1234 purchase
                      autoCapture: false
                    status: APPROVED
                    step: FINALIZE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
                ApprovedAndCaptured:
                  summary: Payment approved and captured
                  description: The payment has been approved and captured
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order123
                    paymentDetails:
                      amount: 75
                      capturedAmount: 75
                      currency: EUR
                      country: DE
                      description: Product ID 1234 purchase
                      autoCapture: false
                    status: APPROVED
                    step: CAPTURE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
                Declined:
                  summary: Payment declined
                  description: The payment has been declined
                  value:
                    status: DECLINED
                    statusInfo:
                      reasonCode: '1000'
                      message: Non sufficient funds
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
              examples:
                MalformedJson:
                  summary: Malformed JSON
                  description: The JSON is not properly formatted
                  value: *ref_8
                ValidationFailure:
                  summary: Validation failure
                  description: The client ID and provider details are invalid
                  value:
                    status: DECLINED
                    statusInfo:
                      reasonCode: validation-error
                      message: Validation failed for one or more fields
                    fields:
                      processingAccountId: Processing Account ID is required
                      providerDetails: Provider details are required
                SignatureError:
                  summary: Signature error
                  description: There was an error signing the signature
                  value: *ref_9
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
              examples:
                InvalidSignature:
                  summary: Invalid signature
                  description: The signature is not valid
                  value: *ref_10
                TokenExpired:
                  summary: Token expired
                  description: Token is expired
                  value: *ref_11
                UnauthorizedError:
                  summary: Unauthorized error
                  description: Unable to authorize user
                  value: *ref_12
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
              examples:
                ForbiddenError:
                  summary: Forbidden error
                  description: Authorization has failed
                  value: *ref_3
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
              examples:
                ConflictError:
                  summary: Conflict error
                  description: Payment transaction is already created
                  value: *ref_13
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
              examples:
                RateLimitError:
                  summary: Rate limit error
                  description: The rate limit has been exceeded
                  value: *ref_14
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
              examples:
                InternalServerError:
                  summary: Internal server error
                  description: An unexpected error has happened
                  value: *ref_15
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
              examples:
                BadGatewayError:
                  summary: Bad gateway error
                  description: Unable to reach the provider
                  value: *ref_16
      summary: Finalize payment
      description: >-
        Finalizes a two-step payment, optionally capturing funds if configured.
        For one-step payments, it serves as the merchant's acknowledgement.
  /payments/charge:
    post:
      tags:
        - Payment Processing APIs
      operationId: chargePayment
      requestBody:
        content:
          application/json:
            schema: &ref_37
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                clientTransactionId:
                  type: string
                  minLength: 1
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                paymentDetails: &ref_39
                  type: object
                  properties:
                    amount:
                      type: integer
                      format: int64
                      minimum: 1
                      description: >-
                        Total payment amount in minor units<br/><small>Example:
                        <i>200</i></small>
                    currency:
                      type: string
                      minLength: 1
                      description: >-
                        Currency code (ISO 4217)<br/><small>Example:
                        <i>EUR</i></small>
                    country:
                      type: string
                      minLength: 1
                      description: >-
                        Country code (ISO 3166-1)<br/><small>Example:
                        <i>DE</i></small>
                    description:
                      type: string
                      minLength: 1
                      description: >-
                        Transaction summary<br/><small>Example: <i>Purchase
                        request of order 1234</i></small>
                    autoCapture:
                      type: boolean
                      description: >-
                        If set to false the payment will require a manual
                        capture after finalization<br/><small>Example:
                        <i>false</i></small>
                  required:
                    - country
                    - currency
                    - description
                  description: Monetary details of the transaction
                providerDetails: &ref_40
                  type: object
                  properties:
                    providerId:
                      type: string
                      enum:
                        - WERO
                        - BLIK
                        - BIZUM
                        - SATISPAY
                        - IRIS
                      description: >-
                        The payment scheme provider ID<br/><small>• <b> WERO</b>
                        New EU digital wallet and instant payment
                        scheme</small><br/><small>• <b> BLIK</b> Polish mobile
                        payments system used for online and in-store
                        transfers</small><br/><small>• <b> BIZUM</b> Spanish
                        real-time mobile payment solution linked to bank
                        accounts</small><br/><small>• <b> SATISPAY</b>
                        Independent Italian mobile money app for everyday
                        payments</small><br/><small>• <b> IRIS</b> Greek instant
                        account-to-account payment system</small>
                  required:
                    - providerId
                  description: Payment scheme provider details
                payerDetails: &ref_38
                  type: object
                  properties:
                    payerId:
                      type: string
                      minLength: 1
                      description: >-
                        The payer's ID provided by the
                        client<br/><small>Example: <i>shopper-1234</i></small>
                    paymentToken:
                      type: string
                      description: >-
                        The payment token of the payer<br/><small>Example:
                        <i>eyJraWQiOiI5MDU5OGE2NC1jZWNlLTQ1YzItOGUzMy02OTAzODA5OTBlYjgiLCJhbGciOiJSUzI1NiJ9...</i></small>
                  required:
                    - payerId
                  description: Payer identity information
                requestContext: *ref_17
                metadata:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Free map of tags set by the
                    client<br/><small>Example</small><pre><code>{
                      "key": "value",
                      "experiment": "checkout_A",
                      "promo_code": "SPRING2025"
                    }</code></pre>
              required:
                - clientTransactionId
                - payerDetails
                - paymentDetails
                - processingAccountId
                - providerDetails
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: &ref_41
                type: object
                properties:
                  processingAccountId:
                    type: string
                    description: >-
                      The organization account ID provided at
                      onboarding<br/><small>Example:
                      <i>merchant-1234</i></small>
                  transactionId:
                    type: string
                    description: >-
                      Nopan's transaction ID<br/><small>Example:
                      <i>ee2anef9bt</i></small>
                  clientTransactionId:
                    type: string
                    description: >-
                      The unique client's internal transaction
                      ID<br/><small>Example: <i>order11234</i></small>
                  providerDetails: &ref_42
                    type: object
                    properties:
                      providerId:
                        type: string
                        enum:
                          - WERO
                          - BLIK
                          - BIZUM
                          - SATISPAY
                          - IRIS
                        description: >-
                          The payment scheme provider ID<br/><small>• <b>
                          WERO</b> New EU digital wallet and instant payment
                          scheme</small><br/><small>• <b> BLIK</b> Polish mobile
                          payments system used for online and in-store
                          transfers</small><br/><small>• <b> BIZUM</b> Spanish
                          real-time mobile payment solution linked to bank
                          accounts</small><br/><small>• <b> SATISPAY</b>
                          Independent Italian mobile money app for everyday
                          payments</small><br/><small>• <b> IRIS</b> Greek
                          instant account-to-account payment system</small>
                      providerTransactionId:
                        type: string
                        description: >-
                          Transaction reference returned by the
                          provider<br/><small>Example: <i>wero-1234</i></small>
                      registeredAt:
                        type: string
                        format: date-time
                        description: >-
                          Timestamp when the transaction was registered in the
                          provider<br/><small>Example: <i>1748699594</i></small>
                    description: Payment scheme provider details
                  metadata:
                    type: object
                    additionalProperties:
                      type: string
                    description: >-
                      Free map of tags set by the
                      client<br/><small>Example</small><pre><code>{
                        "key": "value",
                        "experiment": "checkout_A",
                        "promo_code": "SPRING2025"
                      }</code></pre>
                  step:
                    type: string
                    enum:
                      - INITIATE
                      - FINALIZE
                      - CAPTURE
                      - REFUND
                      - CHARGE
                  status:
                    type: string
                    enum:
                      - ACCEPTED
                      - PENDING
                      - APPROVED
                      - DECLINED
                      - CANCELED
                    description: >-
                      The current state of the transaction<br/><small>• <b>
                      ACCEPTED</b> Refund request received and awaiting
                      processing</small><br/><small>• <b> PENDING</b> The
                      transaction has reached the provider and waits for
                      SCA</small><br/><small>• <b> APPROVED</b> The transaction
                      has been accepted by the provider</small><br/><small>• <b>
                      DECLINED</b> The transaction has been
                      declined</small><br/><small>• <b> CANCELED</b> The
                      transaction has been canceled</small>
                  statusInfo: *ref_1
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
      summary: Charge payment
      description: >-
        Triggers a recurring or token-based payment without user interaction in
        one step.
  /payments/capture:
    post:
      tags:
        - Payment Processing APIs
      operationId: capturePayment
      requestBody:
        content:
          application/json:
            schema: &ref_43
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                clientTransactionId:
                  type: string
                  minLength: 1
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                transactionId:
                  type: string
                  minLength: 1
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
                paymentDetails: &ref_44
                  type: object
                  properties:
                    amount:
                      type: integer
                      format: int64
                      minimum: 1
                      description: >-
                        Total payment amount in minor units<br/><small>Example:
                        <i>200</i></small>
                  description: Monetary details of the transaction
              required:
                - clientTransactionId
                - paymentDetails
                - processingAccountId
                - transactionId
              additionalProperties: false
            examples:
              Capture:
                summary: Capture
                description: Captures partial or full amount
                value:
                  processingAccountId: merchant
                  clientTransactionId: order-1234
                  transactionId: ee2anef9bt
                  paymentDetails:
                    amount: 75
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: *ref_18
              examples:
                Captured:
                  summary: Amount captured
                  description: The amount has been captured
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order123
                    paymentDetails:
                      amount: 75
                      capturedAmount: 75
                      currency: EUR
                      country: DE
                      description: Product ID 1234 purchase
                      autoCapture: false
                    status: APPROVED
                    step: CAPTURE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
              examples:
                MalformedJson:
                  summary: Malformed JSON
                  description: The JSON is not properly formatted
                  value: *ref_8
                SignatureError:
                  summary: Signature error
                  description: There was an error signing the signature
                  value: *ref_9
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
              examples:
                InvalidSignature:
                  summary: Invalid signature
                  description: The signature is not valid
                  value: *ref_10
                TokenExpired:
                  summary: Token expired
                  description: Token is expired
                  value: *ref_11
                UnauthorizedError:
                  summary: Unauthorized error
                  description: Unable to authorize user
                  value: *ref_12
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
              examples:
                ForbiddenError:
                  summary: Forbidden error
                  description: Authorization has failed
                  value: *ref_3
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
              examples:
                ConflictError:
                  summary: Conflict error
                  description: Payment transaction is already created
                  value: *ref_13
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
              examples:
                RateLimitError:
                  summary: Rate limit error
                  description: The rate limit has been exceeded
                  value: *ref_14
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
              examples:
                InternalServerError:
                  summary: Internal server error
                  description: An unexpected error has happened
                  value: *ref_15
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
              examples:
                BadGatewayError:
                  summary: Bad gateway error
                  description: Unable to reach the provider
                  value: *ref_16
      summary: Capture payment
      description: >-
        Captures funds from a previously finalized payment without auto capture.
        Enables delayed capture scenarios for clients who prefer control over
        timing
  /payments/cancel:
    post:
      tags:
        - Payment Processing APIs
      operationId: cancelPayment
      requestBody:
        content:
          application/json:
            schema: &ref_45
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                clientTransactionId:
                  type: string
                  minLength: 1
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                transactionId:
                  type: string
                  minLength: 1
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
              required:
                - clientTransactionId
                - processingAccountId
                - transactionId
              additionalProperties: false
            examples:
              Cancel:
                summary: Cancel
                description: Cancels a payment
                value:
                  processingAccountId: merchant
                  clientTransactionId: order-1234
                  transactionId: ee2anef9bt
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: *ref_18
              examples:
                Initiated canceled:
                  summary: Initiated canceled
                  description: Payment initiated and canceled
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order-1234
                    providerDetails:
                      providerId: SATISPAY
                      providerTransactionId: 019bb12e-843a-784f-bd77-b69dcfc02e8d
                      redirectUrl: >-
                        https://staging-online.satispay.com/pay/019bb12e-843a-784f-bd77-b69dcfc02e8d?redirect_url=https://merchant.com
                      registeredAt: 1768204174405
                      expiresAt: 1768211374402
                    payerDetails:
                      payerId: payerUUID
                    paymentDetails:
                      amount: 100
                      capturedAmount: 0
                      refundedAmount: 0
                      currency: EUR
                      country: IT
                      description: Product ID 1234 purchase
                      autoCapture: true
                    metadata:
                      promo: BLACK_FRIDAY
                      key: value
                    status: CANCELED
                    step: FINALIZE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
                Finalized canceled:
                  summary: Finalized canceled
                  description: Payment finalized and canceled
                  value:
                    transactionId: ee2anef9bt
                    clientTransactionId: order-1234
                    providerDetails:
                      providerId: SATISPAY
                      providerTransactionId: 019bb12e-843a-784f-bd66-b69dcfc02e8d
                      redirectUrl: >-
                        https://staging-online.satispay.com/pay/019bb12e-843a-784f-bd66-b69dcfc02e8d?redirect_url=https://merchant.com
                      registeredAt: 1768204174405
                      expiresAt: 1768211374402
                    payerDetails:
                      payerId: payerUUID
                    paymentDetails:
                      amount: 100
                      capturedAmount: 0
                      refundedAmount: 0
                      currency: EUR
                      country: IT
                      description: Product ID 1234 purchase
                      autoCapture: true
                    metadata:
                      promo: BLACK_FRIDAY
                      key: value
                    status: CANCELED
                    step: INITIATE
                    statusInfo:
                      reasonCode: '-1'
                      message: Request processed successfully
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
              examples:
                MalformedJson:
                  summary: Malformed JSON
                  description: The JSON is not properly formatted
                  value: *ref_8
                SignatureError:
                  summary: Signature error
                  description: There was an error signing the signature
                  value: *ref_9
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
              examples:
                InvalidSignature:
                  summary: Invalid signature
                  description: The signature is not valid
                  value: *ref_10
                TokenExpired:
                  summary: Token expired
                  description: Token is expired
                  value: *ref_11
                UnauthorizedError:
                  summary: Unauthorized error
                  description: Unable to authorize user
                  value: *ref_12
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
              examples:
                ForbiddenError:
                  summary: Forbidden error
                  description: Authorization has failed
                  value: *ref_3
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
              examples:
                RateLimitError:
                  summary: Rate limit error
                  description: The rate limit has been exceeded
                  value: *ref_14
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
              examples:
                InternalServerError:
                  summary: Internal server error
                  description: An unexpected error has happened
                  value: *ref_15
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
              examples:
                BadGatewayError:
                  summary: Bad gateway error
                  description: Unable to reach the provider
                  value: *ref_16
      summary: Cancel payment
      description: >-
        Cancels an initiated but not yet captured payment. Prevents future fund
        movements.
  /payments/refund:
    post:
      tags:
        - Payment Processing APIs
      operationId: refundPayment
      requestBody:
        content:
          application/json:
            schema: &ref_23
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                clientTransactionId:
                  type: string
                  minLength: 1
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                transactionId:
                  type: string
                  minLength: 1
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
                paymentDetails: &ref_24
                  type: object
                  properties:
                    amount:
                      type: integer
                      format: int64
                      minimum: 1
                      description: >-
                        Total payment amount in minor units<br/><small>Example:
                        <i>200</i></small>
                  description: Monetary details of the transaction
              required:
                - clientTransactionId
                - paymentDetails
                - processingAccountId
                - transactionId
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: *ref_18
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
      summary: Refund payment
      description: >-
        Refunds a previously captured payment, either fully or partially. Used
        to reverse a transaction after funds have already been settled.
  /payments/{transactionId}/status:
    get:
      tags:
        - Payment Processing APIs
      operationId: getPaymentStatus
      parameters:
        - name: transactionId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema: *ref_18
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
      summary: Payment status
      description: >-
        Returns the current status of a payment. Optionally includes recent
        history.
  /mock/set:
    post:
      tags:
        - Testing APIs
      operationId: mockPayment
      requestBody:
        content:
          application/json:
            schema: &ref_54
              type: object
              properties:
                processingAccountId:
                  type: string
                  minLength: 1
                  description: >-
                    The organization account ID provided at
                    onboarding<br/><small>Example: <i>merchant-1234</i></small>
                key: &ref_55
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - CLIENT_TRANSACTION_ID
                        - PAYER_ID
                      description: >-
                        Field to match as a key<br/><small>• <b>
                        CLIENT_TRANSACTION_ID</b> Client transaction
                        ID</small><br/><small>• <b> PAYER_ID</b> Payer
                        ID</small>
                    value:
                      type: string
                      minLength: 1
                      description: >-
                        Value of the field set in key. If payment request match
                        this, the mock will be used.
                  required:
                    - type
                    - value
                  description: Information about the key type and value to be mocked
                type:
                  type: string
                  enum:
                    - MOCK
                    - PASSTHROUGH
                  description: >-
                    The mock type<br/><small>• <b> MOCK</b> Use Mock
                    engine</small><br/><small>• <b> PASSTHROUGH</b> Use real
                    payment scheme provider</small>
                oneTime:
                  type: boolean
                  description: >-
                    If true, the mock will be deleted for that step after one
                    call
                steps: &ref_56
                  type: object
                  properties:
                    initiateStep: &ref_52
                      type: object
                      properties:
                        providerDetails: &ref_53
                          type: object
                          properties:
                            providerTransactionId:
                              type: string
                              description: >-
                                Transaction reference returned by the
                                provider<br/><small>Example:
                                <i>wero-1234</i></small>
                            redirectUrl:
                              type: string
                              description: >-
                                The URL where the payer should perform
                                SCA<br/><small>Example:
                                <i>https://auth.merchant.com/token=consent_1234</i></small>
                            registeredAt:
                              type: string
                              format: date-time
                              description: >-
                                Timestamp when the transaction was registered in
                                the provider<br/><small>Example:
                                <i>1748699594</i></small>
                            expiresAt:
                              type: string
                              format: date-time
                              description: >-
                                Timestamp when the redirect URL
                                expires<br/><small>Example:
                                <i>1748622594</i></small>
                          description: Payment scheme provider details
                        statusInfo: *ref_1
                    finalizeStep: &ref_51
                      type: object
                      properties:
                        statusInfo: *ref_1
                    captureStep: &ref_47
                      type: object
                      properties:
                        providerDetails: &ref_48
                          type: object
                          properties:
                            providerOperationId:
                              type: string
                            registeredAt:
                              type: string
                              format: date-time
                              description: >-
                                Timestamp when the transaction was registered in
                                the provider<br/><small>Example:
                                <i>1748699594</i></small>
                          description: Payment scheme provider details
                        statusInfo: *ref_1
                    cancelStep: &ref_46
                      type: object
                      properties:
                        statusInfo: *ref_1
                    refundStep: &ref_57
                      type: object
                      properties:
                        approved:
                          type: boolean
                        providerDetails: &ref_58
                          type: object
                          properties:
                            providerOperationId:
                              type: string
                            registeredAt:
                              type: string
                              format: date-time
                              description: >-
                                Timestamp when the transaction was registered in
                                the provider<br/><small>Example:
                                <i>1748699594</i></small>
                          description: Payment scheme provider details
                        statusInfo: *ref_1
                    chargeStep: &ref_49
                      type: object
                      properties:
                        providerDetails: &ref_50
                          type: object
                          properties:
                            providerTransactionId:
                              type: string
                              description: >-
                                Transaction reference returned by the
                                provider<br/><small>Example:
                                <i>wero-1234</i></small>
                            registeredAt:
                              type: string
                              format: date-time
                              description: >-
                                Timestamp when the transaction was registered in
                                the provider<br/><small>Example:
                                <i>1748699594</i></small>
                          description: Payment scheme provider details
                        statusInfo: *ref_1
                  description: Information to be mocked for each of the payment steps
              required:
                - key
                - processingAccountId
                - type
              additionalProperties: false
            examples:
              MockMode:
                summary: 'Mock mode: All fields mocked'
                description: Create a mock for all the steps in MOCK mode.
                value:
                  processingAccountId: merchant
                  key:
                    type: CLIENT_TRANSACTION_ID
                    value: order123
                  type: MOCK
                  oneTime: false
                  steps:
                    initiate:
                      clientTransactionId: order123
                      status: ACCEPTED
                      providerDetails:
                        providerTransactionId: 9c82132e-eb2a-491c-970d-47260d4122b0
                        redirectUrl: https://merchant.callback.com
                        registeredAt: 1748505211886
                        expiresAt: 1748505271887
                      statusInfo:
                        reasonCode: '-1'
                        message: Awaiting user consent
              PassThroughMode:
                summary: Pass-through mode
                description: Create a mock for all the steps in PASSTHROUGH mode.
                value:
                  processingAccountId: merchant
                  key:
                    type: CLIENT_TRANSACTION_ID
                    value: order123
                  type: PASSTHROUGH
                  oneTime: false
                  steps:
                    initiate:
                      clientTransactionId: order123
                      status: ACCEPTED
        required: true
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
          content:
            application/json:
              schema: *ref_7
              examples:
                MalformedJson:
                  summary: Malformed JSON
                  description: The JSON is not properly formatted
                  value: *ref_8
                ValidationFailure:
                  summary: Validation failure
                  description: The client ID and payment amount are invalid
                  value: *ref_19
        '401':
          description: Unauthorized
          content:
            application/json:
              schema: *ref_2
        '403':
          description: Forbidden
          content:
            application/json:
              schema: *ref_2
        '404':
          description: Not Found
          content:
            application/json:
              schema: *ref_2
        '409':
          description: Conflict
          content:
            application/json:
              schema: *ref_2
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema: *ref_2
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema: *ref_2
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema: *ref_2
      summary: Mock payment flow
      description: >-
        Mocks a payment flow. Mock will match requests using processingAccountId
        and key.
  /notifications/paymentInitiated:
    post:
      tags:
        - Webhooks
      operationId: initiatedNotification
      requestBody:
        content:
          application/json:
            schema: &ref_59
              type: object
              properties:
                notificationId:
                  type: string
                  format: uuid
                  description: >-
                    Unique id of the notification.<br/><small>Example:
                    <i>56562de8-9b89-4628-b2fe-cd1b2cc1e95b</i></small>
                transactionId:
                  type: string
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
                clientTransactionId:
                  type: string
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                notificationType:
                  type: string
                  enum:
                    - PAYMENT_INITIATED
                    - PAYMENT_FINALIZED
                    - PAYMENT_CAPTURED
              additionalProperties: false
            examples:
              Initiated:
                summary: Payment initiated notification
                description: A Payment has been initiated
                value:
                  notificationId: 2d591c23-85b1-4e8c-a6bd-74d89f8955c5
                  transactionId: ee2anef9bt
                  notificationType: PAYMENT_FINALIZED
        required: true
      responses:
        '200':
          description: OK
      summary: Payment initiated notification
      description: >-
        Notifies you when a payment has been initiated. The exact path of the
        request is configured through our portal.
  /notifications/paymentFinalized:
    post:
      tags:
        - Webhooks
      operationId: finalizedNotification
      requestBody:
        content:
          application/json:
            schema: &ref_60
              type: object
              properties:
                notificationId:
                  type: string
                  format: uuid
                  description: >-
                    Unique id of the notification.<br/><small>Example:
                    <i>56562de8-9b89-4628-b2fe-cd1b2cc1e95b</i></small>
                transactionId:
                  type: string
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
                clientTransactionId:
                  type: string
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                notificationType:
                  type: string
                  enum:
                    - PAYMENT_INITIATED
                    - PAYMENT_FINALIZED
                    - PAYMENT_CAPTURED
              additionalProperties: false
            examples:
              Finalized:
                summary: Payment finalized notification
                description: The amount has been captured
                value:
                  notificationId: 2d591c23-85b1-4e8c-a6bd-74d89f8955c5
                  transactionId: ee2anef9bt
                  notificationType: PAYMENT_FINALIZED
        required: true
      responses:
        '200':
          description: OK
      summary: Payment finalized notification
      description: >-
        Notifies you when a payment has been finalized. The exact path of the
        request is configured through our portal.
  /notifications/paymentCaptured:
    post:
      tags:
        - Webhooks
      operationId: captureNotification
      requestBody:
        content:
          application/json:
            schema: &ref_61
              type: object
              properties:
                notificationId:
                  type: string
                  format: uuid
                  description: >-
                    Unique id of the notification.<br/><small>Example:
                    <i>56562de8-9b89-4628-b2fe-cd1b2cc1e95b</i></small>
                transactionId:
                  type: string
                  description: >-
                    Nopan's transaction ID<br/><small>Example:
                    <i>ee2anef9bt</i></small>
                clientTransactionId:
                  type: string
                  description: >-
                    The unique client's internal transaction
                    ID<br/><small>Example: <i>order11234</i></small>
                notificationType:
                  type: string
                  enum:
                    - PAYMENT_INITIATED
                    - PAYMENT_FINALIZED
                    - PAYMENT_CAPTURED
              additionalProperties: false
            examples:
              Capture:
                summary: Payment captured notification
                description: The amount has been captured
                value:
                  notificationId: 2d591c23-85b1-4e8c-a6bd-74d89f8955c5
                  transactionId: ee2anef9bt
                  notificationType: PAYMENT_CAPTURED
        required: true
      responses:
        '200':
          description: OK
      summary: Payment captured notification
      description: >-
        Notifies you when a payment has been captured. The exact path of the
        request is configured through our portal.
components:
  schemas:
    com.nopan.auth.TokenRequest: *ref_20
    com.nopan.auth.TokenResponse: *ref_21
    com.nopan.auth.StatusInfo: *ref_22
    com.nopan.auth.Error: *ref_0
    com.nopan.api.gateway.domain.common.StatusInfo: *ref_1
    com.nopan.api.gateway.domain.errors.ValidationError: *ref_7
    com.nopan.api.gateway.domain.errors.Error: *ref_2
    com.nopan.api.gateway.domain.integrator.RefundRequest: *ref_23
    com.nopan.api.gateway.domain.integrator.RefundRequest.PaymentDetails: *ref_24
    com.nopan.api.gateway.domain.common.CommonResponse: *ref_18
    com.nopan.api.gateway.domain.common.CommonResponse.PayerDetails: *ref_25
    com.nopan.api.gateway.domain.common.CommonResponse.PaymentDetails: *ref_26
    com.nopan.api.gateway.domain.common.CommonResponse.PaymentDetails.CaptureDetails: *ref_27
    com.nopan.api.gateway.domain.common.CommonResponse.PaymentDetails.OperationPaymentDetails: *ref_5
    com.nopan.api.gateway.domain.common.CommonResponse.PaymentDetails.OperationProviderDetails: *ref_6
    com.nopan.api.gateway.domain.common.CommonResponse.PaymentDetails.RefundDetails: *ref_28
    com.nopan.api.gateway.domain.common.CommonResponse.ProviderDetails: *ref_29
    com.nopan.api.gateway.domain.common.Phone: *ref_4
    com.nopan.api.gateway.domain.common.RequestContext: *ref_17
    com.nopan.api.gateway.domain.integrator.InitiateRequest: *ref_30
    com.nopan.api.gateway.domain.integrator.InitiateRequest.PayerDetails: *ref_31
    com.nopan.api.gateway.domain.integrator.InitiateRequest.PaymentDetails: *ref_32
    com.nopan.api.gateway.domain.integrator.InitiateRequest.ProviderDetails: *ref_33
    com.nopan.api.gateway.domain.integrator.InitiateResponse: *ref_34
    com.nopan.api.gateway.domain.integrator.InitiateResponse.ProviderDetails: *ref_35
    com.nopan.api.gateway.domain.integrator.FinalizeRequest: *ref_36
    com.nopan.api.gateway.domain.integrator.ChargeRequest: *ref_37
    com.nopan.api.gateway.domain.integrator.ChargeRequest.PayerDetails: *ref_38
    com.nopan.api.gateway.domain.integrator.ChargeRequest.PaymentDetails: *ref_39
    com.nopan.api.gateway.domain.integrator.ChargeRequest.ProviderDetails: *ref_40
    com.nopan.api.gateway.domain.integrator.ChargeResponse: *ref_41
    com.nopan.api.gateway.domain.integrator.ChargeResponse.ProviderDetails: *ref_42
    com.nopan.api.gateway.domain.integrator.CaptureRequest: *ref_43
    com.nopan.api.gateway.domain.integrator.CaptureRequest.PaymentDetails: *ref_44
    com.nopan.api.gateway.domain.integrator.CancelRequest: *ref_45
    com.nopan.api.gateway.domain.mocksy.CancelStep: *ref_46
    com.nopan.api.gateway.domain.mocksy.CaptureStep: *ref_47
    com.nopan.api.gateway.domain.mocksy.CaptureStep.ProviderDetails: *ref_48
    com.nopan.api.gateway.domain.mocksy.ChargeStep: *ref_49
    com.nopan.api.gateway.domain.mocksy.ChargeStep.ProviderDetails: *ref_50
    com.nopan.api.gateway.domain.mocksy.FinalizeStep: *ref_51
    com.nopan.api.gateway.domain.mocksy.InitiateStep: *ref_52
    com.nopan.api.gateway.domain.mocksy.InitiateStep.ProviderDetails: *ref_53
    com.nopan.api.gateway.domain.mocksy.MockRequest: *ref_54
    com.nopan.api.gateway.domain.mocksy.MockRequest.Key: *ref_55
    com.nopan.api.gateway.domain.mocksy.MockRequest.Steps: *ref_56
    com.nopan.api.gateway.domain.mocksy.RefundStep: *ref_57
    com.nopan.api.gateway.domain.mocksy.RefundStep.ProviderDetails: *ref_58
    PaymentInitiatedNotificationDto: *ref_59
    PaymentFinalizedNotificationDto: *ref_60
    PaymentCapturedNotificationDto: *ref_61
