Criar uma cobrança

Uma vez que a cobrança for gerada, a "vida" é controlada pelo Gestor de Cobranças.

Para gerar uma cobrança, é necessário ter um token válido e utiliza o endpoint POST Criar Cobrança (Order), ou utilizar o portal de cobranças, disponibilizado pela Celcoin para que cada cobrador utilize para as cobranças da sua conta.

Todas as telas são responsivas para formatos Desktop ou Mobile e podem ser também incluídas dentro dos seus canais em formato Whitelabel, sem a necessidade de direcionar seu cliente (gerador da cobrança) para um portal externo.

Jornadas whitelabel no Portal de Cobranças

Abaixo, algumas telas da geração dentro do Portal de Cobranças. Essas telas estão em constante ajuste para contemplar os novos métodos de pagamento adicionados e outras evoluções do produto.

Criando uma cobrança

Ao realizar a chamada de criação, deverá ser informado:

Título da cobrança (será exibida ao pagador)
Descrição (será exibida ao pagador)
Valor original da cobrança.
Data de expiração da cobrança (pode ser um prazo determinado ou indeterminado, cenário no qual não há expiração automática da cobrança)
Pagador (opcional, pode ou não ser especificado, é utilizado para controle, mas não restringe que o pagamento seja feito apenas pelo pagador original da cobrança - para alguns métodos como boletos, é necessário que o pagador seja especificado)
Dados do pagador (Nome Completo, CPF, endereço, email e telefone)
Indicação de envio automático de notificações (true ou false)
Métodos de pagamento permitidos para o pagador
Regras específicas por método de pagamento (ex: quantidade de parcelas)

Após ser feita a geração da cobrança, os dados utilizados na geração ficam armazenados, independente do método de pagamento escolhido pelo seu cliente, permitindo que a qualquer momento você obtenha os dados que foram definidos por quem criou a cobrança.

Toda cobrança gera automaticamente um link de pagamentos com os padrões visuais estabelecidos naquele momento, que pode ou não ser disponibilizado para o pagador, a critério de quem gerou a cobrança.

Uma vez gerada a cobrança, o status é controlado pelo Gestor de Cobranças, podendo ficar:

Aguardando Pagamento (REGISTERED)
Recebido (nesse caso, é possível identificar o método utilizado no recebimento) (PAID)
Expirado (o link expirou sem que o pagamento fosse feito dentro do prazo definido na geração da cobrança) (EXPIRED)
Cancelado (pedido de cancelamento feito pelo gerador da cobrança) (CANCELED)
Estornado (há status específicos para estorno parcial ou integral) (PARTIAL_PAID)

Modelo de Requisição:

Request

curl --request POST
--url https://sandbox.openfinance.celcoin.dev/baas/v1/payment-links/orders
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ****' \

{
    "clientRequestId": "ref-4975801-124",
    "account": "4975801",
    "amount": 5.00,
    "type": "SINGLE_PAYMENT",
    "recurrency": "ONE_SHOT",
    "recurrencyInstruction": {
        "expirationDate": "2026-05-28"
    },
    "description": {
        "title": "Mensalidade PayTrainer",
        "lines": [
            "Serviço com assinatura mensal",
            "Apenas pagamento de cartão"
        ]
    },
    "paymentMethods": {
        "pix": {
            "allowed": true,
            "pixKey": "15663289003"
        },
        "creditCard": {
            "allowed": true,
            "installments": 1
        },
        "openFinance": {
            "allowed": true
        }
    },
    "redirectAfterPaymentUrl": "https://www.celcoin.com.br"
}

Campos da requisição:

Campo Pai	Campo	Descrição	Tipo	Limitação caracteres	Obrigatório
—	clientRequestId	ID externo de referência do cliente	string	255	Sim
—	account	ID da conta bancária vinculada à cobrança	string	255	Sim
—	amount	Valor da cobrança em reais	number	Valor positivo maior que zero	Sim
—	type	Tipo da cobrança: SINGLE_PAYMENT	string		Sim
—	recurrency	Recorrência da cobrança. MONTHLY(mensal) ou ONE_SHOT(cobrança única)	enum		Sim
—	recurrencyInstruction	Instruções de recorrência. Obrigatório para recorrência MONTHLY.	object		Condicional
—	customer	Dados do cliente pagador	object		Não
—	description	Descrição da cobrança	object		Sim
—	paymentMethods	Métodos de pagamento disponíveis para a cobrança	object		Sim
—	customizationId	Id da customização, caso não informado, será injetado o template padrão da conta - se houver.	string		Não
—	redirectAfterPaymentUrl	URL de redirecionamento após o pagamento	string	Checagem se é uma URL válida	Não
recurrencyInstruction	quantity	Quantidade de recorrência de uma cobrança (apenas para recorrência MONTHLY)	number	Min 0 e máximo 100. Sendo 0 referente à uma recorrência sem prazo de finalização	Não
recurrencyInstruction	dueDate	Data de vencimento no formato YYYY-MM-DD. (disponível apenas para cartão de crédito)	string	Formato YYYY-MM-DD	Não
recurrencyInstruction	expirationDate	Data de expiração no formato YYYY-MM-DD. (disponível para cartão de crédito, pix e pix com open finance)	string	Formato YYYY-MM-DD	Não
customer	externalCustomerId	ID externo do cliente cadastrado na plataforma. Quando informado, os dados do cliente são buscados do cadastro e os campos inline são ignorados.	string		Não
customer	name	Nome do cliente. Obrigatório quando externalCustomerId não é informado.	string	255	Condicional
customer	document	CPF ou CNPJ do cliente (somente números). Obrigatório quando externalCustomerId não é informado.	string	11 ou 14 caracteres sem máscara	Condicional
customer	socialName	Nome social do cliente. Ignorado quando externalCustomerId é informado.	string	255	Não
customer	address	Endereço do cliente. Ignorado quando externalCustomerId é informado.	object		Não
customer.address	postalCode	Código Postal (CEP)	string	8 dígitos sem máscara	Sim
customer.address	street	Rua	string	255	Sim
customer.address	number	Número da casa - podendo estar como "S/N"	string	15, apenas dígitos ou “S/N”	Sim
customer.address	city	Cidade	string	255	Sim
customer.address	complement	Complemento do endereço	string	255	Não
customer.address	state	Estado	string	2 caracteres	Sim
description	title	Título da cobrança	string	255	Sim
description	lines	Descrições detalhadas da cobrança, máximo três posições	array[string]	255	Não
paymentMethods	pix	Configuração de pagamento Pix	object		Sim
paymentMethods.pix	allowed	Pagamento via pix habilitado	boolean		Sim
paymentMethods.pix	pixKey	Chave pix	string	255	Condicional
paymentMethods	creditCard	Configuração de pagamento por cartão	object		Sim
paymentMethods.creditCard	allowed	Pagamento via cartão de crédito habilitado	boolean		Sim
paymentMethods.creditCard	installments	Número máximo de parcelas	number	Quando for recorrência MONTHLY, não precisa informar, caso informe, precisa ser o valor 1.	Condicional
paymentMethods.creditCard	split	Configuração de split para cartão de crédito	array[object]	Somatório dos valores dos splits não pode ultrapassar 100	Não
paymentMethods.creditCard.split	account	Identificador numérico de uma conta Celcoin	string	255	Sim
paymentMethods.creditCard.split	value	Valor - em porcentagem - da cobrança para ser dividida entre a conta originária e a informada	number	Valor positivo até 100. Podendo ter uma casa decimal de precisão. Ex: 0,5 é meio por cento	Sim
paymentMethods	openFinance	Configuração de Open Finance	object		Sim
paymentMethods.openFinance	allowed	Pagamento pix via open finance habilitado	boolean		Sim

Response

{
    "version": "1.0.0",
    "body": {
        "id": "6a173a993895abb40ce87724",
        "clientRequestId": "ref-4975801-124",
        "account": "4975801",
        "amount": 5,
        "type": "SINGLE_PAYMENT",
        "status": "REGISTERED",
        "recurrency": "ONE_SHOT",
        "recurrencyInstruction": {
            "quantity": 0,
            "expirationDate": "2026-05-28"
        },
        "paymentMethods": {
            "pix": {
                "allowed": true,
                "pixKey": "15663289003"
            },
            "creditCard": {
                "allowed": true,
                "installments": 1
            },
            "openFinance": {
                "allowed": true
            }
        },
        "receiver": {
            "name": "Nome Sobrenome",
            "document": "12345678910",
            "socialName": "Nome",
            "accountType": "TRAN",
            "bank": {
                "account": "4975801",
                "branch": "0001",
                "ispb": "13935893"
            },
            "address": {
                "postalCode": "12211400",
                "street": "Av Paulista",
                "number": "313",
                "city": "São Paulo",
                "state": "SP"
            }
        },
        "description": {
            "title": "Mensalidade PayTrainer",
            "lines": [
                "Serviço com assinatura mensal",
                "Apenas pagamento de cartão"
            ]
        },
        "redirectAfterPaymentUrl": "https://www.celcoin.com.br",
        "paymentUrl": "https://payment-links/orders/6a173a993895abb40ce87724?token=bca017ae-ab53-4266-87ac-5b4e02daa52c",
        "createdAt": "2026-05-27T18:40:25.381Z",
        "updatedAt": "2026-05-27T18:40:25.381Z"
    },
    "status": 200
}

Campos da resposta

Objeto	Campo	Descrição	Tipo
—	id	Identificador único da cobrança	string
—	clientRequestId	Identificador externo da cobrança na instituição financeira	string
—	clientId	ID do cliente vinculado à cobrança	string
—	account	ID da conta bancária vinculada	string
—	amount	Valor da cobrança em reais	number
—	type	Tipo da cobrança	enum
—	status	Status atual da cobrança	enum
—	recurrency	Recorrência da cobrança	enum
—	recurrencyInstruction	Instruções de recorrência de uma cobrança	object
—	paymentMethods	Métodos de pagamento disponíveis	object
—	customer	Dados do pagador/cliente (campos sensíveis mascarados)	object
—	receiver	Dados do recebedor	object
—	description	Descrição da cobrança	object
—	customization	Customizações visuais da página de pagamento	object
—	redirectAfterPaymentUrl	URL de redirecionamento após o pagamento	string
—	paymentUrl	URL da página de pagamento	string
—	canceledAt	Data em que foi cancelada	Date
—	createdAt	Data de criação do registro	Date
—	updatedAt	Data da última atualização	Date
recurrencyInstruction	quantity	Quantidade de recorrencia de uma cobrança	number
recurrencyInstruction	dueDate	Data de vencimento no formato YYYY-MM-DD	string
recurrencyInstruction	expirationDate	Data de expiração no formato YYYY-MM-DD	string
paymentMethods	pix	Configuração de pagamento Pix	object
paymentMethods	creditCard	Configuração de pagamento por cartão	object
paymentMethods	openFinance	Configuração de Open Finance	object
paymentMethods.creditCard	allowed	Pagamento via cartão de crédito habilitado	boolean
paymentMethods.creditCard	installments	Número máximo de parcelas	number
paymentMethods.creditCard	split	Configuração de split para cartão de crédito	array[object]
paymentMethods.creditCard.split[]	account	numberAccount Celcoin. Se omitido, o backend usa o account da order	string
paymentMethods.creditCard.split[]	value	Percentual de split (1–100)	number
customer	name	Nome	string
customer	document	Documento	string
customer	socialName	Nome social/fantasia	string
customer	address	Endereço do cliente	object
receiver	name	Nome	string
receiver	document	Documento	string
receiver	socialName	Nome social/fantasia	string
receiver	accountType	Tipo de conta do recebedor	enum
receiver	bank	Dados bancários do recebedor	object
receiver	address	Endereço do recebedor	object
receiver.bank	branch	Agência	string
receiver.bank	account	Número da conta bancária	string
receiver.bank	ispb	Código ISPB do banco	string
receiver.address	postalCode	Código Postal (CEP)	string
receiver.address	street	Rua	string
receiver.address	number	Número da casa - podendo estar como S/N	string
receiver.address	city	Cidade	string
receiver.address	complement	Complemento do endereço	string
receiver.address	state	Estado	string
customization	customizationId	ID de um template de customização salvo na plataforma	string
customization	primaryColor	Cor primária em formato hexadecimal	string
customization	secondaryColor	Cor secundária em formato hexadecimal	string
customization	logo	Logotipo da conta em base64 data URI. Formatos aceitos: png, jpeg, svg. Tamanho máximo: 2MB	string
customization	borderRadius	Raio de borda dos componentes	number
customization	theme	Tema visual	enum

Updated about 4 hours ago