This guide will help you perform your first successful integration with the ViaBlocks API by walking you through:
- Requesting your API credentials
- Creating your first transaction (Inbound or Outbound)
- Retrieving the transaction status
By the end of this guide, you will have successfully created and tracked a transaction using the ViaBlocks platform.
Before you can start using the ViaBlocks API, you must request your integration credentials.
Please send a formal request by email to:
carlos.sarmiento@viamericas.com
You will receive a response email containing your credentials:
client_idsecret_key
These credentials uniquely identify your integration and must be included in every API request.
⚠️ Never expose these credentials in client-side applications or public code repositories.
ViaBlocks is a partner-configurable platform.
This means:
- Required fields
- Allowed values
- Validation rules
- Available services
- Response payload structure
may vary per partner, depending on the configuration assigned by Viamericas.
Important notes:
- Inbound and Outbound transactions use the same endpoints and base structure
- However, required fields and validation rules are different
- Responses may also vary depending on:
- Transaction type (Inbound vs Outbound)
- Delivery method
- Funding type
- Compliance rules
All of this is automatically managed by ViaBlocks based on your partner configuration.
To create a transaction, call the following endpoint:
POST /transaction/createThis endpoint accepts a large payload containing:
- Authentication credentials
- Sender information
- Beneficiary information
- Transaction information
- Channel metadata
Below is a complete example payload showing all possible fields.
In your real integration, some fields may be optional or not applicable depending on your configuration.
curl -i -X POST \
https://sandbox-viablocks.viamericas.io/transaction/create \
-H 'Content-Type: application/json' \
-d '{
"client_id": "xxxx123456789",
"secret_key": "xxxx987654321",
"sender": {
"firstName": "MARLON",
"middleName": "",
"lastName": "ARANZA",
"secondLastName": "",
"phone": "3888111965",
"phoneCountryCode": "+52",
"email": "notificationsviablocks@gmail.com",
"dateOfBirth": "1987-01-01",
"addressStreet": "125 Hidalgo, Mezcala, Jalisco 47914, México",
"addressState": "MX-JAL",
"addressCity": "MEZCALA",
"addressCountry": "MEX",
"addressZipCode": "47914",
"documentType": "PA",
"documentDescription": "PASSPORT",
"documentNumber": "FF01231167855",
"documentExpirationDate": "2022-12-30",
"documentState": "MX-JAL",
"documentCountry": "MEX",
"occupation": "DRIVER",
"employer": "UBER DRIVER",
"proofOfIncome": "NOT APPLICABLE"
},
"beneficiary": {
"firstName": "ANGEL",
"middleName": "",
"lastName": "RESTADO",
"secondLastName": "",
"phone": "3057118816",
"phoneCountryCode": "+1",
"email": "notificationsviablocks@gmail.com",
"addressStreet": "1450 Brickell Avenue Apt 2908, Miami, FL 33131, USA",
"addressState": "US-FL",
"addressCity": "MIAMI",
"addressCountry": "USA",
"addressZipCode": "33131",
"documentType": "CC",
"documentNumber": "123456777",
"documentDescription": "CEDULA DE IDENTIDAD",
"documentExpirationDate": "2022-12-30",
"documentCountry": "COL",
"relationShip": "SON"
},
"transactionInformation": {
"originationCountryISO": "MEX",
"originationStateISO": "MX-JAL",
"originationLocationCity": "MEZCALA",
"originationAmount": 360,
"originationCurrencyISO": "MXN",
"exchangeRate": 18.59,
"fee": 0,
"fundingFee": 0,
"fixFee": 0,
"otherFees": 0,
"percentageFee": 0,
"taxes": 0,
"deliveryAmount": 0.00,
"deliveryCountryISO": "USA",
"deliveryStateISO": "US-FL",
"deliveryAmountCurrencyISO": "USD",
"deliveryLocationCode": "T377",
"deliveryLocationNetwork": "PV0001",
"deliveryLocationName": "USA BANK DEPOSIT",
"deliveryLocationCity": "CITY USA BANK",
"deliveryMode": "C",
"deliveryModeDetails": {
"accountNumber": "5369254747",
"routingNumber": 96016930,
"accountType": "S",
"bank": "USA BANK"
},
"funding": {
"type": "A",
"accountNumber": "530000000",
"routingNumber": 80
},
"sourceOfFounds": "SALARY",
"remittancePurpose": "FAMILY"
},
"channel": "API",
"channelMetadata": {}
}'{
"status": "success",
"message": "Transaction created successfully",
"transaction_uuid": "xxxxxx-xxxxx-xxx-xxxx-xxxxx",
"transaction_id": "xxxxxx-8",
"folio": "123456789",
"total_receiver": "46.6200",
"total_pay_receiver": "46.6200",
"source_currency_amount": "840.0000",
"rate": "0.0555",
"status_track_url": "https://status-track.viamericas.io/?token=xxxxxx-xxxxx-xxx-xxxx-xxxxx",
"payment_url": "https://dev-remotepayment.viamericas.io/?session_id=R7U5K08qPZ"
}⚠️ The response payload may vary depending on your partner configuration and transaction type.
Once a transaction has been created, you can track its status using:
POST /transaction/statusThis endpoint is common for both Inbound and Outbound transactions.
curl -i -X POST \
https://sandbox-viablocks.viamericas.io/transaction/status \
-H 'Content-Type: application/json' \
-d '{
"client_id": "xxxx123456789",
"secret_key": "xxxx987654321",
"uuid": "xxxxx-xxxx-xxxx-xxxx-xxxxx"
}'{
"transaction_uuid": "xxxxx-xxxx-xxxx-xxxx-xxxxx",
"status_track_url": "https://status-track.viamericas.io/?token=xxxxx-xxxx-xxxx-xxxx-xxxxx",
"status": "HOLD",
"folio": "1234567890",
"source_currency_amount": 84000,
"source_currency_iso": "MXN",
"total_receiver": 84000,
"total_pay_receiver": 4662,
"currency_receiver_iso": "USD",
"rate": 0.0555,
"holds": [],
"requiredDocumentList": []
}You have successfully:
- Created your first transaction using the ViaBlocks API
- Retrieved its current status
- Completed your first end-to-end integration flow
You can now:
- Explore the API Reference for all available endpoints
- Review the Inbound Transactions and Outbound Transactions guides
- Implement advanced flows such as:
- Payment links
- Compliance document uploads
- Status polling
- Operational follow-ups
If you have any questions or need production access, please contact your Viamericas integration team.