# 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. - **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) ## Beneficiary - [POST /beneficiary](https://docs2-viablocks.viamericas.io/apis/outbound/beneficiary/paths/~1beneficiary/post.md): Creates a new beneficiary (recipient) associated with a sender. ## Purpose Registers a new beneficiary in the system, linking them to a sender. If a beneficiary with the same full name already exists - [GET /beneficiary](https://docs2-viablocks.viamericas.io/apis/outbound/beneficiary/paths/~1beneficiary/get.md): Retrieves a beneficiary by its UUID. ## Purpose Returns the details of a specific beneficiary. Optionally validates that the beneficiary belongs to a given sender. ## Query Parameters - `uuid` (requir - [PUT /beneficiary](https://docs2-viablocks.viamericas.io/apis/outbound/beneficiary/paths/~1beneficiary/put.md): Updates an existing beneficiary's information. ## Purpose Allows modification of a beneficiary's personal details, contact information, and address. Only fields included in the request will be updated ## Catalogs - [GET /catalogs/account-types](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1account-types/get.md): ## Purpose Returns the list of available bank account types (e.g., Checking, Savings) used for bank deposit delivery methods. ## When to Use Use this endpoint when you need to: - Populate account type - [GET /catalogs/all-endpoints](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1all-endpoints/get.md) - [GET /catalogs/countries](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries/get.md): ## Purpose Returns the list of available destination countries for outbound transactions. Each country includes its ISO 3166-1 alpha-3 code and name. ## When to Use Use this endpoint when you need to: - [GET /catalogs/countries/{deliveryCountryISO}/currencies](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1currencies/get.md): ## Purpose Returns the list of available currencies for a specific destination country. Used to determine which currencies are supported for delivery. ## When to Use Use this endpoint when you need to - [GET /catalogs/countries/{deliveryCountryISO}/deliver-methods](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1deliver-methods/get.md): ## Purpose Returns the list of available delivery methods for a specific destination country (e.g., bank deposit, cash pickup, mobile wallet, home delivery). ## When to Use Use this endpoint when you - [GET /catalogs/countries/{deliveryCountryISO}/deliver-methods/{deliveryMode}/payers](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1deliver-methods~1%7Bdeliverymode%7D~1payers/get.md): ## Purpose Returns the payout locations (payers) available for a delivery method in a destination country, together with their real exchange-rate tiers and transaction limits. Unlike `payouts`, which - [GET /catalogs/countries/{deliveryCountryISO}/deliver-methods/{deliveryMode}/payers-rules](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1deliver-methods~1%7Bdeliverymode%7D~1payers-rules/get.md): ## Purpose Returns the dynamic field rules and validation requirements for a specific delivery method and payer in a destination country. Defines which fields are required, optional, or hidden when co - [GET /catalogs/countries/{deliveryCountryISO}/deliver-methods/{deliveryMode}/payouts](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1deliver-methods~1%7Bdeliverymode%7D~1payouts/get.md): ## Purpose Returns the list of available payout networks/agents for a specific delivery method in a destination country. These represent the payment networks or institutions where the recipient can co - [GET /catalogs/countries/{deliveryCountryISO}/deliver-methods/{deliveryMode}/payouts/{deliveryLocationNetwork}/locations](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1deliver-methods~1%7Bdeliverymode%7D~1payouts~1%7Bdeliverylocationnetwork%7D~1locations/get.md): Retrieves payout location details for a specific delivery network in a country and delivery mode. ## Purpose Returns the list of physical locations (branches, agents) where the beneficiary can pick up - [GET /catalogs/countries/{deliveryCountryISO}/identifications](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1identifications/get.md): ## Purpose Returns the list of accepted identification document types for a specific destination country. Used to determine which ID types are valid for sender or recipient verification. ## When to Us - [GET /catalogs/countries/{deliveryCountryISO}/states](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1states/get.md): ## Purpose Returns the list of states/provinces for a specific destination country, using ISO 3166-2 codes as identifiers. ## When to Use Use this endpoint when you need to: - Populate a state/provinc - [GET /catalogs/countries/{deliveryCountryISO}/states/{addressState}/cities](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1countries~1%7Bdeliverycountryiso%7D~1states~1%7Baddressstate%7D~1cities/get.md): ## Purpose Returns the list of cities for a specific state/province within a destination country. ## When to Use Use this endpoint when you need to: - Populate a city selector after the user selects a - [GET /catalogs/funds-origin](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1funds-origin/get.md): ## Purpose Returns the list of available funds origin/source options for remittance transactions. These describe where the sender's money comes from. ## When to Use Use this endpoint when you need to: - [POST /catalogs/google-maps-api](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1google-maps-api/post.md): ## Purpose Provides Google Maps API integration for address autocomplete and geocoding. Proxies requests to Google Maps services through ViaBlocks authentication. ## When to Use Use this endpoint when - [GET /catalogs/industry](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1industry/get.md): ## Purpose Returns the list of industries and occupations available for sender profile information. Used for compliance and KYC data collection. ## When to Use Use this endpoint when you need to: - Po - [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 when you need - [GET /catalogs/master/zipcodes/{addressZipCode}](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1master~1zipcodes~1%7Baddresszipcode%7D/get.md): ## Purpose Looks up location information (city, state) for a given ZIP/postal code. Returns normalized address data associated with the provided zipcode. ## When to Use Use this endpoint when you need - [GET /catalogs/recipients/relationships](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1recipients~1relationships/get.md): ## Purpose Returns the list of available relationship types between sender and recipient. Used for compliance and KYC data collection. ## When to Use Use this endpoint when you need to: - Populate rel - [GET /catalogs/transaction/cancel-reasons](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1transaction~1cancel-reasons/get.md): ## Purpose Returns the list of available cancellation reasons for transactions. These reasons are required when cancelling a transaction via `DELETE /transaction/cancel`. ## When to Use Use this endpo - [GET /catalogs/wire-purpose](https://docs2-viablocks.viamericas.io/apis/outbound/catalogs/paths/~1catalogs~1wire-purpose/get.md): ## Purpose Returns the list of available remittance purpose codes. These describe the reason for the money transfer. ## When to Use Use this endpoint when you need to: - Populate wire/remittance purpo ## Pricing - [GET /pricing/payers](https://docs2-viablocks.viamericas.io/apis/outbound/pricing/paths/~1pricing~1payers/get.md): ## Purpose Retrieves available payers with their exchange rates and transaction limits for a given destination country and branch. ## When to Use - Display available payout options and pricing to cust - [GET /pricing/top-countries](https://docs2-viablocks.viamericas.io/apis/outbound/pricing/paths/~1pricing~1top-countries/get.md): ## Purpose Returns the top countries with the best exchange rates and the payer that offers them for a given branch. ## When to Use - Display optimal sending destinations based on best available rates ## Sender - [POST /sender/id-upload](https://docs2-viablocks.viamericas.io/apis/outbound/sender/paths/~1sender~1id-upload/post.md): ## Purpose Upload sender identification document images (front and optionally back) for KYC processing. ## When to Use Use this endpoint when you need to: - Upload the sender's ID document image after - [GET /sender](https://docs2-viablocks.viamericas.io/apis/outbound/sender/paths/~1sender/get.md): Retrieves a sender's full profile by UUID. ## Purpose Returns the complete profile of an existing sender, including personal, contact, address, identification, compliance (KYC) information, and all up - [GET /sender/search](https://docs2-viablocks.viamericas.io/apis/outbound/sender/paths/~1sender~1search/get.md): Searches for senders by name or phone number. ## Purpose Allows searching for existing senders in the system to retrieve their profile information. Useful for finding a sender before creating a transa ## Service - [POST /service/account/verify](https://docs2-viablocks.viamericas.io/apis/outbound/service/paths/~1service~1account~1verify/post.md): Verifies the validity and status of a bank account number. ## Purpose Validates that a bank account is open, active, and in good standing before initiating a payment or transaction. ## When to use - B - [POST /service/routing/verify](https://docs2-viablocks.viamericas.io/apis/outbound/service/paths/~1service~1routing~1verify/post.md): Verifies a bank routing number and optionally verifies an associated account. ## Purpose Validates a routing number structure (ABA checksum), retrieves bank details and supported payment networks (ACH ## Transaction - [DELETE /transaction/cancel](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1cancel/delete.md): ## Purpose Cancels a pending transaction. Uses the Strategy pattern to apply different validation rules based on transaction type (Outbound vs Inbound). ## Transaction Types ### Outbound (branch start - [POST /transaction/confirm](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1confirm/post.md): Confirms a previously created transaction and finalizes it for processing. ## Purpose Confirms a transaction that was created with a funding type that requires explicit confirmation (e.g., cash, debit - [POST /transaction/create](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1create/post.md): Creates a new money transfer and registers it in the ViaBlocks platform. Supports both **cross-border** (international) and **domestic** (USA to USA) corridors. ## Purpose Initiates a new remittance t - [POST /transaction/quote](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1quote/post.md): ## Purpose Retrieve a real-time pricing quote for a remittance transaction before committing to the actual transfer. This endpoint calculates exchange rates, fees, and total amounts based on the reque - [GET /transaction/receipt](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1receipt/get.md): Generates and retrieves the receipt for a completed transaction. ## Purpose Returns the transaction receipt in HTML or PDF format, including all transaction details, sender/beneficiary information, an - [GET /transaction/status](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1status/get.md): Retrieves the current status and details of a transaction. ## Purpose Returns the real-time status, financial details, compliance information, and tracking data for a specific transaction. ## When to - [PUT /transaction/update](https://docs2-viablocks.viamericas.io/apis/outbound/transaction/paths/~1transaction~1update/put.md): Updates an existing cross-border money transfer transaction. ## Purpose This endpoint allows you to: - Submit compliance information (KYC, DOB, SSN, Source of Funds) when required to complete the tran ## Webhook - [POST /webhook](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook/post.md): Registers a new webhook URL for receiving transaction status change notifications. ## Integration Guide Webhooks allow you to receive real-time HTTP POST notifications when your transactions change st - [DELETE /webhook](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook/delete.md): Deactivates a webhook registration. ## Purpose Sets active=false for the specified webhook. The configuration is preserved and can be re-activated via PUT /webhook. ## Authentication Requires `x-clien - [GET /webhook](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook/get.md): Retrieves webhook configurations for the authenticated partner. ## Behavior - Without webhook_id: Returns ALL webhooks for the partner (array) - With webhook_id: Returns a specific webhook configurati - [PUT /webhook](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook/put.md): Updates the webhook configuration for the authenticated partner. ## Purpose Allows a partner to partially update their webhook configuration including the URL, subscribed events, and active status. ## - [GET /webhook/deliveries](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook~1deliveries/get.md): Returns the delivery history for a specific webhook. ## Purpose Allows a partner to query the delivery log to troubleshoot missed notifications, verify integration, and audit delivery attempts. ## Whe - [POST /webhook/rotate-secret](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook~1rotate-secret/post.md): Rotates the webhook signing secret for a specific webhook. ## Purpose Allows a partner to rotate their webhook_secret for security purposes. The old secret remains valid for a 24-hour grace period so - [POST /webhook/test](https://docs2-viablocks.viamericas.io/apis/outbound/webhook/paths/~1webhook~1test/post.md): Sends a test webhook delivery to verify connectivity and signature verification. ## Purpose Allows a partner to trigger a test delivery to their configured webhook endpoint. This verifies that the end