# Overview


ViaBlocks API Outbound is a secure, server-to-server REST API that enables regulated partners to create, manage, and track **outbound cross-border money transfers from the United States to international destinations** through the Viamericas network. The API supports the full outbound transaction lifecycle, including U.S.-based sender onboarding, international beneficiary onboarding, transaction creation, funding initiation, foreign exchange (FX) handling, payout execution, and end-to-end status monitoring. Partners interact with the platform through two primary endpoints: POST /transaction/create, used to submit sender, beneficiary, and transfer details to initiate an outbound transaction, and POST /transaction/status, used to retrieve the most recent processing status and lifecycle updates for an existing transaction. This API is designed for licensed and compliant U.S. partners and abstracts regulatory, compliance, routing, and payout complexities, allowing integrators to focus on building scalable international money transfer experiences. Version: 1.0.0 ## Servers Sandbox environment ``` https://sandbox-viablocks.viamericas.io ``` ## Download OpenAPI description [Overview](https://docs2-viablocks.viamericas.io/_bundle/apis/outbound.yaml) ## Transaction This section provides the **Transaction** endpoints required to manage and operate the full lifecycle of resources within the ViaBlocks platform.
These endpoints are designed for secure, auditable, and scalable server-to-server integrations, and support core business operations and compliance workflows. ### /transaction/create - [POST /transaction/create](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1create/post.md): ## Purpose Creates a new outbound cross-border money transfer and registers it in the ViaBlocks platform. This request defines the sender, beneficiary, transaction details (amounts, currencies, destination), and the selected funding method. ## When to use Use this endpoint to initiate a new transaction when you are ready to submit: - Sender onboarding details (KYC/AML fields) - Beneficiary details and payout configuration - Origination and delivery amounts/currencies - Funding configuration (cash or remote payment) ## What happens next Next steps depend on the funding method: - Cash funding: Transaction may proceed directly into processing (partner-dependent). - Remote payment funding: Transaction is created in a pending funding state. The sender must complete payment remotely and the transaction will not proceed until funding and risk/compliance review are completed. ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - Request validation is enforced for formats, allowed values, corridor rules, and compliance requirements. - For the remote payment flow, refer to: ../guides/remotepayment.md ## Common errors - 400 Validation errors (missing/invalid fields) - 401 Invalid credentials - 404 Sender/beneficiary linkage issues (when applicable) - 422 Business-rule rejection (e.g., credit limit) - 500 Internal error ### /transaction/status - [GET /transaction/status](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1status/get.md): ## Purpose Retrieves the latest status and processing details for a previously created transaction. ## When to use Use this endpoint to: - Poll for lifecycle updates (funding confirmation, compliance holds, payout progression) - Display current transaction state in your UI or partner system - Retrieve hold reasons and required documents (when applicable) ## Authentication Requires x-client-id and x-secret-key headers. ## How to identify the transaction Provide the uuid query parameter. The uuid is returned by /transaction/create. ## Notes - Responses may include holds and requiredDocumentList when compliance or operational review is required. - Status values reflect internal processing and payout execution steps. ## Common errors - 400 Missing/invalid uuid - 401 Invalid credentials - 404 Transaction not found - 500 Internal error ## Catalogs

This section provides the **Catalogs** endpoints required to retrieve reference and configuration data necessary to construct and validate outbound money transfer transactions within the ViaBlocks platform.
Catalog endpoints expose corridor-specific operational data including supported countries, currencies, delivery methods, payout networks, payout locations, identification document types, industries, remittance purposes, and source-of-funds classifications.
These endpoints are read-only and must be consumed prior to transaction creation to ensure:

Partners should not hardcode catalog values and should instead retrieve them programmatically to maintain synchronization with configuration updates, compliance changes, and corridor availability.

### /catalogs/master/location - [GET /catalogs/master/location](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1master~1location/get.md): ## Purpose Searches master location data (city/state/country) using a partial filter value. Results are normalized to ViaBlocks field naming conventions. ## When to use Use this endpoint to: - Support UI search/type-ahead for location entry - Normalize and validate user-entered location data before transaction creation ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - Input is provided via the filterValue query parameter. - Results may contain multiple matches for the same city name across different states/countries. ## Common errors - 400 Validation errors (missing/invalid filterValue) - 401 Invalid credentials - 404 No matches found (when applicable) - 500 Internal error ### /catalogs/master/zipcodes/{idzipcode} - [GET /catalogs/master/zipcodes/{idzipcode}](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1master~1zipcodes~1%7Bidzipcode%7D/get.md): ## Purpose Retrieves ZIP code metadata including city name, state ISO code, and full state name. ## When to use Use this endpoint to: - Auto-populate city/state after ZIP entry - Validate sender address data prior to transaction creation ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - idzipcode is provided as a path parameter. ## Common errors - 400 Validation errors - 401 Invalid credentials - 404 ZIP code not found (when applicable) - 500 Internal error ### /catalogs/google-maps-api - [POST /catalogs/google-maps-api](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1google-maps-api/post.md): ## Purpose Proxy endpoint for Google Maps operations used for: - Address autocomplete (suggestions) - Geocoding (structured address and coordinates) ## When to use Use this endpoint when you need: - Type-ahead address suggestions for sender/beneficiary addresses - Normalized geocoding results including latitude/longitude ## Authentication Requires x-client-id and x-secret-key headers. ## Request behavior - event=autocomplete returns an array of suggestion objects - event=geocode returns an array of geocoding result objects (including geometry) ## Notes - Response structure depends on the event. - The response is returned as an array (no wrapper object). ## Common errors - 400 Validation errors (missing/invalid address or event) - 401 Invalid credentials - 500 Internal error ### /catalogs/countries/{idCountry}/currencies - [GET /catalogs/countries/{idCountry}/currencies](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1currencies/get.md): ## Purpose Returns the list of supported currencies for the specified country. ## When to use Use this endpoint to: - Populate currency selection options - Validate corridor currency support before transaction creation ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - idCountry is an ISO3 country code (e.g., USA, MEX, COL). ## Common errors - 400 Validation errors - 401 Invalid credentials - 404 Country not found (when applicable) - 500 Internal error ### /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts - [GET /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1deliver-methods~1%7Biddelivery%7D~1payouts/get.md): ## Purpose Returns the available payout methods for a destination country and delivery method. ## When to use Use this endpoint to: - Populate payout provider lists (banks, networks, wallet providers) - Retrieve corridor constraints (min/max, fee, exchange rate) - Validate account formats using the provided accNumberRegex (when present) ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - idCountry is an ISO3 country code. - idDelivery represents the delivery method (e.g., bank deposit vs cash pickup; see your configured codes). - The response may include validation helpers like accNumberRegex. ## Common errors - 400 Validation errors - 401 Invalid credentials - 404 Configuration not found (when applicable) - 500 Internal error ### /catalogs/countries/{idCountry}/identifications - [GET /catalogs/countries/{idCountry}/identifications](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1identifications/get.md): ## Purpose Returns the supported identification document types for the specified country. ## When to use Use this endpoint to: - Populate document type selection during onboarding - Enforce corridor-specific document requirements (expiration date, back side) ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - Response includes flags such as expirationDateRequired and backSideRequired. ## Common errors - 400 Validation errors - 401 Invalid credentials - 404 Country not found (when applicable) - 500 Internal error ### /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts/{idpayout}/locations - [GET /catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts/{idpayout}/locations](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bidcountry%7D~1deliver-methods~1%7Biddelivery%7D~1payouts~1%7Bidpayout%7D~1locations/get.md): ## Purpose Returns the available physical payout locations (branches/agents) for a selected payout method. ## When to use Use this endpoint to: - Populate branch/location selection for cash pickup flows - Display branch details including address, business hours, and pickup instructions ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - Requires idCountry, idDelivery, and idpayout. - Response may include fields such as WhatToBring and BusinessHours for customer guidance. ## Common errors - 400 Validation errors - 401 Invalid credentials - 404 Locations not found (when applicable) - 500 Internal error ### /catalogs/industry - [GET /catalogs/industry](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1industry/get.md): ## Purpose Returns the supported industry categories and associated job titles used for onboarding and compliance classification. ## When to use Use this endpoint to: - Populate industry/job selection lists - Standardize occupation classification for KYC/AML and reporting ## Authentication Requires x-client-id and x-secret-key headers. ## Common errors - 401 Invalid credentials - 500 Internal error ### /catalogs/wire-purpose - [GET /catalogs/wire-purpose](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1wire-purpose/get.md): ## Purpose Returns the supported remittance purposes (reason for transfer) used for compliance classification and reporting. ## When to use Use this endpoint to: - Populate “purpose of transfer” selections - Standardize purpose codes for corridor rules and regulatory reporting ## Authentication Requires x-client-id and x-secret-key headers. ## Common errors - 401 Invalid credentials - 500 Internal error ### /catalogs/funds-origin - [GET /catalogs/funds-origin](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1funds-origin/get.md): ## Purpose Returns supported source-of-funds options used for compliance and risk classification. ## When to use Use this endpoint to: - Populate “source of funds” selections during onboarding - Standardize source-of-funds values for compliance workflows and reporting ## Authentication Requires x-client-id and x-secret-key headers. ## Notes - Response includes an order field that can be used to sort options in UI. ## Common errors - 401 Invalid credentials - 500 Internal error