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

Criando e pagando com autenticação 3DS - Validação externa

Informando os dados essenciais para efetivação de um pagamento, este recurso permite a criação de um pedido com cobrança de pagamento com cartão de crédito ou débito com dados de uma autenticação 3DS.

O 3DS é um protocolo de autenticação de comércio eletrônico que permite o processamento seguro de transações de cartões para pagamentos.

🚧

OBRIGATÓRIO PARA CARTÃO DE DÉBITO

Ao informar os valores no objeto authentication_method.type = THREEDS, a cobrança de uma transação previamente autenticada será realizada.

Para Cartão de Débito este objeto é obrigatório para o processamento da transação.

1. Primeiro passo: Autenticar o cliente

Contrate alguma solução para a realização de autenticações 3DS.

A etapa de autenticação pode ser sem desafio (sem atrito), quando o banco emissor entende que as informações fornecidas são suficientes para autenticar o consumidor ou com desafio (com atrito), quando é necessária uma etapa de validação adicional, uma ação que o consumidor precisa realizar, por exemplo fornecer algum dado enviado via SMS ou a abertura do aplicativo para confirmação da compra. O tipo de desafio fica a critério do banco emissor.

O sucesso de uma autenticação 3DS resulta em alguns dados de autenticação, que devem ser informados na criação de um Pedido com cartão autenticada 3DS, como por exemplo:

  • cavv - Identificador único gerado em cenário de sucesso de autenticação
  • eci - E-Commerce Indicator. Corresponde ao resultado da autenticação
  • xid - Identificador de uma transação de um MPI (Visa/Elo)
  • version - Versão do protocolo 3DS utilizado na autenticação
  • dstrans_id - Id da transação gerada pelo servidor de diretório, durante uma autenticação (Mastercard)

2. Segundo passo: Criar o pedido

Crie um pedido informando os dados de autenticação 3DS no objeto authentication_method com o type = THREEDS, conforme os exemplos a seguir:

Exemplo para Cartão de Crédito:

curl --location --request POST 'https://sandbox.api.pagseguro.com/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {TOKEN}' \
--data-raw '{
    "reference_id": "ex-00001",
    "customer": {
        "name": "Jose da Silva",
        "email": "[email protected]",
        "tax_id": "12345678909",
        "phones": [
            {
                "country": "55",
                "area": "11",
                "number": "999999999",
                "type": "MOBILE"
            }
        ]
    },
    "items": [
        {
            "reference_id": "referencia do item",
            "name": "nome do item",
            "quantity": 1,
            "unit_amount": 500
        }
    ],
    "shipping": {
        "address": {
            "street": "Avenida Brigadeiro Faria Lima",
            "number": "1384",
            "complement": "apto 12",
            "locality": "Pinheiros",
            "city": "São Paulo",
            "region_code": "SP",
            "country": "BRA",
            "postal_code": "01452002"
        }
    },
    "notification_urls": [
        "https://meusite.com/notificacoes"
    ],
    "charges": [
        {
            "reference_id": "referencia da cobranca",
            "description": "descricao da cobranca",
            "amount": {
                "value": 500,
                "currency": "BRL"
            },
                "payment_method":{
        "type":"CREDIT_CARD",
        "installments":1,
        "capture":true,
        "soft_descriptor":"My Store",
        "card":{
            "number":"4111111111111111",
            "exp_month":"03",
            "exp_year":"2026",
            "security_code":"123",
            "holder":{
                "name":"Jose da Silva"
            }
        },
        "authentication_method":{
            "type":"THREEDS",
            "cavv":"BwABBylVaQAAAAFwllVpAAAAAAA=",
            "xid":"BwABBylVaQAAAAFwllVpAAAAAAA=",
            "eci":"05",
            "version":"2.1.0",
            "dstrans_id":"DIR_SERVER_TID"
        }
    }
        }
    ]
}'

{
    "id": "ORDE_18D19860-8210-4682-9A4F-BD3308507E60",
    "reference_id": "ex-00001",
    "created_at": "2023-02-15T14:44:13.769-03:00",
    "customer": {
        "name": "Jose da Silva",
        "email": "[email protected]",
        "tax_id": "12345678909",
        "phones": [
            {
                "type": "MOBILE",
                "country": "55",
                "area": "11",
                "number": "999999999"
            }
        ]
    },
    "items": [
        {
            "reference_id": "referencia do item",
            "name": "nome do item",
            "quantity": 1,
            "unit_amount": 500
        }
    ],
    "shipping": {
        "address": {
            "street": "Avenida Brigadeiro Faria Lima",
            "number": "1384",
            "complement": "apto 12",
            "locality": "Pinheiros",
            "city": "São Paulo",
            "region_code": "SP",
            "country": "BRA",
            "postal_code": "01452002"
        }
    },
    "charges": [
        {
            "id": "CHAR_E5E55042-E50E-4D2C-B49D-3E90185F61B6",
            "reference_id": "referencia da cobranca",
            "status": "PAID",
            "created_at": "2023-02-15T14:44:14.292-03:00",
            "paid_at": "2023-02-15T14:44:16.000-03:00",
            "description": "descricao da cobranca",
            "amount": {
                "value": 500,
                "currency": "BRL",
                "summary": {
                    "total": 500,
                    "paid": 500,
                    "refunded": 0
                }
            },
            "payment_response": {
                "code": "20000",
                "message": "SUCESSO",
                "reference": "032416400102"
            },
            "payment_method": {
                "type": "CREDIT_CARD",
                "installments": 1,
                "capture": true,
                "card": {
                    "brand": "visa",
                    "first_digits": "411111",
                    "last_digits": "1111",
                    "exp_month": "3",
                    "exp_year": "2026",
                    "holder": {
                        "name": "Jose da Silva"
                    }
                },
                "authentication_method": {
                    "type": "THREEDS",
                    "eci": "05",
                    "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                    "xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                    "version": "2.1.0",
                    "dstrans_id": "DIR_SERVER_TID",
                    "status": "AUTHENTICATED"
                },
                "soft_descriptor": "MyStore"
            },
            "links": [
                {
                    "rel": "SELF",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_E5E55042-E50E-4D2C-B49D-3E90185F61B6",
                    "media": "application/json",
                    "type": "GET"
                },
                {
                    "rel": "CHARGE.CANCEL",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_E5E55042-E50E-4D2C-B49D-3E90185F61B6/cancel",
                    "media": "application/json",
                    "type": "POST"
                }
            ]
        }
    ],
    "notification_urls": [
        "https://meusite.com/notificacoes"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_18D19860-8210-4682-9A4F-BD3308507E60",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "PAY",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_18D19860-8210-4682-9A4F-BD3308507E60/pay",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

Exemplo para Cartão de Débito:

curl --location --request POST 'https://sandbox.api.pagseguro.com/orders' \
--header 'Authorization: Bearer {{TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference_id": "ex-00001",
    "customer": {
        "name": "Jose da Silva",
        "email": "[email protected]",
        "tax_id": "12345678909",
        "phones": [
            {
                "country": "55",
                "area": "11",
                "number": "999999999",
                "type": "MOBILE"
            }
        ]
    },
    "items": [
        {
            "reference_id": "referencia do item",
            "name": "nome do item",
            "quantity": 1,
            "unit_amount": 500
        }
    ],
    "shipping": {
        "address": {
            "street": "Avenida Brigadeiro Faria Lima",
            "number": "1384",
            "complement": "apto 12",
            "locality": "Pinheiros",
            "city": "São Paulo",
            "region_code": "SP",
            "country": "BRA",
            "postal_code": "01452002"
        }
    },
    "notification_urls": [
        "https://meusite.com/notificacoes"
    ],
    "charges": [
        {
            "reference_id": "referencia da cobranca",
            "description": "descricao da cobranca",
            "amount": {
                "value": 500,
                "currency": "BRL"
            },
            "payment_method": {
       "type":"DEBIT_CARD",
        "card":{
            "number":"6550000000000001",
            "exp_month":"12",
            "exp_year":"2026",
            "security_code":"123",
            "holder":{
                "name":"Jose da Silva"
            }
        },
        "authentication_method":{
            "type":"THREEDS",
            "cavv":"BwABBylVaQAAAAFwllVpAAAAAAA=",
            "xid":"BwABBylVaQAAAAFwllVpAAAAAAA=",
            "eci":"05",
            "version":"2.1.0",
            "dstrans_id":"DIR_SERVER_TID"
        }
            }
        }
    ]
}'

{
    "id": "ORDE_6F6C1FCA-4A83-4D81-9660-39279FF12E00",
    "reference_id": "ex-00001",
    "created_at": "2023-02-08T16:42:39.888-03:00",
    "customer": {
        "name": "Jose da Silva",
        "email": "[email protected]",
        "tax_id": "12345678909",
        "phones": [
            {
                "type": "MOBILE",
                "country": "55",
                "area": "11",
                "number": "999999999"
            }
        ]
    },
    "items": [
        {
            "reference_id": "referencia do item",
            "name": "nome do item",
            "quantity": 1,
            "unit_amount": 500
        }
    ],
    "shipping": {
        "address": {
            "street": "Avenida Brigadeiro Faria Lima",
            "number": "1384",
            "complement": "apto 12",
            "locality": "Pinheiros",
            "city": "São Paulo",
            "region_code": "SP",
            "country": "BRA",
            "postal_code": "01452002"
        }
    },
    "charges": [
        {
            "id": "CHAR_F0796438-5C00-430B-8B15-D880F38CEBE0",
            "reference_id": "referencia da cobranca",
            "status": "PAID",
            "created_at": "2023-02-08T16:42:40.378-03:00",
            "paid_at": "2023-02-08T16:42:41.000-03:00",
            "description": "descricao da cobranca",
            "amount": {
                "value": 500,
                "currency": "BRL",
                "summary": {
                    "total": 500,
                    "paid": 500,
                    "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": "THREEDS",
                    "eci": "05",
                    "cavv": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                    "xid": "BwABBylVaQAAAAFwllVpAAAAAAA=",
                    "version": "2.1.0",
                    "dstrans_id": "DIR_SERVER_TID",
                    "status": "AUTHENTICATED"
                },
                "soft_descriptor": "IntegracaoPagsegu"
            },
            "links": [
                {
                    "rel": "SELF",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F0796438-5C00-430B-8B15-D880F38CEBE0",
                    "media": "application/json",
                    "type": "GET"
                },
                {
                    "rel": "CHARGE.CANCEL",
                    "href": "https://sandbox.api.pagseguro.com/charges/CHAR_F0796438-5C00-430B-8B15-D880F38CEBE0/cancel",
                    "media": "application/json",
                    "type": "POST"
                }
            ]
        }
    ],
    "notification_urls": [
        "https://meusite.com/notificacoes"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_6F6C1FCA-4A83-4D81-9660-39279FF12E00",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "PAY",
            "href": "https://sandbox.api.pagseguro.com/orders/ORDE_6F6C1FCA-4A83-4D81-9660-39279FF12E00/pay",
            "media": "application/json",
            "type": "POST"
        }
    ]
}