# Quickstart

This guide will help you perform your **first successful integration** with the ViaBlocks API by walking you through:

1. Requesting your API credentials
2. Creating your first transaction (Inbound or Outbound)
3. Retrieving the transaction status


By the end of this guide, you will have successfully created and tracked a transaction using the ViaBlocks platform.

## Step 1 — Request Your API Credentials

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_id`
- `secret_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.


## Step 2 — Understand Partner Configuration

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.

## Step 3 — Create Your First Transaction

To create a transaction, call the following endpoint:


```
POST /transaction/create
```

This 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.

### Example Request — Create Transaction


```bash
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": {}
  }'
```

### Example Response — Create Transaction


```json
{
  "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.


## Step 4 — Retrieve Transaction Status

Once a transaction has been created, you can track its status using:


```
POST /transaction/status
```

This endpoint is **common for both Inbound and Outbound transactions**.

### Example Request — Get Transaction Status


```bash
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"
  }'
```

### Example Response — Get Transaction Status


```json
{
  "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": []
}
```

## 🎉 Congratulations!

You have successfully:

- Created your first transaction using the ViaBlocks API
- Retrieved its current status
- Completed your first end-to-end integration flow


## Next Steps

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.