# Gerar cobrança Cartão internacional

**Área:** Checkout Transparente

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](/referencia/post-gerar-cobranca-cartao) — `POST /v1/charges` com `paymentMethod: "creditcard"`, `cardToken` e `deviceId` gerados pelo SDK de tokenização ([detalhes neste link](/sdks/tokenizacao)). 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`

**Scopes necessários:** `charges/write`

## 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](/referencia/post-criar-link-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`**:

```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"
  }
}
```

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](/referencia/post-gerar-cobranca-cartao): 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](/referencia/post-criar-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](/referencia/post-gerar-cobranca-cartao): 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.

### Request body

```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"
}
```

### Campos do body

**Obrigatórios:** `paymentMethod`, `customer`, `customer.name`, `customer.email`, `customer.address`, `customer.address.country`, `customer.address.zipCode`, `customer.address.street`, `customer.address.number`, `customer.address.city`, `customer.address.state`, `cardToken`, `deviceId`, `items.priceId`

| Campo | Descrição |
|---|---|
| `paymentMethod` | Forma de pagamento. Comprador estrangeiro aceita somente creditcard |
| `customer` | Dados do comprador estrangeiro. Não envie documentNumber |
| `customer.name` | Nome completo |
| `customer.email` | E-mail |
| `customer.address` | Endereço de cobrança. O campo country diferente de BR é o que torna a cobrança internacional |
| `customer.address.country` | País no padrão ISO 3166-1 alfa-2. Diferente de BR torna a cobrança internacional |
| `customer.address.zipCode` | Código postal no formato do país |
| `customer.address.street` | Rua ou logradouro |
| `customer.address.number` | Número |
| `customer.address.city` | Cidade |
| `customer.address.state` | Estado, província ou região |
| `cardToken` | Token do cartão, gerado no navegador do comprador pelo SDK @validapay/tokenize. Vale 5 minutos e só funciona na conta que o gerou |
| `deviceId` | Identificação do dispositivo do comprador, devolvida pelo collectDevice do mesmo SDK. Alimenta a análise antifraude |
| `items.priceId` | ID do preço do produto |

**Opcionais**

| Campo | Descrição |
|---|---|
| `externalId` | Identificador único do pedido no seu sistema; usado como idempotencyKey (evita cobrança duplicada) |
| `customer.phone` | Telefone no formato E.164, com + e o código do país informado em address.country |
| `customer.address.complement` | Complemento |
| `customer.address.neighborhood` | Bairro ou distrito |
| `amount` | Valor total em reais (BRL) para cobrança avulsa. Ignorado quando items é enviado (mín.: 0.01) |
| `items` | Produtos da compra (ou use amount para cobrança avulsa). Preços sempre em reais |
| `items.quantity` | Quantidade (default 1) |
| `installments` | Comprador estrangeiro paga somente à vista: envie 1 ou omita |
| `description` | Descrição livre da cobrança |

### Resposta 200: 200

```json
{
  "success": true,
  "customerId": "cus_xxx",
  "chargeId": "cha_abc123",
  "status": "paid"
}
```


### Resposta 402: 402

```json
{
  "success": false,
  "chargeId": "cha_1784065113577_5dw2oyfic",
  "status": "failed",
  "error": "Cartão recusado"
}
```


### Resposta 403: 403 INTERNATIONAL_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"
  }
}
```


### Resposta 400: 400 INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED

```json
{
  "error": {
    "message": "Pagamento internacional aceita apenas cartão de crédito",
    "code": "INTERNATIONAL_PAYMENT_METHOD_NOT_SUPPORTED"
  }
}
```


### Resposta 400: 400 INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED

```json
{
  "error": {
    "message": "Pagamento internacional aceita apenas pagamento à vista",
    "code": "INTERNATIONAL_INSTALLMENTS_NOT_SUPPORTED"
  }
}
```


### Resposta 400: 400 INVALID_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"
      }
    ]
  }
}
```


### Resposta 400: 400 INVALID_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)"
      }
    ]
  }
}
```


---

Página: https://docs.validapay.com.br/referencia/post-gerar-cobranca-cartao-internacional  
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json