openapi: 3.0.0
info:
  title: NapoleonPay API Docs
  description: NapoleonPay payment gateway API for creating payments
  version: 1.1.0
servers:
  - url: https://api.napoleonpay.com
tags:
  - name: Deposits
    description: Operations related to creating and managing deposits
paths:
  /api/v1/payments:
    post:
      tags:
        - Deposits
      summary: Create a payment
      description: >-
        Create a payment via Apple Pay, Google Pay, BLIK, CARD, ONRAMP using a
        single endpoint. The request schema depends on `paymentMethod`.
      operationId: createPayment
      parameters:
        - name: Authorization
          in: header
          description: Bearer token for authentication
          required: true
          schema:
            type: string
        - name: Signature
          in: header
          description: HMAC SHA-256 signature of the request payload
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            examples:
              ApplePay:
                summary: Create Apple Pay payment
                value:
                  paymentType: DEPOSIT
                  paymentMethod: APPLEPAY
                  amount: 20
                  currency: EUR
                  reference: YOUR-SYSTEM-TRX-ID
                  billingAddress:
                    countryCode: LT
                  returnUrl: https://example.com/return
                  webhookUrl: https://example.com/webhook
              GooglePay:
                summary: Create Google Pay payment
                value:
                  paymentType: DEPOSIT
                  paymentMethod: GOOGLEPAY
                  amount: 20
                  currency: EUR
                  reference: YOUR-SYSTEM-TRX-ID
                  billingAddress:
                    countryCode: LT
                  returnUrl: https://example.com/return
                  webhookUrl: https://example.com/webhook
              BLIK:
                summary: Create BLIK payment
                value:
                  paymentType: DEPOSIT
                  paymentMethod: BLIK
                  amount: 10
                  currency: PLN
                  customer:
                    email: mike.ben@example.com
                    firstName: Mike
                    lastName: Ben
                  returnUrl: https://example.com/return
                  webhookUrl: https://example.com/webhook
              CARD:
                summary: Create Card payment
                value:
                  paymentType: DEPOSIT
                  paymentMethod: CARD
                  amount: 21.2
                  currency: EUR
                  merchantUrl: https://sample.casino
                  customer:
                    referenceId: Reference ID order-32dbe423
                    email: john.doe@example.com
                    firstName: John
                    lastName: Doe
                    phone: 37061111111
                    dateOfBirth: '1992-03-04'
                  billingAddress:
                    address1: Street 1
                    city: Vilnius
                    state: LT
                    countryCode: LT
                    postalCode: '01100'
                  card:
                    pan: '4111111111111111'
                    cvv: '123'
                    exp_month: 3
                    exp_year: 2028
                    holder: Ben John
                  callbackUrl: https://napoleonpay.com/payment_callback.php
                  additionalParameters:
                    purpose: purpose
              ONRAMP:
                summary: Create Onramp payment
                value:
                  paymentType: DEPOSIT
                  paymentMethod: ONRAMP
                  amount: 21.2
                  currency: EUR
                  merchantUrl: https://sample.casino
                  customer:
                    referenceId: KYU891
                    email: john.doe@example.com
                    firstName: John
                    lastName: Doe
                    phone: 37061111111
                    dateOfBirth: '1992-03-04'
                  billingAddress:
                    address1: Street 1
                    city: Vilnius
                    state: LT
                    countryCode: LT
                    postalCode: 1100
                  callbackUrl: https://napoleonpay.com/payment_callback.php
      responses:
        '200':
          $ref: '#/components/responses/PaymentCreated'
      security:
        - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      description: API Key used as a Bearer token
    Signature:
      type: apiKey
      in: header
      name: Signature
      description: HMAC SHA-256 signature of the request payload
  responses:
    PaymentCreated:
      description: Payment created successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentResponse'
          examples:
            ApplePayResponse:
              summary: Apple Pay response
              value:
                id: 01990efa-5437-70c6-8244-85546f382bb3
                paymentStatus: PENDING
                created:
                  date: '2025-09-03 12:48:31.020712'
                  timezone_type: 3
                  timezone: Europe/Vilnius
                paymentType: DEPOSIT
                description: Test GooglePay payment for order order-45c721ca
                paymentMethod: APPLEPAY
                reference: order-45c721ca
                amount: 10.23
                currency: EUR
                customer: null
                billingAddress:
                  address1: null
                  city: null
                  countryCode: GB
                  postalCode: null
                  state: null
            GooglePayResponse:
              summary: Google Pay response
              value:
                id: 01990ef9-cef3-7041-8b78-7b60cea8f49b
                paymentStatus: PENDING
                created:
                  date: '2025-09-03 12:47:57.293162'
                  timezone_type: 3
                  timezone: Europe/Vilnius
                paymentType: DEPOSIT
                description: Test GooglePay payment for order order-9842d960
                paymentMethod: GOOGLEPAY
                reference: order-9842d960
                amount: 10.23
                currency: EUR
                customer: null
                billingAddress:
                  address1: null
                  city: null
                  countryCode: GB
                  postalCode: null
                  state: null
            BlikResponse:
              summary: BLIK response
              value:
                id: 01990efb-a655-74cb-a0bf-da9fcce56282
                paymentStatus: PENDING
                created:
                  date: '2025-09-03 12:49:57.972605'
                  timezone_type: 3
                  timezone: Europe/Vilnius
                paymentType: DEPOSIT
                description: Test payment for BLIK order order-f59d99d0
                paymentMethod: BLIK
                reference: 24614a49f36d4712b6de0496c1e5bdb8
                amount: 20.23
                currency: PLN
                customer:
                  firstName: Mark
                  lastName: Zuk
                  email: johm@gmail.com
                  phone: '9660000001'
                  ipaddress: 2a00:1eb8:c0c5:c99d:7d9c:16c8:a770:8639
                  referenceId: Reference ID order-f59d99d0
                billingAddress:
                  address1: null
                  city: null
                  countryCode: GB
                  postalCode: null
                  state: null
            CARDResponse:
              summary: CARD response
              value:
                id: 01990eff-2aa1-7031-bc33-cbec6a97c4c2
                paymentStatus: COMPLETED
                created:
                  date: '2025-09-03 12:53:49.305205'
                  timezone_type: 3
                  timezone: Europe/Vilnius
                paymentType: DEPOSIT
                description: Test payment
                paymentMethod: CARD
                amount: 21.2
                currency: EUR
                customer:
                  firstName: null
                  lastName: null
                  email: john.doe@example.com
                  phone: null
                  ipaddress: null
                  referenceId: Reference ID order-32dbe423
                billingAddress:
                  address1: null
                  city: Vilnius
                  countryCode: LT
                  postalCode: '01100'
                  state: LT
                authorizationCode: null
                cardType: null
                redirectUrl: null
            ONRAMPesponse:
              summary: ONRAMP response
              value:
                id: 01990eff-2aa1-7031-bc33-cbec6a97c4c2
                paymentStatus: PENDING
                created:
                  date: '2025-09-03 12:53:49.305205'
                  timezone_type: 3
                  timezone: Europe/Vilnius
                paymentType: DEPOSIT
                description: Test payment
                paymentMethod: ONRAMP
                amount: 21.2
                currency: EUR
                customer:
                  firstName: Bau
                  lastName: Mas
                  email: john.doe@example.com
                  phone: 370 66666666
                  ipaddress: null
                  referenceId: KYU891
                  dateOfBirth: '1992-03-04'
                billingAddress:
                  address1: 211, Victory street
                  city: Vilnius
                  countryCode: LT
                  postalCode: '01100'
                  state: LT
                redirectUrl: >-
                  https://paycart.click/m/payment/d4c116018609442c9edb802a0564f618
  schemas:
    PaymentRequest:
      oneOf:
        - $ref: '#/components/schemas/PaymentRequestApplePay'
        - $ref: '#/components/schemas/PaymentRequestGooglePay'
        - $ref: '#/components/schemas/PaymentRequestBlik'
        - $ref: '#/components/schemas/PaymentRequestCARD'
        - $ref: '#/components/schemas/PaymentRequestONRAMP'
      discriminator:
        propertyName: paymentMethod
        mapping:
          APPLEPAY: '#/components/schemas/PaymentRequestApplePay'
          GOOGLEPAY: '#/components/schemas/PaymentRequestGooglePay'
          BLIK: '#/components/schemas/PaymentRequestBlik'
          CARD: '#/components/schemas/PaymentRequestCARD'
          ONRAMP: '#/components/schemas/PaymentRequestONRAMP'
      description: Unified request. The concrete schema is chosen by `paymentMethod`.
    PaymentType:
      type: string
      enum:
        - DEPOSIT
    CustomerInfo:
      type: object
      description: Customer information (all fields optional unless specified by method).
      properties:
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        ipaddress:
          type: string
          nullable: true
        referenceId:
          type: string
          nullable: true
        dateOfBirth:
          type: string
          nullable: true
          description: Required only when making card FTD
    BillingAddress:
      type: object
      description: Billing address (fields optional unless required by method).
      properties:
        address1:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        countryCode:
          type: string
          nullable: true
        postalCode:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
    AdditionalParameters:
      type: object
      description: Method-specific parameters (e.g., BLIK purpose).
      properties:
        purpose:
          type: string
    Browser:
      type: object
      description: Browser information (commonly required for wallet-based methods).
      properties:
        acceptHeader:
          type: string
          nullable: true
        colorDepth:
          type: integer
          nullable: true
        ip:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        screenHeight:
          type: integer
          nullable: true
        screenWidth:
          type: integer
          nullable: true
        timeZone:
          type: integer
          nullable: true
        userAgent:
          type: string
          nullable: true
        javaEnabled:
          type: boolean
          nullable: true
        windowWidth:
          type: integer
          nullable: true
        windowHeight:
          type: integer
          nullable: true
    BaseRequest:
      type: object
      properties:
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        paymentMethod:
          type: string
          enum:
            - APPLEPAY
            - GOOGLEPAY
            - BLIK
            - CARD
            - ONRAMP
            - ONRAMP_PAYID
            - ONRAMP_PIX
            - ONRAMP_ZAR
            - ONRAMP_PSE
            - ONRAMP_KHIPU
            - ONRAMP_QRTHWALLET
            - ONRAMP_CARD
            - ONRAMP_INTERAC
            - ONRAMP_OPENBANKING
            - ONRAMP_GBPBANKTRANSFER
            - ONRAMP_SPEI
            - ONRAMP_APPLEPAY
            - ONRAMP_GOOGLEPAY
          x-displayName: Payment Method
          example: APPLEPAY
        amount:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          example: 10.99
        currency:
          type: string
          example: EUR
        externalApiId:
          type: string
          nullable: true
          example: order-123456
        customer:
          $ref: '#/components/schemas/CustomerInfo'
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        additionalParameters:
          $ref: '#/components/schemas/AdditionalParameters'
        description:
          type: string
          nullable: true
          example: Test payment
        reference:
          type: string
          nullable: true
          example: Reference 123
        webhookUrl:
          type: string
          nullable: true
          example: https://example.com/callback
        returnUrl:
          type: string
          nullable: true
          example: https://example.com/return
        browser:
          $ref: '#/components/schemas/Browser'
      required:
        - paymentType
        - paymentMethod
        - amount
        - currency
    PaymentRequestApplePay:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - APPLEPAY
          required:
            - paymentMethod
            - returnUrl
            - webhookUrl
    PaymentRequestGooglePay:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - GOOGLEPAY
          required:
            - paymentMethod
            - returnUrl
            - webhookUrl
    PaymentRequestBlik:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - BLIK
            customer:
              allOf:
                - $ref: '#/components/schemas/CustomerInfo'
                - type: object
                  required:
                    - firstName
                    - lastName
                    - email
          required:
            - paymentMethod
            - returnUrl
            - webhookUrl
            - customer
    PaymentRequestCARD:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - CARD
            customer:
              allOf:
                - $ref: '#/components/schemas/CustomerInfo'
                - type: object
                  required:
                    - firstName
                    - lastName
                    - email
                    - phone
                    - dateOfBirth
            billingAddress:
              allOf:
                - $ref: '#/components/schemas/BillingAddress'
                - type: object
                  required:
                    - address1
                    - city
                    - countryCode
                    - postalCode
                    - state
            card:
              type: object
              description: Card details required for card payment
              properties:
                pan:
                  type: string
                  example: '4111111111111111'
                cvv:
                  type: string
                  example: '123'
                exp_month:
                  type: integer
                  example: 3
                exp_year:
                  type: integer
                  example: 2028
                holder:
                  type: string
                  example: Ben John
            callbackUrl:
              type: string
              format: uri
              nullable: false
              example: https://napoleonpay.com/payment_callback.php
            merchantUrl:
              type: string
              format: uri
              required: true
              nullable: false
              description: Merchants website URL where actually the payment is made.
              example: https://sample.casino
          required:
            - paymentMethod
            - card
            - callbackUrl
            - merchantUrl
            - customer
            - billingAddress
    PaymentRequestONRAMP:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - ONRAMP
                - ONRAMP_PAYID
                - ONRAMP_PIX
                - ONRAMP_ZAR
                - ONRAMP_PSE
                - ONRAMP_KHIPU
                - ONRAMP_QRTHWALLET
                - ONRAMP_CARD
                - ONRAMP_INTERAC
                - ONRAMP_OPENBANKING
                - ONRAMP_GBPBANKTRANSFER
                - ONRAMP_SPEI
                - ONRAMP_APPLEPAY
                - ONRAMP_GOOGLEPAY
            customer:
              allOf:
                - $ref: '#/components/schemas/CustomerInfo'
                - type: object
                  required:
                    - firstName
                    - lastName
                    - email
                    - phone
                    - dateOfBirth
            billingAddress:
              allOf:
                - $ref: '#/components/schemas/BillingAddress'
                - type: object
                  required:
                    - address1
                    - city
                    - countryCode
                    - postalCode
                    - state
            callbackUrl:
              type: string
              format: uri
              nullable: false
              example: https://napoleonpay.com/payment_callback.php
            merchantUrl:
              type: string
              format: uri
              required: true
              nullable: false
              description: Merchants website URL where actually the payment is made.
              example: https://sample.casino
          required:
            - paymentMethod
            - callbackUrl
            - merchantUrl
            - customer
            - billingAddress
    PaymentResponse:
      oneOf:
        - $ref: '#/components/schemas/PaymentResponseApplePay'
        - $ref: '#/components/schemas/PaymentResponseGooglePay'
        - $ref: '#/components/schemas/PaymentResponseBlik'
        - $ref: '#/components/schemas/PaymentResponseCARD'
        - $ref: '#/components/schemas/PaymentResponseONRAMP'
      discriminator:
        propertyName: paymentMethod
        mapping:
          APPLEPAY: '#/components/schemas/PaymentResponseApplePay'
          GOOGLEPAY: '#/components/schemas/PaymentResponseGooglePay'
          BLIK: '#/components/schemas/PaymentResponseBlik'
          CARD: '#/components/schemas/PaymentResponseCARD'
          ONRAMP: '#/components/schemas/PaymentResponseONRAMP'
      description: Unified response. Concrete schema depends on `paymentMethod`.
    BasePaymentResponse:
      type: object
      properties:
        id:
          type: string
          example: 0198d10e-9bcf-71ec-af66-50fa170e607a
        paymentStatus:
          type: string
          enum:
            - PENDING
            - AUTHORIZED
            - COMPLETED
            - FAILED
            - CANCELED
          example: COMPLETED
        created:
          type: object
          properties:
            date:
              type: string
              example: '2025-08-22 12:14:12.000000'
            timezone_type:
              type: integer
              example: 3
            timezone:
              type: string
              example: Europe/Vilnius
        paymentType:
          type: string
          enum:
            - DEPOSIT
          example: DEPOSIT
        description:
          type: string
          nullable: true
          example: Test payment
        paymentMethod:
          type: string
          enum:
            - APPLEPAY
            - GOOGLEPAY
            - BLIK
            - CARD
            - ONRAMP
            - ONRAMP_PAYID
            - ONRAMP_PIX
            - ONRAMP_ZAR
            - ONRAMP_PSE
            - ONRAMP_KHIPU
            - ONRAMP_QRTHWALLET
            - ONRAMP_CARD
            - ONRAMP_INTERAC
            - ONRAMP_OPENBANKING
            - ONRAMP_GBPBANKTRANSFER
            - ONRAMP_SPEI
        reference:
          type: string
          example: order-62e55adf
        amount:
          type: number
          format: float
          example: 10.23
        currency:
          type: string
          example: EUR
        customer:
          $ref: '#/components/schemas/CustomerInfo'
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
    PaymentResponseApplePay:
      allOf:
        - $ref: '#/components/schemas/BasePaymentResponse'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - APPLEPAY
            walletDetails:
              type: object
              description: Apple Pay–specific details
              properties:
                network:
                  type: string
                  example: VISA
                last4:
                  type: string
                  example: '4242'
                tokenized:
                  type: boolean
                  example: true
    PaymentResponseGooglePay:
      allOf:
        - $ref: '#/components/schemas/BasePaymentResponse'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - GOOGLEPAY
            walletDetails:
              type: object
              description: Google Pay–specific details
              properties:
                network:
                  type: string
                  example: MASTERCARD
                last4:
                  type: string
                  example: '4444'
                tokenized:
                  type: boolean
                  example: true
    PaymentResponseBlik:
      allOf:
        - $ref: '#/components/schemas/BasePaymentResponse'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - BLIK
            blik:
              type: object
              description: BLIK-specific response fields
              properties:
                codeLength:
                  type: integer
                  example: 6
                bank:
                  type: string
                  example: mBank
    PaymentResponseCARD:
      allOf:
        - $ref: '#/components/schemas/BasePaymentResponse'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - CARD
            authorizationCode:
              type: string
              nullable: true
              example: null
            cardType:
              type: string
              nullable: true
              example: null
            redirectUrl:
              type: string
              nullable: true
              example: null
    PaymentResponseONRAMP:
      allOf:
        - $ref: '#/components/schemas/BasePaymentResponse'
        - type: object
          properties:
            paymentMethod:
              type: string
              enum:
                - ONRAMP
                - ONRAMP_PAYID
                - ONRAMP_PIX
                - ONRAMP_ZAR
                - ONRAMP_PSE
                - ONRAMP_KHIPU
                - ONRAMP_QRTHWALLET
                - ONRAMP_CARD
                - ONRAMP_INTERAC
                - ONRAMP_OPENBANKING
                - ONRAMP_GBPBANKTRANSFER
                - ONRAMP_SPEI
            redirectUrl:
              type: string
              nullable: true
              example: null
