Payment Flow

Understanding how payments flow through the Inkress system from customer checkout to merchant payout.

Payment Lifecycle Overview

Every payment in Inkress goes through a series of stages from creation to settlement. Understanding this flow helps you integrate properly and handle edge cases.

Link Creation

Merchant creates a payment link

Customer Visit

Customer visits the payment page

Payment Attempt

Customer enters payment details

Authorization

Payment provider authorizes the transaction

Capture

Funds are captured and confirmed

Settlement

Funds are available for payout

Detailed Flow

Payment Link Creation

The merchant creates a payment link via the dashboard or API, specifying the amount, currency, description, and optional parameters like expiration date or product details.

Create Payment Linktypescript

1const response = await admin.paymentLink.create({
2  title: "Premium Subscription",
3  total: 9900,
4  currency_code: "JMD",
5  description: "Monthly premium plan",
6  expires_at: "2024-12-31T23:59:59Z",
7  redirect_url: "https://yoursite.com/success"
8});
9
10// Payment link is created with status: active
11// Generates unique UID for sharing: pl_abc123xyz

Event triggered: No webhook event at this stage. The link is ready to share.

Customer Visit

The customer clicks on the payment link and lands on the Inkress checkout page. The page displays the payment amount, description, and available payment methods.

What happens:

Payment link visit counter increments
Session is created to track the customer's journey
Available payment methods are displayed based on merchant configuration
Customer information form is shown (if required)

Event triggered: payment_link.visited (optional analytics event)

Payment Attempt

The customer enters their payment information (card details, bank transfer info, etc.) and submits the payment.

An order is created with:

Order ID and reference number
Customer information (email, name, phone)
Payment amount and currency
Status: pending
Link to the payment link

Event triggered: order.created

Payment Authorization

The payment details are sent to the payment provider (card processor, bank, etc.) for authorization. The provider verifies the payment method and places a hold on the funds.

Possible outcomes:

✓ Authorized

Payment method is valid, funds are available, and authorization is approved. Proceeds to capture stage.

⏳ Pending

Some payment methods (bank transfers, ACH) require manual confirmation. Order status: pending_payment.

✗ Declined

Payment declined due to insufficient funds, expired card, fraud detection, or other issues. Customer can retry with different payment method.

Event triggered: payment.pending or payment.failed

Payment Capture

After successful authorization, the payment is captured - meaning the funds are actually transferred from the customer's account.

What happens:

Transaction record is created with status: completed
Order status is updated to: paid
Payment link payment counter increments
Customer receives confirmation (if email is provided)
Merchant is notified of successful payment

Event triggered: payment.success

Timing: For card payments, capture is typically instant. For bank transfers, it may take 1-3 business days.

Settlement & Balance Update

After fees are deducted, the net amount is added to the merchant's available balance. The merchant can then request a payout.

Fee Calculation

1Payment Amount:        JMD 10,000
2Transaction Fee (2%):  JMD   -200
3Platform Fee:          JMD   -100
4────────────────────────────────
5Net to Merchant:       JMD 9,700

Availability

Depending on the merchant's plan and the payment method, funds may be available:

Instantly: For card payments on premium plans
1 business day: For standard card payments
3-5 business days: For bank transfers and ACH

Balance updated: available_payout_balance increases by net amount

Payment Methods Timeline

Different payment methods have different processing times:

Credit/Debit Cards

Instant

Authorization: < 1 second
Capture: Instant
Settlement: 1-2 business days
Payout availability: 1-7 days (plan dependent)

Bank Transfer (ACH)

2-3 Days

Authorization: Instant
Capture: 2-3 business days
Settlement: After capture
Payout availability: 3-7 days after capture

Digital Wallets

Instant

Authorization: < 1 second
Capture: Instant
Settlement: 1 business day
Payout availability: 1-2 days

Edge Cases & Special Scenarios

Failed Payments

If a payment fails after authorization (rare, but possible due to fraud detection or technical issues), the order is marked as failed and the customer can retry. No funds are captured.

Refunds

Merchants can issue full or partial refunds through the dashboard. Refunds are processed back to the original payment method within 5-10 business days. The refunded amount is deducted from the merchant's balance.

Chargebacks

If a customer disputes a charge with their bank, the payment enters chargeback status. Merchants are notified and can provide evidence to contest the chargeback. If the chargeback is upheld, funds are deducted from the merchant's balance.

Expired Payment Links

Payment links with expiration dates automatically become inactive after the expiration time. Customers attempting to pay receive an error message. The merchant can reactivate or create a new link.

Payment Link Quantity Limits

Payment links with quantity limits automatically deactivate after the specified number of successful payments. This is useful for limited inventory or ticket sales.

Integration Points

Where your application hooks into the payment flow:

1. Payment Link Creation

Use the API to programmatically create payment links when users checkout on your site.

2. Redirect URL

Specify where customers return after successful payment. Include order data in query params.

3. Webhook Handlers

Listen for payment.success, payment.failed, and order.created events to update your system in real-time.

4. Order Status Polling

For pending payments, periodically check order status via the API until completion.

← Webhook Security Currencies →