Skip to content
Last updated

Integration Fundamentals




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.

Each request must include:

  • client_id: The partner identifier assigned by Viamericas.
  • secret_key: The shared secret used to authenticate requests.

Credentials are included in the request body to support:

  • Controlled payload validation.
  • Uniform authentication handling across channels.
  • Compatibility with partner infrastructure constraints.

Authentication is mandatory 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.
 
Next page