Pular para o conteúdo
Criar conta
 ou
Entrar
O logotipo da documentação da Stripe
/
Criar conta
Login

Usar a API FX Quotes no Connect

Selecione quais moedas localizar, garanta as taxas de câmbio e decida se repassa as tarifas aos seus clientes.

Use a API FX Quotes para localizar os preços nas moedas dos clientes e reduzir as incertezas sobre a evolução das taxas de câmbio. Você pode especificar uma FX Quote ao criar uma PaymentIntent com a moeda de apresentação do cliente. Você também pode especificar uma FX Quote ao criar uma transferência para confirmar o valor da liquidação na conta conectada. Veja mais detalhes em FX Quotes.

Exemplos de cenários de câmbio

Nos diferentes tipos de cobrança do Connect, o câmbio ocorre das seguintes formas.

Cobranças diretas

As cobranças diretas sempre são convertidas da moeda de apresentação para a moeda padrão da conta conectada. A tarifa da plataforma é convertida para a moeda padrão da plataforma.

Por exemplo, digamos que você aceite uma cobrança para uma conta conectada em USD. A conta conectada recebe fundos em EUR. Os fundos enviados à conta conectada são convertidos em euros e a tarifa da plataforma é convertida de EUR para USD para sua plataforma.

Você pode usar cotações de taxas estendidas da API FX Quotes para reduzir a incerteza cambial sobre cobranças diretas. Ao criar uma cobrança direta, passe o ID da FX Quote para o PaymentIntent. Especifique a moeda do cliente final como from_currency. Especifique a moeda de liquidação padrão da conta conectada como to_currency.

Criar uma FX Quote

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment

As cobranças diretas são realizadas na moeda padrão da conta conectada, mas sua plataforma recebe as tarifas da plataforma para cobranças diretas na moeda padrão da plataforma. O uso de cotações de taxa estendida em cobranças diretas na API FX Quotes não afeta a taxa de câmbio na qual as tarifas da plataforma são convertidas.

Disponibilidade de conta bancária ou cartão de débitoAção de conversão
Disponível para a moeda de liquidaçãoSem conversão
Não disponível para a moeda de liquidaçãoA Stripe converte a tarifa da plataforma com base na moeda padrão da conta da plataforma

Se sua plataforma não usa tarifas da plataforma e retém uma parte das cobranças, esses fundos são repassados da mesma forma que as outras cobranças para a conta da plataforma.

Destination Charges sem on_behalf_of

Ao processar cobranças de destino sem on_behalf_of, a Stripe primeiro as converte da moeda de apresentação para a moeda padrão da plataforma. Os fundos enviados à conta conectada são convertidos para a moeda padrão da conta conectada.

  • Se você usar application_fee_amount, cobraremos a tarifa da plataforma após a conversão para a moeda padrão da conta conectada. Após a adição à plataforma, a tarifa permanece nessa moeda.
  • Se você usar transfer_data[amount], cobraremos a tarifa após a primeira conversão de moeda e ela permanecerá na moeda padrão da plataforma.

Observação

Este fluxo de cobrança está sujeito às políticas regionais e internacionais da Stripe.

Por exemplo, digamos que você aceite uma cobrança de destino para uma conta conectada em EUR. A conta conectada liquida em GBP, e sua plataforma liquida em USD. A cobrança é convertida de EUR para USD, e os fundos enviados à conta conectada são convertidos para GBP.

  • Se você usar application_fee_amount, o valor da tarifa da plataforma será convertido de EUR para GBP e nós o retiraremos do valor que for liquidado na conta conectada.
  • Se você usar transfer_data[amount], a tarifa será retida em USD após a conversão da moeda de apresentação inicial.

Você pode usar cotações de taxas estendidas do FX Quotes API para reduzir a incerteza cambial nas cobranças de destino sem on_behalf_of. Ao criar uma cobrança, passe o ID da FX Quote para o PaymentIntent. No exemplo acima, você tem certeza sobre a taxa de câmbio usada na conversão de EUR (a moeda do cliente final) para USD (a moeda da plataforma). Em FX quotes, especifique a moeda do cliente final como from_currency. Especifique a moeda de liquidação padrão da plataforma como to_currency. Não é possível usar FX Quotes para qualquer conversão ocorrida na transferência da plataforma para a conta conectada, nem em qualquer conversão das tarifas da plataforma.

Criar uma FX Quote

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][destination]"=
{{CONNECTED_ACCOUNT_ID}}

Não convertemos novamente as tarifas da plataforma cobradas com o parâmetro application_fee_amount para cobranças de destino. As plataformas sempre recebem tarifas da plataforma na moeda de liquidação da conta conectada. Use o parâmetro transfer_data[amount] para transferir um valor inferior ao valor da transação e coletar tarifas na moeda de liquidação padrão da plataforma.

Cobranças de destino com on_behalf_of

Ao processar cobranças de destino com on_behalf_of, a Stripe primeiro as converte da moeda de apresentação para a moeda padrão da conta conectada. A tarifa da plataforma permanece na moeda da conta conectada, independentemente de você usar application_fee_amount ou transfer_data[amount].

Por exemplo, a conta conectada aceita uma cobrança em USD, mas liquida em EUR. A cobrança é convertida para EUR e enviada para a conta conectada em EUR. Cobramos a tarifa em EUR, independentemente de você usar application_fee_amount ou transfer_data[amount].

Você pode usar cotações de taxas estendidas da API FX Quotes para reduzir a incerteza cambial nas cobranças de destino com on_behalf_of. Ao criar uma cobrança, passe o ID da FX Quote para o PaymentIntent. No exemplo acima, isso mostra a certeza da taxa de câmbio usada na conversão de USD (a moeda do cliente final) para EUR (a moeda da conta conectada). Em FX quotes, especifique a moeda do cliente final como from_currency. Especifique a moeda de liquidação padrão da conta conectada como to_currency.

Criar uma FX Quote

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=eur \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][on_behalf_of]"=
{{CONNECTED_ACCOUNT_ID}}
 \
  -d "usage[payment][destination]"=
{{CONNECTED_ACCOUNT_ID}}

Não convertemos novamente as tarifas da plataforma cobradas com o parâmetro application_fee_amount para cobranças de destino. As plataformas sempre recebem tarifas da plataforma na moeda de liquidação da conta conectada. Use o parâmetro transfer_data[amount] para transferir um valor inferior ao valor da transação e coletar tarifas na moeda de liquidação padrão da plataforma.

Quando você cria cobranças na plataforma usando os parâmetros destination ou on_behalf_of, pode acumular saldos em várias moedas. Se você não tem contas bancárias para essas outras moedas, a Stripe oferece uma forma de repassar saldos em moedas não padrão para a conta bancária padrão da plataforma.

A Stripe converte as moedas, que são representadas como repasses manuais, com currency definido como a moeda do saldo de origem:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/payouts \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1000 \
  -d currency=xaf

Se houver fundos suficientes no saldo para a moeda especificada, a Stripe converte automaticamente os fundos para a moeda padrão da conta bancária. Não aceitamos o uso de FX Quotes em repasses.

Observação

Este fluxo de cobrança está sujeito às políticas regionais e internacionais da Stripe.

Cobranças e transferências separadas sem on_behalf_of

Nós convertemos as cobranças separadas da moeda de apresentação para a moeda padrão da plataforma. A plataforma transfere posteriormente os fundos para a conta conectada. Os parâmetros application_fee_amount e transfer_data[amount] não são usados para coletar tarifas, porque a plataforma pode escolher o valor adequado para envio no momento da transferência.

Tomemos uma cobrança em USD como exemplo. A moeda padrão da conta da plataforma é GBP. A conversão de moeda de USD para GBP ocorre como parte da cobrança. Quando a plataforma transfere esses fundos para uma conta conectada com EUR como moeda padrão, ocorre outra conversão de moeda, desta vez de GBP para EUR.

Você pode usar cotações de taxas estendidas da API FX Quotes para reduzir a incerteza cambial ao usar cobranças e transferências separadas sem on_behalf_of. Isso se aplica tanto à cobrança como à transferência avulsa.

FX Quote do pagamento

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d "from_currencies[]"=cad \
  -d lock_duration=hour \
  -d "usage[type]"=payment

FX Quote da transferência

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -d to_currency=eur \
  -d "from_currencies[]"=gbp \
  -d lock_duration=five_minutes \
  -d "usage[type]"=transfer \
  -d "usage[transfer][destination]"=
{{CONNECTED_ACCOUNT_ID}}

Ao criar uma cobrança, passe o ID da FX Quote para o PaymentIntent. No exemplo acima, isso mostra a certeza da taxa de câmbio usada na conversão de USD (a moeda do cliente final) para GBP (a moeda da plataforma Connect). Em FX quotes, especifique a moeda do cliente final como from_currency. Especifique a moeda de liquidação padrão da plataforma como to_currency.

Ao criar uma transferência, passe o ID da FX Quote na transferência. No exemplo acima, você tem certeza da taxa de câmbio usada na conversão de GBP (a moeda da plataforma Connect) para EUR (a moeda da conta conectada). Em FX Quote, especifique a moeda da plataforma Connect como from_currency. Especifique a moeda padrão da sua conta conectada como to_currency.

Observação

Este fluxo de cobrança está sujeito às políticas regionais e internacionais da Stripe.

Cobranças e transferências separadas com on_behalf_of

Nós convertemos as cobranças separadas da moeda de apresentação para a moeda padrão da conta conectada. A plataforma transfere posteriormente os fundos para a conta conectada. Não usamos os parâmetros application_fee_amount e transfer_data[amount] para coletar tarifas, porque a plataforma pode escolher o valor adequado para envio no momento da transferência.

Tomemos uma cobrança em USD como exemplo. A moeda padrão da conta conectada é EUR. A conversão de moeda de USD para EUR ocorre como parte da cobrança. Não há conversão de moeda durante a transferência porque os fundos já estão na moeda da conta conectada.

Você pode usar cotações de taxas estendidas da API FX Quotes para reduzir a incerteza cambial ao usar cobranças e transferências separadas com on_behalf_of.

FX quote para a cobrança

Command Line
cURL
No results
curl https://api.stripe.com/v1/fx_quotes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-07-30.basil; fx_quote_preview=v1" \
  -d to_currency=gbp \
  -d "from_currencies[]"=usd \
  -d lock_duration=hour \
  -d "usage[type]"=payment \
  -d "usage[payment][on_behalf_of]"=
{{CONNECTED_ACCOUNT_ID}}

Observação

Este fluxo de cobrança está sujeito às políticas regionais e internacionais da Stripe.

Câmbio em reembolsos

Quando você reembolsa um pagamento que foi originalmente convertido para outra moeda, usamos a taxa de câmbio em tempo real no momento do reembolso. Isso ocorre independentemente de você ter usado a FX Quotes para definir sua taxa de câmbio no pagamento original. A Stripe não cobra uma tarifa de câmbio por nenhuma conversão no reembolso. A Stripe não reembolsa a tarifa de câmbio cobrada na transação original.

Câmbio em repasses

A moeda de liquidação é a moeda em que você pode receber repasses. Consulte as moedas de liquidação aceitas.

Dependendo da disponibilidade de conta bancária ou cartão de débito, as seguintes ações são executadas durante o repasse de um saldo:

Disponibilidade de conta bancária ou cartão de débitoAção de conversão
Disponível para a moedaSem conversão
Várias contas bancárias ou cartões de créditos disponíveis para a moedaSem conversão. A Stripe usa a conta bancária ou cartão de débito definido como default_for_currency
Não disponível para a moedaA Stripe converte o saldo do repasse de acordo com a moeda padrão da conta Stripe
Esta página foi útil?
SimNão