# Integration Fundamentals br div img br br ViaBlocks is a modular, secure, and scalable platform that enable regulated partners to build and operate money transfer experiences through APIs and embeddable components. The platform provides a structured and auditable transaction flow composed of multiple functional blocks that cover the full lifecycle of a money transfer: authentication, sender onboarding, beneficiary management, funding, transaction creation, compliance validation, payout execution, and status tracking. ViaBlocks supports two primary money transfer flows: - **Inbound Transactions**: Transfers from international locations to the United States (World → USA). - **Outbound Transactions**: Transfers from the United States to international destinations (USA → World). This documentation describes how partners can integrate with the ViaBlocks platform using secure server-to-server APIs. ## Intended Audience This documentation is intended for: - Partner engineering teams integrating ViaBlocks API (inbound) into payment systems. - Backend developers building transaction creation and status tracking flows. - Technical architects responsible for end-to-end money movement and operational workflows. - Compliance and risk teams validating required fields, holds, and document requirements. - Integration and platform teams building embedded or white-label financial experiences. A strong understanding of REST APIs, JSON, and secure authentication mechanisms is assumed. ## Platform Overview ViaBlocks is designed around a **block-based transaction model**, where each block represents a functional step in the transaction lifecycle: - Authentication - Sender Profile - Beneficiary Profile - Funding Profile - Transaction Setup - Checkout and KYC - Transaction Status - Administrative and Backoffice Operations Depending on the integration model and the information already available, some blocks may be skipped or pre-filled using secure tokens. ViaBlocks can be used in multiple integration modes, including: - Fully embedded user experiences (Plaid-style widget). - Partner-hosted flows. - API-only server-to-server integrations. - White-label deployments. ## Before You Begin Before starting your integration, make sure you have: - Access to the sandbox environment. - Reviewed the Quickstart Guide. - Defined your integration model (API-only, embedded, or hybrid). ## Environments Viamericas provides two separate environments to its originators: ### Sandbox The sandbox environment is intended for development and integration testing. ⚠️**Important characteristics:** - Data in sandbox is **not persistent**. - Behavior may change **without notice**. - Transactions are simulated and do not represent real fund movement. - Some integrations (banks, payout networks, KYC providers) may be mocked or partially simulated. The sandbox environment should be used to: - Develop and test integrations. - Validate payload formats and business rules. - Perform certification and end-to-end flow testing. ``` https://sandbox-viablocks.viamericas.io ``` ### Production The production environment processes live transactions and includes all security, monitoring, and compliance controls. ⚠️**Important characteristics:** - Transactions represent real financial operations. - All compliance, KYC, AML, and risk controls are enforced. - Monitoring, auditing, and operational controls are enabled. - Access is restricted and requires prior approval. Access to production is granted only after successful sandbox certification and approval by Viamericas. ``` https://viablocks.viamericas.net ``` Separate access will be provided to each environment, including separate base URLs and access keys. ## Models ### Integration ViaBlocks supports multiple integration approaches: - **API-only**: Partners fully manage their own UI and call ViaBlocks APIs server-to-server. - **Embedded UI**: Partners embed ViaBlocks components into their applications. - **Hybrid**: A combination of embedded components and direct API usage. - **White-label**: A full partner-branded experience powered by ViaBlocks. Your Viamericas integration team will help determine the best approach for your use case. ### Authentication ViaBlocks uses a partner-based authentication model for server-to-server communication. All requests must include the following headers: - `x-client-id`: The partner identifier assigned by Viamericas. - `x-secret-key`: The shared secret used to authenticate the request. These credentials are sent in the request headers to ensure: - Consistent authentication across all integrations. - Alignment with secure API communication standards. - Improved compatibility with server-to-server implementations. Authentication is required for all API endpoints. ### Transaction ViaBlocks supports a unified transaction model for both inbound and outbound flows. Each transaction: - Is uniquely identified by a `uuid`. - Goes through multiple processing stages (validation, compliance, funding, routing, payout, settlement). - Can be tracked in real time using the status endpoints. - May be temporarily placed on hold due to compliance or operational reviews. The same API model is used for: - Inbound transactions (World → USA). - Outbound transactions (USA → World). ## Security Best Practices - Never expose `client_id` or `secret_key` in client-side applications. - Restrict API access by IP where possible- **Use HTTPS exclusively**. - Store credentials securely using secret managers or encrypted configuration stores. - Rotate secrets periodically according to your internal security policies. - Restrict API access by IP address whenever possible. - Never log sensitive information such as secrets, tokens, or full personal data. - Validate and sanitize all input data before sending it to the API. Failure to follow these practices may result in integration suspension. ## Next Steps To get up and running quickly, proceed to: **Quickstart Guide** This guide will walk you through: 1. Creating your first transaction. 2. Submitting the required data. 3. Retrieving the transaction status. 4. Understanding the basic transaction lifecycle.