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

Cobrança com cartão autenticada 3DS

Informando os dados essenciais para efetivação de uma cobrança, este recurso permite a criação de uma 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 uma Cobrança 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
  • version - Versão do protocolo 3DS utilizado na autenticação
  • dstrans_id - Id da transação gerada pelo servidor de diretório

2. Segundo passo: Criar a cobrança

Crie uma Cobrança 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/charges' \
--header 'Authorization: {{token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "reference_id":"ex-00001",
    "description":"Motivo do pagamento",
    "amount":{
        "value":1000,
        "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"
        }
    },
    "notification_urls":[
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ]
}'

{
    "id": "CHAR_D8BC9CC5-50CC-4C74-80C4-E8D8CA5E6080",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-11-04T10:18:29.812-03:00",
    "paid_at": "2021-11-04T10:18:30.000-03:00",
    "description": "Motivo do pagamento",
    "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": "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"
    },
    "notification_urls": [
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ],
    "links": [
        {
            "rel": "SELF",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_D8BC9CC5-50CC-4C74-80C4-E8D8CA5E6080",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_D8BC9CC5-50CC-4C74-80C4-E8D8CA5E6080/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}

Exemplo para Cartão de 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 do pagamento",
    "amount":{
        "value":1000,
        "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"
        }
    },
    "notification_urls":[
        "https://yourserver.com/nas_ecommerce/277be731-3b7c-4dac-8c4e-4c3f4a1fdc46/"
    ]
}'

{
    "id": "CHAR_6892D65B-E376-4E71-B8AA-BA1A87D6E0D5",
    "reference_id": "ex-00001",
    "status": "PAID",
    "created_at": "2021-11-04T10:20:20.582-03:00",
    "paid_at": "2021-11-04T10:20:22.000-03:00",
    "description": "Motivo do pagamento",
    "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": "THREEDS",
            "eci": "05",
            "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_6892D65B-E376-4E71-B8AA-BA1A87D6E0D5",
            "media": "application/json",
            "type": "GET"
        },
        {
            "rel": "CHARGE.CANCEL",
            "href": "https://sandbox.api.pagseguro.com/charges/CHAR_6892D65B-E376-4E71-B8AA-BA1A87D6E0D5/cancel",
            "media": "application/json",
            "type": "POST"
        }
    ]
}