Para receber de clientes no exterior pelo HeroPay, crie um link avulso com "enable_international_sales": true em POST /payment_links. O comprador paga com cartão internacional na moeda dele, e você recebe em reais.
O checkout detecta o país do comprador, mostra o preço na moeda dele e a interface no idioma local; o dinheiro entra no seu saldo em reais, no valor configurado no link. Não precisa de conta no exterior nem de link separado por país. A regra que mais derruba integração: o recurso vale só para link avulso. Se o link tiver period, vira recorrência normal e o internacional é ignorado sem erro.
Criar conta sandbox Ler a documentação
Antes de começar
- Conta sandbox e token JWT em app.heropay.tech, em
HEROPAY_API_URLeHEROPAY_JWT_TOKENno servidor. - Preço definido em reais. O link é criado em centavos de real; a conversão para a moeda do comprador acontece no checkout.
- Um endpoint HTTPS para webhooks, com validação de
X-HeroPay-Signature(/webhooks).
Passo a passo
1. Crie o link avulso com vendas internacionais
curl -X POST "$HEROPAY_API_URL/payment_links" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"payment_link": {
"name": "Mentoria individual",
"description": "Sessão de mentoria de 90 minutos",
"price_cents": 100000,
"absorbs_fees": true,
"enable_international_sales": true,
"payment_methods": ["credit_card", "pix"],
"src": "comunidade-portugal"
}
}'Não mande period. O campo enable_international_sales é opcional e o padrão é false. Deixar pix no mesmo link atende quem abre o checkout do Brasil: o mesmo link serve os dois públicos.
Resposta 201 Created (recorte):
{
"message": "Payment link created successfully",
"data": {
"id": 138,
"name": "Mentoria individual",
"price_cents": 100000,
"period": "unitary",
"offer": {
"id": 6096,
"kind": "payment_link",
"url": "https://pay.beta.herospark.com/fc280e25-7cbd-446f-b34f-5b8824bb5124-6096?src=comunidade-portugal",
"accepted_payment_methods": ["credit_card", "pix"]
}
}
}Confira "period": "unitary" na resposta: é o sinal de que o link é avulso, condição para o internacional valer. Para ver a experiência de quem compra de fora, abra a URL a partir de outro país (dica no FAQ de sandbox, abaixo).
2. Envie o link para o comprador de fora
Mande data.offer.url por e-mail, WhatsApp ou no botão da sua página em inglês. Quem abre em Lisboa vê euros e português de Portugal; quem abre em Nova York vê dólares e inglês; quem abre em São Paulo vê reais e pode pagar no Pix. As condições vigentes do fluxo internacional estão na documentação de pagamento internacional.
3. Confirme pelo webhook, em reais
O mesmo spark_payment_confirmed da venda nacional avisa o pagamento. Cadastre uma vez:
curl -X POST "$HEROPAY_API_URL/webhook" \
-H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
-H "Accept: application/vnd.herospark.com; version=1" \
-H "Content-Type: application/json" \
-d '{
"webhook": {
"trigger": "spark_payment_confirmed",
"webhook_url": "https://seuapp.com/webhooks/heropay",
"request_method": "post"
}
}'Recorte dos campos que o handler usa (valores ilustrativos, campos reais do template; o payload completo está na documentação de webhooks):
{
"payment": {
"id": "8812410",
"method": "credit_card",
"net_value_cents": "92000"
},
"offer": { "title": "Mentoria individual" },
"cart": { "src": "comunidade-portugal" }
}Concilie em reais: a documentação garante que você recebe o valor configurado no link, e net_value_cents é quanto entra no saldo. Não construa lógica em cima de campos de moeda estrangeira no payload.
4. Faça a conta antes de precificar
A taxa vigente na documentação de tarifas é 7,9% + R$ 1 por transação internacional aprovada no cartão (verificado em setembro/2026). Numa venda de R$ 1.000, a tarifa é R$ 80 e entram R$ 920. Numa de R$ 497, a tarifa é R$ 40,26 e entram R$ 456,74. Recusa não paga.
Variações
Por prompt, com o llms.txt
Cole https://heropay.ai/llms.txt no Claude, ChatGPT, Cursor, Lovable e outros (mais em /ai) e peça:
Cria um link avulso de R$ 1.000 para "Mentoria individual" com vendas
internacionais ligadas, cartão e Pix, src "comunidade-portugal".
Não coloca recorrência.Com o contrato da API no contexto, a IA monta o POST /payment_links com enable_international_sales: true e price_cents: 100000. A última frase do prompt importa: ela impede a IA de "ajudar" colocando period. Revise a chamada antes de rodar. Um MCP server oficial está em desenvolvimento.
Sem código, pelo painel
Em app.heropay.tech você acompanha as vendas e o saldo sem código. Para ligar o internacional num link, o caminho documentado hoje é o campo enable_international_sales na criação pela API; se preferir não programar, a variação por prompt acima faz a chamada por você.
Erros comuns e como ler a mensagem
| Sintoma ou status | Mensagem (real) | Causa e correção |
|---|---|---|
201, mas o estrangeiro vê reais | nenhuma | O link tem period. Com recorrência, o internacional não é aplicado e a API não avisa. Crie um link avulso. |
422 | Price cents must be greater than or equal to 500 | Preço enviado na moeda estrangeira ou em reais sem centavos. price_cents é sempre centavo de real. |
422 | Absorbs fees is not included in the list | absorbs_fees ausente. Ele define se você absorve os juros do parcelamento. |
500 | Failed to create payment link: Error occurred while parsing request parameters | JSON malformado, em geral true entre aspas ou vírgula sobrando. |
401 | corpo com error | Token de sandbox contra produção, ou sem Bearer . |
Perguntas frequentes
Consigo cobrar assinatura de cliente no exterior?
Não pelo checkout internacional. A documentação é explícita: pagamento internacional vale só para vendas unitárias. Se você cria um link com period, ele funciona como recorrência normal, em reais, e o internacional é ignorado sem erro. Para um cliente de fora que paga todo mês, a alternativa honesta hoje é um link avulso por ciclo, criado pelo seu sistema na data da cobrança, ou um plano anual avulso. Pix Automático e boleto não servem para quem não tem conta no Brasil.
Em que moeda eu recebo?
Em reais, direto no saldo da sua conta HeroPay, no valor configurado no link. O comprador vê e paga na moeda local dele; a conversão acontece no checkout, no momento da compra. Você não precisa de conta em dólar, de conta no exterior nem de contrato de câmbio avulso por venda. Consulte o saldo com GET /financial/balance e saque para uma chave Pix do mesmo CPF ou CNPJ da conta com POST /financial/withdrawals.
Quanto custa receber de fora?
A taxa vigente na documentação é 7,9% + R$ 1 por transação internacional aprovada no cartão, sem mensalidade, ativação ou mínimo. Numa venda de R$ 1.000, a tarifa é R$ 80 e entram R$ 920. Se o mesmo link for pago no Pix por alguém no Brasil, a tarifa é R$ 0. A referência oficial e atualizada é sempre /precos.
Preciso criar um link por país?
Não. O mesmo link com enable_international_sales: true detecta a região de quem abre e ajusta moeda e idioma sozinho. Use o src para saber de onde veio cada venda (comunidade-portugal, ads-eua); ele volta em cart.src em todo webhook. Um link por campanha, não por país, é o suficiente.
E a parte fiscal de vender para o exterior?
O HeroPay processa o pagamento e liquida em reais; a nota fiscal e o enquadramento da receita de exportação de serviço ficam com você. Regras de ISS, PIS e Cofins sobre exportação de serviços variam por atividade e município, então valide com o seu contador antes de escalar. Guarde o payment.id e o cart.src de cada venda internacional: é o que liga o pagamento à nota emitida.
Posso testar o checkout internacional no sandbox?
O sandbox roda o mesmo contrato da produção, então o POST /payment_links com enable_international_sales e o webhook funcionam igual. Para ver a experiência do comprador, abra a URL do link com uma VPN em outro país.