Worldfy PaymentsWorldfy Payments
SuporteDashboard
GuiaAPI Reference
SuporteDashboard

Começando

IntroduçãoAutenticaçãoErrosPaginação e Filtros
Cobranças
Visão GeralMétodos de PagamentoCaptura e Estorno
Financeiro
RecebíveisAntecipaçõesCarteiras e ExtratosSaques
Configuração
Chaves de APIRecebedores
SDK de Segurança
Visão geralTokenizaçãoAutenticação 3DSAnálise de fraudeFluxo simplificadoFluxo completoErrosProdução e segurança
Webhooks
Visão GeralConfiguraçãoRetentativas
Eventos
Eventos de CobrançasEventos de Saques

Visão Geral

Entenda como funcionam cobranças na API Worldfy

Captura e Estorno

Como capturar e estornar cobranças na API Worldfy

Cobranças

Métodos de Pagamento

Como criar cobranças com cada método de pagamento

Campos Comuns

Todos os métodos compartilham os mesmos campos base:

{
  "amount": 10000,
  "currency": "BRL",
  "product_type": "digital",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "tax_id": "12345678901",
    "phone": "11999998888",
    "type": "individual"
  },
  "items": [
    {
      "name": "Curso de Programação",
      "quantity": 1,
      "unit_price": 10000,
      "tangible": false
    }
  ],
  "payment_method": "...",
  "payment_details": {}
}

O campo currency é opcional e usa o formato ISO 4217 de três letras (padrão BRL). Ele é validado contra as moedas ativas da plataforma e normalizado para maiúsculas.

Dados do Cliente (customer)

CampoTipoObrigatórioDescrição
namestringSimNome completo
emailstringSimE-mail
tax_idstringSimCPF (11 dígitos) ou CNPJ (14 dígitos)
phonestringSimTelefone com DDD
typestringSimindividual (PF) ou company (PJ)
birthdatestringNãoData de nascimento

Itens do Pedido (items)

CampoTipoObrigatórioDescrição
namestringSimNome do item
quantityintegerSimQuantidade
unit_priceintegerSimPreço unitário em centavos
tangiblebooleanSimSe é um produto físico
descriptionstringNãoDescrição do item
categorystringNãoCategoria
codestringNãoCódigo SKU

Cartão de Crédito

Para cobranças com cartão de crédito, envie os dados do cartão ou um token no campo payment_details:

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "payment_method": "credit_card",
    "product_type": "digital",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "tax_id": "12345678901",
      "phone": "11999998888",
      "type": "individual"
    },
    "items": [
      { "name": "Curso Online", "quantity": 1, "unit_price": 25000, "tangible": false }
    ],
    "payment_details": {
      "number": "4111111111111111",
      "holder_name": "MARIA SILVA",
      "expiration_month": "12",
      "expiration_year": "2027",
      "cvv": "123",
      "installments": 3,
      "statement_descriptor": "WORLDFY"
    }
  }'
const response = await fetch('https://api.worldfypayments.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 25000,
    payment_method: 'credit_card',
    product_type: 'digital',
    customer: {
      name: 'Maria Silva',
      email: 'maria@email.com',
      tax_id: '12345678901',
      phone: '11999998888',
      type: 'individual',
    },
    items: [
      { name: 'Curso Online', quantity: 1, unit_price: 25000, tangible: false },
    ],
    payment_details: {
      number: '4111111111111111',
      holder_name: 'MARIA SILVA',
      expiration_month: '12',
      expiration_year: '2027',
      cvv: '123',
      installments: 3,
      statement_descriptor: 'WORLDFY',
    },
  }),
});

Campos de payment_details (Cartão de Crédito)

CampoTipoObrigatórioDescrição
numberstringSim*Número do cartão
holder_namestringSim*Nome do titular
expiration_monthstringSim*Mês de expiração (ex: 12)
expiration_yearstringSim*Ano de expiração (ex: 2027)
cvvstringSim*Código de segurança
tokenstringSim*Token do cartão (alternativa aos dados acima)
installmentsintegerNãoNúmero de parcelas (1-24, padrão: 1)
statement_descriptorstringNãoDescrição na fatura (máx. 13 caracteres)

Envie os dados do cartão (number, holder_name, etc.) ou o token. Se informar o token, os demais campos do cartão são ignorados.


Cartão de Débito

Para cobranças com cartão de débito, envie os mesmos dados de cartão usados no crédito. O parcelamento não é suportado — o valor é sempre cobrado em parcela única.

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "payment_method": "debit_card",
    "product_type": "digital",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@email.com",
      "tax_id": "12345678901",
      "phone": "11999998888",
      "type": "individual"
    },
    "items": [
      { "name": "Assinatura Mensal", "quantity": 1, "unit_price": 15000, "tangible": false }
    ],
    "payment_details": {
      "number": "4111111111111111",
      "holder_name": "MARIA SILVA",
      "expiration_month": "12",
      "expiration_year": "2027",
      "cvv": "123",
      "statement_descriptor": "WORLDFY"
    }
  }'
const response = await fetch('https://api.worldfypayments.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 15000,
    payment_method: 'debit_card',
    product_type: 'digital',
    customer: {
      name: 'Maria Silva',
      email: 'maria@email.com',
      tax_id: '12345678901',
      phone: '11999998888',
      type: 'individual',
    },
    items: [
      { name: 'Assinatura Mensal', quantity: 1, unit_price: 15000, tangible: false },
    ],
    payment_details: {
      number: '4111111111111111',
      holder_name: 'MARIA SILVA',
      expiration_month: '12',
      expiration_year: '2027',
      cvv: '123',
      statement_descriptor: 'WORLDFY',
    },
  }),
});

Campos de payment_details (Cartão de Débito)

CampoTipoObrigatórioDescrição
numberstringSim*Número do cartão
holder_namestringSim*Nome do titular
expiration_monthstringSim*Mês de expiração (ex: 12)
expiration_yearstringSim*Ano de expiração (ex: 2027)
cvvstringSim*Código de segurança
tokenstringSim*Token do cartão (alternativa aos dados acima)
statement_descriptorstringNãoDescrição na fatura (máx. 13 caracteres)

Envie os dados do cartão (number, holder_name, etc.) ou o token. Cartão de débito não suporta parcelamento — o campo installments é ignorado e o valor é sempre cobrado em parcela única.


PIX

Cobranças PIX geram um QR Code que o cliente pode pagar instantaneamente:

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "payment_method": "pix",
    "product_type": "digital",
    "customer": {
      "name": "João Santos",
      "email": "joao@email.com",
      "tax_id": "98765432100",
      "phone": "11988887777",
      "type": "individual"
    },
    "items": [
      { "name": "E-book", "quantity": 1, "unit_price": 5000, "tangible": false }
    ],
    "payment_details": {
      "expires_in_seconds": 3600
    }
  }'
const response = await fetch('https://api.worldfypayments.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000,
    payment_method: 'pix',
    product_type: 'digital',
    customer: {
      name: 'João Santos',
      email: 'joao@email.com',
      tax_id: '98765432100',
      phone: '11988887777',
      type: 'individual',
    },
    items: [
      { name: 'E-book', quantity: 1, unit_price: 5000, tangible: false },
    ],
    payment_details: {
      expires_in_seconds: 3600,
    },
  }),
});

Campos de payment_details (PIX)

CampoTipoObrigatórioDescrição
expires_in_secondsintegerNãoTempo de expiração do QR Code em segundos (mínimo: 60)

A resposta incluirá os dados do PIX para apresentar ao cliente (QR Code, código copia-e-cola, etc.).


Boleto

Cobranças por boleto geram um boleto bancário com data de vencimento:

curl -X POST https://api.worldfypayments.com/v1/charges \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 35000,
    "payment_method": "boleto",
    "product_type": "physical",
    "customer": {
      "name": "Ana Costa",
      "email": "ana@email.com",
      "tax_id": "11122233344",
      "phone": "11977776666",
      "type": "individual"
    },
    "billing_address": {
      "street": "Rua das Flores",
      "number": "100",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "zip_code": "01001000"
    },
    "items": [
      { "name": "Camiseta", "quantity": 2, "unit_price": 15000, "tangible": true },
      { "name": "Frete", "quantity": 1, "unit_price": 5000, "tangible": false }
    ],
    "payment_details": {
      "due_date": "2026-03-15",
      "instructions": "Não receber após o vencimento"
    }
  }'
const response = await fetch('https://api.worldfypayments.com/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 35000,
    payment_method: 'boleto',
    product_type: 'physical',
    customer: {
      name: 'Ana Costa',
      email: 'ana@email.com',
      tax_id: '11122233344',
      phone: '11977776666',
      type: 'individual',
    },
    billing_address: {
      street: 'Rua das Flores',
      number: '100',
      neighborhood: 'Centro',
      city: 'São Paulo',
      state: 'SP',
      zip_code: '01001000',
    },
    items: [
      { name: 'Camiseta', quantity: 2, unit_price: 15000, tangible: true },
      { name: 'Frete', quantity: 1, unit_price: 5000, tangible: false },
    ],
    payment_details: {
      due_date: '2026-03-15',
      instructions: 'Não receber após o vencimento',
    },
  }),
});

Campos de payment_details (Boleto)

CampoTipoObrigatórioDescrição
due_datestringSimData de vencimento (formato YYYY-MM-DD)
instructionsstringNãoInstruções de pagamento impressas no boleto
document_numberstringNãoNúmero do documento

Campos Opcionais

Além dos campos obrigatórios, você pode enviar dados adicionais em qualquer cobrança:

CampoTipoDescrição
currencystringMoeda ISO 4217 de três letras (padrão BRL)
shipping_amountintegerValor do frete em centavos
billing_addressobjectEndereço de cobrança
shipping_addressobjectEndereço de entrega
metadataobjectDados adicionais livres (ex: { "order_id": "12345" })
splitarrayRegras de split para dividir o valor entre outros merchants (ver abaixo)

Split de Pagamentos

Para dividir o valor de uma cobrança entre outros merchants, envie o array split na criação da cobrança. Cada entrada define um merchant recebedor e a parcela que ele recebe:

{
  "amount": 10000,
  "payment_method": "pix",
  "split": [
    {
      "recipient_id": "550e8400-e29b-41d4-a716-446655440000",
      "recipient_type": "merchant",
      "type": "percentage",
      "amount": 30,
      "cross_company": false
    }
  ]
}

Campos de cada entrada do split

CampoTipoObrigatórioDescrição
recipient_idstringSimID (UUID) do merchant que recebe a parcela
recipient_typestringSimSempre merchant
typestringSimpercentage (percentual do valor) ou fixed (valor fixo em centavos)
amountintegerSimPercentual (quando percentage) ou valor em centavos (quando fixed)
cross_companybooleanNãoIndica split entre empresas distintas (padrão false)

A soma das parcelas do split não pode exceder o valor total da cobrança. Caso contrário, a API retorna SPLIT_AMOUNT_EXCEEDS_TOTAL ou SPLIT_ALLOCATION_EXCEEDS_TOTAL.

Visão Geral

Entenda como funcionam cobranças na API Worldfy

Captura e Estorno

Como capturar e estornar cobranças na API Worldfy

On this page

Campos ComunsDados do Cliente (customer)Itens do Pedido (items)Cartão de CréditoCampos de payment_details (Cartão de Crédito)Cartão de DébitoCampos de payment_details (Cartão de Débito)PIXCampos de payment_details (PIX)BoletoCampos de payment_details (Boleto)Campos OpcionaisSplit de PagamentosCampos de cada entrada do split