Payment Gateway Docs
    Payment Gateway Docs
    • SDK Flow

    SDK Flow

    Payment Flow Diagrams#

    This document describes the various payment flows available in the OPG Public API.

    1. Intent Creation to Payment Confirmation with Saved Card#

    Description: This flow demonstrates the complete payment process for a registered customer using a previously saved card token. The customer must be identified by customerId during intent creation, which enables card management operations.
    Key Details:
    Authentication: Uses Secret Key for intent creation, Public Key for client-side operations
    customerId: Required for saved cards; enables customerToken generation
    Card Token: Encrypted stored card reference; requires CVV for each transaction
    3DS Flow: Most card transactions redirect to bank's 3D Secure page
    Security: CVV is never stored; only provided during confirmation

    2. Intent Creation to Payment Confirmation Without Customer ID (Anonymous/Guest Checkout)#

    Description: This flow enables guest users to make payments without registration or card tokenization. The card details are passed directly during confirmation, ideal for one-time purchases.
    Key Details:
    No Registration: Guest users can pay without creating an account
    Direct Card Entry: Card details sent in paymentData (not tokenized)
    No Card Storage: saveCard must be false (no customerToken available)
    Security: Card details are processed immediately, not stored
    Use Case: Ideal for e-commerce guest checkout, one-time donations

    3. Intent Creation to Payment Confirmation with QRIS#

    Description: QRIS (QR Code Indonesian Standard) payment flow generates a QR code that customers scan with their banking/e-wallet apps to complete payment.
    Key Details:
    QR Code: Generated in EMVCo QR format (readable by all Indonesian bank apps)
    Expiration: QR codes expire after 24 hours (configurable)
    Async Payment: Customer completes payment offline in their app
    Polling: Merchant must poll status or use webhook for updates
    Supported Apps: All Indonesian banking apps, Gopay, OVO, Dana, etc.

    4. Intent Creation to Payment Confirmation with Virtual Account#

    Description: Virtual Account (VA) payment creates a unique account number for the customer to transfer funds to via bank transfer (ATM, mobile banking, or internet banking).
    Key Details:
    VA Number Format: 8808 + merchantCode + unique identifier
    Bank Options: CIMB, BNI, BRI supported
    24-Hour Expiry: VA numbers expire after 24 hours
    Exact Amount: Customer must transfer exact amount
    Real-time: Webhook notification when payment received
    Use Case: Bank transfers, corporate payments, B2B transactions

    5. Intent Creation to Payment Confirmation with WeChat Pay#

    Description: WeChat Pay integration for Chinese customers. Generates a QR code that can be scanned within the WeChat app to complete payment.
    Key Details:
    Target Users: Chinese customers with WeChat accounts
    QR Code: Dynamic QR generated per transaction
    Currency: IDR converted to CNY by WeChat
    Real-time: Instant notification on payment completion
    Mobile Only: Requires WeChat app on mobile device
    Alternative: Also supports merchant-presented QR (MPM)

    6. Intent Creation to Payment Confirmation with Alipay#

    Description: Alipay integration for Chinese customers. Generates a QR code that can be scanned within the Alipay app to complete payment.
    Key Details:
    Target Users: Chinese customers with Alipay accounts
    QR Code: Dynamic QR generated per transaction
    Currency: IDR transactions supported
    Real-time: Instant settlement notification
    Mobile First: Optimized for Alipay mobile app
    Security: Alipay's risk management system protects transactions

    Common Response Patterns#

    Success Response (with action required)#

    {
  "id": "pi_xxx",
  "status": "processing",
  "paymentMethod": "credit_card",
  "nextAction": {
    "redirectToUrl": {
      "url": "/v1.0/credit-card/credit-card-redirect/tx_xxx"
    }
  }
}

    Success Response (QR/VA)#

    {
  "id": "pi_xxx",
  "status": "processing",
  "paymentMethod": "qris",
  "nextAction": {
    "displayQr": {
      "qrCode": "000201010211260014BR.GOV.BCB.PIX...",
      "expiresAt": "2026-02-03T15:45:20Z"
    }
  }
}

    Status Check Response#

    {
  "id": "pi_xxx",
  "status": "processing",
  "amount": 100000,
  "currency": "IDR",
  "paymentMethod": "credit_card",
  "transactionId": "tx_xxx",
  "metadata": {
    "order_id": "order_123"
  }
}

    Authentication Requirements#

    EndpointAuth MethodKey Type
    POST /v1/payment-intentsX-Secret-KeySecret (Server-side)
    GET /v1/payment-methodsX-Public-KeyPublic (Client-side)
    POST /v1/card-tokensX-Public-KeyPublic (Client-side)
    GET /v1/card-tokensX-Public-KeyPublic (Client-side)
    POST /v1/payments/confirmX-Public-KeyPublic (Client-side)
    GET /v1/payments/{id}/statusX-Public-KeyPublic (Client-side)

    Status Lifecycle#

    Security Considerations#

    1.
    Secret Key: Never expose in client-side code (browser/mobile)
    2.
    Public Key: Safe for frontend usage
    3.
    Client Secret: Single-use token for payment confirmation
    4.
    Customer Token: Contains encrypted customer reference
    5.
    Card Tokens: Encrypted card references (not raw card data)
    6.
    CVV: Never stored, required for each card transaction
    7.
    3DS: Required for most card transactions (PSD2 compliance)
    Built with