Pagamentos internacionais

A integração pagsmile-payin utiliza uma conexão por App ID, ambiente e região. Ela é separada de integrações Pix e BaaS. Habilitar uma moeda no merchant não contrata um método na adquirente.

Países e métodos

BLIK, BLIK OneClick, PayU PLN/CZK e Chek permanecem indisponíveis até confirmação do contrato e do app correto. Pré-autorização de cartão na Costa Rica também permanece bloqueada: não se deve tratar AUTHORIZED como pagamento concluído ou capturar automaticamente. O nome do app europeu contendo “UK” não habilita métodos britânicos. Métodos descontinuados não são oferecidos.

As rotas da Worldfy são comuns a todas as adquirentes. País, moeda e conexão configurada determinam os recursos disponíveis; a integração usa os mesmos endereços ao trocar ou adicionar uma adquirente.

Descobrir uma capacidade

Consulte GET /v1/charges/methods?country=CO&currency=COP com a autenticação do merchant. A resposta exige moeda habilitada, carteiras disponíveis, método habilitado, taxa configurada e uma conexão com a capacidade selecionada. Os códigos de país públicos são ISO alpha-2 (CO); a integração resolve o código da Pagsmile (COL).

data.methods mantém a lista de métodos do contrato existente. Quando país e moeda são informados, data.payment_capabilities detalha as variantes disponíveis. Uma capacidade identifica a variante exata. Por exemplo, col.nequi.qr, col.nequi.prompt e col.wallet.nequi não são intercambiáveis. A ausência de capacidades significa que o checkout não deve oferecer o método. O catálogo respeita o fluxo e as conexões do merchant. Para cartão por sessão, configure uma rota exclusiva da Pagsmile nessa moeda; fluxos de cartão que misturam adquirentes por bandeira ou divisão de tráfego não permitem escolher esse formulário antes da entrada dos dados do cartão.

Criar uma cobrança

{
  "country": "CO",
  "currency": "COP",
  "amount": 200000,
  "product_type": "digital",
  "payment_method": "nequi",
  "payment_details": { "capability_id": "col.nequi.qr" },
  "customer": { "name": "Cliente Exemplo", "email": "cliente@example.com", "type": "individual" },
  "items": [{ "name": "Pedido", "quantity": 1, "unit_price": 200000, "tangible": false }],
  "return_url": "https://merchant.example.com/resultado"
}

Envie uma Idempotency-Key estável em POST /v1/charges. Em links de pagamento, use o campo idempotency_key de POST /v1/public/checkout/{id}/pay; país, moeda e preço fixo são definidos pelo link. Repita a mesma chave somente com os mesmos dados. Uma resposta pendente deve recuperar a cobrança existente.

amount, frete, itens e taxas fixas usam inteiros na menor unidade da moeda: 200000 COP = 2000,00 COP, 10000 CLP = 10000 CLP. CLP não possui centavos. A precisão da moeda não elimina uma eventual restrição do método a valores inteiros: PSE, por exemplo, exige múltiplos de 100 unidades mínimas de COP.

Instruções e confirmação

As instruções ficam diretamente em data.payment_fields, com payment_method, version = 1, capability_id, next_action e, quando disponíveis, alternatives. A criação e as consultas de cobrança usam esse mesmo formato, sem um objeto payin intermediário:

alternatives pode incluir outra forma de consultar as instruções. Nunca renderize instruções externas como HTML. Os campos públicos de cartão não incluem a Security Key.

O checkout recupera a mesma cobrança após recarregar. GET /v1/public/checkout/charges/by-ref/{linkId}/{ref}/status consulta o estado e as instruções usando a referência da compra. O ref é um identificador de acesso e deve ser mantido privado pelo comprador.

INITIAL, PROCESSING, AUTHORIZED e análise de risco permanecem pendentes. Código 10000, retorno do navegador ou sucesso da chamada ao JavaScript não comprovam pagamento. Somente o servidor confirma captured, após validar notificação assinada ou consultar a ordem no app original.

Bancos, documentos e cartão

PSE e Khipu usam a lista de bancos da conexão e do ambiente. O checkout consulta GET /v1/public/checkout/{id}/payment-methods/{capabilityId}/banks. O servidor verifica novamente o banco antes do envio da ordem. Não use essa consulta genericamente para Cash e BankTransfer.

Informe identification_type junto com customer.tax_id quando o método solicitar documento. A capacidade informa os campos obrigatórios em requires_identification, requires_phone, requires_billing_address, requires_wallet_account e requires_user_ip. Todito exige payment_details.account_number e account_verification_code; o código não é persistido. CPF/CNPJ não são exigidos para compradores internacionais. Nequi por notificação exige telefone; a integração normaliza os códigos telefônicos dos países latino-americanos atendidos.

Equador, Peru e Europa usam a sessão prepay_id com o JavaScript oficial da Pagsmile. Costa Rica, Chile, Colômbia e México usam /card/tokenize no host de segurança e depois /trade/pay; PAGSMILE_PCI_DIRECT_ENABLED=false bloqueia esse segundo fluxo por padrão. Ative-o apenas após aprovação do escopo PCI e dos contratos dos apps. PAN e CVV não são persistidos nas tentativas; credenciais de servidor não são expostas ao navegador. A política própria de 3DS do merchant continua sendo aplicada; a sessão da Pagsmile não é presumida equivalente a uma sessão 3DS da Worldfy.

Contas virtuais

POST /v1/acquirers/connections/{connectionId}/virtual-accounts registra um cliente em uma conexão habilitada:

{
  "capability_id": "per.virtual_account",
  "buyer_id": "cliente-123",
  "customer": { "name": "Cliente Exemplo", "email": "cliente@example.com" }
}

Consulte o cadastro com GET /v1/acquirers/connections/{connectionId}/virtual-accounts/{id}. A consulta exige o merchant proprietário e a mesma conexão usada na criação.

A criação da conta não cria uma cobrança paga. Cada transferência recebida é correlacionada por app, conexão, conta e comprador, validada em sua moeda e convertida em uma cobrança independente. A criação do recebível usa o fluxo financeiro central; não se credita a mesma entrada como depósito BaaS.

Transferências sem correspondência, com valores inválidos ou sem preparo financeiro do merchant ficam para reconciliação. Não atribua automaticamente uma transferência parcial, adicional ou sem referência a um link de valor fixo. Cadastro com resultado unknown não deve ser reenviado: recupere a identidade da conta com a Pagsmile e concilie a operação original.

Estornos e operação

Estornos de cartão utilizam operações duráveis. A aceitação do pedido permanece pendente até confirmação assinada da operação identificada por out_request_no. Cartão mexicano permite apenas estorno integral. Estornos dos demais métodos permanecem bloqueados até habilitação específica; não use o retorno técnico como confirmação financeira.

Saques internacionais permanecem manuais. A moeda original é preservada em cobrança, taxa, recebível e carteira. Esta integração não faz conversão cambial nem liquidação automática em BRL.

Fontes: Payin por país, notificações, JavaScript, consulta de bancos, estornos.