Introduction

Welcome to the integration guide for Vivamo, a multi-payment gateway platform. Our suite of APIs is designed to seamlessly integrate various payment gateways into your application, offering a unified platform for processing payments across multiple providers and payment types. Whether you're looking to support credit cards, digital wallets, or alternative payment methods, our APIs provide the flexibility and security necessary to manage transactions efficiently and reliably.

Quick Start

Contact [email protected] to get your account setup and API Credentials (or if you need help at any point!).
Learn about how the API is authenticated.
Get Vivamo into your product by first adding Customers.
Start making payments and disbursements through the Vivamo API and SDK.
Check out the full API reference here: https://documenter.getpostman.com/view/36924290/2sA3e4ApJA

Vivamo Key Features

Unified API Interface: Integrate with multiple payment gateways through a single API, reducing complexity and development time.
Multi-Currency Support: Process payments in various currencies, making it easier to operate in global markets.
Advanced Security: Industry-standard encryption and compliance protecting sensitive payment and customer information.
Real-Time Transaction Management: Monitor and manage transactions in real-time, with detailed reporting and analytics.
Extensibility: Easily add new payment providers as your business grows, without overhauling your existing integration.

Who Should Use This API?

This API is ideal for developers and businesses looking to integrate a robust and flexible payment processing solution into their web or mobile applications. Whether you're building an e-commerce platform, a subscription-based service, or any application that requires payment processing, our API provides the tools you need to manage payments across multiple gateways efficiently.

Support

To begin using our API, you will need to chat with our team to configure desired payment options, before obtaining an API key.

<aside> ❓ To get in touch with Vivamo team for any reason, please contact: [email protected], or check with our team for a shared Slack channel.

</aside>

Environment Setup: Production vs. Testing (Sandbox)

We provide separate environments for development/testing and production. This ensures that you can build and test your integration before going live. Below, we explain the differences between these environments, including the API hostnames and best practices for switching between them.

1. Production Environment

The Production Environment is where real transactions are processed. This environment is fully secure, compliant with industry standards, and should only be used once your integration has been thoroughly tested and approved.

API Hostname: https://api.vivamo.co/v1
Usage: Handle live transactions with real money and data.
SSL/TLS: Mandatory; all requests must be encrypted.
Best Practices:
- Always use HTTPS for secure communication (only https is supported).
- Ensure all API keys and sensitive data are stored securely.
- 🚧 Regularly monitor your transaction logs and error reports COMING SOON
- 🚧 Implement rate limiting and retry logic to handle potential API throttling COMING SOON

2. Testing/Sandbox Environment

The Testing/Sandbox Environment is designed for development and testing purposes. It allows you to simulate transactions without processing real payments, providing a safe space to validate your integration.

API Hostname: https://api.test.vivamo.co/v1
Usage: Simulate transactions, test error handling, and verify API behaviour.
SSL/TLS: Mandatory; all requests must be encrypted.
Best Practices:
- Test all possible transaction scenarios, including successful payments, failures, and edge cases.
- Validate that your integration correctly handles all API responses and errors.
- Use mock data that mimics real customer data, but avoid using any actual sensitive information.
- Frequently reset and refresh your testing environment to prevent stale data from affecting your tests.

3. Switching Between Environments

To switch between the Production and Testing/Sandbox environments, you will need to update the API hostname in your application's configuration. Make sure that you also use the appropriate API keys for each environment, as these will differ.

Production to Testing: Update your API requests from https://api.vivamo.co/v1 to https://api.test.vivamo.co/v1.
Testing to Production: Ensure all test cases pass, then update your API requests back to https://api.vivamo.co/v1.

Please note, when initialising the SDK, the environment can be specified using a configuration object. If no environment is specified, Vivamo will default to production.

// Setting up the test environment

const vivamo = Vivamo(
  "pk_test_yourapikey",
  { environment: "test" }
);

4. Environment-Specific Considerations

API Keys: Each environment requires a separate set of API keys. Ensure that these are managed securely and never hard-coded in your application.
Webhook URLs: If using webhooks, make sure to configure different endpoints for each environment to avoid mixing test data with production data.
🚧 Rate Limits COMING SOON: Be aware that rate limits may be more lenient in the sandbox environment compared to production. Plan accordingly when testing under load.

5. Testing Scenarios

To ensure your integration is robust, consider testing the following scenarios in the Sandbox environment:

Successful Payments: Process payments with various amounts and currencies.
Failed Payments: Simulate declined transactions, insufficient funds, and various failure reasons (e.g. AVS and more).
Edge Cases: Test scenarios such as duplicate transactions, incorrect payment details, and timeouts.

🚧 Versioning and Release Notes COMING SOON

Versioning

To ensure a smooth integration and long-term compatibility with our Vivamo Multi-Payment Gateway Solution, we follow a structured versioning approach. Each version of the API is carefully managed to maintain backward compatibility where possible and to introduce new features and improvements in a controlled manner.

API Versioning: Each release of our API is tagged with a version number (e.g., v1, v2), which reflects major updates or changes. This versioning helps you manage dependencies and ensure that your application continues to function as expected when updates are made.
Version Updates: Major version updates may introduce breaking changes, while minor updates typically include backward-compatible improvements and bug fixes.

Release Notes

To keep you informed of the latest changes, enhancements, and bug fixes, we will be providing detailed release notes with each new version of the API. These notes will include:

New Features: Descriptions of new functionality added to the API.
Improvements: Enhancements to existing features or performance optimisations.
Bug Fixes: Details of resolved issues or security patches.
Breaking Changes: We will endeavour to provide as much collaboration, warning and detail about upcoming changes that may require modifications to your existing integration.

Deprecated versions: