Skip to main content
POST
/
payments
/
v2
/
create-credit-card
curl -X POST "https://api-gateway.gates2b.com/payments/v2/create-credit-card" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "customer_name": "João Silva",
    "customer_email": "joao@example.com",
    "external_reference": "ORDER-12345",
    "instructions": "Pagamento do pedido #12345",
    "redirect_url": "https://meusite.com/pagamento/sucesso",
    "expire_at": "2025-11-04T23:59:59Z"
  }'

{
  "id": 12345,
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100.50,
  "status": "WAITING_FILL",
  "id_transaction": "550e8400-e29b-41d4-a716-446655440000",
  "checkout_id": 12345,
  "checkout_url": "https://pay.bpix.app/12345",
  "external_reference": "ORDER-12345",
  "name_client": "João Silva",
  "email": "joao@example.com",
  "description": "Pagamento do pedido #12345",
  "redirect_url": "https://meusite.com/pagamento/sucesso",
  "expire_at": "2025-11-04T23:59:59.000Z",
  "createdAt": "2025-11-03T10:30:00.000Z",
  "updatedAt": "2025-11-03T10:30:00.000Z"
}
​
Authorization
string
required
O token de autenticação no formato Bearer é obrigatório para acessar este endpoint.
​
amount
number
required
Valor do pagamento (mínimo: 1.00).
​
customer_name
string
Nome do cliente.
​
customer_email
string
E-mail do cliente.
​
external_reference
string
Referência externa ao seu sistema para identificar o pedido.
​
instructions
string
Instruções ou descrição do pagamento.
​
redirect_url
string
URL para onde o cliente será redirecionado após o pagamento.
​
expire_at
string
Data de expiração da fatura (formato ISO 8601).

​
Response

​
id
number
ID único da fatura criada.
​
invoice_id
string
ID da invoice/cobrança (UUID). Este valor deve ser usado como externalId ao processar o pagamento com cartão.
​
amount
number
Valor da fatura.
​
status
string
Status da fatura. Valor inicial: WAITING_FILL (aguardando preenchimento dos dados do cartão).
​
id_transaction
string
ID da transação (UUID).
​
checkout_id
number
ID do checkout gerado.
​
checkout_url
string
URL do checkout onde o cliente pode preencher os dados do cartão.
​
external_reference
string
Referência externa informada na criação.
​
name_client
string
Nome do cliente.
​
email
string
E-mail do cliente.
​
description
string
Descrição/instruções do pagamento.
​
redirect_url
string
URL de redirecionamento após pagamento.
​
expire_at
string
Data e hora de expiração da fatura.
​
createdAt
string
Data e hora de criação da fatura.
​
updatedAt
string
Data e hora da última atualização.
curl -X POST "https://api-gateway.gates2b.com/payments/v2/create-credit-card" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.50,
    "customer_name": "João Silva",
    "customer_email": "joao@example.com",
    "external_reference": "ORDER-12345",
    "instructions": "Pagamento do pedido #12345",
    "redirect_url": "https://meusite.com/pagamento/sucesso",
    "expire_at": "2025-11-04T23:59:59Z"
  }'

{
  "id": 12345,
  "invoice_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100.50,
  "status": "WAITING_FILL",
  "id_transaction": "550e8400-e29b-41d4-a716-446655440000",
  "checkout_id": 12345,
  "checkout_url": "https://pay.bpix.app/12345",
  "external_reference": "ORDER-12345",
  "name_client": "João Silva",
  "email": "joao@example.com",
  "description": "Pagamento do pedido #12345",
  "redirect_url": "https://meusite.com/pagamento/sucesso",
  "expire_at": "2025-11-04T23:59:59.000Z",
  "createdAt": "2025-11-03T10:30:00.000Z",
  "updatedAt": "2025-11-03T10:30:00.000Z"
}

​
Próximo Passo

Processar Pagamento

Após criar a fatura, use o invoice_id retornado para processar o pagamento com os dados do cartão.

​
Observações Importantes

​
Status da Fatura

Após a criação, a fatura fica com status WAITING_FILL aguardando o preenchimento dos dados do cartão. Os possíveis status são:
  • WAITING_FILL: Aguardando preenchimento dos dados do cartão
  • WAITING_PAYMENT: Dados preenchidos, aguardando processamento
  • PAID: Pagamento aprovado e processado
  • DECLINED: Pagamento recusado
  • EXPIRED: Fatura expirou antes do pagamento
  • CANCELLED: Fatura cancelada

​
Invoice ID (ID da Cobrança)

O campo invoice_id retornado é essencial e deve ser armazenado. Este é o identificador da cobrança criada e será usado como externalId ao chamar o endpoint de processamento do pagamento com cartão.

​
Checkout URL

A checkout_url pode ser usada para direcionar o cliente a uma página de checkout hospedada, onde ele pode preencher os dados do cartão de forma segura.

​
Expiração

Se nenhuma data de expiração for informada, o sistema usará um valor padrão. Após a expiração, a fatura não poderá mais ser paga.

​
Códigos de Status HTTP

  • 201: Fatura criada com sucesso
  • 400: Dados inválidos no payload
  • 401: Token de autenticação ausente ou inválido
  • 500: Erro interno ao criar fatura

​
Validações

  1. Valor: Deve ser maior que 0.01
  2. E-mail: Formato válido de e-mail (se fornecido)
  3. Data de Expiração: Deve ser uma data futura (se fornecida)

​
Boas Práticas

  1. Armazene o Invoice ID: Guarde o invoice_id no seu banco de dados junto com o pedido - ele é necessário para processar o pagamento
  2. Referência Externa: Use a external_reference para vincular a fatura ao pedido no seu sistema
  3. Webhook: Configure webhooks para receber notificações sobre mudanças de status
  4. Expiração: Defina um tempo de expiração adequado (ex: 30 minutos, 24 horas)
  5. Redirect URL: Configure uma URL de retorno apropriada para melhor experiência do usuário