Understanding Transactions

Transaction Flow

1. Create Transaction

Initialize a payment transaction by submitting payment details to the API:

What happens:

• Your server sends a POST request to https://api.paysecurez.com/api/v1/transactions with payment details
• ZepoPay validates the request and creates a transaction record
• You receive a unique transaction ID and initial status
• A checkout URL is provided for the customer to complete payment

Response Fields:

• transactionId - Unique transaction identifier (store this for future reference)
• reference - Your custom reference/order ID
• currency - Payment currency code (e.g., AUD, USD)
• amount - Transaction amount
• status - Initial transaction status (typically "Pending")
• message - Human-readable status message
• checkoutUrl - Payment page URL where customer completes payment
• supportsIframe - Whether the checkout can be embedded in an iframe

2. Process Payment

Complete the payment through the appropriate channel:

For redirect-based flows (e.g., bank transfers, e-wallets):

• Redirect the customer to the checkoutUrl provided in the response
• Customer completes payment on the payment processor's page
• Customer is redirected back to your successUrl after completion

For API-based flows:

• Payment is processed directly through the API call
• No customer redirect required
• Immediate response with payment result

3. Monitor Status

Track the transaction status through webhook notifications:

Webhook notifications:

• Receive real-time HTTP POST requests to your webhook endpoint
• Triggered on every transaction status change
• Contains complete transaction data in webhook format
• Verify webhook signatures for security

API status checks:

• Use GET https://api.paysecurez.com/api/v1/transactions/{txNo}/status to check current status
• Do not poll these endpoint - rely on webhooks for production use

4. Handle Completion

Process the final transaction outcome:

On Success (Captured):

• Fulfill the order/service to the customer
• Send confirmation email
• Update your internal order management system
• Store transaction details for reconciliation

On Failure/Decline:

• Display appropriate error message to the customer
• Offer alternative payment methods
• Log the failure reason for support purposes
• Allow customer to retry if appropriate

On Pending:

• Display "processing" status to customer
• Wait for webhook notification with final status
• Don't fulfill order until status is "Captured"

Transaction States

Status	Description
PENDING	Transaction initiated
PROCESSING	Payment in progress
COMPLETED	Payment successful
FAILED	Payment failed
CANCELLED	User cancelled
DECLINED	Card/payment declined
REFUNDED	Payment refunded

Best Practices

1. Always Store the Transaction ID

• Store transactionId immediately after creating a transaction
• Required for status checks, refunds, and customer support
• Use as primary reference in webhook processing

2. Implement Webhook Handling

• Set up HTTPS endpoint and respond with HTTP 200 within 30 seconds
• Process asynchronously and handle duplicate notifications
• Validate signatures and log all payloads

3. Use Idempotency Keys

• Generate unique key (UUID) for each transaction attempt
• Include in request to prevent duplicate transactions on retry
• Store keys with your order records

4. Handle Timeouts Gracefully

• Set 30-60 second timeouts for API requests
• Don't assume timeout = failure; check status with GET endpoint

5. Implement Proper Error Handling

• Display user-friendly messages, not technical codes
• Log detailed errors for debugging
• Provide fallback payment options