Processar Pagamento com Cartão

Esta rota não requer autenticação. Antes de processar o pagamento, você deve criar uma fatura usando o endpoint /payments/v2/create-credit-card-payment.

externalId

string

required

ID da transação retornado no campo invoice_id ao criar a fatura. Este é o invoice_id da cobrança criada.

installments

number

required

Número de parcelas (1 a 24).

purchaseTitle

string

required

Título da compra.

description

string

required

Descrição do pagamento.

Objeto payment

payment

object

required

Dados do pagamento e cartão.

payment.capture

boolean

required

Se deve capturar o pagamento automaticamente.

payment.chargeType

string

Tipo de cobrança das taxas.

Objeto payment.card

payment.card

object

required

Dados do cartão de crédito.

payment.card.name

string

required

Nome impresso no cartão (exatamente como aparece).

payment.card.number

string

required

Número do cartão (16 dígitos, sem espaços).

payment.card.expiration

string

required

Data de validade do cartão (formato: MM/YYYY).

payment.card.securityCode

string

required

CVV do cartão (3 ou 4 dígitos).

Objeto buyer

buyer

object

required

Dados do comprador.

buyer.name

string

required

Nome completo do comprador.

buyer.document

string

required

CPF ou CNPJ do comprador (apenas números).

buyer.email

string

required

E-mail do comprador.

buyer.phone

string

required

Telefone do comprador (com DDD, sem espaços).

buyer.countryCode

string

required

Código do país (ex: “55” para Brasil).

Objeto buyer.address

buyer.address

object

required

Endereço completo do comprador.

buyer.address.country

string

required

País.

buyer.address.state

string

required

Estado (sigla de 2 letras).

buyer.address.city

string

required

Cidade.

buyer.address.district

string

required

Bairro.

buyer.address.street

string

required

Nome da rua.

buyer.address.number

string

required

Número do endereço.

buyer.address.zipCode

string

required

CEP (apenas números).

buyer.address.complement

string

required

Complemento do endereço.

Objeto additionalInfo

additionalInfo

object

required

Informações adicionais do pagamento.

additionalInfo.customerIp

string

required

Endereço IP do cliente que está realizando a compra.

additionalInfo.orderId

string

required

ID do pedido no seu sistema.

additionalInfo.customerId

string

required

ID do cliente no seu sistema.

Response

message

string

Mensagem de confirmação do processamento.

invoice_id

string

ID da invoice/cobrança que foi paga. Este é o mesmo valor enviado como externalId.

transactionId

string

ID da transação processada.

status

string

Status do pagamento. Valores possíveis:

PAID: Pagamento aprovado e processado
WAITING_TO_FILL: Pagamento esperando preenchimento de dados
DENIED: Pagamento recusado
CANCELED: Pagamento cancelado
REFUNDED: Pagamento reembolsado

Como padrão ele sempre retorna WAITING_TO_FILL

installments

number

Número de parcelas processadas.

amount

number

Valor total do pagamento.

paymentId

string

ID do pagamento gerado pelo gateway.

curl -X POST "https://api-gateway.gates2b.com/payments/v2/credit-card" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "installments": 3,
    "purchaseTitle": "Compra na Loja XYZ",
    "description": "Pagamento do pedido #12345",
    "payment": {
      "capture": true,
      "card": {
        "name": "JOAO SILVA",
        "number": "5555555555554444",
        "expiration": "12/2026",
        "securityCode": "123"
      }
    },
    "buyer": {
      "name": "João Silva",
      "document": "12345678900",
      "email": "joao@example.com",
      "phone": "11987654321",
      "countryCode": "55",
      "address": {
        "country": "Brasil",
        "state": "SP",
        "city": "São Paulo",
        "district": "Centro",
        "street": "Rua das Flores",
        "number": "123",
        "zipCode": "01234567",
        "complement": "Apto 45"
      }
    },
    "additionalInfo": {
      "customerIp": "192.168.1.1",
      "orderId": "ORDER-12345",
      "customerId": "CUSTOMER-789"
    }
  }'

{
  "message": "Pagamento processado com sucesso",
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PAID",
  "installments": 3,
  "amount": 100.50,
  "paymentId": "507f1f77bcf86cd799439011"
}

Fluxo Completo de Pagamento

Criar Fatura

Primeiro, crie uma fatura usando POST /payments/v2/create-credit-card-payment com o valor e dados do cliente.

{
  "amount": 100.50,
  "customer_name": "João Silva",
  "customer_email": "joao@example.com",
  "external_reference": "ORDER-12345"
}

Você receberá o campo invoice_id na resposta que será usado como externalId.

Processar Pagamento

Use o invoice_id recebido no passo anterior como valor do campo externalId para processar o pagamento com os dados do cartão neste endpoint.

Receber Confirmação

Aguarde a resposta com o status do pagamento (PAID, DECLINED, etc).

Webhook (Opcional)

Configure webhooks para receber notificações automáticas sobre mudanças no status do pagamento.

Possíveis Motivos de Recusa

Os seguintes problemas podem causar recusa do pagamento:

Cartão sem limite disponível: Saldo insuficiente para cobrir o valor total
Cartão expirado: Data de validade já passou
CVV incorreto: Código de segurança não confere
Problemas com a operadora: Emissor do cartão indisponível ou com problemas
Suspeita de fraude: Transação bloqueada por segurança
Dados inválidos: Número do cartão incorreto ou dados inconsistentes

Observações Importantes

Segurança PCI-DSS

Nunca armazene dados sensíveis do cartão (número completo, CVV)
Use HTTPS em todas as requisições
Não exponha dados do cartão em logs ou mensagens de erro

ExternalId / Invoice ID

O campo externalId utilizado neste endpoint corresponde ao campo invoice_id retornado ao criar a fatura usando o endpoint /payments/v2/create-credit-card-payment. Importante:

Ao criar a fatura, armazene o valor do campo invoice_id retornado
Use esse invoice_id como valor do campo externalId ao processar o pagamento
O mesmo invoice_id será retornado na resposta deste endpoint para confirmação

Validações

Dados do Cartão: Valide número, validade e CVV no frontend antes de enviar
CPF/CNPJ: Valide formato e dígitos verificadores
CEP: Valide formato (8 dígitos)
E-mail: Valide formato de e-mail válido
Telefone: Inclua DDD e número válido

Parcelamento

Parcelas Disponíveis: 1 a 24 parcelas
Valor Mínimo: Consulte configuração específica da sua conta
Taxas: Calculadas automaticamente baseadas na configuração

Códigos de Status HTTP

201: Pagamento processado com sucesso
400: Dados inválidos no payload
404: Invoice não encontrada (externalId inválido)
422: Cartão recusado ou sem saldo
500: Erro interno ao processar pagamento

Boas Práticas

Validação Client-Side: Implemente validação básica dos dados do cartão antes de enviar
Timeout: Configure timeouts adequados (recomendado: 30-60 segundos)
Retry Logic: Implemente retry apenas para erros 500 (não para recusas 422)
Logs: Registre tentativas de pagamento (sem dados sensíveis)
Rate Limiting: Implemente limitação de tentativas para prevenir abuso
IP do Cliente: Sempre envie o IP real do cliente em customerIp

Informações Básicas

API Key

PIX

Cartão de Crédito

Crypto

Reembolsos

Objeto payment

Objeto payment.card

Objeto buyer

Objeto buyer.address

Objeto additionalInfo

Response

Fluxo Completo de Pagamento

Possíveis Motivos de Recusa

Observações Importantes

ExternalId / Invoice ID

Validações

Parcelamento

Códigos de Status HTTP

Boas Práticas

Informações Básicas

API Key

PIX

Cartão de Crédito

Crypto

Reembolsos

​Objeto payment

​Objeto payment.card

​Objeto buyer

​Objeto buyer.address

​Objeto additionalInfo

​Response

​Fluxo Completo de Pagamento

​Possíveis Motivos de Recusa

​Observações Importantes

​ExternalId / Invoice ID

​Validações

​Parcelamento

​Códigos de Status HTTP

​Boas Práticas

Objeto payment

Objeto payment.card

Objeto buyer

Objeto buyer.address

Objeto additionalInfo

Response

Fluxo Completo de Pagamento

Possíveis Motivos de Recusa

Observações Importantes

ExternalId / Invoice ID

Validações

Parcelamento

Códigos de Status HTTP

Boas Práticas