Suporte

Criação do Pagamento com 3DS

Criar Pagamento com 3DS

post

Cria uma cobrança utilizando 3DS2. O objeto threeDSecure é obrigatório para transações 3DS. ⚠️ IMPORTANTE: Caso a transação retorne como pendente (challenged = true), será necessário implementar um fluxo assíncrono com Step Up Challenge e polling para verificar o status final.

Autorizações
Parâmetros de cabeçalho
x-idempotency-keystring · uuidObrigatório

Chave de idempotência para evitar duplicação de transações

Corpo
startDatestring · dateObrigatório

Data de início da cobrança

Example: 2025-04-16
valuenumber · decimal · mín: 0.01Obrigatório

Valor da cobrança

Example: 130
installmentsinteger · mín: 1 · máx: 12Obrigatório

Número de parcelas

Example: 3
urlCallBackstring · uriOpcional

URL de callback para notificações

Example: https://webhook.site/unique-id
titlestring · máx: 255Obrigatório

Título da cobrança

Example: Compra Exemplo
descriptionstring · máx: 500Opcional

Descrição da cobrança

Example: Descrição da compra
uuidBuyerstring · uuidObrigatório

UUID do comprador

Example: 71d12215-267a-4620-9b17-0715c84d23bd
Respostas
201

Ordem criada com sucesso

application/json
post
POST /v2/orders HTTP/1.1
Host: api.barte.com
X-Token-Api: YOUR_API_KEY
x-idempotency-key: 123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json
Accept: */*
Content-Length: 1573

{
  "startDate": "2025-04-16",
  "value": 130,
  "installments": 3,
  "urlCallBack": "https://webhook.site/unique-id",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "payment": {
    "method": "CREDIT_CARD_EARLY_SELLER",
    "card": {
      "cardToken": "efde9a25-76f9-4d0a-bfbc-1abbdbd8bc07",
      "cvv": "950"
    },
    "fraudData": {
      "internationalDocument": {
        "documentNumber": "04909778128",
        "documentType": "cpf",
        "documentNation": "BR"
      },
      "name": "João Silva",
      "email": "joao@example.com",
      "phone": "5511999994444",
      "billingAddress": {
        "country": "BR",
        "state": "MG",
        "city": "Uberlândia",
        "district": "Centro",
        "street": "Rua Exemplo",
        "zipCode": "38411999",
        "number": "123",
        "complement": "Apto 45"
      }
    }
  },
  "threeDSecure": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "setupId": "e453da0b-b6a1-4c9a-8820-f2da23b3ffb7",
    "redirectURL": "http://localhost:3000/checkout.html",
    "requestorURL": "http://localhost:3000",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "colorDepth": 24,
      "screenHeight": 1080,
      "screenWidth": 1920,
      "timeZoneOffset": "-180",
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "billingAddress": {
      "city": "Uberlândia",
      "country": "BR",
      "streetNumber": "123",
      "zipCode": "38411999",
      "state": "MG",
      "street": "Rua Exemplo"
    },
    "shippingAddress": {
      "city": "Uberlândia",
      "country": "BR",
      "streetNumber": "123",
      "zipCode": "38411999",
      "state": "MG",
      "street": "Rua Exemplo"
    },
    "cardHolder": {
      "email": "teste@teste.com",
      "mobilePhone": "24999329393"
    }
  },
  "uuidBuyer": "71d12215-267a-4620-9b17-0715c84d23bd"
}
{
  "uuid": "4668ab70-39c3-4ab3-8770-995f6333e200",
  "status": "SENT",
  "title": "Compra Exemplo",
  "description": "Descrição da compra",
  "value": 130,
  "installments": 3,
  "startDate": "2025-04-16",
  "payment": "CREDIT_CARD_EARLY_SELLER",
  "customer": {
    "document": "89259815053",
    "type": "CPF",
    "documentCountry": "BR",
    "name": "João Silva",
    "email": "comprador@email.com",
    "phone": "11948256898",
    "alternativeEmail": "compradoralt@email.com",
    "integrationCustomerId": "91e89dc6-5226-47f3-a8b8-f8a2009c669e"
  },
  "idempotencyKey": "5e643a79-3b3f-4db9-95a3-a998caf914ff",
  "subSellerPaymentResponse": [
    {}
  ],
  "charges": [
    {
      "uuid": "27dccdbb-73a9-4799-93c9-e30e2c71cc75",
      "title": "Compra Exemplo",
      "expirationDate": "2025-04-16",
      "value": 130,
      "paymentMethod": "CREDIT_CARD_EARLY_SELLER",
      "status": "SCHEDULED",
      "customer": {
        "document": "89259815053",
        "type": "CPF",
        "name": "João Silva",
        "email": "comprador@email.com",
        "phone": "11948256898",
        "alternativeEmail": "compradoralt@email.com"
      }
    }
  ],
  "threeDSResponse": {
    "dataOnly": false,
    "requiresLiabilityShift": false,
    "redirectURL": "http://localhost:3000/checkout.html",
    "browser": {
      "ip": "127.0.0.1",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36",
      "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8",
      "language": "pt-BR",
      "screenHeight": 1080,
      "screenWidth": 1920,
      "javaEnabled": false,
      "javaScriptEnabled": true
    },
    "auth": {
      "action": "REDIRECT",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
      "stepUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp"
    },
    "challenged": true,
    "authenticated": false,
    "offeredType": "Challenge",
    "liabilityShift": false
  }
}

Observações:

  • Adição do objeto threeDSecure na requisição para criar o pedido.

  • O seller precisa estar com o merchant habilitado para 3DS.

  • É importante estar ciente que, caso haja necessidade de desafio na transação, ou seja, caso ela retorne pendente, será necessário criar um fluxo assíncrono no checkout.

Fluxo:

  • Enviou transação → Retornou pendente → Faz o desafio (Step Up Challenge).

  • Caso o desafio tenha sucesso, será necessário criar um pool para consultar o status do pedido.

Sugestão: Criar um loading no checkout até a transação retornar PAID (Considerando os timeouts).

⚠️ Campos importantes:

  • auth.dataOnly

  • auth.requiresLiabilityShift

  • authentication3DS.liabilityShift

  • authentication3DS.auth.stepUrl e authentication3DS.auth.token (para Step Up Challenge)

AnteriorCriação da sessão 3DSPróximoRealizar Step Up Challenge

Atualizado

Isto foi útil?