These docs are for v2.1. Click to read the latest docs for v4.1.

Cobrança com token de bandeira

Informando os dados essenciais para efetivação de uma cobrança, este recurso permite a criação de uma cobrança de pagamento com token de bandeira previamente gerado.

A Tokenização de Bandeira é o processo de substituição dos dados sensíveis do cartão do portador por tokens de pagamento gerados pelas bandeiras.

🚧

IMPORTANTE

A Cobrança com token de bandeira é diferente da tokenização PagSeguro.

  • Com a Tokenização PagSeguro o cartão de crédito fica armazenado para compras futuras e na resposta da requisição você terá o token do cartão em payment_method.card.id.

  • Com a Cobrança com token de bandeira os dados utilizados para a criação de uma transação são os do próprio Token de Bandeira, fornecido pelas bandeiras e que possui características similiares a um cartão de crédito ou débito.

1. Primeiro passo: Gerar o token de bandeira

Contrate alguma solução para a geração de tokens de bandeira diretamente com as bandeiras.

📘

IMPORTANTE

A cobrança com tokens das bandeiras VISA e MASTER tem a mesma estrutura e solicitam os mesmos dados, contudo a cobrança com token da bandeira ELO solicita dados diferentes.

O sucesso de uma tokenização resulta em dados do token e, em alguns casos, dados adicionais de tokenização, que devem ser informados na criação de uma Cobrança com token de bandeira, como por exemplo:

Mastercard e Visa

  • cryptogram - Criptograma gerado pela bandeira
  • requestor_id - Identificador de quem gerou o token de bandeira (Token Requestor)
  • wallet - Tipo de carteira que armazenou o token de bandeira
  • ecommerce_domain - Identificador do domínio de origem da transação
  • assurance_level - Conteúdo que indica o nível de confiança do token de bandeira

Elo

Quando um token é gerado pela bandeira Elo através de uma carteira digital, é necessário informar dados de autenticação In-App:

  • cavv - Identificador único gerado em cenário de sucesso de autenticação
  • eci - E-Commerce Indicator.

2. Segundo passo: Criar a cobrança

Crie uma Cobrança informando os dados do token de bandeira e, de acordo com a bandeira, dados adicionais de tokenização no objeto token_data ou dados de autenticação no objeto authentication_method, conforme os exemplos a seguir:

Exemplos para as bandeiras VISA e MASTERCARD (Crédito e Débito):

curl --location --request POST 'https://sandbox.api.pagseguro.com/charges' \
--header 'Authorization: {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"reference_id":"ex-00001",
	"description":"Motivo da cobrança",
	"amount":{
		"value":1000,
		"currency":"BRL"
	},
	"payment_method":{
		"type":"CREDIT_CARD",
		"installments":1,
		"capture":true,
		"card":{
			"network_token":"5454555555555555",
			"exp_month":"12",
			"exp_year":"2026",
			"security_code":"123",
			"holder":{
				"name":"Jose da Silva"
			},
			"token_data":{
				"requestor_id":"12345678901",
				"wallet":"APPLE_PAY",
				"cryptogram":"BNQ1qJkmBYWiAAuzyDDhAoABFA==",
				"ecommerce_domain":"br.com.pagseguro",
				"assurance_level":88
			}
		}
	},
	"notification_urls":[
		"https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
	]
}'

{
    "id": "CHAR_E2DE7895-98DE-4B25-8EBC-58072E7F95EA",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-10-20T10:58:14.789-03:00",
    "paid_at": "2021-10-20T10:58:15.000-03:00",
    "description": "Motivo da cobrança",
    "amount": {
        "value": 1000,
        "currency": "BRL",
        "summary": {
            "total": 1000,
            "paid": 1000,
            "refunded": 0
        }
    },
    "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
    },
    "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
            "brand": "mastercard",
            "first_digits": "545455",
            "last_digits": "5555",
            "exp_month": "12",
            "exp_year": "2026",
            "holder": {
                "name": "Jose da Silva"
            },
            "token_data": {
                "requestor_id": "12345678901",
                "wallet": "APPLE_PAY",
                "ecommerce_domain": "br.com.pagseguro",
                "assurance_level": 88
            }
        },
        "soft_descriptor": "MyStore"
    },
    "notification_urls": [
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_E2DE7895-98DE-4B25-8EBC-58072E7F95EA",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_E2DE7895-98DE-4B25-8EBC-58072E7F95EA/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

curl --location --request POST 'https://sandbox.api.pagseguro.com/charges' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key;' \
--data-raw '{
	"reference_id":"ex-00001",
	"description":"Motivo da cobrança",
	"amount":{
		"value":1000,
		"currency":"BRL"
	},
	"payment_method":{
		"type":"DEBIT_CARD",
		"card":{
			"network_token":"4111111111111111",
			"exp_month":"03",
			"exp_year":"2026",
			"security_code":"123",
			"holder":{
				"name":"Jose da Silva"
			},
			"token_data":{
				"requestor_id":"12345678901",
				"wallet":"APPLE_PAY",
				"cryptogram":"BNQ1qJkmBYWiAAuzyDDhAoABFA==",
				"ecommerce_domain":"br.com.pagseguro",
				"assurance_level":99
			}
		},
		"authentication_method":{
			"type":"THREEDS",
			"cavv":"BwABBylVaQAAAAFwllVpAAAAAAA=",
			"xid":"BwABBylVaQAAAAFwllVpAAAAAAA=",
			"eci":"01",
			"version":"2.1.0",
			"dstrans_id":"DIR_SERVER_TID"
		}
	},
	"notification_urls":[
		"https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
	]
}'

{
    "id": "CHAR_DA931E88-E2A3-413D-895F-002712E209AA",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-11-16T15:05:48.352-03:00",
    "paid_at": "2021-11-16T15:05:51.000-03:00",
    "description": "Motivo da cobrança",
    "amount": {
        "value": 1000,
        "currency": "BRL",
        "summary": {
            "total": 1000,
            "paid": 1000,
            "refunded": 0
        }
    },
    "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
    },
    "payment_method": {
        "type": "DEBIT_CARD",
        "card": {
            "brand": "visa",
            "first_digits": "411111",
            "last_digits": "1111",
            "exp_month": "3",
            "exp_year": "2026",
            "holder": {
                "name": "Jose da Silva"
            },
            "token_data": {
                "requestor_id": "12345678901",
                "wallet": "APPLE_PAY",
                "ecommerce_domain": "br.com.pagseguro",
                "assurance_level": 99
            }
        },
        "authentication_method": {
            "type": "THREEDS",
            "eci": "01",
            "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
            "xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
            "version": "2.1.0",
            "dstrans_id": "DIR_SERVER_TID",
            "status": "AUTHENTICATED"
        },
        "soft_descriptor": "MyStore"
    },
    "notification_urls": [
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_DA931E88-E2A3-413D-895F-002712E209AA",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_DA931E88-E2A3-413D-895F-002712E209AA/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

Exemplos para bandeira ELO (Crédito e Débito):

curl --location --request POST 'https://sandbox.api.pagseguro.com/charges' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key;' \
--data-raw '{
   "reference_id":"ex-00001",
   "description":"Motivo da cobrança",
   "amount":{
      "value":1000,
      "currency":"BRL"
   },
   "payment_method":{
      "type":"CREDIT_CARD",
      "installments":1,
      "capture":true,
      "soft_descriptor":"My Store",
      "card":{
         "network_token":"6550000000000001",
         "exp_month":"12",
         "exp_year":"2026",
         "security_code":"123",
         "holder":{
            "name":"Jose da Silva"
         }
      },
      "authentication_method":{
         "type":"INAPP",
         "cavv":"BwABBylVaQAAAAFwllVpAAAAAAA=",
         "eci":"04"
      }
   },
   "notification_urls":[
      "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
   ]
}'

{
    "id": "CHAR_145601C7-4326-4516-B2FC-C910644BD723",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-10-20T16:09:18.664-03:00",
    "paid_at": "2021-10-20T16:09:19.000-03:00",
    "description": "Motivo da cobrança",
    "amount": {
        "value": 1000,
        "currency": "BRL",
        "summary": {
            "total": 1000,
            "paid": 1000,
            "refunded": 0
        }
    },
    "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
    },
    "payment_method": {
        "type": "CREDIT_CARD",
        "installments": 1,
        "capture": true,
        "card": {
            "brand": "elo",
            "first_digits": "655000",
            "last_digits": "0001",
            "exp_month": "12",
            "exp_year": "2026",
            "holder": {
                "name": "Jose da Silva"
            }
        },
        "authentication_method": {
            "type": "INAPP",
            "eci": "04",
            "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA="
        },
        "soft_descriptor": "MyStore"
    },
    "notification_urls": [
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_145601C7-4326-4516-B2FC-C910644BD723",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_145601C7-4326-4516-B2FC-C910644BD723/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

curl --location --request POST 'https://sandbox.api.pagseguro.com/charges' \
--header 'Authorization: Bearer TOKEN' \
--header 'Content-Type: application/json' \
--header 'x-idempotency-key;' \
--data-raw '{
	"reference_id":"ex-00001",
	"description":"Motivo da cobrança",
	"amount":{
		"value":1000,
		"currency":"BRL"
	},
	"payment_method":{
		"type":"DEBIT_CARD",
		"card":{
			"network_token":"6550000000000001",
			"exp_month":"12",
			"exp_year":"2026",
			"security_code":"123",
			"holder":{
				"name":"Jose da Silva"
			}
		},
		"authentication_method":{
			"type":"INAPP",
			"cavv":"BwABBylVaQAAAAFwllVpAAAAAAA=",
			"eci":"04"
		}
	},
	"notification_urls":[
		"https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
	]
}'

{
    "id": "CHAR_EFE8F9C2-B904-44B1-A45F-584100457250",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-10-20T16:05:56.451-03:00",
    "paid_at": "2021-10-20T16:05:58.000-03:00",
    "description": "Motivo da cobrança",
    "amount": {
        "value": 1000,
        "currency": "BRL",
        "summary": {
            "total": 1000,
            "paid": 1000,
            "refunded": 0
        }
    },
    "payment_response": {
        "code": "20000",
        "message": "SUCESSO",
        "reference": "032416400102"
    },
    "payment_method": {
        "type": "DEBIT_CARD",
        "card": {
            "brand": "elo",
            "first_digits": "655000",
            "last_digits": "0001",
            "exp_month": "12",
            "exp_year": "2026",
            "holder": {
                "name": "Jose da Silva"
            }
        },
        "authentication_method": {
            "type": "INAPP",
            "eci": "04",
            "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA="
        },
        "soft_descriptor": "MyStore"
    },
    "notification_urls": [
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_EFE8F9C2-B904-44B1-A45F-584100457250",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_EFE8F9C2-B904-44B1-A45F-584100457250/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}