[POST] /payment

Gera uma cobrança única à vista ou parcelada

Este endpoint permite criar uma ordem de cobrança pontual via cartão de crédito, com ou sem parcelamento.

Endpoints

Método POST

Sandbox (firebanking.dev)

https://api-gateway.firebanking.dev/credit-card/v1/payment

Produção (firebanking.com.br)

https://api-gateway.firebanking.com.br/credit-card/v1/payment

Requisição

Headers

Campo	Valor	Tipo	Descrição
Content-Type	application/json	string	Define o conteúdo como JSON
x-api-key	123	string	Sua chave API

Campos a serem enviados no Body

Campo	Tipo	Obrigatório	Descrição
purchaseValue	number	Sim	Valor da transação. Aceita valores quebrados, separados por ponto, como 123.45, representando R$123,45, por exemplo.
installments	number	Sim	Número de parcelas da cobrança (mínimo 1)
externalId	string	Sim	Identificador único para ser usado como rastreio das cobranças no envio do Webhook
purchaseTitle	string	Não	Título da cobrança
description	string	Não	Descrição da cobrança
payment.chargeType	string	Condicional	Modelo de cobrança da taxa. É obrigatório caso as parcelas sejam maior do que 1. Os valores permitidos são: FEE_TO_CUSTOMER = O repasse da taxa das parcelas será para o cliente FEE_TO_SELLER = O repasse da taxa das parcelas será para o vendedor, então você (seller) assume as taxas.
payment.capture	boolean	Não	Indica se a transação deve ser capturada imediatamente após a autorização
payment.card.name	string	Sim	Nome impresso no cartão
payment.card.number	string	Sim	Número do cartão (PAN)
payment.card.expiration	string	Sim	Data de expiração do cartão Formato MM/YYYY (mês/ano)
payment.card.securityCode	string	Sim	Código de verificação (CCV/CVC)
buyer.name	string	Sim	Nome do comprador
buyer.document	string	Sim	Documento do comprador (CPF/CNPJ). Apenas números, sem caracteres especiais.
buyer.email	string	Sim	E-mail do comprador
buyer.phone	string (máx. 11)	Sim	Número de telefone do comprador. Apenas números, sem caracteres especiais. Formato (DDD+Número).
buyer.countryCode	string	Sim	Código do país / DDI (Discagem Direta Internacional). Exemplo: "55" para Brasil. Apenas números.
buyer.address.country	string	Sim	Sigla do país de origem do comprador. Formato de dois dígitos. Exemplo: “BR” para Brasil.
buyer.address.state	string	Sim	Estado do endereço do comprador. Formato UF. Exemplo: “SP” para o estado de São Paulo.
buyer.address.city	string	Sim	Cidade do endereço do comprador
buyer.address.district	string	Sim	Bairro do endereço do comprador
buyer.address.street	string	Sim	Rua do endereço do comprador
buyer.address.zipCode	string	Sim	CEP do endereço do comprador
buyer.address.number	string	Sim	Número do endereço do comprador
buyer.address.complement	string	Não	Complemento do endereço do comprador
buyer.billingAddress	object	Não	Endereço de cobrança do comprador associado ao cartão. Esse campo é um objeto que possui os mesmos campos/propriedades do `buyer.address`. Ele deve ser preenchido apenas caso o endereço de cobrança seja diferente do endereço padrão do comprador.
transaction.additionalInfo	object	Não	Você pode enviar até 10 itens dentro do dicionário, além do “customerIp”, caso queira enviar. O modelo é “chave e valor” e estas propriedades serão enviadas no retorno do Webhook.
transaction.additionalInfo.customerIp	string	Não	O IP do comprador que está realizando a compra dentro do seu checkout. É um parâmetro opcional e pode ser utilizado para melhor tracking controle do antifraude das cobranças geradas.
callbackUrl	string	Não	Caso precise direcionar o webhook para outra URL que não seja a já cadastrada por padrão ou tenha uma URL dinâmica, esse campo pode ser utilizado para atender a esse cenário. OBS: Caso esse campo seja preenchido, o webhook não é enviado para a URL padrão da conta.

Cartões para teste

Como testar cobranças de cartão em sandbox

Os cartões a serem utilizados no teste, devem ter números válidos e podem ser gerados a partir de qualquer site gerador de cartões, devendo o comportamento seguir as seguinte regra para diferentes validação de diferentes cenários:

Cartão	Autorizado?	Status	Exemplo
Final 0, 1 ou 4	SIM	Aprovado	5186882549895601
Final 2	NÃO	Não autorizado	5465415736976082
Final 3	NÃO	Cartão expirado	5112970800105403
Final 5	NÃO	Cartão bloqueado	5528430335513025
Final 6	NÃO	Timeout	5479620928050436
Final 7	NÃO	Cartão cancelado	5325827236673227
Final 8	Aleatório SIM/NÃO	Aprovado / Timeout	5397549970735078

Em sandbox, para testar os cenários acima, o CVV sempre deve ser um número de 3 dígitos terminado em zero (Ex. 220). Um número de CVV diferente de zero, irá resultar em falha na geração da transação. Abaixo está um exemplo do cartão completo válido, para testar a aprovação de uma cobrança:

{
  "card": {
    "name": "João Silva",
    "number": "5186882549895601",
    "expiration": "12/2025",
    "securityCode": "220"
  }
}

cURL

O cURL abaixo está com a configuração de sandbox. Atentar-se a URL.

curl --request POST \
  --url https://api-gateway.firebanking.dev/credit-card/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <sua-chave-api>' \
  --data '{
  "purchaseValue": 10,
  "installments": 1,
  "externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
  "purchaseTitle": "iPhone Pro Max 256GB",
  "description": "Smartphone Apple Pro Max",
  "payment": {
    "capture": false,
    "card": {
      "name": "João Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
		"customerIp": "192.128.0.1",
    "orderId": "order-123",
    "customerId": "customer-123"
  }
}'

Cobrança pontual à vista

{
  "purchaseValue": 10,
  "installments": 1,
  "externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
  "purchaseTitle": "iPhone Pro Max 256GB",
  "description": "Smartphone Apple Pro Max",
  "payment": {
    "capture": true,
    "card": {
      "name": "João Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
    "customerIp": "192.128.0.1",
    "orderId": "order-123",
    "customerId": "customer-123"
  }
}

Observação sobre o método de cobrança e repasse de taxas

O tipo NO_FEE_TO_CUSTOMER é exclusivo para transações à vista. Não é preciso informar o chargeType em caso de parcelamento único.

Cobrança pontual com parcelamento

{
  "purchaseValue": 100,
  "installments": 4,
  "externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
  "purchaseTitle": "iPhone Pro Max 256GB",
  "description": "Smartphone Apple Pro Max",
  "payment": {
    "chargeType": "FEE_TO_SELLER",
    "capture": true,
    "card": {
      "name": "João Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
    "customerIp": "192.128.0.1",
    "orderId": "order-123",
    "customerId": "customer-123"
  }
}

Cobrança pontual sem pré-captura

{
  "purchaseValue": 10,
  "installments": 1,
  "externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
  "purchaseTitle": "iPhone Pro Max 256GB",
  "description": "Smartphone Apple Pro Max",
  "payment": {
    "capture": false,
    "card": {
      "name": "João Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
    "customerIp": "192.128.0.1",
    "orderId": "order-123",
    "customerId": "customer-123"
  }
}

Cobrança pontual com endereço diferente do endereço de cobrança

{
  "purchaseValue": 10,
  "installments": 1,
  "externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
  "purchaseTitle": "iPhone Pro Max 256GB",
  "description": "Smartphone Apple Pro Max",
  "payment": {
    "capture": true,
    "card": {
      "name": "João Silva",
      "number": "5186882549895601",
      "expiration": "12/2025",
      "securityCode": "220"
    }
  },
  "buyer": {
    "name": "João Silva",
    "document": "12345678909",
    "email": "[email protected]",
    "phone": "11999999999",
    "countryCode": "+55",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "district": "Centro",
      "street": "Rua das Flores",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    },
		"billingAddress": {
      "country": "BR",
      "state": "CE",
      "city": "Ceará",
      "district": "Centro",
      "street": "Avenida Washington Soares",
      "zipCode": "01234-567",
      "number": "123",
      "complement": "Apto 45"
    }
  },
  "additionalInfo": {
    "customerIp": "192.128.0.1",
    "orderId": "order-123",
    "customerId": "customer-123"
  }
}

Exemplo de resposta

Campos a serem recebidos

Campo	Tipo	Descrição
internalId	string	Identificador único gerado para cobrança/transação
externalId	string	Identificador único para ser usado como rastreio das cobranças
status	string	Status da cobrança/transação
value	string	Valor da transação
chargeType	string	Data/momento da geração do pagamento
creditCardBrand	string	Data/momento da expiração do pagamento
creditCardAuthorizationCode	string	Código de autorização da transação
creditCardNsu	string	Código NSU que identifica de forma exclusiva cada transação realizada com cartão de crédito ou débito
dueDate	string	Data de vencimento da transação. No momento, não aceitamos transações futuras, portanto esse valor sempre será do dia em que ocorrer a transação.
captureDate	string timestamp \| null	Dados que mostram o momento/data da captura
paymentDate	string timestamp \| null	Dados que mostram o momento/data do pagamento
refundDate	string date \| null	Data do reembolso da transação

JSON

Exemplo 1

{
	"internalId": "6968c9aa-c29f-4ee5-a241-bc3d22ccbb33",
	"externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
	"status": "PAID",
	"value": 10,
	"installments": 1,
	"chargeType": "NO_FEE_TO_CUSTOMER",
	"creditCardBrand": "mastercard",
	"creditCardAuthorizationCode": "2579896",
	"creditCardNsu": "9611344",
	"dueDate": "2025-08-04",
	"captureDate": "2025-08-04T16:55:53.106Z",
	"paymentDate": null,
	"refundDate": null
}

Exemplo 2

{
	"internalId": "6968c9aa-c29f-4ee5-a241-bc3d22ccbb33",
	"externalId": "38d25346-f14b-4a9a-82f4-ecef7840fca3",
	"status": "PAID",
	"value": 50,
	"installments": 2,
	"chargeType": "FEE_TO_SELLER",
	"creditCardBrand": "mastercard",
	"creditCardAuthorizationCode": "5009480",
	"creditCardNsu": "8215605",
	"dueDate": "2025-08-04",
	"captureDate": "2025-08-05T01:46:10.393Z",
	"paymentDate": "2025-08-05T01:46:13.665Z",
	"refundDate": null
}

Exemplo de erro

{
	"statusCode": 400,
	"timestamp": "2025-08-05T01:36:25.564Z",
	"path": "/v1/payments",
	"message": [
		"chargeType is required when installments > 1"
	],
	"errorCode": "HTTP_ERROR"
}