Transacionar utilizando Token de bandeira externo (Pass Through)
Tokenização de bandeira Pass Through
Uma compra não presencial com a Tokenização Pass Through segue o seguinte fluxo:
O Pagar.me recebe os dados transacionais, incluindo o do Network Token enviado pelo lojista, que ao serem enviadas para as adquirentes substituem o envio de informações sensíveis do cartão no fluxo transacional.
O Pagar.me então envia os dados do Network Token para a adquirente, que em seguida faz a comunicação com a bandeira do cartão utilizado e com o banco emissor.
Para utilizar a tokenização Pass Through deve-se alterar as requisições transacionais.
Tokenização Pagar.me
Caso você não consiga tokenizar diretamente com a bandeira (ou seja, exercer o papel de Token Requestor), você pode utilizar a funcionalidade de Tokenização Pagar.me:
Saiba mais sobre Tokenização Pagar.me na qual a Pagar.me é a responsável por tokenizar junto a bandeira.Para utilizar a tokenização Pagar.me não é necessária nenhuma modificação na integração e você tem acesso a todos os benefícios da tokenização de bandeira.
Adquirentes
A Pagar.me está integrada com as principais adquirentes do mercado. É possível transacionar utilizando o Network Token nas seguintes adquirentes:
Stone
Cielo
Adquirentes não integradas
Demais adquirentes ainda não estão habilitadas para transacionar utilizando o Network Token.
A API Pagar.me consegue identificar este cenário e segue operando plenamente pelo fluxo primitivo (utilizando os dados do cartão, como o PAN).
Caso você tenha regras de gateway para adquirentes que aceitam e não aceitam a tokenização, é possível enviar os objetoscard
enetwork_token
na mesma requisição para que a API Pagar.me consiga transacionar em ambas as adquirentes para a mesma transação.
No seu Dashboard:
A transação continuará apresentando as mesmas características de uma transação com cartão de crédito.
Integração
O que irá mudar?
As transações passarão a ser feitas utilizando os dados do Token de Bandeira (Network Token) ao invés dos dados do cartão aberto.
Como preparar a sua integração via API para utilizar Network Token:
No fluxo de criação de Pedidos, devemos incluir o objeto network_token
dentro de credit_card
do nó de payments
. O objeto network_token
substitui o objeto card
e contém as seguintes propriedades:
Atributos | Tipo | Descrição |
---|---|---|
number | string | Número do Network Token. Entre 13 e 19 caracteres. Ex: 4190000000000069 |
holder_name | string | Nome do portador como está impresso no cartão. Máximo de 64 caracteres (Caracteres especiais e números não são aceitos) |
exp_month | int32 | Mês de validade do Network Token. Valor entre 1 e 12 (inclusive) |
exp_year | int32 | Ano de validade do Network Token. Formatos yy ou yyyy. Ex: 23 ou 2023. |
cryptograms | string | Criptograma de autenticação para Network Token. Pode enviar mais de um, caso queira em uma lista de strings. Formato em base64. Ex: ANfQt43bddROAAEnSAMhAAADFA==== |
O Network Token substitui a necessidade das informações do cartão de crédito original. A API Pagar.me v5 aceita o objeto
network_token
como um substituto do objetocard
.O fluxo transacional e as regras de negócio da API são idênticas a uma transação com cartão de crédito.
Pelas definições das bandeiras como Mastercard e Visa, é necessário enviar um novo criptograma gerado pela bandeira no campo
cryptograms
a cada transação realizada utilizando umnetwork_token
.
Exemplo de Requisição:
{
"items": [
{
"amount": 2990,
"description": "Chaveiro do Tesseract",
"quantity": 1
}
],
"customer": {
"name": "Tony Stark",
"email": "[email protected]"
},
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"capture": false,
"installments": 1,
"statement_descriptor": "AVENGERS",
"network_token": {
"number": "4190000000000010",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 30,
"cryptograms": [
"ANfQt43bddROAAEnSAMhAAADFA===="
],
"billing_address": {
"line_1": "10880, Malibu Point, Malibu Central",
"zip_code": "90265",
"city": "Malibu",
"state": "CA",
"country": "US"
}
}
}
}
]
}
{
"id": "or_q9XPwXOuBQI3AV8Z",
"code": "KLQ2FNVB17",
"amount": 2990,
"currency": "BRL",
"closed": true,
"items": [
{
"id": "oi_2GNXdM7F88Tw9nQj",
"type": "product",
"description": "Chaveiro do Tesseract",
"amount": 2990,
"quantity": 1,
"status": "active",
"created_at": "2023-02-16T13:25:55Z",
"updated_at": "2023-02-16T13:25:55Z"
}
],
"customer": {
"id": "cus_xBWrv8ltDEc7v8KV",
"name": "Tony Stark",
"email": "[email protected]",
"delinquent": false,
"created_at": "2023-02-16T12:22:13Z",
"updated_at": "2023-02-16T13:25:18Z",
"phones": {}
},
"status": "pending",
"created_at": "2023-02-16T13:25:55Z",
"updated_at": "2023-02-16T13:25:56Z",
"closed_at": "2023-02-16T13:25:55Z",
"charges": [
{
"id": "ch_Gv3lK2cn1tqLZqdK",
"code": "KLQ2FNVB17",
"amount": 2990,
"status": "pending",
"currency": "BRL",
"payment_method": "credit_card",
"created_at": "2023-02-16T13:25:55Z",
"updated_at": "2023-02-16T13:25:56Z",
"customer": {
"id": "cus_xBWrv8ltDEc7v8KV",
"name": "Tony Stark",
"email": "[email protected]",
"delinquent": false,
"created_at": "2023-02-16T12:22:13Z",
"updated_at": "2023-02-16T13:25:18Z",
"phones": {}
},
"last_transaction": {
"operation_key": "107132490",
"id": "tran_1vY7WgJ9UPt5VQRD",
"transaction_type": "credit_card",
"gateway_id": "26e4c3cf-f910-4dab-8306-6be4ed8ae3f7",
"amount": 2990,
"status": "authorized_pending_capture",
"success": true,
"installments": 1,
"installment_type": "merchant",
"statement_descriptor": "AVENGERS",
"acquirer_name": "simulator",
"acquirer_tid": "685417787",
"acquirer_nsu": "28973",
"acquirer_auth_code": "224",
"acquirer_message": "Transação autorizada com sucesso",
"acquirer_return_code": "00",
"entry_mode": "ecommerce",
"operation_type": "auth_only",
"network_token": {
"id": "nt_YlZX9YnpieCpBjwE",
"first_six_digits": "419000",
"last_four_digits": "0010",
"brand": "Visa",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 2030,
"created_at": "2023-02-16T13:25:19Z",
"updated_at": "2023-02-16T13:25:19Z",
"status": "active",
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Malibu Central",
"city": "Malibu",
"state": "CA",
"country": "US"
}
},
"payment_type": "Token",
"created_at": "2023-02-16T13:25:55Z",
"updated_at": "2023-02-16T13:25:55Z",
"gateway_response": {
"code": "200",
"errors": []
},
"antifraud_response": {},
"metadata": {}
}
}
]
}
{
"items": [
{
"amount": 2990,
"description": "Chaveiro do Tesseract",
"quantity": 1
}
],
"amount": "2990",
"customer": {
"name": "Tony Stark",
"email": "[email protected]"
},
"payments": [
{
"payment_method": "credit_card",
"credit_card": {
"card": {
"billing_address": {
"line_1": "10880, Malibu Point, Malibu Central",
"zip_code": "90265",
"city": "Malibu",
"state": "CA",
"country": "US"
},
"number": "4327983295276633",
"holder_name": "Homelander",
"exp_month": 04,
"exp_year": 24,
"cvv": "873"
},
"network_token": {
"number": "4000000000000010",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 30,
"cryptograms": [
"ANfQt43bddROAAEnSAMhAAADFA===="
],
}
}
}
]
}
{
"id": "or_wRO9WWXFZcyZ9BdZ",
"code": "JKYC81BVD3",
"amount": 2990,
"currency": "BRL",
"closed": true,
"items": [
{
"id": "oi_7aBR6Ata1CoPVreM",
"type": "product",
"description": "Chaveiro do Tesseract",
"amount": 2990,
"quantity": 1,
"status": "active",
"created_at": "2023-02-16T13:26:27Z",
"updated_at": "2023-02-16T13:26:27Z"
}
],
"customer": {
"id": "cus_7gvBW06CehZ4nre9",
"name": "Tony Stark",
"email": "[email protected]",
"delinquent": false,
"created_at": "2023-02-16T13:03:43Z",
"updated_at": "2023-02-16T13:03:43Z",
"phones": {}
},
"status": "failed",
"created_at": "2023-02-16T13:26:27Z",
"updated_at": "2023-02-16T13:26:27Z",
"closed_at": "2023-02-16T13:26:27Z",
"charges": [
{
"id": "ch_eqkd7wP3frFqxvnJ",
"code": "JKYC81BVD3",
"amount": 2990,
"status": "failed",
"currency": "BRL",
"payment_method": "credit_card",
"created_at": "2023-02-16T13:26:27Z",
"updated_at": "2023-02-16T13:26:27Z",
"customer": {
"id": "cus_7gvBW06CehZ4nre9",
"name": "Tony Stark",
"email": "[email protected]",
"delinquent": false,
"created_at": "2023-02-16T13:03:43Z",
"updated_at": "2023-02-16T13:03:43Z",
"phones": {}
},
"last_transaction": {
"operation_key": "268288889",
"id": "tran_KJwOvMyIyCYEvM4m",
"transaction_type": "credit_card",
"gateway_id": "2e02feb7-68c3-48ff-9633-3703ca71ffc2",
"amount": 2990,
"status": "not_authorized",
"success": false,
"installments": 1,
"installment_type": "merchant",
"acquirer_name": "simulator",
"acquirer_tid": "898358270",
"acquirer_nsu": "51271",
"acquirer_message": "Transação não autorizada",
"acquirer_return_code": "01",
"entry_mode": "ecommerce",
"operation_type": "auth_and_capture",
"card": {
"id": "card_Ovx2mLMuMgUm5LVZ",
"first_six_digits": "432798",
"last_four_digits": "6633",
"brand": "Visa",
"holder_name": "Homelander",
"exp_month": 4,
"exp_year": 2024,
"status": "active",
"type": "credit",
"created_at": "2023-02-16T13:03:44Z",
"updated_at": "2023-02-16T13:03:44Z",
"billing_address": {
"zip_code": "90265",
"city": "Malibu",
"state": "CA",
"country": "US",
"line_1": "10880, Malibu Point, Malibu Central"
}
},
"network_token": {
"id": "nt_ArXmkyT45IvZn6yd",
"first_six_digits": "400000",
"last_four_digits": "0010",
"brand": "Visa",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 2030,
"created_at": "2023-02-16T13:04:09Z",
"updated_at": "2023-02-16T13:04:09Z",
"status": "active"
},
"payment_type": "Token",
"created_at": "2023-02-16T13:26:27Z",
"updated_at": "2023-02-16T13:26:27Z",
"gateway_response": {
"code": "200",
"errors": []
},
"antifraud_response": {},
"metadata": {}
}
}
]
}
{
"amount": 2990,
"customer": {
"name": "Tony Stark",
"email": "[email protected]"
},
"payment": {
"payment_method": "credit_card",
"credit_card": {
"statement_descriptor": "AVENGERS",
"network_token": {
"number": "4190000000000010",
"holder_name": "Tony Stark",
"exp_month": 12,
"exp_year": 2030,
"token_requestor_id": "50110540444",
"cryptograms": [
"ANfQt43bddROAAEnSAMhAAADFA===="
],
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Central Malibu",
"city": "Malibu",
"state": "CA",
"country": "US"
}
}
}
},
"metadata": {
"code": "123"
}
}
{
"id": "ch_34kbq0XLI7S2qQmD",
"code": "0KGVFD2TV9",
"amount": 2990,
"paid_amount": 2990,
"status": "paid",
"currency": "BRL",
"payment_method": "credit_card",
"paid_at": "2023-02-16T13:34:00Z",
"created_at": "2023-02-16T13:34:00Z",
"updated_at": "2023-02-16T13:34:00Z",
"customer": {
"id": "cus_vD74PNjIySYPdR9y",
"name": "Tony Stark",
"email": "[email protected]",
"document": "34018569289",
"type": "individual",
"delinquent": false,
"created_at": "2023-02-16T13:05:51Z",
"updated_at": "2023-02-16T13:06:43Z",
"phones": {}
},
"last_transaction": {
"operation_key": "975809555",
"id": "tran_ArX1KEaUEulK38g5",
"transaction_type": "credit_card",
"gateway_id": "2cc4cf15-fa9b-4330-b89a-a4c5cda6761c",
"amount": 2990,
"status": "captured",
"success": true,
"installments": 1,
"installment_type": "merchant",
"statement_descriptor": "AVENGERS",
"acquirer_name": "simulator",
"acquirer_tid": "129460491",
"acquirer_nsu": "50766",
"acquirer_auth_code": "932",
"acquirer_message": "Transação capturada com sucesso",
"acquirer_return_code": "00",
"entry_mode": "ecommerce",
"operation_type": "auth_and_capture",
"network_token": {
"id": "nt_29nmd9wfJUZRkYN4",
"first_six_digits": "419000",
"last_four_digits": "0010",
"brand": "Visa",
"holder_name": "Tony Stark",
"exp_month": 12,
"exp_year": 2030,
"created_at": "2023-02-16T13:05:51Z",
"updated_at": "2023-02-16T13:05:51Z",
"status": "active",
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Central Malibu",
"city": "Malibu",
"state": "CA",
"country": "US"
}
},
"payment_type": "Token",
"created_at": "2023-02-16T13:34:00Z",
"updated_at": "2023-02-16T13:34:00Z",
"gateway_response": {
"code": "200",
"errors": []
},
"antifraud_response": {},
"metadata": {}
},
"metadata": {
"code": "123"
}
}
{
"billing_type": "prepaid",
"payment_method": "credit_card",
"interval": "day",
"interval_count": 1,
"installments": 1,
"items": [
{
"name": "Silver",
"description": "Com anuncios",
"quantity": 1,
"pricing_scheme": {
"price": 2000
}
}
],
"setup": {
"amount": 4990,
"description": "Matricula da assinatura",
"payment": {
"metadata": {
"mundipagg_payment_method_code": "19"
},
"gateway_affiliation_id": "6a507067-4435-4f45-9e38-7103de8cc91b",
"payment_method": "credit_card",
"credit_card": {
"installments": 1,
"statement_descriptor": "SETUP",
"network_token": {
"number": "4190000000000010",
"holder_name": "Tony Stark",
"exp_month": 1,
"exp_year": 30,
"cryptograms": [
"ANfQt43bddROAAEnSAMhAAADFA===="
],
"billing_address": {
"line_1": "10880, Malibu Point, Malibu Central",
"zip_code": "90265",
"city": "Malibu",
"state": "CA",
"country": "US"
}
}
}
}
},
"customer": {
"name": "Tony Stark",
"email": "[email protected]",
"document": "34018569289",
"type": "individual"
},
"gateway_affiliation_id": "6a507067-4435-4f45-9e38-7103de8cc91b",
"metadata": {
"mundipagg_payment_method_code": "19"
},
"card": {
"holder_name": "Subs Stark",
"number": "5184497224393053",
"exp_month": 6,
"exp_year": 2025,
"cvv": "571",
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Central Malibu",
"city": "Malibu",
"state": "CA",
"country": "US"
}
}
}
{
"items": [
{
"amount": 2990,
"description": "Teste de débito",
"quantity": 1,
"code": "123"
}
],
"customer": {
"name": "Tony Stark",
"email": "[email protected]",
"document": "93095135270",
"type": "individual",
"document_type": "CPF",
"address": {
"line_1": "375, Av. General Justo, Centro",
"line_2": "8º andar",
"zip_code": "20021130",
"city": "Rio de Janeiro",
"state": "RJ",
"country": "BR"
}
},
"payments": [
{
"payment_method": "debit_card",
"debit_card": {
"capture": false,
"installments": 1,
"statement_descriptor": "AVENGERS",
"network_token": {
"number": "5256621004565548",
"holder_name": "Tony Stark",
"exp_month": 12,
"exp_year": 2023,
"cryptograms": [
"ANfQt43bddROAAEnSAMhAAADFA===="
],
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Central Malibu",
"city": "Malibu",
"state": "CA",
"country": "US"
}
}
},
}
]
}
{
"id": "or_nEA3rVEC7TqOVWM2",
"code": "W2NQAEJF3J",
"amount": 2990,
"currency": "BRL",
"closed": true,
"items": [
{
"id": "oi_2jdEG82C8Cz5wLy4",
"type": "product",
"description": "Teste de débito",
"amount": 2990,
"quantity": 1,
"status": "active",
"created_at": "2023-04-14T18:13:25Z",
"updated_at": "2023-04-14T18:13:25Z",
"code": "123"
}
],
"customer": {
"id": "cus_4qN8MKbCxt8aDovj",
"name": "Tony Stark",
"email": "[email protected]",
"document": "93095135270",
"document_type": "cpf",
"type": "individual",
"delinquent": false,
"address": {
"id": "addr_bve7jDhwvsm5orDk",
"line_1": "375, Av. General Justo, Centro",
"line_2": "8º andar",
"zip_code": "20021130",
"city": "Rio de Janeiro",
"state": "RJ",
"country": "BR",
"status": "active",
"created_at": "2023-04-14T18:13:16Z",
"updated_at": "2023-04-14T18:13:16Z"
},
"created_at": "2023-04-14T18:13:16Z",
"updated_at": "2023-04-14T18:13:16Z",
"phones": {}
},
"status": "paid",
"created_at": "2023-04-14T18:13:25Z",
"updated_at": "2023-04-14T18:13:28Z",
"closed_at": "2023-04-14T18:13:25Z",
"charges": [
{
"id": "ch_K83x0jXHMLumQalm",
"code": "W2NQAEJF3J",
"gateway_id": "f942829d-4a63-47b2-9af1-bef65ced0a5a",
"amount": 2990,
"paid_amount": 2990,
"status": "paid",
"currency": "BRL",
"payment_method": "debit_card",
"paid_at": "2023-04-14T18:13:27Z",
"created_at": "2023-04-14T18:13:25Z",
"updated_at": "2023-04-14T18:13:27Z",
"customer": {
"id": "cus_4qN8MKbCxt8aDovj",
"name": "Tony Stark",
"email": "[email protected]",
"document": "93095135270",
"document_type": "cpf",
"type": "individual",
"delinquent": false,
"address": {
"id": "addr_bve7jDhwvsm5orDk",
"line_1": "375, Av. General Justo, Centro",
"line_2": "8º andar",
"zip_code": "20021130",
"city": "Rio de Janeiro",
"state": "RJ",
"country": "BR",
"status": "active",
"created_at": "2023-04-14T18:13:16Z",
"updated_at": "2023-04-14T18:13:16Z"
},
"created_at": "2023-04-14T18:13:16Z",
"updated_at": "2023-04-14T18:13:16Z",
"phones": {}
},
"last_transaction": {
"id": "tran_BaQ7M70FRiQbVZew",
"transaction_type": "debit_card",
"gateway_id": "db376787-7071-49d4-9ab0-a3a5d4d176f2",
"amount": 2990,
"status": "captured",
"success": true,
"statement_descriptor": "AVENGERS",
"acquirer_name": "stone",
"acquirer_affiliation_code": "266B24CD5F429E56134743A01287BACB",
"acquirer_tid": "20430073908801",
"acquirer_nsu": "20430073908801",
"acquirer_auth_code": "908801",
"acquirer_message": "Stone|Aprovado",
"acquirer_return_code": "0000",
"operation_type": "capture",
"network_token": {
"id": "nt_doLl3pGmUrIo5Pgn",
"first_six_digits": "525662",
"last_four_digits": "5548",
"brand": "Mastercard",
"holder_name": "Tony Stark",
"exp_month": 12,
"exp_year": 2023,
"created_at": "2023-04-14T18:13:16Z",
"updated_at": "2023-04-14T18:13:16Z",
"status": "active",
"billing_address": {
"street": "Malibu Point",
"number": "10880",
"zip_code": "90265",
"neighborhood": "Central Malibu",
"city": "Malibu",
"state": "CA",
"country": "US"
}
},
"payment_type": "Token",
"created_at": "2023-04-14T18:13:25Z",
"updated_at": "2023-04-14T18:13:25Z",
"gateway_response": {
"code": "201",
"errors": []
},
"antifraud_response": {},
"metadata": {}
},
}
]
}
Para transações com o cartão de débito basta alterar o nó de credit_card
para debit_card
.
Para simular transações utilizando o Network Token definimos algumas regras que devem ser utilizadas. Cada uma dessas regras implica em uma resposta específica da API, e dessa forma você pode testar transações de maneira completa, verificando como tratar as respostas da nossa API e entendendo totalmente o funcionamento dela.
Entenda mais sobre o Simulador de Network Token aqui.
Casos de uso
O cliente pode enviar os dados de Network Token nos seguintes cenários transacionais:
- Criação de pedido
- Criação de cobranças
- Criação de assinaturas (pré-pagas e setup)
Perguntas frequentes
Qual a diferença entre Token de bandeira (Network Token) vs Card_id/Token id?
A Tokenização de Bandeira é realizada junto as bandeiras dos cartões, e consiste no processo de substituição dos dados sensíveis do cartão do portador por um Network Token, adicionando maior segurança, conversão e demais benefícios.
O Card_id/Token id, é utilizado como um identificador, para que você cliente possa referenciar os cartões na Wallet da Pagar.me, ou seja, armazenar os cartões dos seus clientes para futuras compras.
A Tokenização Pagar.me não afeta o uso do Card_id/Token id, assim como o contrário também é verdadeiro.
E se ocorrer falha ao provisionar o Token de Bandeira (Network Token) do lado do cliente? Ou seja não foi possível tokenizar o cartão do portador?
Neste caso, é possível seguir enviando os dados do cartão de crédito normalmente, o uso do Pass Through não elimina/desativa o método mais primitivo de transacionar.
Caso desejar, o cliente pode seguir enviando ambos os dados (cartão de crédito+Network Token), em tal caso o Network Token sempre terá a prioridade na hora de transacionar na adquirente.
Caso eu não seja um Token Requestor, ou não transacione utilizando o Network Token, o que pode acontecer?
Em um futuro próximo todas as transações serão tokenizadas, e as transações não tokenizadas provavelmente terão um custo maior a partir de uma data definida pela bandeira. O custo para tokenizar com a gente é zero.
Saiba mais sobre Tokenização Pagar.me na qual a Pagar.me é a responsável por tokenizar junto a bandeira.