Quotes API

The Quotes API allows you to generate payment quotes that include exchange rates, fees, and timing information for transfers between payment profiles. Quotes are required before creating payment instructions.

Endpoints

Create Quote - POST /api/v1/companies/{company_id}/quotes

Create Quote

Generate a payment quote for a transfer between two payment profiles.

Endpoint

POST /api/v1/companies/{company_id}/quotes

Headers

Authorization: Bearer {jwt_token}
Content-Type: application/json

Request Body

{
  "quote": {
    "from_profile_id": "string",
    "to_profile_id": "string",
    "instructed_amount": {
      "amount": 1000.00,
      "currency": "USD"
    }
  }
}

Parameters

Parameter	Type	Required	Description
`from_profile_id`	string	Yes	ID of the source payment profile
`to_profile_id`	string	Yes	ID of the destination payment profile
`instructed_amount`	object	Yes	Amount to quote
`instructed_amount.amount`	number	Yes	Monetary amount (e.g., 1000.00)
`instructed_amount.currency`	string	Yes	Currency code (e.g., "USD")

Example Request - Same Currency

curl -X POST "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/quotes" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": {
      "from_profile_id": "gid://app/PaymentProfile/1",
      "to_profile_id": "gid://app/PaymentProfile/2", 
      "instructed_amount": {
        "amount": 1000.00,
        "currency": "USD"
      }
    }
  }'

Example Request - Cross Currency

curl -X POST "https://api.treasurypath.com/api/v1/companies/comp_1234567890abcdef/quotes" \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "quote": {
      "from_profile_id": "gid://app/PaymentProfile/1",
      "to_profile_id": "gid://app/PaymentProfile/3",
      "instructed_amount": {
        "amount": 1000.00,
        "currency": "USD"
      }
    }
  }'

Success Response - Same Currency (201 Created)

{
  "data": {
    "id": "quote_abc123def456",
    "instructed_amount": "1000.00",
    "instructed_amount_currency": "USD",
    "source_amount": "1005.00",
    "source_amount_currency": "USD",
    "target_amount": "1000.00",
    "target_amount_currency": "USD",
    "currency_pair": null,
    "exchange_rate": 1.0,
    "expires_at": "2024-01-15T10:45:00Z",
    "fee": "5.00",
    "fee_currency": "USD",
    "expected_completion_date": "2024-01-16",
    "from_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
      "status": "active",
      "currency": "USD",
      "payment_method": "ach",
      "usage_type": "debit"
    },
    "to_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z", 
      "status": "active",
      "currency": "USD",
      "payment_method": "ach",
      "usage_type": "credit"
    }
  }
}

Success Response - Cross Currency (201 Created)

{
  "data": {
    "id": "quote_xyz789abc123",
    "instructed_amount": "1000.00",
    "instructed_amount_currency": "USD",
    "source_amount": "1005.00",
    "source_amount_currency": "USD",
    "target_amount": "850.00",
    "target_amount_currency": "EUR",
    "currency_pair": "USDEUR",
    "exchange_rate": 0.85,
    "expires_at": "2024-01-15T10:45:00Z",
    "fee": "5.00",
    "fee_currency": "USD",
    "expected_completion_date": "2024-01-17",
    "from_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8x",
      "status": "active",
      "currency": "USD",
      "payment_method": "ach",
      "usage_type": "debit"
    },
    "to_profile": {
      "id": "Z2lkOi8vd2FsbGV0LWFwcC9QYXltZW50UHJvZmlsZS8z",
      "status": "active",
      "currency": "EUR",
      "payment_method": "swift",
      "usage_type": "credit"
    }
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique quote identifier
`instructed_amount`	decimal	Original requested amount
`instructed_amount_currency`	string	Currency of instructed amount
`source_amount`	decimal	Total amount debited from source account
`source_amount_currency`	string	Currency of source amount
`target_amount`	decimal	Amount credited to recipient
`target_amount_currency`	string	Currency of target amount
`currency_pair`	string	Currency pair for FX (e.g., "USDEUR")
`exchange_rate`	decimal	Exchange rate used for conversion
`expires_at`	string	Quote expiration timestamp (ISO 8601)
`fee`	decimal	Fee amount
`fee_currency`	string	Currency of the fee
`expected_completion_date`	string	Expected date when payment will complete
`from_profile`	object	Source payment profile details
`to_profile`	object	Destination payment profile details

Payment Profile Fields

Field	Type	Description
`id`	string	Unique payment profile identifier
`status`	string	Status of the payment profile (e.g., active, draft)
`payment_method`	string	Payment method (e.g., ach, wire, swift)
`currency`	string	Currency code for the payment profile
`usage_type`	string	Usage type (debit or credit)

Error Responses

400 Bad Request - Missing company_id

{
  "errors": [
    {
      "field": "company_id",
      "message": "Company ID is required"
    }
  ]
}

422 Unprocessable Entity - Invalid Amount

{
  "errors": [
    {
      "field": "instructed_amount",
      "message": "Instructed amount must be greater than zero"
    }
  ]
}

422 Unprocessable Entity - Profile Validation

{
  "errors": [
    {
      "field": "from_profile_id", 
      "message": "From profile does not have any connections"
    }
  ]
}

422 Unprocessable Entity - Cross Currency Error

{
  "errors": [
    {
      "field": "base",
      "message": "No active Airwallex account found for the entity"
    }
  ]
}

Quote Lifecycle

Creation: Quote is generated with current exchange rates and fees
Expiration: Quotes expire after 15 minutes
Usage: Valid quotes can be used to create payment instructions
FX Integration: Cross-currency quotes integrate with Airwallex for live rates

Same Currency vs Cross Currency

Same Currency Transfers

Exchange rate is always 1.0
No external FX provider needed
Fees based on payment method and amount
Faster quote generation

Cross Currency Transfers

Live exchange rates from Airwallex
External quote ID for tracking
Currency pair notation (e.g., "USDEUR")
Requires active Airwallex account for the entity
15-minute validity period

Fee Calculation

Fees are calculated based on: - Payment method (ACH, wire, SWIFT, etc.) - Transfer amount - Currency pair (for FX transfers) - Fee schedule configuration

Net vs Gross Strategy

Net Strategy (default): - Recipient receives exactly the instructed amount - Sender pays instructed amount + fees - source_amount = instructed_amount + fees

Gross Strategy: - Sender pays exactly the instructed amount
- Recipient receives instructed amount - fees - target_amount = instructed_amount - fees

Using Quotes

Create a quote to get pricing and exchange rate information
Use the quote ID when creating a payment instruction
Quotes must be used before expiration (15 minutes)
Each quote can only be used once

Error Handling

Common error scenarios: - 401 Unauthorized: Invalid or missing JWT token - 404 Not Found: Payment profiles not found - 422 Unprocessable Entity: Validation errors - 500 Internal Server Error: FX provider errors or server issues

Rate Limiting

Quote generation is subject to rate limiting. Excessive quote requests may result in temporary throttling.