DOCSEARCHbyAlgolia
Submit Docs

Plexy Payment Gateway Documentation

website·Indexed 32 days ago

https://developer.plexy.money

A comprehensive payment gateway solution for businesses, featuring a robust HTTP API and client-side SDKs for Android, iOS, React Native, and Flutter. Plexy supports various integration paths including Sessions Flow for rapid deployment and Advanced Flow for full UI control, alongside support for Apple Pay, Google Pay, payment links, recurring payments, and a dedicated Wallet API.

Tokens
117K
Snippets
556
Records
750
Agent score
64%

What's inside Plexy

  1. Overview of Direct Payments (Host-to-Host)

    Direct Payments allow a merchant to collect card data in their own UI, encrypt it using a PlexyPay public key, and create a payment via the POST /v1/payments/direct endpoint. This is an API-only flow that bypasses hosted checkout UIs, giving the merchant full control over the user experience. Note that 3-D Secure (3DS) challenges may be required by the issuing bank, which the merchant must handle by presenting the redirect URL to the user.

  2. Overview of Plexy Payment Gateway

    Plexy is a PCI DSS compliant payment gateway providing secure payment processing for businesses. It supports major card networks (Visa, Mastercard, American Express, UnionPay) and digital wallets (Apple Pay, Google Pay™). The platform provides a RESTful API, a sandbox environment for testing, and real-time event notifications via webhooks.

  3. Overview of the Plexy Advanced Flow payment lifecycle

    The Advanced flow allows developers to build their own payment forms and manage the full payment lifecycle. It is designed for maximum flexibility but requires more development effort than the Sessions flow. The process consists of four primary steps: 1. Get available payment methods, 2. Collect and encrypt payment details, 3. Initiate the payment, and 4. Handle any required additional actions (like 3D Secure or redirects).

  4. Overview of the Plexy Sessions Flow

    The Sessions flow is the fastest way to accept payments. Plexy handles payment method rendering, 3D Secure authentication, redirects, and result processing. The general workflow is: 1. Create a session via server-side API; 2. Initialize the checkout component on the frontend using the session ID; 3. Customer completes payment in the embedded UI; 4. Server receives payment results via webhooks to update order status.

  5. TransactionHistoryEventData response schema

    The response.TransactionHistoryEventData object provides detailed information about a transaction event. It includes financial data (amounts in fractional units), timestamps for various stages of the transaction lifecycle (authorized, charged, posted, settled, refunded, rejected), and identifiers for the customer, merchant, and payment session.
    # Key properties of response.TransactionHistoryEventData
properties:
  id: string
  amount: number
  amountFractionalUnit: integer
  currency: string
  status: string
  type: string
  createdAt: string
  updatedAt: string
  customerId: string
  merchantId: string
  merchantReference: string
  paymentMethod: string
  authorizedAmountFractionalUnit: integer
  authorizedAt: string
  chargedAmountFractionalUnit: integer
  chargedAt: string
  settledAmountFractionalUnit: integer
  settledAt: string
  refundedAmountFractionalUnit: integer
  refundedAt: string
  rejectedAmountFractionalUnit: integer
  rejectedAt: string
  orderMetadata: object # Merchant-defined metadata

  6. Retrieve transaction details by order reference

    Use the GET /v1/transactions/by-order-reference/{order_reference} endpoint to retrieve detailed information about a specific transaction. This includes payment status, currency, amounts in fractional units, and pay-in balance information (payInBalanceBefore and payInBalanceAfter).

    Request Details:

    • Method: GET
    • Path Parameter: order_reference (string, required)
    • Authentication: Requires PrivateKeyAuth

    Response Fields:

    • amount: The transaction amount.
    • amountFractionalUnit: Amount in the smallest currency unit.
    • currency: The currency code.
    • status: The current status of the transaction.
    • paymentId: Unique identifier for the payment.
    • orderMetadata: An optional object containing up to 5 merchant-defined string key/value pairs (keys: 1–40 chars, values: max 100 chars).
    • splitRequests: An array of split request objects containing id, paymentBeneficiaryId, merchantId, transactionId, and netAmout (fractional unit).

    HTTP Response Codes:

    • 200: Successfully retrieved transaction details.
    • 400: Invalid transaction ID.
    • 401: Unauthorized.
    • 404: Transaction not found.
    • 500: Internal server error.
    curl -X GET "https://api.plexy.money/v1/transactions/by-order-reference/{order_reference}"

  7. TransactionResponse object schema

    The response.TransactionResponse object is returned by the Plexy API to provide the result of a transaction. It contains details about the payment status, transaction identifiers, and card information.
    response.TransactionResponse:
  type: object
  properties:
    amount: { type: number }
    authCode: { type: string }
    cardExpiryDate: { type: string }
    cardMask: { type: string }
    cardScheme: { type: string }
    cardTokenId: { type: string }
    cardholderName: { type: string }
    code: { type: integer }
    currency: { type: string }
    id: { type: string }
    message: { type: string }
    networkTransactionReference: { type: string }
    orderReference: { type: string }
    originalTransactionId: { type: string }
    paymentMethod: { type: string }
    remainingBalance: { type: number }
    responseCode: { type: string }
    status: { type: string }
    success: { type: boolean }

  8. CustomerTransaction response object schema

    The response.CustomerTransaction object provides details about a specific customer transaction. It includes the transaction amount, timestamp, currency, unique identifier, and current processing status.
    response.CustomerTransaction:
  type: object
  properties:
    id:
      type: string
      description: "Unique identifier for the transaction (UUID format)."
      example: "123e4567-e89b-12d3-a456-426614174000"
    amount:
      type: number
      description: "Total amount of the transaction (e.g., 100.50 for $100.50)."
      example: 100.5
    currency:
      type: string
      description: "Currency for the payment."
      enum: [KZT, USD, EUR, GBP]
      example: "USD"
    createdAt:
      type: string
      description: "Timestamp when the transaction was created (ISO 8601)."
      example: "2025-03-14T12:34:56Z"
    status:
      type: string
      description: "Current state of the transaction."
      enum: [new, processing, authorized, charged, rejected, failed, abandoned, 3d, cancelled, refunded, refund_pending, settled]
      example: "completed"

  9. Understand the Transaction object schema

    The Transaction object returned by the API contains details about a specific payment. Key fields include storeId, amount, currency, status, customerId, paymentId, paymentMethod, createdAt, updatedAt, and orderMetadata.

  10. Define a DistributionCreateRequest for fund distribution

    The DistributionCreateRequest object is used to request a fund distribution. It requires details about the order, the amount, the currency, the recipient's banking information, and the purpose of the payment.
    DistributionCreateRequest:
  type: object
  required:
    - orderReference
    - amount
    - currency
    - recipient
    - paymentPurpose
  properties:
    orderReference:
      type: string # Example: DIST-100001
    amount:
      type: integer # format: int64. Example: 150000
    currency:
      type: string # Example: KZT
    recipient:
      $ref: '#/components/schemas/DistributionRecipient'
    paymentPurpose:
      type: string # Example: Распределение средств по договору 123

  11. Reference for common refusal reason codes

    When a payment is Refused, the refusalReasonCode provides specific details about the failure. Common codes include:

    • 2: Refused (Try different method)
    • 3: Referral (Contact bank)
    • 5: Blocked Card
    • 6: Expired Card
    • 11: 3D Secure Failed
    • 12: Not Enough Balance
    • 14: Fraud
    • 17: Invalid Pin
    • 20: Fraud - Risk
    • 22/24: CVV/CVC failure
    • 32: AVS Declined

  12. Access payment method details via PaymentMethodDto

    The PaymentMethodDto provides metadata about the payment method used, including the brand, funding source, and group.
    PaymentMethodDto:
  type: object
  properties:
    brand: # The brand name
      type: string
    brands: # List of possible brands
      type: array
      items: { type: string }
    configuration: # Configuration for the payment method
      type: object
    fundingSource: # The funding source
      type: string
    group: # The group where this payment method belongs
      type: string
    name: # The payment method name
      type: string
    type: # The payment method type
      type: string