📘

O que você irá aprender com esse artigo?

• Criar Cliente via API
• Criar Método de Pagamento
• Tokenização de cartões de crédito
• Cobrança simples em Cartão de Crédito

Caso de uso

“Preciso que meu cliente consiga pagar por um produto/serviço utilizando o cartão de crédito como método de pagamento num processo simples e com Checkout Transparente.”

Ativar método credit_card

Já ativo? Pule para a etapa 1. Se não, ative o método Cartão de Crédito em sua conta. Para isso, utilize o endpoint Configurar Conta — v1/accounts/configuration. Informe true no parâmetro active do objeto credit_card.

📘

Verifique esta informação

Utilize o endpoint Informações da Conta — v1/accounts/{id}. No objeto configuration > credit_card > active = true (ou false).

1. Criar Cliente (opcional)

Já tem um cliente criado? Utilize o endpoint Listar ou Buscar Cliente — GET v1/customers/{id}. Pule para a etapa 2 com o customer_id.

Se não, utilize o endpoint Criar Cliente — POST v1/customers. Atente-se aos parâmetros:

• email — E-mail do Cliente
• name — Nome do Cliente

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/customers?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "email": "[email protected]",
  "name": "Nome do Cliente"
}
'

{
  "id": "CAD4999627F8418989606750C82FBB6D",
  "email": "[email protected]",
  "name": "Nome do Cliente",
  "notes": null,
  "created_at": "2024-05-28T14:30:55-03:00",
  "updated_at": "2024-05-28T14:30:55-03:00",
  "cc_emails": null,
  "cpf_cnpj": null,
  "zip_code": null,
  "number": null,
  "complement": null,
  "phone": null,
  "phone_prefix": null,
  "custom_variables": [],
  "payment_methods": [],
  "default_payment_method_id": null,
  "proxy_payments_from_customer_id": null,
  "city": null,
  "state": null,
  "district": null,
  "street": null
}

2. Tokenizar Cartão de Crédito

Na iugu, há duas formas de tokenizar os dados de um Cartão de Crédito. São eles:

• Via iugu.js. Saiba mais.
• Via API. Utilize o endpoint Criar Token — v1/payment_token.

🚧

PCI-DSS

Recomendamos as empresas não PCI-DSS utilizarem o iugu.js. Requisições à API Criar Token sujeitará auditorias do próprio PCI.

Request e Response exemplo

curl --location --request POST 'https://api.iugu.com/v1/payment_token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw '{
    "data": {
        "number": "4111111111111111",
        "verification_value": "123",
        "first_name": "Customer",
        "last_name": "Tester",
        "month": "06",
        "year": "2026"
    },
    "account_id": "{{account_id}}",
    "method": "credit_card"
}'

{
  "id": "ac2a7578-41a5-4851-a9c2-6b302c75f37e",
  "method": "credit_card",
  "extra_info": {
    "bin": "411111",
    "year": 2030,
    "month": 6,
    "brand": "VISA",
    "holder_name": "Primeiro Nome Sobrenome",
    "display_number": "XXXX-XXXX-XXXX-1111"
  },
  "test": true
}

3. Cobrar

Com o Token que representa o cartão de crédito, o customer_id ou customer_payment_method_id em mãos, utilize o endpoint Cobrança Direta — POST v1/charge para, de fato, realizar a cobrança.

• customer_id — É possível requisitar esta API sem o token ou customer_payment_method_id, desde que este cliente tenha um Método de Pagamento Padrão adicionado (default_payment_method_id).

🚧

Token de uso único

Qualquer retorno (sucesso ou falha) à requisição ao endpoint v1/charge tornará o token inutilizável. Para reutilização, opte por Criar Forma de Pagamento — v1/customers/{customer_id}/payment_methods

Request e Response exemplo

curl --request POST \
     --url 'https://api.iugu.com/v1/charge?api_token=<seu-api_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payer": {
    "name": "Nome do Pagador",
    "cpf_cnpj": "113.436.750-30"
  },
  "token": "d2a133e0-280c-4401-8624-94cd84254ac5",
  "items": [
    {
      "description": "Descrição do Item",
      "quantity": 1,
      "price_cents": 5000
    }
  ],
  "email": "[email protected]"
}
'

{
  "message": "Autorizado",
  "errors": {},
  "status": "captured",
  "info_message": "Transação capturada",
  "reversible": null,
  "token": "000000000000000000000000000000000000001",
  "brand": null,
  "bin": null,
  "last4": null,
  "issuer": null,
  "success": true,
  "url": "https://checkout.iugu.com/invoices/1a427045-0afc-4bfd-a582-bed6d7141ded-a5d1",
  "pdf": "https://checkout.iugu.com/invoices/1a427045-0afc-4bfd-a582-bed6d7141ded-a5d1.pdf",
  "identification": null,
  "invoice_id": "1A4270450AFC4BFDA582BED6D7141DED",
  "LR": "00"
}

👍

Atribuir uma Fatura à Cobrança Direta

Para cobrar associando a uma fatura, utilize o parâmetro invoice_id. Os dados como payer, customer_id e items serão herdados.

Sequência de Chamadas

Features complementares

Pagamento com 1-clique

O pagamento com 1-clique, amplamente adotado pelos principais e-commerces, permite que os compradores finalizem suas compras utilizando os dados previamente armazenados na loja. Este processo simplificado requer apenas um clique para concluir a transação. Saiba mais.

Siga esta sequência:

1. Armazene os dados previamente. Utilize o endpoint Criar Cliente — POST v1/customers no momento de cadastro ou primeira compra.
2. Opção de Salvar Método de Pagamento. Utilize o endpoint Criar Forma de Pagamento — POST v1/customers/{customer_id}/payment_methods.
   1. Utilize o endpoint Listar Formas de Pagamento — GET v1/customers/{customer_id}/payment_methods para mais opções de escolha (se houver).
3. Cobrar. Utilize o endpoint Cobrança Direta — POST v1/charge. Preencha o parâmetro customer_payment_method_id com o id da etapa 2 (ou etapa 2.1)