openapi: 3.1.1
info:
  title: OmegaPay API
  description: >-
    <strong>Задача: Интеграция платежной системы с поддержкой нескольких
    методов.</strong><br/> <strong>Рекомендация по реализации:</strong>
    Выполняйте интеграцию каждого платежного метода отдельно, следуя приведенным
    ниже пунктам.<br/><br/>

    <strong>Список требований к интеграции:</strong><br/> <strong>Базовая
    интеграция</strong><br/><br/>

    Реализовать общую интеграцию с платежной системой (ПС).<br/>

    <strong>Панель управления методами</strong><br/> Создать админ-панель для
    управления платежными методами.<br/> Реализовать возможность создавать новые
    методы с указанием поля payment_method (например: basic_card, P2P-card, pix
    и т.д.).<br/><br/>


    <strong>Лимиты сумм</strong><br/> Для каждого метода должны быть
    настраиваемые лимиты: минимальная и максимальная сумма платежа.<br/><br/>


    <strong>Округление сумм</strong><br/> Реализовать функцию округления суммы
    платежа в зависимости от метода.<br/>

    <strong>Особое внимание для P2P-платежей:</strong> Для валют, таких как
    гривна (UAH) и аргентинское песо (ARS), сумма должна передаваться только в
    целых числах. Это предотвратит проблемы с зачислением средств из-за ручного
    округления со стороны пользователей.<br/><br/>


    <strong>Обработка колбэков (вебхуков)</strong><br/> Реализовать возможность
    обновления статуса платежа через колбэк.<br/><br/>

    <strong>Пример сценария:</strong><br/>

    Пользователь совершает P2P-платеж, который завершается ошибкой.<br/>
    Автоматически приходит вебхук со статусом DECLINE.<br/> После ручной
    проверки оператором инициируется повторная отправка вебхука со статусом
    COMPLETED.<br/> При получении статуса COMPLETED баланс пользователя должен
    пополниться автоматически.<br/><br/>


    <strong>Экранирование данных</strong><br/> Реализовать экранирование имени
    владельца карты, которое передается в вебхуке. Это необходимо для корректной
    обработки имен с особыми символами (например, греческими).<br/><br/>


    <strong>Процесс тестирования</strong><br/> Категорически рекомендуется
    выполнить полную реализацию и тестирование на дев-стендах.<br/> После
    успешного тестирования необходимо проверить работоспособность на
    продакшн-среде.<br/>
  license:
    name: Apache 2.0
    identifier: Apache-2.0
  version: 1.0.106
servers:
  - url: https://CONTACT_YOUR_MANAGER
    description: Sandbox
  - url: https://CONTACT_YOUR_MANAGER
    description: Production
paths:
  /api/v1/payments:
    post:
      tags:
        - Payments
      summary: Create payment
      description: Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS
      operationId: createPayment
      requestBody:
        description: Payment Request - Request to initiate a payment
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            examples:
              default_example:
                $ref: '#/components/examples/SimpleDepositRequest'
              basic_card_hpp_deposit_example:
                $ref: '#/components/examples/BasicCardHppDepositRequest'
        required: true
      responses:
        '200':
          description: Payment response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
              examples:
                deposit_example:
                  $ref: '#/components/examples/CreateDepositResponse'
                withdrawal_example:
                  $ref: '#/components/examples/CreateWithdrawalResponse'
                refund_example:
                  $ref: '#/components/examples/CreateRefundResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-codeSamples:
        - lang: Python
          label: Create payment with Python requests
          source: |
            import requests, json

            BASE_URL = "https://api.example.com"
            API_KEY  = "YOUR_API_KEY"

            headers = {
                "Content-Type": "application/json",
                "X-API-Key": API_KEY,
            }

            payload = {
                "paymentType": "DEPOSIT",
                "currency": "EUR"
            }

            response = requests.post(
                f"{BASE_URL}/v1/payments",
                headers=headers,
                data=json.dumps(payload)
            )
            print(response.status_code, response.text)
  /api/v1/payments/{id}:
    get:
      tags:
        - Payments
      summary: Find payment
      description: Find payment by Id
      operationId: getPayment
      parameters:
        - name: id
          in: path
          description: Payment Id
          required: true
          schema:
            pattern: /[a-zA-Z0-9]{32}/
            type: string
      responses:
        '200':
          description: Payment Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
webhooks:
  paymentq:
    post:
      tags:
        - Payments
      summary: Payment processing completed
      description: Publish details of a new processed payment.
      operationId: publishPaymentFinalizedEvent
      requestBody:
        description: Information about a new finalized payment
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Payment'
      responses:
        '200':
          description: >-
            Return a 200 status to indicate that the data was received
            successfully
      security:
        - SignatureAuth: []
    servers:
      - url: https://merchant-website.com
        description: Webhook URL on merchant side
components:
  schemas:
    AccountType:
      type: string
      description: Account Type
      example: SAVINGS
      enum:
        - SAVINGS
        - CHECKING
    PaymentType:
      type: string
      description: Payment Type
      example: DEPOSIT
      enum:
        - DEPOSIT
        - WITHDRAWAL
        - REFUND
    PaymentMethod:
      type: string
      description: Payment Method
      example: BASIC_CARD
      enum:
        - AHLPAY
        - ALFAKIT
        - ALFAMART
        - ALYCEPAY
        - APPLEPAY
        - ARI10
        - ASTROPAY
        - B2BINPAY
        - BANCONTACT
        - BANKTRANSFER
        - BANKTRANSFER_AR
        - BANKTRANSFER_BO
        - BANKTRANSFER_BR
        - BANKTRANSFER_CL
        - BANKTRANSFER_CO
        - BANKTRANSFER_CR
        - BANKTRANSFER_EC
        - BANKTRANSFER_GT
        - BANKTRANSFER_HN
        - BANKTRANSFER_MX
        - BANKTRANSFER_PA
        - BANKTRANSFER_PE
        - BANKTRANSFER_TR
        - BANKTRANSFER_UY
        - BASIC_CARD
        - BASIC_CARD_HPP
        - BILLLINE
        - BINANCE_PAY
        - BIOPAGO
        - BIZUM
        - BKASH
        - BLIK
        - BOLETO
        - BRITE
        - BYBIT_PAY
        - CASH
        - CASHLIB
        - CHEK
        - CIP
        - CLICK
        - CODI
        - CRYPTO
        - CUP
        - DANA
        - DPOPAY
        - DRAGON_PAY
        - EASYPAISA
        - EFECTY
        - EFT
        - EMANAT
        - ENAIRA
        - EPAY_BG
        - EPS
        - EXTERNAL_HPP
        - FAWRY
        - FINRAX
        - FLEXEPIN
        - FPS
        - FPX
        - FUPS
        - GATE8TRANSACT
        - GATEIQ
        - GCASH
        - GIROPAY
        - GOOGLEPAY
        - GOPAY
        - GPAY_IN
        - HAVALE
        - HAYDIPAY
        - HAYHAY
        - HELP2PAY
        - HITES
        - IDEAL
        - IMPS
        - INAI
        - INRPAY
        - INTERAC
        - INTERAC_ACH
        - INTERAC_ETO
        - INTERAC_RTO
        - JAZZCASH
        - JETONCASH
        - JETONWALLET
        - KAKAOPAY
        - KBZ
        - KESSPAY
        - KHIPU
        - KLAP_EFECTIVO
        - KLAP_TRANSFERENCIA
        - KLARNA
        - LOCALPAYMENT
        - M10
        - MACH
        - MACROPAY
        - MBWAY
        - MEFETE
        - MERCADOPAGO
        - MIFINITY
        - MISTERCASH
        - MOBILE_COMMERCE
        - MOBILE_MONEY
        - MOLLIE
        - MOMOPAY_RW
        - MOMOPAY_VN
        - MONERCHY
        - MONETIX
        - MONEYTOLIA
        - MONNET
        - MPAY
        - MPESA
        - MUCHBETTER
        - MULTIBANCO
        - MYBANK
        - MYPAYZ
        - N26
        - NAGAD
        - NAVERPAY
        - NEFT
        - NEOSURF
        - NEQUI
        - NETBANKING
        - NETELLER
        - NGENIUS
        - NODA
        - NODA_REVOLUT
        - OMNIMATRIX
        - ONEVOUCHER
        - ONLINE_BANKING
        - OPEN_BANKING
        - OPENPAYD
        - OPTIMONEY
        - OVO
        - OXXO
        - P24
        - P2P_ACCESS
        - P2P_CARD
        - P2P_CARD_HUMO
        - P2P_CARD_UZCARD
        - P2P_CROSS_BORDER
        - P2P_EMANAT
        - P2P_IBAN
        - P2P_KAPITAL
        - P2P_M10
        - P2P_MOBILE
        - P2P_SBP
        - P2P_UPI
        - PAGO_MOVIL
        - PAGO_MOVIL_INST
        - PAGO46
        - PAGOEFECTIVO
        - PAGOFACIL
        - PAPARA
        - PAPEL
        - PARAM
        - PARATIM
        - PARAZULA
        - PAROLAPARA
        - PAY_BY_LINK
        - PAY2PLAY
        - PAYCASH
        - PAYCELL
        - PAYCO_TR
        - PAYDO_WALLET
        - PAYFIX
        - PAYFUN
        - PAYID
        - PAYMAXIS
        - PAYMAYA
        - PAYNOW
        - PAYOUT_NONSEPA_REQUEST
        - PAYOUT_SEPA_BATCH
        - PAYPAL
        - PAYPAY
        - PAYPO
        - PAYPORT
        - PAYRETAILERS
        - PAYSAFECARD
        - PAYSAFECASH
        - PAYSHOP
        - PAYTM
        - PEC
        - PEP
        - PERFECTMONEY
        - PG_PARA
        - PHONEPE
        - PIASTRIX
        - PICPAY
        - PIX
        - POLI
        - POPY
        - POPY_PARA
        - PREPAID_CARD
        - PROMPTPAY
        - PSE
        - PUNTOPAGO
        - PUSH
        - QR
        - QRIS
        - RAPIDTRANSFER
        - RAPIPAGO
        - REVOLUT
        - ROCKET
        - RTGS
        - RUBPAY
        - SBERPAY
        - SBP
        - SBP_CROSS_BORDER
        - SEPA
        - SERVIFACIL
        - SHOPEEPAY
        - SIPAY
        - SKRILL
        - SOFORT
        - SOFT2PAY
        - SPEI
        - SPOYNT
        - STICPAY
        - SWISH
        - TED
        - TINK
        - TOSLA
        - TRANSFIYA
        - TRUEMONEY
        - TRUSTLY
        - TRUSTPAYMENTS
        - UPI
        - USSD
        - VIETTEL
        - VIRTUAL_ACCOUNT
        - VNPAY_QR
        - VOLT
        - VOUCHERRY
        - VOUCHSTAR
        - WAVE
        - WEBPAY
        - WISE
        - XANPAY
        - XINPAY
        - YAPE
        - YAPILY
        - ZALO
        - ZIMPLER
        - ZIPAY
        - ZOTAPAY
    PaymentState:
      type: string
      description: Payment State
      example: PENDING
      enum:
        - CHECKOUT
        - PENDING
        - AUTHORIZED
        - CANCELLED
        - DECLINED
        - COMPLETED
    Operation:
      type: string
      description: Operation performed during payment processing
      example: CREATE_PAYMENT
      enum:
        - CREATE_PAYMENT
        - CHECKOUT
        - CANCEL
        - CONFIRMATION
        - CASCADING
        - REDIRECT
        - CONTINUE
        - CONTINUE_ANTI_FRAUD
        - DETECT_FRAUD
        - DEPOSIT
        - WITHDRAWAL
        - REFUND
        - CHARGEBACK
        - CAPTURE
        - VOID
        - CHECK_STATE
        - HANDLE_WEBHOOK
        - MANUAL_UPDATE
        - MANUAL_CHECK_STATE
    DocumentType:
      type: string
      description: Document Type
      example: BR_CPF
      enum:
        - AR_CDI
        - AR_PP
        - AR_CUIL
        - AR_CUIT
        - AR_DNI
        - AR_OTRO
        - BO_CEX
        - BO_CI
        - BO_NIT
        - BO_OD
        - BO_PP
        - BR_CNPJ
        - BR_CPF
        - BR_PP
        - CL_CE
        - CL_CI
        - CL_ID
        - CL_OTRO
        - CL_PP
        - CL_RUN
        - CL_RUT
        - CL_TIN
        - CO_CC
        - CO_CE
        - CO_DL
        - CO_DNI
        - CO_NE
        - CO_NIT
        - CO_PP
        - CO_SS
        - CO_TI
        - CO_TIN
        - CR_CDI
        - EC_CC
        - EC_DNI
        - EC_PP
        - EC_RUC
        - GT_CUI
        - GT_DPI
        - GT_NIT
        - IN_DL
        - IN_ID
        - IN_UID
        - MX_CRI
        - MX_CURP
        - MX_IFE
        - MX_PP
        - MX_RFC
        - MX_TIN
        - PA_CIP
        - PE_CE
        - PE_CPP
        - PE_DNI
        - PE_FRC
        - PE_ID
        - PE_OTRO
        - PE_PP
        - PE_RUC
        - PE_TIN
        - UK_PP
        - UK_NIC
        - UK_DL
        - UK_BTI
        - UK_TIN
        - UY_CI
        - UY_RUT
        - VN_TIN
    CurrencyAmount:
      required:
        - currency
        - amount
      description: Currency and amount
      type: object
      properties:
        currency:
          type: string
          description: Currency
          format: ISO 4217 code for FIAT currencies or cryptocurrency symbol
          example: EUR
        amount:
          multipleOf: 1.e-18
          maximum: 1000000000
          minimum: 0.00001
          type: number
          description: Amount in the specified currency
          example: 11.12
    PaymentMethodDetails:
      type: object
      properties:
        customerAccountNumber:
          maxLength: 256
          type: string
          description: Customer account Id in external system or masked card PAN
          example: 400000***0002
        cardToken:
          maxLength: 32
          type: string
          description: >-
            Card token which can be used instead of full card number (for
            BASIC_CARD payment method only)
          example: 3529d42227424875af8722cbf54d7073
        cardholderName:
          maxLength: 128
          type: string
          description: Cardholder name (for BASIC_CARD payment method only)
          example: John Doe
        cardExpiryMonth:
          minLength: 2
          maxLength: 2
          type: string
          description: Card expiration month (for BASIC_CARD payment method only)
          example: '01'
        cardExpiryYear:
          minLength: 4
          maxLength: 4
          type: string
          description: Card expiration year (for BASIC_CARD payment method only)
          example: '2030'
        cardBrand:
          type: string
          description: Card brand (for BASIC_CARD payment method only)
          example: VISA
          enum:
            - AMEX
            - DINERS
            - DISCOVER
            - JCB
            - MAESTRO
            - MASTERCARD
            - MIR
            - RUPAY
            - UNIONPAY
            - VISA
            - HUMO
            - VERVE
            - TROY
            - UNKNOWN
        cardIssuingCountryCode:
          minLength: 2
          maxLength: 2
          type: string
          description: Card issuing country code (for BASIC_CARD payment method only)
          example: CY
    BillingAddress:
      type: object
      properties:
        addressLine1:
          maxLength: 50
          type: string
          description: Line 1 of the address (e.g., Number, street, etc)
          example: 7, Sunny street
        addressLine2:
          maxLength: 50
          type: string
          description: Line 2 of the address (e.g., Suite, apt)
          example: Office 3
        city:
          maxLength: 50
          type: string
          description: City name
          example: Limassol
        countryCode:
          maxLength: 2
          minLength: 2
          pattern: '[A-Z]{2}'
          type: string
          description: 2-character IS0-3166-1 country code
          example: CY
        postalCode:
          maxLength: 12
          type: string
          description: Postal code
          example: '4141'
        state:
          maxLength: 40
          type: string
          description: State code
          example: CA
      description: Customer's billing address
    Card:
      type: object
      properties:
        cardNumber:
          maxLength: 23
          type: string
          description: >-
            Card primary account number (PAN). All non-numeric characters will
            be ignored.
          example: 4000 0000 0000 0002
        cardToken:
          maxLength: 32
          type: string
          description: Card token which can be used instead of full card number.
          example: 3529d42227424875af8722cbf54d7073
        cardholderName:
          maxLength: 128
          type: string
          description: Cardholder's name printed on the card
          example: John Smith
        cardSecurityCode:
          minLength: 3
          maxLength: 4
          type: string
          description: Card security code (CVV2 / CVC2 / CAV2)
          example: '010'
        expiryMonth:
          minLength: 2
          maxLength: 2
          type: string
          description: Card expiration month, 2 digits
          example: '01'
        expiryYear:
          minLength: 4
          maxLength: 4
          type: string
          description: Card expiration year, 4 digits
          example: '2030'
      description: >
        You must be PCI DSS compliant to collect card data on your side. 

        If you are not certified, do not add this field to your request and we
        will collect the data on our page.
    Customer:
      type: object
      properties:
        referenceId:
          maxLength: 128
          type: string
          description: Id of the customer assigned by Merchant
          example: customer_123
        citizenshipCountryCode:
          maxLength: 2
          minLength: 2
          type: string
          description: Customer country of citizenship
          example: AU
        firstName:
          maxLength: 128
          type: string
          example: John
        lastName:
          maxLength: 128
          type: string
          example: Smith
        dateOfBirth:
          maxLength: 10
          minLength: 10
          type: string
          format: ISO 8601 (YYYY-MM-DD)
          example: '2001-12-03'
        email:
          maxLength: 256
          type: string
          description: Email address of the customer
          format: email
          example: my@email.com
        phone:
          maxLength: 18
          type: string
          description: >-
            International phone number of the customer, without the '+'. Use a
            space as a separator between the dialing country code and local
            phone number.
          example: 357 123123123
        locale:
          maxLength: 2
          minLength: 2
          type: string
          description: Customer preferred display language
          example: ru
        accountNumber:
          maxLength: 256
          type: string
          description: >-
            Customer account number in the provider's system. Used for some
            types of withdrawals.
        accountName:
          maxLength: 64
          type: string
          description: >-
            Customer account name in the provider's system. Used for some types
            of withdrawals.
        accountType:
          $ref: '#/components/schemas/AccountType'
        bank:
          maxLength: 64
          type: string
          description: Customer bank name. Used for some types of withdrawals.
        bankCode:
          maxLength: 64
          type: string
          description: Customer bank code. Used for some types of withdrawals.
        bankBranch:
          maxLength: 64
          type: string
          description: Customer bank branch name. Used for some types of withdrawals.
        bankBranchCode:
          maxLength: 64
          type: string
          description: Customer bank branch code. Used for some types of withdrawals.
        documentType:
          $ref: '#/components/schemas/DocumentType'
        documentNumber:
          maxLength: 64
          type: string
          description: An identifier for the customer assigned by a government authority
        routingGroup:
          maxLength: 64
          type: string
          description: >-
            Identify the customer as belonging to a specific group that is used
            for routing
          example: VIP
        kycStatus:
          type: boolean
          description: Indicates whether the customer has passed KYC verification
          example: true
        paymentInstrumentKycStatus:
          type: boolean
          description: >-
            Indicates whether the payment instrument (usually the card number)
            has passed KYC verification
          example: true
        dateOfFirstDeposit:
          type: string
          format: ISO 8601 (YYYY-MM-DD)
          description: Date of the first deposit from the customer
          example: '2021-01-01'
        depositsAmount:
          type: integer
          description: How much the customer has deposited, in base currency
          example: 5000
        withdrawalsAmount:
          type: integer
          description: How much the customer has withdrawn, in base currency
          example: 1000
        depositsCnt:
          type: integer
          description: How many times the customer made a deposit
          example: 5000
        withdrawalsCnt:
          type: integer
          description: How many times the customer made a withdrawal
          example: 1000
    Payment:
      type: object
      properties:
        id:
          maxLength: 32
          type: string
          description: Payment Id
          example: 91d27876e87f4b22b3ecd53924bf973d
        referenceId:
          maxLength: 256
          type: string
          description: referenceId from payment request
          example: payment-123
        created:
          type: string
          format: ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)
          description: Date and time when this payment was created, in UTC time zone
          example: '2030-12-25T10:11:12'
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        state:
          $ref: '#/components/schemas/PaymentState'
        description:
          maxLength: 512
          type: string
          description: Description of the transaction
          example: Deposit via TEST shop
        parentPaymentId:
          maxLength: 32
          type: string
          description: Initial transaction Id from payment request
          example: 91d27876e87f4b22b3ecd53924bf973d
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        paymentMethodDetails:
          $ref: '#/components/schemas/PaymentMethodDetails'
        amount:
          multipleOf: 1.e-18
          maximum: 1000000000
          minimum: 0.00001
          type: number
          description: Amount sent to the payment provider
          example: 11.12
        currency:
          type: string
          description: Currency sent to the payment provider
          format: ISO 4217 code for FIAT currencies or cryptocurrency symbol
          example: EUR
        customerAmount:
          type: number
          description: >-
            Amount from payment request. Filled only if the request currency
            differs from the currency sent to the payment provider.
          example: 15
        customerCurrency:
          type: string
          description: >-
            Currency from payment request. Filled only if it differs from the
            currency sent to the payment provider.
          format: ISO 4217 code for FIAT currencies or cryptocurrency symbol
          example: USD
        redirectUrl:
          maxLength: 256
          type: string
          description: URL to redirect the customer
          example: http://start/payment/6ccaa03cb2c242a68ce332f38fedfad7
        errorCode:
          type: string
          description: Check 'Error Codes' section for details
          example: '4.01'
        errorMessage:
          type: string
          description: Check 'Error Codes' section for details
          example: Insufficient Funds
        externalResultCode:
          type: string
          description: Result code from external provider
          example: '03'
        customer:
          $ref: '#/components/schemas/Customer'
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        startRecurring:
          type: boolean
          description: Indicates whether this payment has started a recurring chain
        preAuth:
          type: boolean
          description: >-
            Indicates whether this is a Pre-Authorization request (for 2-phase
            deposit)
        recurringToken:
          type: string
          description: Token that can be used to continue the recurring chain
        terminalName:
          type: string
          description: The name of the provider that was used to process this payment
        externalFeeAmount:
          type: number
          description: Provider fee. Filled only if supported by the provider.
          example: 15
        externalFeeCurrency:
          type: string
          description: Provider fee currency. Filled only if supported by the provider.
          format: ISO 4217 code for FIAT currencies or cryptocurrency symbol
          example: USD
    PaymentRequest:
      required:
        - currency
        - paymentType
      type: object
      properties:
        referenceId:
          maxLength: 256
          type: string
          description: >-
            Reference assigned by Merchant. Will not go outside the system. Will
            be sent unchanged in the PaymentResponse.
          example: payment_id=123;custom_ref=456
        paymentType:
          $ref: '#/components/schemas/PaymentType'
        paymentMethod:
          $ref: '#/components/schemas/PaymentMethod'
        amount:
          multipleOf: 1.e-18
          maximum: 1000000000
          minimum: 0.00001
          type: number
          description: Payment amount
          example: 11.12
        currency:
          type: string
          description: Payment currency
          format: ISO 4217 code for FIAT currencies or cryptocurrency symbol
          example: EUR
        parentPaymentId:
          maxLength: 32
          type: string
          description: >-
            Id of initial deposit for refunds, Id of initial recurring payment
            for subsequent payments
          example: 91d27876e87f4b22b3ecd53924bf973d
        description:
          maxLength: 512
          type: string
          description: >-
            Description of the transaction shown to the Customer. Can be sent
            outside the system.
          example: Deposit 123 via TEST shop
        card:
          $ref: '#/components/schemas/Card'
        customer:
          $ref: '#/components/schemas/Customer'
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        returnUrl:
          maxLength: 512
          type: string
          description: URL to redirect Customer after processing
          example: https://mywebsite.com/{id}/{referenceId}/{state}/{type}
        webhookUrl:
          maxLength: 512
          type: string
          description: Url to receive payment status notifications
          example: https://mywebsite.com/webhooks
        startRecurring:
          type: boolean
          description: >-
            Send 'true' if you want this payment to initiate recurring chain.
            Default is 'false'.
        preAuth:
          type: boolean
          description: >-
            Send 'true' if you want to request a Pre-Authorization charge
            (initiate a 2-phase deposit).
        recurringToken:
          type: string
          description: >-
            To continue recurring chain, send a token from a previously
            initiated recurring payment.
        additionalParameters:
          type: object
          description: >-
            Additional parameters required by some payment providers. Contact
            support for more information.
          additionalProperties:
            type: string
          example:
            bankCode: ABHY0065032
            countryOfBirth: CY
        checkoutStyle:
          type: string
          description: >-
            If shop has multiple checkout styles and you want to use a custom
            style for this specific payment, specify the style name using this
            parameter.
    PaymentResponse:
      type: object
      properties:
        timestamp:
          type: string
          format: ISO 8601
          example: '2020-10-07T13:36:32.595+00:00'
        status:
          type: integer
          description: HTTP status code
          example: 200
        result:
          $ref: '#/components/schemas/Payment'
    BadRequestError:
      type: object
      properties:
        timestamp:
          type: string
          format: ISO 8601
          example: '2020-10-07T13:32:19.444+00:00'
        status:
          type: integer
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
        errors:
          type: array
          items:
            type: object
            properties:
              codes:
                type: array
                items:
                  type: string
              arguments:
                type: array
                items:
                  type: object
                  properties:
                    codes:
                      type: array
                      items:
                        type: string
                    defaultMessage:
                      type: string
              defaultMessage:
                type: string
              objectName:
                type: string
              field:
                type: string
              bindingFailure:
                type: boolean
        path:
          type: string
          example: /api/v1/payments
    UnauthorizedError:
      type: object
      properties:
        status:
          type: integer
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Invalid token
        timestamp:
          type: string
          format: ISO 8601
          example: '2020-10-07T13:32:19.444+00:00'
        path:
          type: string
          example: /api/v1/payments
    NotFoundError:
      type: object
      properties:
        status:
          type: integer
          example: 404
        error:
          type: string
          example: Not Found
        message:
          type: string
          example: Payment not found
        timestamp:
          type: string
          format: ISO 8601
          example: '2024-10-07T13:32:19.444+00:00'
        path:
          type: string
          example: /api/v1/payments
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BadRequestError'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnauthorizedError'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NotFoundError'
  examples:
    SimpleDepositPatchRequest:
      summary: Request with a minimum set of parameters
      value:
        customerIp: 152.13.130.125
    SimpleDepositRequest:
      summary: Simple deposit
      value:
        paymentType: DEPOSIT
        currency: EUR
    BasicCardHppDepositRequest:
      summary: Basic card HPP deposit
      value:
        paymentType: DEPOSIT
        amount: 10.01
        currency: GBP
        customer:
          email: jw@mail.com
          phone: 44 02072243688
        billingAddress:
          countryCode: GB
          city: London
          addressLine1: 221b Baker St, Marylebone
          postalCode: NW1 6XE
    CreateDepositResponse:
      summary: Deposit
      value:
        timestamp: '2024-09-24T20:29:11.632+00:00'
        status: 200
        result:
          id: 96365a23dca04a5a9bcbb0031e7b06ac
          paymentType: DEPOSIT
          state: CHECKOUT
          currency: GBP
          redirectUrl: https://gateway-domain.com/payment/96365a23dca04a5a9bcbb0031e7b06ac
    CreateWithdrawalResponse:
      summary: Withdrawal
      value:
        timestamp: '2024-09-24T20:29:11.632+00:00'
        status: 200
        result:
          id: 96365a23dca04a5a9bcbb0031e7b06ac
          paymentType: WITHDRAWAL
          state: PENDING
          currency: GBP
    CreateRefundResponse:
      summary: Refund
      value:
        timestamp: '2024-09-24T20:29:11.632+00:00'
        status: 200
        result:
          id: 4e2ca455643c41fab7c611f003907ad5
          paymentType: REFUND
          state: PENDING
          currency: GBP
          parentPaymentId: 96365a23dca04a5a9bcbb0031e7b06ac
  securitySchemes:
    BearerAuth:
      type: http
      description: >-
        The client sends HTTP requests with the Authorization header that
        contains the word Bearer followed by a space and the Shop Api Key.
      scheme: bearer
    SignatureAuth:
      type: apiKey
      description: >
        HMAC-SHA256 hash generated from JSON body using Shop Signing Key as a
        secret.


        **PHP Example for signature verification:**


        ```php

        protected function checkSignature(): bool

        {
            $signKey = 'YOUR_SHOP_SIGNING_KEY';
            $data = file_get_contents('php://input');
            $sign = $this->request->getHeader('signature');

            $generateSign = hash_hmac('sha256', $data, $signKey);

            if ($sign != $generateSign) {
                return false;
            }

            return true;
        }

        ```


        **How it works:**

        1. Get the raw request body using `file_get_contents('php://input')`

        2. Get the `Signature` header from the request

        3. Generate HMAC-SHA256 hash using your Shop Signing Key as secret

        4. Compare the generated signature with the received signature
      name: Signature
      in: header
security:
  - BearerAuth: []
tags:
  - name: Payments
    description: Payments API
  - name: Error codes
    description: >
      | Code | Description                                                     
      |

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

      | 1.00 | Illegal Workflow State                                          
      |

      | 1.01 | Not Found                                                       
      |

      | 1.02 | Communication Problem                                           
      |

      | 1.03 | Internal Server Error                                           
      |

      | 1.04 | Cancelled by Timeout                                            
      |

      | 1.05 | Terminal not Found                                              
      |

      | 1.06 | Recurring Token not Found                                       
      |

      | 1.07 | Payer Unaccepted                                                
      |

      | 1.08 | Invalid Amount                                                  
      |

      | 1.09 | Invalid Currency                                                
      |

      | 1.10 | Insufficient Balance                                            
      |

      | 2.00 | Cancelled by Customer                                           
      |

      | 3.00 | Declined by Acquirer                                            
      |

      | 3.01 | Declined by Acquirer: Anti-fraud                                
      |

      | 3.02 | Declined by Acquirer: Request Validation                        
      |

      | 3.03 | Acquirer Malfunction                                            
      |

      | 3.04 | Acquirer Timeout                                                
      |

      | 3.05 | Acquirer Limits Reached                                         
      |

      | 3.06 | Declined by Acquirer: Card Scheme                               
      |

      | 3.07 | Declined by Acquirer: Card Data                                 
      |

      | 3.08 | Declined by Acquirer: Business Rules                            
      |

      | 3.09 | Not Fully 3DS                                                   
      |

      | 3.10 | Unknown Error Code                                              
      |

      | 3.11 | Payer cannot pay                                                
      |

      | 3.12 | Invalid ID Document                                             
      |

      | 3.13 | ID Document Restrictions                                        
      |

      | 3.14 | Declined Due to Age Requirements                                
      |

      | 3.15 | ID Document Under Temporary Restrictions                        
      |

      | 3.16 | Duplicate Payment                                               
      |

      | 3.17 | Channel not active                                              
      |

      | 3.18 | Cancelled or abandoned transaction                              
      |

      | 3.19 | Card PAN blacklisted                                            
      |

      | 3.20 | Card PAN not whitelisted                                        
      |

      | 3.21 | Invalid mobile number                                           
      |

      | 3.22 | Card BIN country not allowed                                    
      |

      | 3.23 | Bank not supported                                              
      |

      | 4.00 | Declined by Issuer                                              
      |

      | 4.01 | Insufficient Funds                                              
      |

      | 4.02 | Do Not Honor                                                    
      |

      | 4.03 | Invalid Account Number                                          
      |

      | 4.04 | Declined by Issuer: Invalid card expiration date                
      |

      | 4.05 | Issuer Limits Reached                                           
      |

      | 4.06 | Card not active                                                 
      |

      | 4.07 | Invalid Security Code                                           
      |

      | 4.08 | Declined by Issuer: Business Rules                              
      |

      | 4.09 | Declined by Issuer: Anti-fraud                                  
      |

      | 4.10 | Transaction not permitted to cardholder                         
      |

      | 4.11 | AVS failed                                                      
      |

      | 5.00 | Declined by 3DS                                                 
      |

      | 5.01 | 3DS Timeout                                                     
      |

      | 5.02 | ACS malfunction                                                 
      |

      | 6.00 | Declined by Internal Anti-fraud                                 
      |

      | 6.01 | Card PAN Blacklisted                                            
      |

      | 6.02 | Customer Email Blacklisted                                      
      |

      | 6.03 | Card Issuing Country Restricted                                 
      |

      | 6.04 | IP Country Restricted                                           
      |

      | 6.05 | Restricted Currency                                             
      |

      | 6.06 | Invalid Amount                                                  
      |

      | 6.07 | IP Country Must Be Equal to Billing Country                     
      |

      | 6.08 | IP Country Must Be Equal to Card Issuing Country                
      |

      | 6.09 | Billing Country Must Be Equal to Card Issuing Country           
      |

      | 6.10 | Payment Created Within Closed Period of Day                     
      |

      | 6.11 | Card PAN not Whitelisted                                        
      |

      | 6.12 | Cardholder name is invalid                                      
      |

      | 6.13 | The same card is used by different customers                    
      |

      | 6.14 | Customer Phone Blacklisted                                      
      |

      | 6.15 | Card Brand not supported                                        
      |

      | 6.21 | Limit exceeded: Number of completed deposits                    
      |

      | 6.22 | Limit exceeded: Number of completed deposits for card           
      |

      | 6.23 | Limit exceeded: Number of declined deposits for card            
      |

      | 6.24 | Limit exceeded: Number of cards for IP address                  
      |

      | 6.25 | Limit exceeded: Number of IP addresses for card                 
      |

      | 6.26 | Limit exceeded: IP country does not match card country          
      |

      | 6.27 | Limit exceeded: Same amount and currency for card               
      |

      | 6.28 | Limit exceeded: Amount of deposits in specified currency        
      |

      | 6.29 | Limit exceeded: Amount of deposits for card and currency        
      |

      | 6.30 | Limit exceeded: Amount of deposits in base currency             
      |

      | 6.31 | Limit exceeded: Amount of deposits for card in base currency    
      |

      | 6.32 | Limit exceeded: Number of IP countries for card                 
      |

      | 6.33 | Limit exceeded: Amount of deposits for customer in base currency
      |

      | 6.34 | Limit exceeded: Withdrawal amount for customer in base currency 
      |

      | 6.35 | Billing Country Restricted                                      
      |

      | 6.36 | Customer Citizenship Country Restricted                         
      |

      | 6.37 | Limit exceeded: Number of withdrawals                           
      |

      | 6.38 | Limit exceeded: Amount of withdrawals in specified currency     
      |

      | 6.39 | Card BIN Blacklisted                                            
      |

      | 6.40 | UPI VPA Blacklisted                                             
      |

      | 6.41 | ID Document Blacklisted                                         
      |

      | 6.42 | Limit exceeded: Decline deposits streak for card                
      |

      | 6.43 | Limit exceeded: Incomplete deposits APM streak for email        
      |

      | 6.44 | Customer email contains restricted word                         
      |

      | 6.45 | Limit exceeded: Pending deposits for customer                   
      |

      | 6.46 | Limit exceeded: Pending same amount deposits for customer       
      |

      | 6.47 | Limit exceeded: Number of completed deposits for email          
      |

      | 6.48 | Limit exceeded: Number of completed deposits for IP address     
      |

      | 7.00 | Declined by External Anti-fraud                                 
      |

      | 7.01 | External Anti-fraud Communication Problem                       
      |
  - name: Testing
    description: >
      For a successful deposit in the sandbox environment, the amount should be
      less than 10000000. 

      For test withdrawals and refunds, the limit is 10000.


      ### Test cards

      | Card Number         |
      Result                                                         |

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

      | 4000 0000 0000 0002 | 3D-Secure enrolled, successful
      authorization                   |

      | 4242 4242 4242 4242 | 3D-Secure enrolled, declined
      authorization                     |

      | 4000 0000 0000 0408 | Not enrolled for 3D-Secure, successful
      authorization           |

      | 4000 0000 0000 0416 | Not enrolled for 3D-Secure, declined
      authorization             |
