📘

O que você irá aprender com esse artigo?

• Alterar o método de pagamento
• Consultar o cartão default (padrão)
• Consultar cartões de um cliente

Caso de uso

“Um cliente deseja alterar o cartão de crédito de sua assinatura ou inserir um novo para uma compra específica”.

Diagrama de sequência

Alterar o método de pagamento

Toda vez que tiver de criar uma cobrança via cartão de crédito, esse item de ser validado através do processo de tokenização, que basicamente garante segurança ao criptonizar os dados. Esse processo pode ser realizado de duas maneiras:

1. Iugu JS

Para empresas que não são PCI Dss (Padrão de Segurança de Dados da Indústria de Pagamento com Cartão), o indicado e que o processo de tokenização utilize o método iugu.js. Com esse código de javascript inserido na sua webpage, você garante que os dados de cartão inseridos pelo cliente serão coletados apenas pelo front-end da sua aplicação. O método iugu.js irá retornar o token desse cartão que você poderá usar para realizar a cobrança direta ou criar a forma de pagamento.

2. Direto via Api

Agora, se sua empresa tenha a certificação PCI Dss, você pode realizar esse processo de tokenização diretamente na API com uma chamada POST na API Criar Token, onde será gerado um token id e retornado no response.

Modelo de request

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": "4111 1111 1111 1111",
        "verification_value": "123",
        "first_name": "Customer",
        "last_name": "Tester",
        "month": "06",
        "year": "2026"
    },
    "account_id": "{{account_id}}",
    "method": "credit_card"
}'

Modelo de response

Com esse token, é preciso criar uma forma de pagamento através da api Criar Forma de Pagamento. Dessa maneira, você terá como retorno o identificador desse novo cartão (id).

Modelo de request

curl --location --request POST 'https://api.iugu.com/v1/customers/{{customer_id}}/payment_methods' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw '{
     "token": "31d033ce-c21f-44a3-afd4-ad547fb0eca7",
     "description": "Teste  3",
     "set_as_default": true
}'

Modelo de response

Como esse cliente já tem uma forma de pagamento atrelada ao seu perfil, para alterá-la precisamos realizar uma nova chamada na API Alterar Forma de Pagamento.

Modelo de request

curl --location --request PUT 'https://api.iugu.com/v1/customers/F224FD03ED7F4F5892999B3600EABD94/payment_methods/{{payment_method_id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw ''

Modelo de response

Uma vez realizada essa alteração, as próximas cobranças serão feitas no novo cartão de crédito.

OBS.: O mesmo processo deve ser realizado caso o cliente deseje fazer uma compra avulsa com um novo método de pagamento.

Consultar o cartão default (padrão)

Para consultar qual o cartão padrão para as transações de um cliente, basta realizar uma consulta na API Buscar Cliente, passando o id do cliente na url, onde será apresentado uma propriedade chamada default_payment_method_id.

Modelo de request

curl --location -g --request GET 'https://api.iugu.com/v1/customers?{{customer_id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw ''

Modelo de response

Após obter o id com a propriedade default_payment_method_id e com o id do cliente, é possível consultar na api Buscar Forma de Pagamento os primeiros e últimos dígitos do cartão desse cliente. Também será apresentada a seguinte response:

Modelo de request

curl --location --request GET 'https://api.iugu.com/v1/customers/{{customer_id}}/payment_methods/{{payment_method_id}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw ''

Modelo de response

Na propriedade display_number é possível consultar os 4 últimos dígitos do cartão, enquanto que em bin você confere os primeiros dígitos.

Consultar cartões de um cliente

Para consultar os cartões de crédito de um cliente basta realizar uma chamada GET na API Listar Formas de Pagamento, inserindo o id do cliente.

Modelo de request

curl --location --request GET 'https://api.iugu.com/v1/customers/{{customer_id}}/payment_methods' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{api_token in base64}}' \
--header 'Cookie: __cfruid=ca1be8a3bc81800098d0c3711c4f38bddca4926f-1626092966' \
--data-raw ''

Modelo de retorno