Paycheckout

Checkout por API

# Criar Checkout via API

Para gerar uma solicitação de Checkout a partir de um sistema externo, é necessário enviar uma requisição POST para a seguinte API (ambiente de PRODUÇÃO):

O corpo da solicitação consiste em 6 parâmetros e três objetos aninhados, delineados abaixo:

• amount*: Custo do produto ou serviço pelo qual a cobrança é realizada.
• externalId*: Número de referência ou identificador único da transação. Este número deve ser exclusivo para a respectiva chave.
• externalProductId*: Número de identificação do produto no sistema externo.
• externalProductName*: Nome do produto no sistema externo.
• key*: Chave gerada no Sistema Bass Pago.
• solicitacao*: Mensagem de texto.

Objeto devedor*:

• devedorCep*: CEP do endereço do devedor. Deve conter apenas 8 dígitos.
• devedorEndereco*: Endereço do devedor, incluindo rua e número.
• devedorBairro*: Bairro do endereço do devedor.
• devedorCidade*: Cidade do endereço do devedor.
• devedorUf*: Estado (UF) do endereço do devedor. Deve conter apenas 2 letras.
• devedorDdd: DDD do telefone do devedor.
• devedorTelefone: Número de telefone do devedor.
• devedorMail: E-mail do usuário que efetua o pagamento. Por meio desse e-mail, o devedor receberá notificações sobre a conclusão do pagamento. (IMPORTANTE: Este parâmetro é opcional. Se fornecido, o Sistema Bass Pago enviará notificações por e-mail ao devedor, informando sobre a nova cobrança criada em seu nome, além de lembretes antes do vencimento da cobrança.)
• devedorNome*: Nome completo do devedor.

Objeto boleto:

• dataDeVencimento*: Data de Vencimento do Boleto. No formato yyyy-MM-dd.
• boletoDescontoDataFixa: Data de Desconto do Boleto. No formato yyyy-MM-dd.
• descontoValorPerc: Valor de Desconto do Boleto. Percentual aplicado até a data de desconto.
• jurosValorPerc: Juro percentual aplicado ao valor do boleto após o vencimento (máximo 1%).
• multaValorPerc: Multa percentual aplicada ao valor do boleto após o vencimento (máximo 2%).
• boletoExpired: Se juros ou multas forem aplicados, o boleto permanecerá disponível para pagamento pelo número de dias indicado após a data de vencimento. (Caso a data não seja fornecida, por padrão, serão configurados automaticamente 90 dias após o vencimento.)

Objeto pix:

• dataDeVencimento*: Data de Vencimento do PIX. No formato yyyy-MM-dd.
• pixDescontoDataFixa: Data de Desconto do PIX. No formato yyyy-MM-dd.
• descontoValorPerc: Valor de Desconto do PIX. Percentual aplicado até a data de desconto.
• jurosValorPerc: Juro percentual aplicado ao valor do PIX após o vencimento.
• multaValorPerc: Multa percentual aplicada ao valor do PIX após o vencimento.
• boletoExpired: Se juros ou multas forem aplicados, o boleto permanecerá disponível para pagamento pelo número de dias indicado após a data de vencimento. (Caso a data não seja fornecida, por padrão, serão configurados automaticamente 90 dias após o vencimento.)

Com o exposto acima, a solicitação deve conter:

        {
	"amount": "10",
	"externalId": "ABCD00001",
	"externalProductId": "PROD00001",
	"externalProductName": "Produto",
	"key": "19r17NxcQBBZiJsCqydpZvPkr3ZKFsru",
	"solicitacao": "Pagamento de Produto",
	"devedor": {
		"devedorCep": "98300000",
		"devedorEndereco": "Rua Jon Cecato",
		"devedorBairro": "Solar das Missoes",
		"devedorCidade": "Palmeira das Missoes",
		"devedorUf": "RS",
		"devedorDdd": "55",
		"devedorTelefone": "990010035",
		"devedorInscricaoNacional": "60375093072",
		"devedorMail": "[email protected]",
		"devedorNome": "BERNARDO FRANCISCO AGUIRRE"
	},
	"boleto": {
		"dataDeVencimento": "2023-08-18",
		"boletoDescontoDataFixa": "2023-08-14",
		"descontoValorPerc": 0,
		"jurosValorPerc": 0,
		"multaValorPerc": 0,
		"boletoExpired": 10
	},
	"pix": {
		"dataDeVencimento": "2023-08-18",
		"pixDescontoDataFixa": "2023-08-14",
		"descontoValorPerc": 0,
		"jurosValorPerc": 0,
		"multaValorPerc": 0,
		"pixExpired": 5
	}
}

      

        {
	"token": "PMU5O4RL107YWT6XR2U0EXBE1AG6ZUKSTPDMCEDHWQJYU4US",
	"key": "19r17NxcQBBZiJsCqydpZvPkr3ZKFsru",
	"referenceNumber": "PCH4ODS0BH0",
	"externalProductId": "PROD00001",
	"amount": 1.0
}

      

        {
	"message": "notValidKey"
}

      

O campo "token" é um elemento essencial que desempenha um papel central nas etapas subsequentes do processo. Ele é gerado de forma exclusiva para cada transação de Checkout realizada, servindo como uma espécie de "chave" que identifica e autoriza a continuidade das interações.

Por sua vez, o campo “referenceNumber” possui a função de ser um identificador único e exclusivo gerado pelo Sistema Bass Pago para cada transação. Esse número serve como uma referência para rastrear e associar os dados da transação específica, auxiliando na organização e controle.

Os demais dados contidos nesse contexto permitem uma validação mais detalhada do solicitante dos dados armazenados. Essa validação ajuda a assegurar a autenticidade e a integridade dos dados envolvidos na transação.

A partir desse ponto, surge a opção de conclusão do processo de duas formas distintas:

URL de Pagamento: Nesse caso, o processo pode ser direcionado para uma URL específica de pagamento, onde o usuário final pode efetuar o pagamento de maneira convencional.

Continuação via API: Alternativamente, a integração pode prosseguir através da API, o que requer que a empresa que realiza a integração implemente as etapas finais do processo. Isso possibilita um maior controle sobre o fluxo de pagamento e personalização da experiência para os usuários finais.

Essas abordagens oferecem flexibilidade na conclusão do processo, permitindo que a solução seja adaptada às necessidades específicas da empresa e dos clientes.

# Checkout por URL

Neste cenário, o Sistema Bass Pago assume a responsabilidade de proporcionar a interface de usuário durante o processo de pagamento. Isso significa que o pagador terá a oportunidade de selecionar o método de pagamento de sua preferência, tudo dentro do ambiente provido pelo Sistema Bass Pago. Quando o pagamento for devidamente identificado e confirmado, uma notificação será enviada por meio do WebHook correspondente.

Para criar o link que direcionará o usuário ao processo de pagamento, basta construir um URL usando o formato indicado. Isso permitirá aos pagadores acessarem o ambiente de pagamento de forma conveniente e intuitiva, facilitando a conclusão bem-sucedida do processo.

Exemplo de acordo com o Token Obtido na solicitação anterior:

A partir desse ponto, o Sistema Bass Pago assume a continuidade das etapas restantes do processo. Essa URL pode ser integrada em um iFrame dentro do site da empresa ou, alternativamente, possibilitar que o usuário que está efetuando o pagamento simplesmente clique no link correspondente. Isso garante uma experiência de pagamento fluida e conveniente para os usuários.

# Integração através da API

Essa abordagem de integração oferece à equipe a capacidade de, uma vez que um Paycheckout é iniciado e um token é obtido, escolher o tipo de Cobrança que será disponibilizado para o usuário final e gerar os documentos em PDF correspondentes à cobrança (tanto para Boleto quanto para PIX).

• API para Listagem de Tipos de Pagamento associados a um Token

Essa API retorna os tipos de pagamento associados a um Token específico. A resposta será influenciada pela maneira como a chave foi criada no sistema. Se uma única opção de pagamento foi selecionada, a resposta refletirá isso. Se, durante a API de criação do Checkout via API, apenas um dos objetos PIX ou BOLETO foi enviado, a resposta será ajustada de acordo.

IMPORTANTE: Esta API não é obrigatória, sendo concebida como uma ferramenta auxiliar para exibir ao usuário informações relevantes baseadas em cada tipo de pagamento. Ela oferece suporte para uma experiência mais informativa e personalizada durante o processo de pagamento.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP"
}

      

Resposta:

A resposta compreende uma lista de tipos de pagamento, com os parâmetros de resposta detalhados abaixo.

• trxOperationTypeName: Nome da operação de pagamento. (Valores possíveis: PAY_CHECKOUT_BOLETO_BRL, PAY_CHECKOUT_PIX_BRL, PAY_CHECKOUT_CARD_BRL)
• trxOperationTypeCode: Código da operação de pagamento. (Valores possíveis: PAY_CHECKOUT_BOLETO, PAY_CHECKOUT_PIX, PAY_CHECKOUT_CARD)
• amount: Valor a ser pago de acordo com o tipo de operação.
• taxa: Taxa da operação. (Em alguns casos, podem existir taxas de processamento aplicadas além do valor processado, dependendo do tipo específico.)
• trxWalletCurrencyCode: Código da moeda. (Valores possíveis: BRL)
• dataDeVencimento: Data de vencimento para este tipo de pagamento. Se houver Juro e/ou Multa, eles serão aplicados a partir do dia seguinte ao vencimento. Caso contrário, o pagamento é considerado concluído.
• descontoDataFixa: Data de desconto para este tipo de pagamento, caso esteja configurado.
• descontoValorPerc: Valor percentual de desconto.
• multaValorPerc: Valor percentual da multa.
• jurosValorPerc: Valor percentual de juros.
• dataExpired: Data de fechamento para este tipo de pagamento. Se não houver Juro e/ou Multa, esta data será igual à data de vencimento. (Dados específicos para Pagamento com Cartão)
• cardConfig: Objeto contendo parâmetros de pagamento com cartão.
• splitType: Define se é possível efetuar o pagamento com um ou dois cartões. Neste momento só é permitido com um cartão: SINGLE_CARD.(Valores possíveis: SINGLE_CARD, TWO_CARD)
• parcels: Número máximo de parcelas permitidas na configuração de chave.
• taxInstallment: Quantidade de parcelas a partir das quais é repassado o valor das Taxas para o cliente, conforme configuração da chave.

Observação: Todas as datas estão no horário UTC.

        [
    {
        "trxOperationTypeName": "PAY_CHECKOUT_PIX_BRL",
        "trxOperationTypeCode": "PAY_CHECKOUT_PIX",
        "amount": 100.0,
        "taxa": 0.0,
        "trxWalletCurrencyCode": "BRL",
        "dataDeVencimento": "2024-11-12T23:59:59.999Z",
        "multaValorPerc": null,
        "jurosValorPerc": null,
        "descontoDataFixa": null,
        "descontoValorPerc": null,
        "dataExpired": "2024-11-12T23:59:59.999Z",
        "cardConfig": null
    },
    {
        "trxOperationTypeName": "PAY_CHECKOUT_BOLETO_BRL",
        "trxOperationTypeCode": "PAY_CHECKOUT_BOLETO",
        "amount": 100.0,
        "taxa": 0.0,
        "trxWalletCurrencyCode": "BRL",
        "dataDeVencimento": "2024-11-12T23:59:59.999Z",
        "multaValorPerc": null,
        "jurosValorPerc": null,
        "descontoDataFixa": null,
        "descontoValorPerc": null,
        "dataExpired": "2024-11-12T23:59:59.999Z",
        "cardConfig": null
    },
    {
        "trxOperationTypeName": "PAY_CHECKOUT_CARD_BRL",
        "trxOperationTypeCode": "PAY_CHECKOUT_CARD",
        "amount": 100.0,
        "taxa": 0.0,
        "trxWalletCurrencyCode": "BRL",
        "dataDeVencimento": null,
        "multaValorPerc": null,
        "jurosValorPerc": null,
        "descontoDataFixa": null,
        "descontoValorPerc": null,
        "dataExpired": null,
        "cardConfig": {
            "splitType": "SINGLE_CARD",
            "isDebit": null,
            "isCredit": true,
            "parcels": 12,
            "taxInstallment": 2
        }
    }
]

      

# Criar Paycheckout PIX

Através dessa API, é possível gerar o QR Code correspondente a um pagamento via PIX. O QR Code gerado representa a informação necessária para que o pagador possa efetuar o pagamento utilizando o sistema PIX. Essa abordagem agiliza o processo de pagamento e oferece aos usuários uma maneira conveniente de realizar transações financeiras utilizando essa tecnologia de pagamentos instantâneos.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP"
}

      

Resposta:

• referenceNumber: O campo referenceNumber é um identificador único gerado pelo Sistema Bass Pago.
• externalId*: Número de referência ou identificador único da transação. Esse número não pode ser duplicado para a mesma chave.
• externalProductId*: Número de identificação do produto no sistema externo.
• externalProductName*: Nome do produto no sistema externo.
• amount: Valor a ser pago de acordo com o tipo de operação.
• key: Chave gerada pelo Sistema Bass Pago.
• devedorMail: E-mail do usuário que realiza o pagamento.
• status: Status do pagamento.
• type: Tipo de pagamento.
• merchantName: Nome da empresa.
• merchantDocument: CNPJ da empresa.
• createdAt: Data de criação.
• keyCurrencyCode: Código de moeda.
• qrCode: QR Code do PIX.
• taxa: Taxa de operação. (Em alguns casos, podem existir taxas de processamento aplicadas acima do valor processado, de acordo com um tipo específico.)
• totalAmount: Valor total a ser pago.
• dataDeVencimento: Data de vencimento do PIX.
• dataExpired: Data de expiração do PIX.

        {
	"referenceNumber": "PCH2CIZO1QW",
	"externalId": "ABCD00042",
	"externalProductId": "PROD00001",
	"externalProductName": "Paquete",
	"amount": 2.0,
	"key": "xm9RSLfh3QW4PvFkIaDItbdjkdzyo2kZ",
	"devedorMail": "[email protected]",
	"status": "PENDING",
	"type": "PIX",
	"merchantName": "EMPRESA PAGAMENTOS LTDA",
	"merchantDocument": "31111110000190",
	"createdAt": "2023-08-16T17:22:27.243216Z",
	"keyCurrencyCode": "BRL",
	"qrCode": "00020126940014BR.GOV.BCB.PIX2572api-pix.bancobs2.com.br/spi/v2/cobv/80953ce1-e11f-4133-9a6e-a8fdeb6e286652040000530398654042.005802BR5909Bass Pago6015Palmeira das Mi61089830097162070503***63048AAF",
	"taxa": 0.0,
	"totalAmount": 2.0,
	"dataExpired": "2023-08-18T06:00:00Z",
	"dataDeVencimento": "2023-08-18T03:00:00Z"
}

      

Esses parâmetros detalhados oferecem informações abrangentes sobre a transação PIX, permitindo aos envolvidos uma visão completa do status e dos detalhes da operação financeira.

# Obter PDF com cobrança PIX

Esta API devolve uma Fatura de Cobrança, em formato PDF.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP"
}

      

# Criar Paycheckout Boleto

Por meio dessa API, é possível gerar tanto o Código de Barras quanto a Linha Digitável associados a um boleto de pagamento. Esses elementos são essenciais para que o pagador possa efetuar o pagamento do boleto de forma precisa e conveniente. A geração automática do Código de Barras e da Linha Digitável agiliza o processo de pagamento e oferece aos usuários uma maneira eficaz de efetuar transações financeiras utilizando o método de pagamento por boleto. Isso garante uma experiência mais fluida e evita possíveis erros manuais na inserção dos dados do boleto ao realizar o pagamento.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP"
}

      

Resposta:

• referenceNumber: O campo referenceNumber é um identificador único gerado pelo Sistema Bass Pago.
• externalId: Número de referência ou identificador único da transação. Este número não pode ser repetido para a mesma chave.
• externalProductId: Número de identificação do produto no sistema externo.
• externalProductName: Nome do produto no sistema externo.
• amount: Valor a ser pago de acordo com o tipo de operação.
• key: Chave gerada pelo Sistema Bass Pago.
• devedorMail: E-mail do usuário que realiza o pagamento.
• status: Status do pagamento.
• type: Tipo de pagamento.
• merchantName: Nome da empresa.
• merchantDocument: CNPJ da empresa.
• createdAt: Data de criação.
• keyCurrencyCode: Código da moeda.
• codigoBarras: Este código deve ser convertido em um código de barras e lido automaticamente por dispositivos.
• linhaDigitavel: Linha Digitável do Boleto.
• taxa: Taxa de operação. (Em alguns casos, a pedido de alguns clientes, podem existir taxas que são aplicadas acima do valor do pagamento, de acordo com um tipo específico.)
• totalAmount: Valor total a ser pago.
• dataDeVencimento: Data de vencimento do boleto.
• dataExpired: Data de encerramento do boleto.

        {
	"referenceNumber": "PCHP5P37ZGT",
	"externalId": "ABCD00049",
	"externalProductId": "PROD00001",
	"externalProductName": "Paquete",
	"amount": 2.0,
	"key": "xm9RSLfh3QW4PvFkIaDItbdjkdzyo2kZ",
	"devedorMail": "[email protected]",
	"status": "PENDING",
	"type": "BOLETO",
	"merchantName": "EMPRESA PAGAMENTOS LTDA",
	"merchantDocument": "31111110000190",
	"createdAt": "2023-08-17T17:20:44.738850Z",
	"keyCurrencyCode": "BRL",
	"codigoBarras": "63394944800000002000001112228089400156715338",
	"linhaDigitavel": "63390001161222808940001567153380494480000000200",
	"taxa": 0.0,
	"totalAmount": 2.0,
	"dataExpired": "2023-08-31T03:00:00Z",
	"dataDeVencimento": "2023-08-21T03:00:00Z"
}

      

Esses parâmetros fornecem um panorama abrangente das transações realizadas através do Paycheckout Boleto, permitindo que todas as partes envolvidas compreendam e gerenciem as informações essenciais para o processo de pagamento por boleto.

# Obter PDF com cobrança Boleto

Esta API devolve o PDF de Boleto.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP",
	"key": "BYJ0ZzDl9NtM59jaGPJVLVCEb5qR5Wp7"
}

      

# Pagamento com Cartão

Para pagamento com cartão, está disponível uma API que fornece uma lista de parcelas, definida com base no valor a ser cobrado e nas configurações definidas na chave. Permite que seja mostrado ao cliente o valor a pagar por cada parcela e os impostos por parcelamento, caso tenha sido configurado.

        {
	"token": "QUWV8V6W9ZGZEBJ8Q25MIV0ZY7MUTOY0WTULIVA3XW2HPYNP",
        "brand" : "VISA"
}

      

• brand: Bandeira do cartão (Primeiro você deve capturar o número do cartão e validar a bandeira, ou solicitar diretamente ao usuário a bandeira do cartão). Existem taxas diferentes de acordo com o tipo de bandeira. (Valores possíveis: VISA, MASTERCARD, AMEX, ELO, HIPERCARD)

Resposta:

• parcelNumber: Número da parcela.
• parcelValue: Valor da parcela.
• totalTax: Valor dos juros.
• totalPayment: Valor total do pagamento.

        [
    {
        "parcelNumber": 1,
        "parcelValue": 104.22,
        "totalTax": 4.22,
        "totalPayment": 104.22
    },
    {
        "parcelNumber": 2,
        "parcelValue": 52.81,
        "totalTax": 5.62,
        "totalPayment": 105.62
    }
]

      

Com esta lista é possível mostrar ao usuário as opções de loteamento e os possíveis valores a pagar.

API de Pagamento: Para efetuar o pagamento, é utilizada a seguinte API

        {
    "token" : "KMSCMVNS9QGEHMSGTYBK3JENCZ0KYZDSE9L37V844CA5V1YM",
    "installments" : 2,
    "cardInfoCardNumber" : "4176660000000100",
    "brand" : "VISA",
    "cardInfoCardholderName" : "JOHN D. DOE",
    "cardInfoSecurityCode" : "597",
    "cardInfoExpirationMonth" : "12",
    "cardInfoExpirationYear" : "2027",
    "isCardSplit" : false
}

      

O corpo da solicitação consiste em:

• token: Token do checkout
• installments: Número de parcela
• cardInfoCardNumber: Número do cartão. Só números
• brand: Bandeira do cartão
• cardInfoCardholderName: Nome do proprietario do cartão
• cardInfoSecurityCode: CVV do cartão
• cardInfoExpirationMonth: Mês de vencimento do cartão
• cardInfoExpirationYear: Ano de vencimento do cartão
• isCardSplit: No caso de pagamento com dois cartões, envie “true”. No momento, apenas “false” é aceito

A resposta em caso de pagamento correto é um HTTP Status 200.

Em caso de pagamento incorreto, a resposta é um HTTP Status 400 (Bad Request).

        {
    "entityName": "pyPayCheckout",
    "errorKey": "14 - Invalid card number",
    "type": "https://www.jhipster.tech/problem/problem-with-message",
    "title": "14 - Invalid card number",
    "status": 400,
    "message": "error.14 - Invalid card number",
    "params": "pyPayCheckout"
}