Get Quotation with Dynamic Spread and Fees

Get Quotation with Dynamic Spread and Fees

POST {{Environment_URL}}/vendors/v1/charges/quotation

Before starting the payment creation process, it is necessary to obtain a quotation for the desired amount.

With Dynamic Spread and Fee, the system can define, in real time, the spread and fee to be applied to a specific transaction. By sending the parameters spread and fee in the Get Quotation request, these values will override the default configuration and will be used only for that quotation. The API will then return a quotation_id, which must be used in the standard Comm.Pix payment creation flow.

PS: To use this route, you need a specific permission from our Frente Corretora development team. If you want to enable it, please contact us through our support Slack channel. This is a sensitive route, as it allows you to temporarily change your spread and fee values for a single transaction

Key	Description	Required	Data Type	Example
amount	Operation value in cents	true	Integer	4200 This results in a Quotation for $42,00
currency	Operation Currency	true	String	USD
spread	Operation custom Spread. Spread is a +% to the operation value. Minimum Value: 0 Maximum Value: 20	false	Float	0.15
fee	Operation custom Fee. Fee is a fixed value added to the operation. Value in cents	false	Integer	250 This results in a Fee of $2,50

The response will have the quotation id, you must use it to create a new charge.

The spread and fee fields must be used at the request body.

Headers

Name	Value
Authorization	Bearer <token>

Important note about currency.clamp

When consuming the quotation endpoint, developers must always check the currency.clamp field in the response. This field can have two possible values:

NORMAL → The quotation was calculated normally, without hitting any limits.

MAXIMUM → The quotation has reached the maximum allowed value. In this case, the returned amount is already capped at the defined limit, currently 200,000 USD approximately.

⚠️ Attention: If the response indicates MAXIMUM, it means the amount used for the calculation is already the maximum allowed. This exact value will also be applied in the create charge operation, so it is essential not to recalculate or assume a different amount than the one returned by the quotation.

💡 Note: The maximum allowed value is also exposed in the field currency.maxValueSimplePay.

Body Params

Name	Type	Description	Value
amount	Number	desired amount	5197
currency	String	currency	USD
spread	Float	Dynamic Spread	0.015
fee	Number	Dynamic Fee	10

Request

Get Quotation with Dynamic Spread and Fees

{
  "amount": 10000,
  "currency": "USD",
  "reverse": false,
  "spread": 0.015,
  "fee": 10
}

Response

200 - OK

{
  "id": "quot_01jxabcde123456789",
  "metadata": {
    "type": "CHARGE",
    "externalId": "vendor_123"
  },
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "clamp": "NORMAL",
    "commercialExchangeRate": {
      "value": 550,
      "divisor": 100,
      "currency": "USD",
      "precision": 2,
      "updatedAt": "2024-07-10T13:21:22.485Z"
    },
    "countryFlagUrl": "https://example.com/flags/usd.png",
    "levelingRate": {
      "value": 550,
      "divisor": 100,
      "currency": "BRL"
    },
    "offer": {
      "value": 10000,
      "divisor": 100,
      "currency": "USD"
    },
    "price": {
      "withoutSpread": {
        "value": 55000,
        "divisor": 100,
        "currency": "BRL"
      },
      "withoutTax": {
        "value": 55100,
        "divisor": 100,
        "currency": "BRL"
      },
      "withTax": {
        "value": 55200,
        "divisor": 100,
        "currency": "BRL"
      },
      "withTaxesAndFees": {
        "value": 55300,
        "divisor": 100,
        "currency": "BRL"
      },
      "withFutureTax": {
        "value": 55400,
        "divisor": 100,
        "currency": "BRL"
      }
    }
  },
  "tax": {
    "iof": {
      "percentage": 0,
      "total": {
        "value": 0,
        "divisor": 100,
        "currency": "BRL"
      }
    }
  },
  "taxesAndCosts": {
    "value": 0,
    "divisor": 100,
    "currency": "BRL"
  },
  "futureTax": {
    "ir": {
      "percentage": 0.225,
      "total": {
        "value": 1125,
        "divisor": 100,
        "currency": "BRL"
      }
    }
  },
  "total": {
    "withoutSpread": {
      "value": 55000,
      "divisor": 100,
      "currency": "BRL"
    },
    "withoutTax": {
      "value": 55100,
      "divisor": 100,
      "currency": "BRL"
    },
    "withTax": {
      "value": 55200,
      "divisor": 100,
      "currency": "BRL"
    },
    "withTaxesAndFees": {
      "value": 55300,
      "divisor": 100,
      "currency": "BRL"
    },
    "withFutureTax": {
      "value": 55400,
      "divisor": 100,
      "currency": "BRL"
    }
  },
  "createdAt": "2024-07-10T13:21:22.485Z",
  "reward": {}
}