Pagamento com cartão de crédito

Fluxo de pagamento com cartão de crédito e 3DS na My Gateway: tokenização do cartão, criação do pagamento e tratamento do desafio.

Nesta página

O pagamento com cartão usa autenticação 3DS. Antes de criar o pagamento, o checkout inicializa o SDK 3DS no navegador e o seu backend tokeniza o cartão.

Fluxo#

Gere o sessionId
No início do checkout, gere um sessionId único para a tentativa.
Inicialize o SDK 3DS
Use o domínio do checkout e o mesmo sessionId. Veja SDK 3DS.
Obtenha o code3DS
Execute a autorização do SDK e leia o código com GetThreeDsCode().
Tokenize o cartão
Envie o número do cartão e receba o numberToken.
Crie o pagamento
Envie paymentType: 3, o numberToken, o code3DS e o fingerprint.
Trate o desafio, se houver
Se a resposta vier com Challenge, apresente o desafio pelo SDK e valide o resultado. Veja Desafio 3DS.

Consulte a situação
Acompanhe o paymentId até um estado final.

Tokenizar o cartão#

POST/payments/v1/creditcard/generate/token

Troca o número do cartão por um token, usado na criação do pagamento.

Cabeçalhos

Authorizationstringobrigatório
Valor de authenticationToken retornado na autenticação, sem o prefixo Bearer.
x-api-keystringobrigatório
Chave do API Gateway do ambiente.

Content-Typestringobrigatório
Sempre application/json.

Corpo da requisição

cardNumberstringobrigatório
Número do cartão válido pelo algoritmo de Luhn. Envie de preferência só dígitos.
transactionIdstringobrigatório
Identificador de correlação gerado pelo integrador, com no máximo 40 caracteres. UUID é recomendado.

Requisição

curl --request POST \
  --url 'https://api.mygateway.com.br/payments/v1/creditcard/generate/token' \
  --header 'Authorization: TOKEN_DE_AUTENTICACAO' \
  --header 'x-api-key: SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"cardNumber":"4111111111111111","transactionId":"a2d77f66-0bd1-421d-8ad5-3beab6cfcc79"}'

const response = await fetch("https://api.mygateway.com.br/payments/v1/creditcard/generate/token", {
  method: "POST",
  headers: {
    Authorization: token,
    "x-api-key": process.env.MYGATEWAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cardNumber: "4111111111111111",
    transactionId: "a2d77f66-0bd1-421d-8ad5-3beab6cfcc79"
  }),
});

const result = await response.json();

<?php
$ch = curl_init('https://api.mygateway.com.br/payments/v1/creditcard/generate/token');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ' . $token,
        'x-api-key: ' . getenv('MYGATEWAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'cardNumber' => '4111111111111111',
        'transactionId' => 'a2d77f66-0bd1-421d-8ad5-3beab6cfcc79',
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);

import os
import requests

response = requests.post(
    "https://api.mygateway.com.br/payments/v1/creditcard/generate/token",
    headers={
        "Authorization": token,
        "x-api-key": os.environ["MYGATEWAY_API_KEY"],
    },
    json={
        "cardNumber": "4111111111111111",
        "transactionId": "a2d77f66-0bd1-421d-8ad5-3beab6cfcc79",
    },
)
result = response.json()

Respostas

Cartão tokenizado.

JSON

{
  "data": {
    "numberToken": "11111111-1111-1111-1111-111111111111"
  }
}

Payload inválido ou regra de negócio não atendida. Veja Erros.

ValidationError

{
  "notificationErrors": {
    "error": {
      "erros": [
        {
          "propertyName": "items.value",
          "propertyErrors": [
            "O valor informado é inválido."
          ]
        }
      ]
    }
  },
  "errorTypeDescription": "ValidationError",
  "errorType": 1
}

Atributos da resposta

data.numberTokenstringobrigatório
Token do cartão, usado em creditCard.cardInfo.numberToken. Não é o número real do cartão.

Criar o pagamento#

POST/payments/v1/create

Cria o pagamento no cartão com autenticação 3DS.

Cabeçalhos

Authorizationstringobrigatório
Valor de authenticationToken retornado na autenticação, sem o prefixo Bearer.
x-api-keystringobrigatório
Chave do API Gateway do ambiente.
Content-Typestringobrigatório
Sempre application/json.

Corpo da requisição

paymentTypeintegerobrigatório
Deve ser 3 para cartão com 3DS.
Valores aceitos: 3
creditCardobjectobrigatório
Dados do pagamento no cartão.
Atributos de creditCard
- clientChargeIdUUIDobrigatório
  Identificador da cobrança no sistema do integrador. Não o reutilize em cobranças diferentes.
- paymentobjectobrigatório
  Valor e parcelamento.
  Atributos de payment
  valueintegerobrigatório
  Total em centavos. Maior que zero.
  installmentsintegerobrigatório
  Número de parcelas, entre 1 e 24.
- cardInfoobjectobrigatório
  Dados tokenizados e de verificação do cartão. Não envie o número do cartão aqui.
  Atributos de cardInfo
  numberTokenstringobrigatório
  Token retornado pela tokenização.
  cardHolderNamestringobrigatório
  Nome impresso no cartão. Máximo recomendado de 30 caracteres.
  cardHolderDocumentstringopcional
  CPF ou CNPJ válido do titular, somente dígitos.
  cardHolderPhonestringcondicional
  Telefone do titular, somente dígitos. Se enviado, cardHolderPhoneDDD também é obrigatório.
  cardHolderPhoneDDDstringcondicional
  DDD do titular. Se enviado, cardHolderPhone também é obrigatório.
  securityCodestringobrigatório
  CVV/CVC. Nunca armazene nem registre este valor.
  expirationMonthintegerobrigatório
  Mês entre 1 e 12.
  expirationYearintegerobrigatório
  Ano com quatro dígitos. O mês/ano não pode estar vencido.
- sellerInfoobjectrecomendado
  Dados que identificam o estabelecimento na fatura.
  Atributos de sellerInfo
  softDescriptorstringrecomendado
  Deve conter exatamente um *, não começar por * e usar só letras, números e *. Máximo recomendado de 22 caracteres.
- antifraudobjectobrigatório
  Dados 3DS e fingerprint.
  Atributos de antifraud
  theeDsobjectobrigatório
  Configuração 3DS. A grafia theeDs faz parte do contrato.
  Atributos de theeDs
  threeDsTypeintegerobrigatório
  Use 1, único tipo público suportado hoje.
  Valores aceitos: 1
  itemsobjectobrigatório
  Dados produzidos na sessão 3DS.
  Atributos de items
  code3DSstringobrigatório
  Código obtido com GetThreeDsCode() no SDK 3DS.
  urlSite3DSstringobrigatório
  URL HTTPS do checkout que executa o SDK.
  fingerprintobjectobrigatório
  Fingerprint da sessão. O sessionId deve ser o mesmo usado na inicialização do SDK.
- customerobjectobrigatório
  Dados do pagador.
- itemsarrayobrigatório
  Itens do pagamento. Precisa ter pelo menos um.
- discountintegeropcional
  Desconto em centavos. Nunca negativo.
  Padrão: 0
- segmentstringopcional
  Código de segmentação comercial previamente acordado com a My Gateway. Omita quando não fizer parte do seu contrato.

Corpo da requisição

{
  "paymentType": 3,
  "creditCard": {
    "clientChargeId": "00000000-0000-0000-0000-000000000001",
    "payment": {
      "value": 10000,
      "installments": 1
    },
    "cardInfo": {
      "numberToken": "11111111-1111-1111-1111-111111111111",
      "cardHolderName": "MARIA DA SILVA",
      "cardHolderDocument": "52998224725",
      "cardHolderPhone": "999998888",
      "cardHolderPhoneDDD": "11",
      "securityCode": "123",
      "expirationMonth": 12,
      "expirationYear": 2030
    },
    "sellerInfo": {
      "softDescriptor": "LOJA*PEDIDO"
    },
    "antifraud": {
      "theeDs": {
        "threeDsType": 1,
        "items": {
          "code3DS": "CODIGO_GERADO_PELO_SDK",
          "urlSite3DS": "https://loja.exemplo.com/checkout"
        }
      },
      "fingerprint": {
        "sessionId": "32c37c71-2b34-45e2-b678-d6627d0f9001",
        "channel": 1,
        "deviceInfo": {
          "deviceId": "IDENTIFICADOR_DO_DISPOSITIVO",
          "httpAcceptBrowserValue": "application/json",
          "httpAcceptContent": "*/*",
          "httpBrowserLanguage": "pt-BR",
          "httpBrowserJavaEnabled": "N",
          "httpBrowserJavaScriptEnabled": "Y",
          "httpBrowserColorDepth": "24",
          "httpBrowserScreenHeight": "1080",
          "httpBrowserScreenWidth": "1920",
          "httpBrowserTimeDifference": "180",
          "userAgentBrowserValue": "Mozilla/5.0 (...)"
        },
        "network": {
          "ip": "203.0.113.10",
          "referer": "https://loja.exemplo.com/checkout",
          "userAgent": "Mozilla/5.0 (...)"
        }
      }
    },
    "customer": {
      "name": "Maria da Silva",
      "document": "52998224725",
      "email": "[email protected]",
      "phoneNumber": "33334444",
      "phoneNumberDDD": "11",
      "mobilePhoneNumber": "999998888",
      "mobilePhoneNumberDDD": "11",
      "address": {
        "street": "Rua Exemplo",
        "number": "123",
        "neighborhood": "Centro",
        "zipcode": "01001000",
        "city": "Sao Paulo",
        "complement": "Apto 10",
        "state": "SP",
        "country": "BR"
      }
    },
    "items": [
      {
        "id": "33333333-3333-3333-3333-333333333333",
        "name": "Produto A",
        "value": 6000,
        "amount": 1
      },
      {
        "id": "44444444-4444-4444-4444-444444444444",
        "name": "Produto B",
        "value": 4000,
        "amount": 1
      }
    ],
    "discount": 0
  }
}

Requisição

# cartao.json: o corpo da requisição mostrado acima
curl --request POST \
  --url 'https://api.mygateway.com.br/payments/v1/create' \
  --header 'Authorization: TOKEN_DE_AUTENTICACAO' \
  --header 'x-api-key: SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data @cartao.json

// payload: o corpo da requisição mostrado acima

const response = await fetch("https://api.mygateway.com.br/payments/v1/create", {
  method: "POST",
  headers: {
    Authorization: token,
    "x-api-key": process.env.MYGATEWAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(payload),
});

const result = await response.json();

<?php
// $payload: o corpo da requisição mostrado acima
$ch = curl_init('https://api.mygateway.com.br/payments/v1/create');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: ' . $token,
        'x-api-key: ' . getenv('MYGATEWAY_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);

import os
import requests

# payload: o corpo da requisição mostrado acima
response = requests.post(
    "https://api.mygateway.com.br/payments/v1/create",
    headers={
        "Authorization": token,
        "x-api-key": os.environ["MYGATEWAY_API_KEY"],
    },
    json=payload,
)
result = response.json()

Respostas

Pagamento criado. Pode vir com ou sem desafio 3DS.

Sem desafio

{
  "data": {
    "status": "WaitingPayment",
    "paymentId": "f3da8969-3db8-49f1-91cf-50ff444252e7",
    "orderNumber": "1234567890123"
  }
}

Com desafio (Challenge)

{
  "data": {
    "antifraud": [
      {
        "name": "threeDs",
        "value": "{\"status\":\"Challenge\",\"threeDsVersion\":\"2.2.0\",\"acsUrl\":\"https://...\",\"authenticationTransactionId\":\"...\",\"pareq\":\"...\"}"
      }
    ],
    "status": "Challenge",
    "paymentId": "f3da8969-3db8-49f1-91cf-50ff444252e7",
    "orderNumber": "1234567890123"
  }
}

Payload inválido ou regra de negócio não atendida. Veja Erros.

ValidationError

{
  "notificationErrors": {
    "error": {
      "erros": [
        {
          "propertyName": "items.value",
          "propertyErrors": [
            "O valor informado é inválido."
          ]
        }
      ]
    }
  },
  "errorTypeDescription": "ValidationError",
  "errorType": 1
}

Atributos da resposta

data.statusstringobrigatório
Situação inicial, normalmente WaitingPayment ou Challenge.
data.paymentIdUUIDobrigatório
Identificador usado na consulta e na validação 3DS.
data.orderNumberstringobrigatório
Identificador da transação gerado para o processamento do pagamento.
data.antifraudarrayopcional
Presente quando há dados adicionais do 3DS, especialmente em Challenge.
Atributos de data.antifraud
- namestringobrigatório
  Tipo do dado. Para o desafio, threeDs.
- valuestring (JSON)obrigatório
  Objeto 3DS serializado como texto. Faça JSON.parse antes de ler os atributos. Veja os dados do 3DS.

Quando data.status for Challenge, siga o fluxo do desafio 3DS. Trate o desafio como continuação da mesma transação, nunca como uma nova cobrança.

Última atualização em 29 de outubro de 2026

Pagamento com cartão de crédito

Fluxo#

Tokenizar o cartão#

Criar o pagamento#

Soluções

Taxa

Empresa

Políticas

Suporte