Skip to content
API Reference/
Money Transfer
/
/Catalogs

Overview (1.0.0)



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.

Overview
Contact
viablocks-support@viamericas.com
Terms of Service
Languages
Servers
Sandbox environment
https://sandbox-viablocks.viamericas.io

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.

Operations

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:

  • Compliance with country-specific regulatory requirements
  • Correct validation of amounts, currencies, and payout configurations
  • Dynamic population of UI selection fields
  • Alignment with real-time operational rules and payout network constraints
Partners should not hardcode catalog values and should instead retrieve them programmatically to maintain synchronization with configuration updates, compliance changes, and corridor availability.

Operations

/catalogs/master/location

Request

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
Query
filterValuestring[ 2 .. 60 ] charactersrequired

Search filter value for location lookup (city, state, or country name). Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: filterValue=Miami
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  'https://sandbox-viablocks.viamericas.io/catalogs/master/location?filterValue=Miami' \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
addressCountrystring

Country ISO3 code

stateNamestring

Full state/province name

addressCitystring

City name

addressZipCodestring

Postal/ZIP code

]
Response
application/json
[
  {
    "addressCountry": "USA",
    "stateName": "Florida",
    "addressCity": "MIAMI",
    "addressZipCode": "33101"
  },
  {
    "addressCountry": "USA",
    "stateName": "Florida",
    "addressCity": "MIAMI BEACH",
    "addressZipCode": "33139"
  }
]

/catalogs/master/zipcodes/{idzipcode}

Request

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
Path
idzipcodestringrequired

Zipcode to lookup

Example: 33101
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/master/zipcodes/33101 \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/json
cityNamestring
stateIso2string
stateNamestring
Response
application/json
{
  "cityName": "MIAMI",
  "stateIso2": "FL",
  "stateName": "Florida"
}

/catalogs/google-maps-api

Request

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
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
Bodyapplication/jsonrequired
addressstringrequired

Address to geocode or autocomplete

eventstringrequired

Type of operation: "geocode" for full address details with coordinates, "autocomplete" for address suggestions

Enum"geocode""autocomplete"
countriesArray of strings

List of country codes to restrict search (e.g., ["us"])

curl -i -X POST \
  https://sandbox-viablocks.viamericas.io/catalogs/google-maps-api \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321' \
  -d '{
    "address": "5 Avenida del Río",
    "event": "geocode",
    "countries": [
      "us"
    ]
  }'

Responses

Response success - structure varies based on event type. Returns array directly without wrapper.

Bodyapplication/json
One of:

Autocomplete response - array of address suggestions

Array [
descriptionstring
matched_substringsArray of objects
place_idstring
referencestring
structured_formattingobject
termsArray of objects
typesArray of strings
]
Response
application/json
[
  {
    "description": "5305 East Henry Avenue, Tampa, FL, USA",
    "matched_substrings": [ … ],
    "place_id": "ChIJ3_QxWgbGwogR04swL1uTbSw",
    "reference": "ChIJ3_QxWgbGwogR04swL1uTbSw",
    "structured_formatting": { … },
    "terms": [ … ],
    "types": [ … ]
  },
  {
    "description": "5305 West Henry Avenue, Tampa, FL, USA",
    "matched_substrings": [ … ],
    "place_id": "EiY1MzA1IFdlc3QgSGVucnkgQXZlbnVlLCBUYW1wYSwgRkwsIFVTQSIxEi8KFAoSCWfsYkUqwsKIEY9LoPUfGgxVELkpKhQKEgmfQZSn1cPCiBEzGqGVtU_6IA",
    "reference": "EiY1MzA1IFdlc3QgSGVucnkgQXZlbnVlLCBUYW1wYSwgRkwsIFVTQSIxEi8KFAoSCWfsYkUqwsKIEY9LoPUfGgxVELkpKhQKEgmfQZSn1cPCiBEzGqGVtU_6IA",
    "structured_formatting": { … },
    "terms": [ … ],
    "types": [ … ]
  }
]

/catalogs/countries/{idCountry}/currencies

Request

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
Path
idCountrystringrequired

Country ISO3 code (e.g., USA, MEX, COL)

Example: USA
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/countries/USA/currencies \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
idstring
namestring
codestring
]
Response
application/json
[
  {
    "id": "1",
    "name": "US Dollar",
    "code": "USD"
  },
  {
    "id": "2",
    "name": "Euro",
    "code": "EUR"
  }
]

/catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts

Request

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
Path
idCountrystringrequired

Country ISO3 code (e.g., USA, MEX, COL)

Example: USA
idDeliverystringrequired

Delivery method ID (e.g., C for bank deposit, P for cash pickup)

Example: C
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/countries/USA/deliver-methods/C/payouts \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
idpayoutstring
namePayoutstring
idCountrystring
nameCountrystring
idPayerstring
exchangeRatenumber
feenumber
minAmountnumber
maxAmountnumber
urlImagestring
iso3Currencystring
accNumberRegexstring
]
Response
application/json
[
  {
    "idpayout": "1001",
    "namePayout": "Bank of America",
    "idCountry": "USA",
    "nameCountry": "United States",
    "idPayer": "BOA001",
    "exchangeRate": 1,
    "fee": 5,
    "minAmount": 10,
    "maxAmount": 10000,
    "urlImage": "https://example.com/boa.png",
    "iso3Currency": "USD",
    "accNumberRegex": "^\\d{10,12}$"
  }
]

/catalogs/countries/{idCountry}/identifications

Request

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
Path
idCountrystringrequired

Country ISO3 code (e.g., USA, MEX, COL)

Example: USA
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/countries/USA/identifications \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
documentTypestring
documentDescriptionstring
expirationDateRequiredboolean
backSideRequiredboolean
]
Response
application/json
[
  {
    "documentType": "PA",
    "documentDescription": "PASSPORT",
    "expirationDateRequired": true,
    "backSideRequired": false
  },
  {
    "documentType": "DL",
    "documentDescription": "DRIVER'S LICENSE",
    "expirationDateRequired": true,
    "backSideRequired": true
  }
]

/catalogs/countries/{idCountry}/deliver-methods/{idDelivery}/payouts/{idpayout}/locations

Request

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
Path
idCountrystringrequired

Country ISO3 code (e.g., USA, MEX, COL)

Example: USA
idDeliverystringrequired

Delivery method ID

Example: C
idpayoutstringrequired

Payout method ID

Example: 1001
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/countries/USA/deliver-methods/C/payouts/1001/locations \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
PaymentLocationCodestring
PaymentLocationNamestring
CityNamestring
SubDivisionNamestring
AddressBranchstring
WhatToBringstring
BusinessHoursstring
]
Response
application/json
[
  {
    "PaymentLocationCode": "LOC001",
    "PaymentLocationName": "Main Branch",
    "CityName": "Miami",
    "SubDivisionName": "Florida",
    "AddressBranch": "123 Main St, Miami, FL 33101",
    "WhatToBring": "Valid ID and transaction reference",
    "BusinessHours": "Mon-Fri 9AM-5PM"
  }
]

/catalogs/industry

Request

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
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/industry \
  -H 'x-client-id: stringstringstri' \
  -H 'x-secret-key: stringstringstringstringstringst'

Responses

Response success

Bodyapplication/jsonArray [
idstring
industrystring
orderinteger
jobsArray of objects
]
Response
application/json
[
  {
    "id": "7",
    "industry": "AGRICULTURE/FARMING",
    "order": 1,
    "jobs": [ … ]
  }
]

/catalogs/wire-purpose

Request

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
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/wire-purpose \
  -H 'x-client-id: stringstringstri' \
  -H 'x-secret-key: stringstringstringstringstringst'

Responses

Response success

Bodyapplication/jsonArray [
idstring
remittancePurposestring
]
Response
application/json
[
  {
    "id": "B",
    "remittancePurpose": "BILLS/UTILITY PAYMENT"
  },
  {
    "id": "E",
    "remittancePurpose": "EDUCATION"
  },
  {
    "id": "F",
    "remittancePurpose": "FAMILY SUPPORT"
  }
]

/catalogs/funds-origin

Request

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
Headers
x-client-idstring[ 16 .. 64 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx123456789
x-secret-keystring[ 32 .. 128 ] charactersrequired

Error codes: required=400001, type=400002, minLength=400003, maxLength=400004

Example: xxxx987654321
curl -i -X GET \
  https://sandbox-viablocks.viamericas.io/catalogs/funds-origin \
  -H 'x-client-id: xxxx123456789' \
  -H 'x-secret-key: xxxx987654321'

Responses

Response success

Bodyapplication/jsonArray [
idinteger

Unique identifier for the funds origin

fundsOriginstring

Description of the funds origin source

orderinteger

Display order for the funds origin option

]
Response
application/json
[
  {
    "id": 6,
    "fundsOrigin": "EMPLOYMENT INCOME",
    "order": 1
  },
  {
    "id": 2,
    "fundsOrigin": "SAVINGS",
    "order": 2
  }
]