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. 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.

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.