Create A Proposal with Multiple Intentions

With Create A Proposal with Single Intention, you can create a proposal and get a proposal ID for only one intention, eg. installment, or FX. But a payment request is only allowed to send with one proposal ID, thus when you need to send a payment request with multiple intentions, eg. installment and FX, you’ll need to create a proposal with multiple intentions and use this proposal ID to go ahead with the payment request.

HTTP Request

POST /v1/payments/proposals

RequestResponse

Request Headers

{
    "Content-Type": "application/json",
    "Authorization": "Bearer {{access_token}}",
    "x-api-key": "{{api_key}}"
}

Create A Proposal with Installment and FX

Request Body

{
    "amount": 100000,
    "country": "BR",
    "currency": "USD",
    "targetCurrency": "BRL",
    "installmentPlanId": "2daac1cf-40f0-4311-9114-fb7e10e5f682"
}

Create A Proposal with Installment and Tax

Request Body

{
    "amount": 100000,
    "country": "BR",
    "currency": "BRL",
    "installmentPlanId": "fcb50514-2124-4e89-9238-8357714f1593",
    "taxPlanId": "f29d3d48-0806-41ca-b3ba-cdb4228d100d"
}

Create A Proposal with FX and Tax

Request Body

{
    "amount": 100000,
    "country": "BR",
    "currency": "USD",
    "targetCurrency": "BRL",
    "taxPlanId": "f29d3d48-0806-41ca-b3ba-cdb4228d100d"
}

Create A Proposal with Installment, FX and Tax

Request Body

{
    "amount": 100000,
    "country": "BR",
    "currency": "USD",
    "targetCurrency": "BRL",
    "installmentPlanId": "fcb50514-2124-4e89-9238-8357714f1593",
    "taxPlanId": "f29d3d48-0806-41ca-b3ba-cdb4228d100d"
}

Response

{
"id":"3c31a13f-69a2-425d-a383-1bbd697329db",
"submitTime":"2023-09-21T10:53:39Z",
"expirationTime":"2023-09-21T11:53:39Z",
"paymentIntent":{
    "amount":100000,
    "country":"BR",
    "currency":"USD",
    "targetCurrency":"BRL",
    "installmentPlanId":"2daac1cf-40f0-4311-9114-fb7e10e5f682"
},
"planDetails":{
    "installment":[
        {
            "modifierType":"RATE",
            "rate":0,
            "installments":1
        },
        {
            "modifierType":"RATE",
            "rate":0,
            "installments":2
        },
        {
            "modifierType":"RATE",
            "rate":0,
            "installments":3
        }
    ],
    "fx":[
        {
            "base":"USD",
            "target":"BRL",
            "spreadRate":0.02
        },
        {
            "base":"USD",
            "target":"MXN",
            "spreadRate":0.02
        }
    ],
    "tax": [
        {
            "modifierType": "RATE",
            "rate": 0.0038,
            "type": "BR_IOF_FX_TAX"
        }
    ]
},
"proposalDetails":{
    "fxProposalDetails":{
        "fxRate":{
            "modifierType":"RATE",
            "base":"USD",
            "target":"BRL",
            "timestamp":1664443743,
            "exchangeRate":5.4835098
        },
        "baseAmount":100000,
        "targetAmount":548351
    },
    "installmentProposalDetails":[
        {
            "installmentAmount":548351,
            "installments":1,
            "totalAmount":548351
        },
        {
            "installmentAmount":274176,
            "installments":2,
            "totalAmount":548351
        },
        {
            "installmentAmount":182784,
            "installments":3,
            "totalAmount":548351
        }
    ],
    "taxProposalDetails": [
        {
            "taxRate": {
                "modifierType": "RATE",
                "rate": 0.0038,
                "type": "BR_IOF_FX_TAX"
            },
            "amount": 380
        }
    ]
  }
}

HTTP Headers Details

Key	Value
Authorization	"bearer" + " " + {{access_token}}
x-api-key	{{api_key}}

Request Body Parameters

Parameter	Type	Description
amount	Long	The transfer amount, The minimum settlement granularity of the current currency, such as 100=1BRL
country	String	The country code.
currency	String	The transaction currency code, which can be USD, BRL, MXN, COP or CLP.
targetCurrency	String	The target currency code, can only be local currencies. Required if you need foreign exchange
installmentPlanId	String	The installment plan ID. Required when you need to include installment plan.
taxPlanId	String	The tax plan ID. Required when you need to include tax plan.

Response Body Parameters

Parameter	Type	Description
id	String	The proposal ID.
submitTime	String	The proposal submit time.
expirationTime	String	The proposal expiration time.
paymentIntent	JSON	The payment intention.
planDetails	JSON	The plan details.
proposalDetails	JSON	The proposal details.

Object Parameters

paymentIntent

Parameter	Type	Description
amount	Long	The transfer amount, The minimum settlement granularity of the current currency, such as 100=1BRL
country	String	The country code.
currency	String	The base currency code.
targetCurrency	String	The target currency code.
installmentPlanId	String	The installment plan ID.
taxPlanId	String	The tax plan ID.

planDetails

Parameter	Type	Description
installment	JSON Array	Installments plan details.
fx	JSON Array	fx plan details.
tax	JSON Array	Tax plan details.

installment

Parameter	Type	Description
modifierType	String	Modifier type. RATE
rate	Positive Float	Surcharge rate.
installments	Integer	Number of installments.

fx

Parameter	Type	Description
base	String	base currency
target	String	target currency
spreadRate	Positive Float	Foreign exchange spread rate

tax

Parameter	Type	Description
modifierType	String	Modifier type. RATE
rate	Positive Float	Tax rate.
type	String	Type of tax fee.

proposalDetails

Parameter	Type	Description
fxProposalDetails	JSON Array	The fx proposal details.
installmentProposalDetails	JSON Array	The installment proposal details.
taxProposalDetails	JSON Array	The tax proposal details.

installmentProposalDetails

Parameter	Type	Description
installmentAmount	Long	Installment amount.
installments	Integer	Number of installments.
totalAmount	Long	Installments total amount.

fxProposalDetails

Parameter	Type	Description
fxRate	JSON	The foreign exchange rate details.
baseAmount	Long	The amount of base currency.
targetAmount	Long	The amount of target currency.

fxRate

Parameter	Type	Description
modifierType	String	Modifier type. RATE
base	String	Base currency, e.g. USD
target	String	Target currency, e.g. BRL
timestamp	Long	The timestamp when exchanging currency.
exchangeRate	Positive Float	The exchange rate.

taxProposalDetails

Parameter	Type	Description
taxRate	JSON	The foreign exchange rate details.
amount	Long	The tax amount.

taxRate

Parameter	Type	Description
modifierType	String	Modifier type. RATE
rate	Positive Float	Tax rate.
type	String	Type of tax fee.