InícioReferência

[POST] /payment

v2 - Gera uma cobrança imediata via PIX (Cash In)

Para saber mais

Cobrança Imediata (Cash In)

O que muda nessa versão?

Migração da v1 para v2 - O que muda?

Endpoint de produção

Método POST

https://api-gateway.firebanking.com.br/pix/v2/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

transaction.value

number

Sim

Valor da transação. Aceita valores quebrados, separados por ponto, como 123.45, representando R$123,45, por exemplo.

transaction.description

string

Não

Descrição da cobrança

transaction.expirationTime

number

Não

Tempo de vida da cobrança, especificado em segundos, a partir do momento da criação da transação. Caso não seja informado, o valor padrão é 86400 segundos, que representa 24 horas.

transaction.externalId

string

Não

Identificador único para ser usado como rastreio das cobranças no envio do Webhook

transaction.additionalInfo

object

Não

Você pode enviar até 10 itens dentro do dicionário, além do “sellerId”, caso queira enviar.

O modelo é “chave e valor” e estas propriedades serão enviadas no retorno do Webhook.

transaction.additionalInfo.sellerId

string

Não

O ID do seu vendedor associado ao fluxo de cobrança. É um parâmetro opcional e pode ser utilizado para melhor tracking das cobranças geradas por um vendedor específico.

Esse cenário é muito comum para gateways ou intermediadores.

payer.fullName

string

Sim

Nome do cliente/pagador

payer.document

string

Sim

Documentação do cliente/pagador, CPF ou CNPJ

splits

array

Não

Lista de beneficiários a receber um valor pré-configurado após a cobrança ser efetivamente paga

splits[].pixKey

string

Sim

Chave PIX do beneficiário

splits[].pixKeyType

string | enum

Sim

Tipo da chave PIX do beneficiário.

Podendo ser dos tipos: "RANDOM_KEY" (chave-aleatória), "DOCUMENT" (CPF ou CNPJ) ou "EMAIL" (e-mail)

splits[].document

string

Sim

CPF ou CNPJ do beneficiário

splits[].externalId

string

Sim

Identificador único para que possa ser usado em caso de alteração/cancelamento do pagamento split

splits[].percent

number

Sim

Valor em percentual a ser enviado. Por exemplo: caso a cobrança seja de R$10,00 (dez reais) e seja informado o valor “10” no campo percent, então será considerado 10% sobre R$10,00, que é R$1,00.

Este valor pode ser somado automaticamente com o valor fixo (amount). Este valor não pode ser maior do que o valor líquido recebido pela cobrança.

splits[].amount

number

Sim

Valor fixo a ser enviado.

Este valor pode ser somado automaticamente com o valor percentual (percent). Este valor não pode ser maior do que o valor líquido recebido pela cobrança.

Cobrança sem split

Exemplo de Objeto JSON a ser enviado no Body (sem split)

{
	"transaction": {
		"value": 0.15,
		"description": "Cobrança de teste",
		"expirationTime": 300,
		"externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"additionalInfo": {
			"sellerId": 123,
			"whatsAppPhone": "37988996655"
		}
	},
	"payer": {
		"fullName": "John Marvin",
		"document": "12312312387"
	}
}

cURL 

curl --request POST \
  --url https://api-gateway.firebanking.com.br/pix/v2/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <sua-chave-api>' \
  --data '{
	"transaction": {
		"value": 0.15,
		"description": "Cobrança de teste",
		"expirationTime": 300,
		"externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"additionalInfo": {
			"sellerId": 123,
			"whatsAppPhone": "37988996655"
		}
	},
	"payer": {
		"fullName": "John Marvin",
		"document": "12312312387"
	}
}'

Cobrança com split

Exemplo de Objeto JSON a ser enviado no Body (com split)

{
	"type": "PIX",
	"transaction": {
		"value": 1.15,
		"description": "Cobrança de teste",
		"expirationTime": 300,
		"externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"additionalInfo": {
			"sellerId": 123,
			"whatsAppPhone": "37988996655"
		}
	},
	"payer": {
		"fullName": "John Marvin",
		"document": "12312312387",
		"contact": {
			"phone": "11999887766",
			"mail": "[email protected]"
		}
	},
	"splits": [
		{
			"pixKey": "180b0070-bc07-4454-b645-1503326a310f",
			"pixKeyType": "RANDOM_KEY",
			"document": "61865163341",
			"externalId": "9cb7cd76-0b15-42f1-bac9-c3ab17843cfa",
			"percent": 0,
			"amount": 0
		}
	]
}

cURL 

curl --request POST \
  --url https://api-gateway.firebanking.com.br/pix/v1/payment \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <sua-chave-api>' \
  --data '{
	"type": "PIX",
	"transaction": {
		"value": 1.15,
		"description": "Cobrança de teste",
		"expirationTime": 300,
		"externalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
		"additionalInfo": {
			"sellerId": 123,
			"whatsAppPhone": "37988996655"
		}
	},
	"payer": {
		"fullName": "John Marvin",
		"document": "12312312387",
		"contact": {
			"phone": "11999887766",
			"mail": "[email protected]"
		}
	},
	"splits": [
		{
			"pixKey": "180b0070-bc07-4454-b645-1503326a310f",
			"pixKeyType": "RANDOM_KEY",
			"document": "61865163341",
			"externalId": "9cb7cd76-0b15-42f1-bac9-c3ab17843cfa",
			"percent": 0,
			"amount": 0
		}
	]
}'

Exemplo de resposta

Campos a serem recebidos

Campo

Tipo

Descrição

transactionId

string

Identificador único gerado para cobrança/transação

status

string

Status da cobrança/transação.

Inicialmente, "WAITING_PAYMENT“ é o status padrão após gerar uma cobrança e aguardar o pagamento do usuário

pixQrCode

string

Imagem QRCode codificado em Base64 (data:image/png;base64)

pixCode

string

Código PIX Copia e Cola

generateTime

string | timestamp

Data/momento da geração do pagamento

expirationDate

string | timestamp

Data/momento da expiração do pagamento

paymentLink

string

URL para link de pagamento

JSON 

{
    "transactionId":"cd722e93-032f-45e1-b638-87a2490dcea7",
    "status":"WAITING_PAYMENT",
    "pixQrCode":"iVBORw0KGgoAAAANSUhEUgAABbQAAAW0CAYAAAAeooXXAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2kGu5DqSRNFmI/a/ZfbwVw7+Q2XLM2UWfs4CBKdIKQIXOvfe+z8AAAAAABDuf98eAAAAAAAA...",
    "pixCode":"00020101021226880014br.gov.bcb.pix2566qrcode-h.firebanking.com.br/QR/cob/EEA7B851BBAFFB546073CE80810F56AA0F95204000053039865802BR5925VICTOR NERY TEIXEIRA CONS6009Sao Paulo610905726-10062070503***630498E0",
    "generateTime":"2024-04-14T02:58:04.997Z",
    "expirationDate": "2024-04-15T02:58:04.997Z",
    "paymentLink":"https://pay.firebanking.com.br/cd722e93-032f-45e1-b638-87a2490dcea7"
}