Payments

This guide walks through each stage of a payment: creating an intent, launching the SDK, processing, and receiving the result.

Payment flow overview

A payment follows four stages:

1. Create a payment intent — Your backend creates an intent via the API and receives a clientSecretKey.
2. Launch the SDK — Pass the clientSecretKey to the Vivamo SDK on your frontend. The SDK renders the payment form, collects payment details, and handles customer verification.
3. Processing — Vivamo routes the transaction to the appropriate processor, applies any surcharges, and processes the payment.
4. Result — You receive the outcome via webhook, SDK event listener, or by polling the intent status.

Step 1: Create a payment intent

Use the Create Payment Intent endpoint from your backend to set up the customer and amount for the transaction.

The response includes:

• clientSecretKey — Pass this to the SDK on your frontend. It authenticates the SDK session for this specific intent.
• expirationTime — The intent expires 2 hours after creation. After this, the customer can no longer submit a payment and you must create a new intent.
• clientSecretKeyValidTill — The authentication window for the client secret (24 hours). In practice, the 2-hour intent expiration is the effective limit.

Step 2: Launch the SDK

Pass the clientSecretKey to the Vivamo SDK on your frontend. The SDK handles the payment form, payment method selection, and any required customer verification. See the Vivamo SDK guide for setup instructions.

Step 3: Processing

Once the customer submits, Vivamo routes the transaction to the appropriate processor based on your configuration, the payment method, and the customer's location. Surcharges and sales tax, if enabled, are calculated and applied automatically.

Step 4: Receive the result

You can receive the payment outcome in several ways:

SDK event listeners

Listen for events emitted by the SDK to respond in your frontend:

Webhooks (recommended)

Vivamo sends a webhook to your registered URL when the payment status changes. This is the most reliable method, especially for asynchronous payment methods like bank transfers. See the Webhooks guide for authentication and payload details.

Polling

You can poll the payment intent status via the Get Payment Intent Status endpoint. This works but adds unnecessary request overhead compared to webhooks.

Payment statuses

Payments move through the following statuses:

Supported payment methods

The available payment methods depend on your operator configuration. Vivamo supports:

• Card: credit and debit card payments, processed synchronously.
• Bank (ACH): standard bank transfers, processed asynchronously.
• Pay By Bank: instant ACH payments via bank linking, processed asynchronously.
• Crypto: cryptocurrency payments.

Amount format

The amount field should be a string in dollars and cents (e.g. "100.00", "9.99"). Amounts are stored and returned as strings throughout the API to avoid floating-point precision issues.

Key considerations

• Payment intents expire after 2 hours. If a payment is not completed in time, create a new intent.
• The externalPaymentIntentId field is for your own reference and is not enforced as unique. Submitting the same ID twice creates two separate intents. Use your own deduplication logic if needed.
• Processing fees vary by payment method and processor.
• Customers can save their payment method for faster checkout in future transactions.
• Bank and Pay By Bank payments may take longer to settle. Use webhooks to track the final outcome rather than relying on the immediate API response.
• See the Error Handling guide for error responses and status codes.