Dashboard

Checkout Transparente

Gerar cobrança Cartão internacional

Cobrança no cartão de crédito para comprador de fora do Brasil (pagamento internacional). Usa a mesma rota da cobrança no cartão — POST /v1/charges com paymentMethod: "creditcard", cardToken e deviceId gerados pelo SDK de tokenização (detalhes neste link). O que muda é o comprador: customer.address.country com um país diferente do Brasil.

POST/v1/charges
Base URL Produção:https://api.validapay.com.br
Base URL Sandbox:https://sandbox.validapay.com.br

Pré-requisito obrigatório: solicitar a habilitação do pagamento internacional (internationalEnabled)

O pagamento internacional vem desativado em todas as contas. Para usá-lo, o titular da conta precisa solicitar ao suporte da ValidaPay a habilitação do pagamento internacional (internationalEnabled). Não existe rota da API nem opção no painel que ative isso sozinho.

  • A habilitação é por conta e por ambiente: solicite separadamente para a conta de sandbox e para a conta de produção.
  • Depois de habilitada, a conta pode (1) cobrar compradores estrangeiros por esta rota e (2) criar links de pagamento com internationalEnabled: true.

O que acontece sem a habilitação

Se a conta não tiver o pagamento internacional habilitado, a API recusa a requisição com HTTP 403 e o código INTERNATIONAL_CHECKOUT_NOT_ENABLED:

{
  "error": {
    "message": "Pagamento internacional não habilitado para esta conta. Entre em contato com o suporte da ValidaPay para solicitar a habilitação",
    "code": "INTERNATIONAL_CHECKOUT_NOT_ENABLED"
  }
}

Esse erro ocorre em dois casos:

  1. POST /v1/charges com customer.address.country diferente de BR (esta rota).
  2. Criação ou edição de link de pagamento com internationalEnabled: true.

Como resolver: solicitar a habilitação ao suporte. Repetir a requisição não resolve e a cobrança não é criada. Cobranças de compradores brasileiros continuam funcionando normalmente sem a habilitação.

Como a API decide se a cobrança é internacional

A regra usa somente customer.address.country:

| customer.address.country | Tipo de cobrança | Regras aplicadas | |---|---|---| | Código ISO 3166-1 alfa-2 diferente de BR (US, PT, AR, GB, DE...) | Internacional | As regras desta página | | Ausente, BR ou texto fora do padrão ISO ("Brasil") | Nacional | As da cobrança no cartão: CPF/CNPJ obrigatório, telefone brasileiro |

O telefone não define o tipo da cobrança: um comprador com country: "US" e telefone +55... é recusado (o código do telefone precisa ser o do país).

Regras do comprador estrangeiro

| Campo | Regra | Se não cumprir | |---|---|---| | paymentMethod | Somente creditcard | 400 INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED | | installments | Somente 1 (à vista), ou omitir | 400 INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED | | customer.address.country | ISO 3166-1 alfa-2, diferente de BR | Tratada como cobrança nacional | | customer.address.zipCode | Obrigatório, no formato do país | 400 INVALID_DATA | | customer.address.street | Obrigatório | 400 INVALID_DATA | | customer.address.number | Obrigatório | 400 INVALID_DATA | | customer.address.city | Obrigatório | 400 INVALID_DATA | | customer.address.state | Obrigatório (estado, província ou região) | 400 INVALID_DATA | | customer.address.neighborhood / complement | Opcionais | — | | customer.phone | Opcional. Se enviar: formato E.164, com + e o código do país de country (+12125550199) | 400 INVALID_DATA | | customer.documentNumber | Não envie. Documento não faz parte do pagamento internacional | — |

Checklist antes de chamar a rota

  1. A conta tem o pagamento internacional habilitado pelo suporte (senão: 403 INTERNATIONAL_CHECKOUT_NOT_ENABLED).
  2. paymentMethod é "creditcard".
  3. cardToken e deviceId foram gerados agora pelo SDK (o cardToken vale 5 minutos).
  4. customer.address.country tem o código ISO do país do comprador.
  5. customer.address tem zipCode, street, number, city e state preenchidos.
  6. installments é 1 ou não foi enviado.
  7. customer.phone, se enviado, começa com + e o código do mesmo país.
  8. customer.documentNumber não foi enviado.
  9. amount (ou o preço dos items) está em reais.

Moeda e valor

  • amount e os preços dos items são sempre em reais (BRL) e a cobrança é feita em reais.
  • O banco emissor do cartão converte para a moeda do comprador na fatura dele, com a cotação e as tarifas do próprio banco. A API não converte moeda nem aceita valor em outra moeda.

Checkout hospedado

Para vender a compradores estrangeiros pelo checkout da ValidaPay, sem integração própria, crie o link de pagamento com internationalEnabled: true (exige a mesma habilitação da conta). O checkout detecta o país do visitante, traduz a página, mostra o valor aproximado na moeda local e aplica as mesmas regras desta rota.

Resposta

  • 200 — cartão aprovado: success: true, chargeId, customerId, status: "paid".
  • 402 — cartão recusado pelo banco emissor: success: false, status: "failed" e o motivo em error.

Erros e como corrigir

| HTTP | error.code | Causa | Correção | |---|---|---|---| | 403 | INTERNATIONAL_CHECKOUT_NOT_ENABLED | Pagamento internacional não habilitado na conta | Solicitar a habilitação ao suporte | | 400 | INTERNATIONAL_PROVIDER_NOT_SUPPORTED | A conta ainda não está configurada para processar cartão internacional | Falar com o suporte | | 400 | INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED | paymentMethod diferente de creditcard | Usar creditcard | | 400 | INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED | installments maior que 1 | Enviar installments: 1 | | 400 | INVALID_DATA | Endereço incompleto ou telefone fora do padrão; error.details[].path indica o campo | Completar o campo indicado | | 400 | CARD_TOKEN_EXPIRED | cardToken com mais de 5 minutos | Gerar outro no navegador | | 409 | DUPLICATE_CHARGE | externalId já usado | Usar o chargeId de error.details | | 402 | — | Cartão recusado pelo banco emissor | Pedir outro cartão ao comprador |

Cartões de teste (sandbox)

Valem os mesmos cartões da cobrança no cartão: o número digitado na tokenização define o resultado. A conta de sandbox também precisa da habilitação, e as regras de comprador estrangeiro são validadas do mesmo jeito.

Boas práticas

  • Envie o endereço de cobrança do cartão, e não o de entrega: é ele que o banco emissor compara na análise de fraude.
  • Mostre ao comprador que o valor é cobrado em reais e que a fatura dele pode variar conforme a cotação do banco.
  • Não ofereça parcelamento nem peça documento ao comprador estrangeiro na sua página.

Authorizations

bearer

Authorization

string obrigatório

Cabeçalho de autenticação Bearer no formato Bearer {{token}} onde {{token}} é o seu token OAuth2.

Escopos requeridos

charges/write

Body

application/json

Content-Type:application/json
JSON
{
  "paymentMethod": "creditcard",
  "externalId": "pedido-2026-0002",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": "+12125550199",
    "address": {
      "country": "US",
      "zipCode": "10001",
      "street": "5th Avenue",
      "number": "350",
      "complement": "Suite 12",
      "neighborhood": "Manhattan",
      "city": "New York",
      "state": "NY"
    }
  },
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "deviceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 130.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "installments": 1,
  "description": "Curso online"
}

Schema

paymentMethodstringobrigatório
Forma de pagamento. Comprador estrangeiro aceita somente creditcard
Valores aceitos:pixcreditcardboletopix_automatico
customerobjectobrigatório
Dados do comprador estrangeiro. Não envie documentNumber
cardTokenstringobrigatório
Token do cartão, gerado no navegador do comprador pelo SDK @validapay/tokenize. Vale 5 minutos e só funciona na conta que o gerou
deviceIdstringobrigatório
Identificação do dispositivo do comprador, devolvida pelo collectDevice do mesmo SDK. Alimenta a análise antifraude
externalIdstringopcional
Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada)
Regra:até 100 caracteres
amountnumberopcional
Valor total em reais (BRL) para cobrança avulsa. Ignorado quando items é enviado
Regra:0.01
itemsarray[1]opcional
Produtos da compra (ou use amount para cobrança avulsa). Preços sempre em reais
installmentsnumberopcional
Comprador estrangeiro paga somente à vista: envie 1 ou omita
Regra:1 a 12
descriptionstringopcional
Descrição livre da cobrança

Headers

Content-Typeopcional
application/json
const url = 'https://sandbox.validapay.com.br/v1/charges';

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {{token}}',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "paymentMethod": "creditcard",
  "externalId": "pedido-2026-0002",
  "customer": {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "phone": "+12125550199",
    "address": {
      "country": "US",
      "zipCode": "10001",
      "street": "5th Avenue",
      "number": "350",
      "complement": "Suite 12",
      "neighborhood": "Manhattan",
      "city": "New York",
      "state": "NY"
    }
  },
  "cardToken": "ctk_9f8s7d6f5g4h3j2k1l0",
  "deviceId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "amount": 130.00,
  "items": [
    {
      "priceId": "price_abc123",
      "quantity": 1
    }
  ],
  "installments": 1,
  "description": "Curso online"
})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

Response Examples

200▾
JSON
{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "status": "paid"
}
402▾
JSON
{
  "success": false,
  "chargeId": "cha_1784065113577_5dw2oyfic",
  "status": "failed",
  "error": "Cartão recusado"
}
403INTERNATIONAL_CHECKOUT_NOT_ENABLED▾
JSON
{
  "error": {
    "message": "Pagamento internacional não habilitado para esta conta. Entre em contato com o suporte da ValidaPay para solicitar a habilitação",
    "code": "INTERNATIONAL_CHECKOUT_NOT_ENABLED"
  }
}
400INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED▾
JSON
{
  "error": {
    "message": "Pagamento internacional aceita apenas cartão de crédito",
    "code": "INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED"
  }
}
400INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED▾
JSON
{
  "error": {
    "message": "Pagamento internacional aceita apenas pagamento à vista",
    "code": "INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED"
  }
}
400INVALID_DATA (endereço)▾
JSON
{
  "error": {
    "message": "Cidade é obrigatória para pagador internacional",
    "code": "INVALID_DATA",
    "details": [
      {
        "code": "custom",
        "path": [
          "customer",
          "address",
          "city"
        ],
        "message": "Cidade é obrigatória para pagador internacional"
      }
    ]
  }
}
400INVALID_DATA (telefone)▾
JSON
{
  "error": {
    "message": "Telefone internacional inválido. Informe no formato E.164 com o DDI do país do endereço (ex.: +12125550199)",
    "code": "INVALID_DATA",
    "details": [
      {
        "code": "custom",
        "path": [
          "customer",
          "phone"
        ],
        "message": "Telefone internacional inválido. Informe no formato E.164 com o DDI do país do endereço (ex.: +12125550199)"
      }
    ]
  }
}

← Anterior

Gerar cobrança Cartão 3DS

Próximo →

Pagar em sandbox