Apple Pay

Com Apple Pay, a sua integração cria uma cobrança pela API e redireciona o comprador para a checkout_url devolvida pela Worldfy. O comprador conclui o pagamento no checkout seguro da Worldfy.

Não é necessário hospedar um botão de Apple Pay nem fazer uma configuração adicional de carteira no domínio da sua loja.

Antes de exibir Apple Pay

Consulte os métodos para a moeda que será cobrada. Com currency, a resposta considera a sua conta e a moeda solicitada.

curl "https://api.worldfypayments.com/v1/charges/methods?currency=EUR" \
  -H "Authorization: Basic {credentials}"

Só apresente Apple Pay se data.methods contiver apple_pay. A moeda e o método precisam estar habilitados para o merchant; uma requisição válida no schema, por si só, não garante disponibilidade de processamento. Não use apenas a detecção do navegador como critério de disponibilidade.

Criar a cobrança

Envie payment_method: "apple_pay" e os campos comuns da cobrança. Não envie payment_details, token de carteira nem split.

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15900,
    "currency": "EUR",
    "payment_method": "apple_pay",
    "product_type": "digital",
    "return_url": "https://sualoja.com.br/pedidos/123",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "tax_id": "12345678901",
      "phone": "11999998888",
      "type": "individual"
    },
    "items": [
      {
        "name": "Curso Online",
        "quantity": 1,
        "unit_price": 15900,
        "tangible": false
      }
    ]
  }'

Na primeira criação bem-sucedida, a API responde com 201 e uma sessão pendente:

{
  "data": {
    "id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
    "status": "pending",
    "payment_fields": {
      "payment_method": "apple_pay"
    },
    "checkout_url": "https://securecheckoutwp.com/wallet/0a1b2c3d-4e5f-6789-abcd-ef0123456789",
    "expires_at": "2026-08-25T18:30:00.000Z",
    "created_at": "2026-08-25T18:15:00.000Z"
  },
  "status": 201,
  "message": "Checkout de carteira criado com sucesso"
}

const result = await response.json();

if (!result.error && result.data.checkout_url) {
  window.location.assign(result.data.checkout_url);
}

Uma repetição com a mesma chave de idempotência pode responder 200 com a mesma sessão e a mesma checkout_url. Reutilize essa URL em vez de criar uma sessão paralela.

Branding da loja e imagens dos produtos

Envie store para apresentar a identidade da loja no checkout. O cabeçalho exibe somente o logo, centralizado; name identifica a loja no título da página e nos rótulos acessíveis. O objeto inteiro é opcional, assim como cada campo: você pode enviar somente name, somente logo_url, ambos ou nenhum. As informações são persistidas na cobrança; o checkout não consulta um cadastro externo para obter o branding.

Os fallbacks são independentes: sem store.name, o título e a identificação acessível usam o nome atual do merchant; sem store.logo_url, aparece a identidade Worldfy. Se o logo não carregar, a identidade Worldfy é usada. Um item sem imagem, ou cuja imagem não carregar, mantém nome, quantidade e preço, sem imagem quebrada.

URLs com credenciais, endereços IP, localhost, hosts locais/privados, caracteres de controle ou protocolos diferentes de HTTPS são recusadas. Não envie URLs data:, HTML, SVG inline ou conteúdo de imagem codificado nesses campos. As imagens são carregadas pelo navegador do comprador, sem proxy ou download pela API; use um servidor público de imagens confiável. Nome, descrição e SKU são apresentados como texto, sem interpretação de HTML.

Os produtos continuam no campo items, com unit_price como preço unitário. code pode identificar o SKU e description pode apresentar detalhes já existentes do produto, como tamanho ou cor. Não existe um campo separado de variação. O preço exibido na linha é quantity × unit_price.

O checkout usa amount como subtotal e amount + shipping_amount como total. O frete aparece somente quando shipping_amount for maior que zero; omitir o campo equivale a zero. O modelo não possui valores separados de desconto nem de taxa cobrada do comprador, portanto essas linhas não são exibidas. A soma dos itens não substitui o subtotal informado na cobrança.

Todos os valores monetários usam unidades mínimas da moeda de currency. O checkout de carteira atual suporta EUR, GBP e USD, todas com duas casas decimais; a moeda escolhida precisa estar habilitada para o merchant e para Apple Pay. Neste exemplo EUR, o subtotal é € 225,00, o frete € 15,00 e o total € 240,00. O checkout mantém a seleção de idioma disponível na interface.

Exemplo completo de corpo para POST /v1/charges, com um produto com imagem e outro sem imagem:

{
  "amount": 22500,
  "shipping_amount": 1500,
  "currency": "EUR",
  "payment_method": "apple_pay",
  "product_type": "physical",
  "return_url": "https://sualoja.com.br/pedidos/123",
  "store": {
    "name": "Loja Aurora",
    "logo_url": "https://assets.sualoja.com.br/logo.png"
  },
  "customer": {
    "name": "Maria Silva",
    "email": "maria@example.com",
    "tax_id": "12345678901",
    "phone": "11999998888",
    "type": "individual"
  },
  "billing_address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310100",
    "country": "BR"
  },
  "shipping_address": {
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310100",
    "country": "BR"
  },
  "items": [
    {
      "name": "Camiseta de algodão",
      "description": "Tamanho M, cor azul",
      "code": "CAM-AZ-M",
      "quantity": 2,
      "unit_price": 10000,
      "tangible": true,
      "image_url": "https://assets.sualoja.com.br/camiseta-azul.jpg"
    },
    {
      "name": "Ecobag",
      "quantity": 1,
      "unit_price": 2500,
      "tangible": true
    }
  ]
}

Os novos campos são opcionais para todos os métodos de criação de cobrança. Integrações existentes podem continuar enviando o corpo anterior. O botão oficial e a autorização Apple Pay permanecem no mesmo fluxo; o branding não altera a disponibilidade de métodos nem habilita Google Pay.

O que acontece depois do redirecionamento

1. O comprador abre a checkout_url da Worldfy.
2. O comprador conclui o pagamento no checkout seguro.
3. A Worldfy atualiza o status da cobrança e envia os eventos configurados para os seus webhooks.
4. A sua integração confirma a compra pelo webhook ou por GET /v1/charges/{id} autenticado.
5. Depois de um estado final, o comprador pode ser encaminhado para a return_url opcional.

O retorno do navegador não é uma confirmação de pagamento. Confirme sempre pelo status da cobrança ou pelo webhook.

return_url precisa ser pública e HTTPS. Ela é apenas o destino final do comprador: não substitui checkout_url e não deve ser usada como sinal de pagamento aprovado.

Expiração e estorno

A sessão expira na data retornada em expires_at. Depois disso, crie uma nova cobrança; não tente reabrir a sessão antiga.

Para estornar uma cobrança Apple Pay capturada, use o endpoint normal POST /v1/charges/{id}/refund. Envie apenas o ID da cobrança Worldfy; nenhum identificador adicional é necessário.

Links de pagamento

Em um link de pagamento hospedado, o checkout público aplica o mesmo fluxo. Quando apple_pay estiver disponível para a moeda, o comprador é levado ao checkout seguro da Worldfy; não é necessária configuração de carteira no domínio da sua loja.

Erros do fluxo

Consulte Erros para HOSTED_WALLET_ACQUIRER_REQUIRED, HOSTED_WALLET_SPLITS_NOT_SUPPORTED, WALLET_CHECKOUT_EXPIRED, WALLET_CHECKOUT_UNAVAILABLE e WALLET_TRANSACTION_NOT_FOUND.