> ## Documentation Index
> Fetch the complete documentation index at: https://docs.easybilling.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate transaction

> Creates a new payment request and returns the gateway redirect URL and the payment transaction status. Idempotent on transactionId — re-issuing an already-PROCESSING / FAILED transaction may reuse the existing gateway link or re-issue depending on each gateway's shouldReissuePaymentOnFailed policy.



## OpenAPI

````yaml /payment.openapi.json post /api/transactions
openapi: 3.1.0
info:
  title: payment hub
  description: |
    Focused OpenAPI 3.1 contract for the **launch-payment** endpoint
    (`POST /api/transactions`). The request body is polymorphic on
    `paymentGatewayType`; each gateway sub-schema documents the gateway-specific
    fields. Highlights:

      * `onlineScenario=true` → customer-initiated, Hosted-Checkout / redirect flow
      * `onlineScenario=false` → merchant-initiated debit using a previously
        stored payment method (only valid on gateways that support offline)
      * `supportOfflineScenario` (Stripe / PayerMax only) — when `true` and
        `onlineScenario=true`, the gateway is instructed to remember the card
        so a future off-session (merchant-initiated) charge can succeed.
  version: 1.0.0
  summary: ''
servers:
  - url: https://sbx.api.easybilling.cloud/payment-hub
    description: SBX
  - url: https://api.easybilling.cloud/payment-hub
    description: Production-AWS
security:
  - token: []
tags:
  - name: Payment Hub
paths:
  /api/transactions:
    post:
      tags:
        - Payment Hub
      summary: Initiate transaction
      description: >-
        Creates a new payment request and returns the gateway redirect URL and
        the payment transaction status. Idempotent on transactionId — re-issuing
        an already-PROCESSING / FAILED transaction may reuse the existing
        gateway link or re-issue depending on each gateway's
        shouldReissuePaymentOnFailed policy.
      parameters:
        - name: Authorization
          in: header
          description: ''
          required: false
          example: ''
          schema:
            type: string
        - name: trace-id
          in: header
          description: ''
          required: false
          example: '{{$string.uuid}}'
          schema:
            type: string
            default: '{{$string.uuid}}'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                transactionId:
                  type: string
                  title: Transaction ID
                  description: >-
                    The business transaction id corresponding to the payment,
                    such as order number，the length is less than or equal to 36
                    bits
                  maxLength: 32
                description:
                  type: string
                  title: Transaction Description
                  description: Description of the business transaction
                amount:
                  type: string
                  title: Transaction Amount
                currency:
                  type: string
                  title: Currency Unit
                  description: ISO 4217 standard
                customerIdentifier:
                  type: string
                  title: Customer Unique Identifier
                  description: >-
                    Customer unique identifier, which can be phone
                    number/email/UUID, etc. When using Stripe payment, this
                    value must be an email
                paymentGatewayType:
                  type: string
                  description: stripe-connect (Stripe), payer-max-isv(PayerMax)
                  title: ''
                  enum:
                    - stripe-connect
                    - payer-max-isv
                    - alipay-page
                    - wechat-pay-native
                onlineScenario:
                  type: boolean
                  title: One-time Payment
                  description: True for instant payment, false for recurring payment
                supportOfflineScenario:
                  type: boolean
                  description: >-
                    when onlineScenario is true and set supportOfflineScenario
                    to true, it is to support recurring auto payment, i.e. next
                    time with onlineScenario false, payment will be collected
                    successfully.
                completePayRedirectUrl:
                  type: string
                  title: Callback URL after payment completion
                  description: >-
                    Both successful and failed payments are considered
                    completed. When the payment gateway is Stripe, this field is
                    required and must start with https
                cancelPayRedirectUrl:
                  type: string
                  title: Cancel Payment Callback URL
                  description: >-
                    When the payment gateway is Stripe, this field is required
                    and must be a URL starting with https
              required:
                - transactionId
                - amount
                - currency
                - paymentGatewayType
                - completePayRedirectUrl
                - cancelPayRedirectUrl
                - onlineScenario
                - customerIdentifier
            examples:
              Stripe:
                value:
                  transactionId: Order-123
                  description: Order-123 Payment
                  amount: '123.00'
                  currency: USD
                  paymentGatewayType: stripe-connect
                  customerIdentifier: customer@test.com
                  onlineScenario: true
                  completePayRedirectUrl: https://example.com/payment/success
                  cancelPayRedirectUrl: https://example.com/payment/cancel
                summary: Stripe
              PayerMax:
                value:
                  transactionId: Order-456
                  description: Order-456 Payment
                  amount: '456.00'
                  currency: USD
                  paymentGatewayType: payer-max-isv
                  customerIdentifier: customer@test.com
                  onlineScenario: true
                  completePayRedirectUrl: https://example.com/payment/success
                  cancelPayRedirectUrl: https://example.com/payment/cancel
                summary: PayerMax
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  paymentUrl:
                    type: string
                    title: Payment Link Address
                    description: >-
                      Stripe, PayerMax can directly navigate to the payment page
                      via this URL
                  paymentId:
                    type: string
                    title: Unique ID generated by the payment system
                    description: Unique ID generated when initiating payment
                  expireTime:
                    type: integer
                    title: Timeout duration in seconds
                    description: Payment timeout duration (in seconds)
                  status:
                    type: string
                    title: Payment Status
                    enum:
                      - waiting
                      - processing
                      - succeeded
                      - failed
                      - closed
                    description: Payment status
                required:
                  - paymentUrl
                  - paymentId
                  - expireTime
                  - status
          headers: {}
      deprecated: false
      security:
        - token: []
components:
  securitySchemes:
    token:
      type: http
      scheme: bearer

````