openapi: 3.1.0
info:
  title: Allpay Payment Gateway API
  version: '9'
  description: "Allpay API for Israel-based businesses. Accept payments from clients in Israel and worldwide.\n\n**Base URL:**\
    \ https://allpay.to/app/\n\n**Authentication:** All requests use POST method with JSON body containing:\n- `login` (string):\
    \ Your API login from Settings → Integrations\n- `sign` (string): SHA256 signature\n\n**Signature Algorithm:**\n1. Remove\
    \ the `sign` field from the request body (do not include it in the signature string).\n2. Exclude parameters with empty\
    \ values (`\"\"`, `null`, missing). Use empty strings instead of `0` when a parameter is meant to be empty.\n3. Sort top-level\
    \ keys alphabetically.\n4. Build a list of chunks (strings):\n   - If a value is a string and not empty: add it.\n   -\
    \ If a value is an array of objects (e.g. `items`): for each object, sort its keys alphabetically and add each non-empty\
    \ string value in that order.\n5. Join chunks with `:` and append `:` + `api_key` to the end.\n6. Calculate SHA256 hex\
    \ digest of the resulting string.\n\n\n**Important Notes:**\n- Do not trim spaces from values\n- Do not use null or 0\
    \ instead of empty strings\n- All routing is done via query parameters: ?show=ENDPOINT&mode=api9\n"
  contact:
    email: support@allpay.co.il
  x-logo:
    url: https://www.allpay.co.il/logo
  x-generated: 'Updated to match web API reference. Generated: 2025-12-15'
servers:
- url: https://allpay.to/app
  description: Production server
tags:
- name: Payments
  description: Create and manage payments
- name: Subscriptions
  description: Recurring billing management
- name: Refunds
  description: Full and partial refunds
- name: Tokens
  description: Card tokenization for repeat payments
- name: J5 Transactions
  description: Pre-authorization and two-step payments
- name: Verification
  description: Status checks and API key validation
paths:
  /?show=getpayment&mode=api9:
    post:
      tags:
      - Payments
      operationId: createPayment
      summary: Create payment
      description: 'Creates a new payment and returns a payment_url to redirect the customer.

        After successful payment, Allpay sends a webhook to your notifications_url.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentRequest'
            examples:
              basicPayment:
                summary: Basic payment request
                value:
                  login: your_api_login
                  order_id: ORDER-12345
                  items:
                  - name: Item 1
                    price: 100
                    qty: 2
                    vat: 1
                  - name: Item 2
                    price: 200
                    qty: 1
                    vat: 1
                  currency: ILS
                  lang: EN
                  notifications_url: https://site.com/checkout-confirm
                  client_name: Joe Doe
                  client_email: joe@doe.com
                  client_phone: '+972545678900'
                  expire: 1734200000
                  sign: generated_sha256_signature
      responses:
        '200':
          description: Payment URL returned
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  description: 'Redirect flow (no allpay_token): returns a URL for redirecting the customer to the Allpay
                    payment page.'
                  properties:
                    payment_url:
                      type: string
                      format: uri
                      example: https://allpay.to/pay/abc123
                  required:
                  - payment_url
                - type: object
                  description: 'Token payment flow (allpay_token provided): payment is executed immediately without redirect.'
                  properties:
                    order_id:
                      type: string
                      description: Allpay order ID
                    status:
                      type: string
                      description: Payment status
                  required:
                  - order_id
                  - status
        '400':
          $ref: '#/components/responses/Error'
  /?show=paymentstatus&mode=api9:
    post:
      tags:
      - Payments
      operationId: getPaymentStatus
      summary: Check payment status
      description: 'Verify the status of a payment. Call at least 2 seconds after the payment attempt.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Payment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatusResponse'
        '400':
          $ref: '#/components/responses/Error'
  /?show=refund&mode=api9:
    post:
      tags:
      - Refunds
      operationId: createRefund
      summary: Refund payment
      description: 'Issue a full or partial refund.

        - Full refund: omit the `items` parameter

        - Partial refund: include `items` array with amounts


        **Note:** Items array amounts must be strings (e.g., "200" not 200).

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefundRequest'
            examples:
              fullRefund:
                summary: Full refund
                value:
                  login: your_api_login
                  order_id: ORDER-12345
                  amount: 100.0
                  sign: generated_sha256_signature
              partialRefund:
                summary: Partial refund
                value:
                  login: your_api_login
                  order_id: ORDER-12345
                  amount: 200.0
                  items:
                  - amount: '0'
                  - amount: '200'
                  - amount: '0'
                  sign: generated_sha256_signature
      responses:
        '200':
          description: Refund successful
          content:
            application/json:
              schema:
                type: object
                required:
                - order_id
                - status
                properties:
                  order_id:
                    type: string
                  status:
                    type: integer
                    description: '- 3: Refunded

                      - 4: Partially refunded

                      '
                    enum:
                    - 3
                    - 4
        '400':
          $ref: '#/components/responses/Error'
  /?show=gettoken&mode=api9:
    post:
      tags:
      - Tokens
      operationId: getToken
      summary: Get payment token
      description: 'Request a token for a successful payment. Can be used for future payments without re-entering card details.


        **Note:** Bit payments do not support tokenization.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Token details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/Error'
  /?show=cancelsubscription&mode=api9:
    post:
      tags:
      - Subscriptions
      operationId: cancelSubscription
      summary: Cancel subscription
      description: Cancel an active subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Cancellation status
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                properties:
                  status:
                    type: integer
                    description: '- 2: Completed (no cancellation required)

                      - 4: Cancelled

                      '
                    enum:
                    - 2
                    - 4
        '400':
          $ref: '#/components/responses/Error'
  /?show=subscriptionstatus&mode=api9:
    post:
      tags:
      - Subscriptions
      operationId: getSubscriptionStatus
      summary: Get subscription status
      description: Get detailed status and charge history of a subscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StatusRequest'
      responses:
        '200':
          description: Subscription details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatusResponse'
        '400':
          $ref: '#/components/responses/Error'
  /?show=getsubscriptions&mode=api9:
    post:
      tags:
      - Subscriptions
      operationId: listSubscriptions
      summary: List subscriptions
      description: 'Get a paginated list of subscriptions (100 per page)

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionsListRequest'
      responses:
        '200':
          description: List of subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsListResponse'
        '400':
          $ref: '#/components/responses/Error'
  /?show=subscriptionsinfo&mode=api9:
    post:
      tags:
      - Subscriptions
      operationId: getSubscriptionsStatistics
      summary: Get subscription statistics
      description: Get statistical breakdown by subscription status and currency
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - login
              - sign
              properties:
                login:
                  type: string
                  description: Your API login
                sign:
                  type: string
                  description: SHA256 signature
      responses:
        '200':
          description: Statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionsInfoResponse'
        '400':
          $ref: '#/components/responses/Error'
  /?show=runauthorizedpayment&mode=api9:
    post:
      tags:
      - J5 Transactions
      operationId: chargeJ5Payment
      summary: Charge pre-authorized payment
      description: 'Complete a J5 pre-authorization by charging the reserved amount.

        Can only be done once within 168 hours (7 days) of the reservation.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - login
              - order_id
              - amount
              - sign
              properties:
                order_id:
                  type: string
                  description: Order ID from the original pre-authorization request
                amount:
                  type: number
                  format: double
                  description: Amount to charge (must be ≤ reserved amount)
                  example: 100.0
                sign:
                  type: string
                  description: SHA256 signature
                login:
                  type: string
                  description: Your API login
      responses:
        '200':
          description: Charge result
          content:
            application/json:
              schema:
                type: object
                required:
                - order_id
                - status
                properties:
                  order_id:
                    type: string
                  status:
                    type: integer
                    description: '- 0: Payment failed

                      - 1: Successful payment

                      '
                    enum:
                    - 0
                    - 1
                  amount:
                    type: number
                    format: double
        '400':
          $ref: '#/components/responses/Error'
  /?show=checkkeys&mode=api9:
    post:
      tags:
      - Verification
      operationId: verifyApiKeys
      summary: Verify API credentials
      description: 'Verify the validity of API login and key without making a payment.

        Useful for platforms integrating Allpay.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - login
              - sign
              properties:
                login:
                  type: string
                  description: API login to verify
                sign:
                  type: string
                  description: SHA256 signature generated with the API key
      responses:
        '200':
          description: Keys are valid
          content:
            application/json:
              schema:
                type: object
                properties:
                  last_paid_order_id:
                    type: string
                    description: Last paid order ID or "-1" if none
                  last_paid_order_date:
                    type: string
                    description: Unix timestamp or "-1" if none
        '400':
          description: Invalid credentials
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Signature is incorrect
components:
  schemas:
    PaymentRequest:
      type: object
      required:
      - login
      - order_id
      - items
      - sign
      properties:
        login:
          type: string
          description: Your API login from Settings → Integrations
        order_id:
          type: string
          description: Unique order identifier in your system
          example: ORDER-12345
        items:
          type: array
          description: List of products/services
          minItems: 1
          items:
            $ref: '#/components/schemas/PaymentItem'
        currency:
          type: string
          description: Billing currency (default ILS)
          enum:
          - ILS
          - USD
          - EUR
          default: ILS
        lang:
          type: string
          description: Payment page language (default AUTO)
          enum:
          - AUTO
          - EN
          - RU
          - HE
          - AR
          default: AUTO
        notifications_url:
          type: string
          format: uri
          description: Webhook URL for payment confirmation
        success_url:
          type: string
          format: uri
          description: Redirect URL after successful payment
        backlink_url:
          type: string
          format: uri
          description: URL for "Return to site" button
        inst:
          type: integer
          minimum: 1
          maximum: 12
          description: Maximum number of installment payments
        inst_fixed:
          type: integer
          enum:
          - 0
          - 1
          default: 0
          description: '- 0: Customer chooses 1 to inst payments

            - 1: Fixed number of payments (equal to inst)

            '
        allpay_token:
          type: string
          description: Token for payment without entering card details
        client_name:
          type: string
          description: Customer's full name (required for Hosted Fields)
        client_tehudat:
          type: string
          description: Tehudat Zehut / Company Number (use "000000000" to hide for non-Israelis)
        client_email:
          type: string
          format: email
          description: Customer email (required for Hosted Fields)
        client_phone:
          type: string
          description: Customer phone number
        add_field_1:
          type: string
          description: Custom data (returned unchanged in webhook)
        add_field_2:
          type: string
          description: Custom data (returned unchanged in webhook)
        show_applepay:
          type: boolean
          description: Show Apple Pay button (module must be enabled)
        show_bit:
          type: boolean
          description: Show Bit payment button (module must be enabled)
        expire:
          type: integer
          format: int64
          description: Unix timestamp when payment link expires (default 1 week)
        preauthorize:
          type: boolean
          description: Create J5 pre-authorization instead of immediate charge
        subscription:
          $ref: '#/components/schemas/SubscriptionObject'
        sign:
          type: string
          description: SHA256 signature
    PaymentItem:
      type: object
      required:
      - name
      - qty
      - price
      - vat
      properties:
        name:
          type: string
          description: Item name (product/service)
          example: Product A
        qty:
          type: number
          format: double
          description: Quantity
          example: 2
        price:
          type: number
          format: double
          description: Price per item (VAT included, 2 decimals)
          example: 100.0
        vat:
          type: integer
          description: 'VAT included in price:

            - 0: No VAT (VAT-exempt dealer)

            - 1: 18% VAT

            - 3: 0% VAT

            '
          enum:
          - 0
          - 1
          - 3
        discount_val:
          type: number
          format: double
          description: Discount amount for item
        discount_type:
          type: string
          enum:
          - fixed
          - perc
          description: '- fixed: Fixed amount discount

            - perc: Percentage discount



            Required when discount_val is provided.'
      dependentRequired:
        discount_val:
        - discount_type
    SubscriptionObject:
      type: object
      required:
      - start_type
      - end_type
      description: Subscription configuration (requires Subscriptions module)
      properties:
        start_type:
          type: integer
          enum:
          - 1
          - 2
          - 3
          description: 'When first charge occurs:

            - 1: Immediately

            - 2: On specific date (use start_date)

            - 3: After N days (use start_n)

            '
        start_date:
          type: integer
          format: int64
          description: Unix timestamp (required if start_type=2)
        start_n:
          type: integer
          description: Number of days (required if start_type=3)
        end_type:
          type: integer
          enum:
          - 1
          - 2
          - 3
          description: 'When subscription ends:

            - 1: Infinite (until cancelled)

            - 2: On specific date (use end_date)

            - 3: After N charges (use end_n)

            '
        end_date:
          type: integer
          format: int64
          description: Unix timestamp (required if end_type=2)
        end_n:
          type: integer
          description: Number of charges (required if end_type=3)
    StatusRequest:
      type: object
      required:
      - login
      - order_id
      - sign
      properties:
        login:
          type: string
        order_id:
          type: string
        sign:
          type: string
    PaymentStatusResponse:
      type: object
      required:
      - order_id
      - status
      properties:
        order_id:
          type: string
        status:
          type: integer
          description: '- 0: Unpaid (pending or failed)

            - 1: Successful payment

            - 3: Refunded

            - 4: Partially refunded

            '
          enum:
          - 0
          - 1
          - 3
          - 4
        amount:
          type: number
          format: double
        client_name:
          type: string
        client_email:
          type: string
          format: email
        client_tehudat:
          type: string
        client_phone:
          type: string
        inst:
          type: integer
          description: Number of installment payments
        currency:
          type: string
          enum:
          - ILS
          - USD
          - EUR
        card_mask:
          type: string
          example: 465901******7049
        card_brand:
          type: string
          example: Visa
        foreign_card:
          type: integer
          enum:
          - 0
          - 1
          description: 0=local card, 1=foreign card
        receipt:
          type: string
          format: uri
          description: Digital receipt URL (if module active)
    RefundRequest:
      type: object
      required:
      - login
      - order_id
      - amount
      - sign
      properties:
        login:
          type: string
        order_id:
          type: string
        items:
          type: array
          description: For partial refunds - must match original items count/order
          items:
            type: object
            required:
            - amount
            properties:
              amount:
                type: string
                description: Refund amount for this item (use "0" to skip)
                example: '200'
        amount:
          type: number
          format: double
          description: Total refund amount
          example: 100.0
        sign:
          type: string
    TokenResponse:
      type: object
      required:
      - order_id
      - allpay_token
      properties:
        order_id:
          type: string
        card_mask:
          type: string
          example: 465901******7049
        card_brand:
          type: string
          example: Visa
        foreign_card:
          type: integer
          enum:
          - 0
          - 1
        allpay_token:
          type: string
          description: Token for future payments
    SubscriptionStatusResponse:
      type: object
      required:
      - order_id
      - status
      properties:
        order_id:
          type: string
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          description: '- 1: Active

            - 2: Completed

            - 3: Error (retry tomorrow)

            - 4: Cancelled

            '
        amount:
          type: number
          format: double
          description: Amount per charge
        currency:
          type: string
          enum:
          - ILS
          - USD
          - EUR
        payments_n:
          type: integer
          description: Number of successful charges
        paid_total:
          type: number
          format: double
          description: Total amount charged
        payments:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionCharge'
    SubscriptionCharge:
      type: object
      properties:
        ts:
          type: integer
          format: int64
          description: Unix timestamp of charge
        amount:
          type: number
          format: double
        receipt:
          type: string
          format: uri
    SubscriptionsListRequest:
      type: object
      required:
      - login
      - sign
      properties:
        login:
          type: string
        status:
          type: integer
          enum:
          - 0
          - 1
          - 2
          - 3
          - 4
          default: 0
          description: '- 0: Any status

            - 1: Active

            - 2: Completed

            - 3: Error

            - 4: Cancelled

            '
        page:
          type: integer
          description: Page number (100 subscriptions per page)
        sign:
          type: string
    SubscriptionsListResponse:
      type: object
      properties:
        total_n:
          type: integer
          description: Total number of returned subscriptions
        next_page:
          type: integer
          description: Next page number or 0 if no more pages
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionDetail'
    SubscriptionDetail:
      type: object
      properties:
        name:
          type: string
          description: Subscription name (first item name)
        status:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
        client_name:
          type: string
        client_email:
          type: string
        client_phone:
          type: string
        client_tehudat:
          type: string
        start_date:
          type: integer
          format: int64
          description: Unix timestamp of first charge
        end_date:
          type: integer
          format: int64
          description: Unix timestamp of last charge
        next_payment:
          type: integer
          format: int64
          description: Unix timestamp of next charge
        amount:
          type: number
          format: double
          description: Cost per charge
        payments_n:
          type: integer
          description: Number of successful charges
        paid_total:
          type: number
          format: double
          description: Total charged amount
        currency:
          type: string
          enum:
          - ILS
          - USD
          - EUR
        add_field_1:
          type: string
        add_field_2:
          type: string
    SubscriptionsInfoResponse:
      type: object
      properties:
        info:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                enum:
                - 1
                - 2
                - 3
                - 4
              total_n:
                type: integer
                description: Total subscriptions with this status
              per_currency:
                type: array
                items:
                  type: object
                  properties:
                    currency:
                      type: string
                      enum:
                      - ILS
                      - USD
                      - EUR
                    total_n_currency:
                      type: integer
                      description: Number of subscriptions in this currency
                    total_amount_currency:
                      type: number
                      format: double
                      description: Total monthly amount (turnover)
    WebhookPaymentNotification:
      type: object
      description: 'POST request sent to notifications_url after successful payment.

        Verify signature using your API key.

        '
      required:
      - order_id
      - status
      - sign
      properties:
        order_id:
          type: string
        amount:
          type: number
          format: double
        status:
          type: integer
          enum:
          - 0
          - 1
          description: 0=unpaid, 1=paid
        client_name:
          type: string
        client_email:
          type: string
        client_phone:
          type: string
        client_tehudat:
          type: string
        inst:
          type: integer
        currency:
          type: string
          enum:
          - ILS
          - USD
          - EUR
        foreign_card:
          type: integer
          enum:
          - 0
          - 1
        card_mask:
          type: string
        card_brand:
          type: string
        receipt:
          type: string
          format: uri
        add_field_1:
          type: string
        add_field_2:
          type: string
        sign:
          type: string
          description: SHA256 signature to verify
    ApiError:
      type: object
      properties:
        error:
          type: string
          description: Error message
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    ApiSignature:
      type: apiKey
      in: header
      name: sign
      description: 'SHA256 signature of request body.

        See documentation for signature generation algorithm.

        '
x-readme:
  samples-languages:
  - php
  - javascript
  - python
  - curl