Documentação da API do BS Bank

A API BS Bank serve para integrar sistemas informatizados para realizar e gerenciar cobranças de cartão de crédito, boletos e PIX no mundo online, bem como gerenciar transações de cartão de crédito e débito por dispositivos POS. É uma solução simples, completa e inovadora para seu caso de uso.

A comunicação com a API é feita majoritariamente através de GraphQL, alternativa a REST, sendo um protocolo de comunicação inovador e agnóstico à linguagem de programação, também usando HTTP e JSON.

Para uma experiência completa, acesse o GraphQL Playground da nossa API. Lá você encontrará todas as chamadas disponíveis, embora algumas possam ter menos descrição dos campos. Além de ser uma ferramenta para explorar a documentação, o GraphQL Playground também permite testar consultas e mutações em tempo real.

Nosso objetivo com a documentação é facilitar o processo de integração para nossos usuários. Embora ainda esteja em constante aprimoramento, ela já inclui todas as chamadas essenciais para o fluxo de cobrança em nossa API.

Valorizamos muito o seu feedback. Se encontrar alguma lacuna na documentação ou tiver sugestões de melhorias, não hesite em nos informar. Estamos sempre em busca de aprimorar nossa documentação para melhor atender às suas necessidades de integração.

Abraço, sucesso e muito obrigado.

Equipe BS Bank

Por onde começar

Antes de começar a utilizar nossa API, recomendamos que você explore nossa documentação para entender melhor os conceitos do GraphQL. Na seção de Conceitos do GraphQL, você encontrará explicações detalhadas sobre cada aspecto importante da linguagem GraphQL. Isso proporcionará uma base sólida para aproveitar ao máximo os recursos da nossa API.

Compreender os conceitos fundamentais do GraphQL antes de utilizar nossa API é essencial para garantir uma integração eficaz e bem-sucedida. Ao dominar os conceitos de consultas, mutations, Schema, argumentos, conexões e tipos de dados, você estará mais preparado para criar consultas e mutations que atendam às suas necessidades específicas de integração.

Ao utilizar nossa API de pagamentos, você provavelmente começará criando cobranças, seja por Boleto, cartão de crédito ou PIX. A seção Cobrança da documentação oferece várias chamadas para criação e gerenciamento de cobranças, incluindo as mencionadas acima.

Além disso, na seção Webhook, você aprenderá como criar Webhooks na nossa API para receber notificações de eventos importantes, como o pagamento de um boleto.

Por fim, na seção Objetos, você encontrará a descrição detalhada dos objetos que compõem nossa API, incluindo os campos que podem ser retornados em consultas e mutations.

Compreender esses conceitos e explorar a documentação irá capacitá-lo a utilizar nossa API de forma eficaz e aproveitar ao máximo seus recursos. Estamos ansiosos para vê-lo integrando com sucesso nossa API de pagamentos!

Conceitos de GraphQL

1.Consultas (Queries):
Quando você precisa acessar informações específicas na nossa API, você utilizará consultas. Por exemplo, você pode querer buscar transações recentes, verificar boletos vencidos ou obter detalhes sobre um pagamento em particular. Cada consulta é cuidadosamente projetada para fornecer os dados necessários para suas operações.

2. Mutations (Mutações):
As mutations são usadas para modificar os dados na nossa API. Elas permitem que você execute ações como criar uma nova cobrança, atualizar o status de um pagamento ou cancelar uma transação. É importante lembrar que mutations afetam diretamente os dados na API e devem ser usadas com cautela.

3. Schema da API:
O Schema da nossa API define a estrutura dos dados disponíveis e as operações que podem ser realizadas. Ele serve como um guia para entender quais dados podem ser acessados e quais ações podem ser executadas. Cada tipo de objeto no Schema possui campos que representam os dados associados a esse objeto.

4. Argumentos e Variáveis:
Ao fazer uma consulta ou uma mutation, você pode precisar fornecer informações específicas, como datas, IDs ou valores. Essas informações são passadas como argumentos na própria consulta ou mutation. Além disso, o uso de variáveis permite tornar suas consultas mais dinâmicas, permitindo que você personalize os valores conforme necessário.

5. Resolvers e Conexões:
Os resolvers são responsáveis por buscar os dados solicitados em uma consulta ou realizar as operações definidas em uma mutation. Eles são como "tradutores" que convertem suas consultas e mutations em ações reais no sistema. Nas consultas que envolvem listas de objetos, como transações ou boletos, usamos o conceito de conexões para navegar entre os objetos relacionados de maneira eficiente.

6. Tipos de Dados e Relacionamentos:
Na nossa API GraphQL, os tipos de dados representam os diferentes recursos disponíveis, como transações, cobranças ou clientes. Esses tipos de dados podem ter relacionamentos entre si, definidos no Schema da API. Por exemplo, uma transação pode estar associada a um cliente ou a uma cobrança. Compreender esses relacionamentos é essencial para criar consultas eficazes e entender como os dados estão conectados na API.

Autenticação

A autenticação ocorre por meio do token JWT, mais detalhes sobre este formato em JWT Docs.

Para autenticar, basta executar uma requisição tokenAuth com seu nome de usuário e senha que foram enviados por email. Sendo a solicitação bem-sucedida, você recebe um token utilizado nas requisições subsequentes. A validade do token é de 24h a partir da sua criação.

As demais requisições da API precisam do header HTTP "Authorization": "JWT token", onde token é o token obtido pelo tokenAuth.

POST | TokenAuth

 https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation tokenAuth ($username: String!, $password: String!) {\n tokenAuth (username: $us'

Body graphql

Query

                      
graphql

mutation tokenAuth ($username: String!, $password: String!) {
    tokenAuth (username: $username, password: $password) {
        payload
        refreshExpiresIn
        token
		errors{
			code
			field
			message
		}
        user {
			id
            username
            userType
            firstName
            lastName
            dateJoined
            email
            sandbox
            company{
                id
            }
        }
        
    }
}

                      
json



{
	"username": "",
	"password": ""
}

Instruções para homologação

No ambiente de homologação da API (https://api.sandbox.netcredbrasil.com.br/graphql) você pode fazer todas as chamadas da nossa plataforma sem a necessidade de criar registros reais. Isso, entretanto, tem algumas limitações por enquanto, como não ser possível simular um pagamento de Boleto ou PIX.

No ambiente de homologação existem alguns dados padrão para testar determinada resposta.

Números de cartão

• CPF/CNPJ do Customer com final "1" para aprovação em análise de risco
• CPF/CNPJ do Customer com final diferente de "1" para rejeição em análise de risco

Análise de risco:

• 4970100000000048 para testar a aprovação
• 4970100000000071 para testar a rejeição

IMPORTANTE: evite utilizar dados reais no ambiente de homologação, sempre utilizando ferrametas para a geração de CPFs por exemplo.

Análise de risco

A análise de risco tem como objetivo principal prevenir chargebacks, que ocorrem quando um golpista usa um cartão clonado para efetuar uma compra online. Posteriormente, o legítimo proprietário do cartão percebe a fraude e solicita ao banco o reembolso do valor gasto. Isso resulta na loja não recebendo o pagamento pela compra realizada, mesmo já tendo enviado o produto ao golpista.

Como funciona a análise de risco:

A análise de risco é realizada em duas etapas:

1. Um script será disponibilizado para sua aplicação, coletando dados públicos do dispositivo do usuário para armazenamento no campo SessionID. Essas informações serão enviadas à ClearSale, plataforma de solução antifraude parceira BS Bank. O processo, com duração média de 3 segundos, visa correlacionar esses dados com coletas anteriores. Recomenda-se integrar o script em páginas interativas, preservando a experiência do usuário, sem comprometer a segurança.
2. Ao finalizar o processo de compra, caso a modalidade de pagamento seja cartão, o SessionID deve ser enviado de forma obrigatória no campo sessionId presente dentro do parâmetro orderInput explicado abaixo (e também na seção ChargeCreateCard, se aplicável). Na finalização da criação da cobrança, a combinação dessas informações será enviada à ClearSale, que retornará a aprovação ou rejeição do processo de compra com base na análise feita.

Para ter acesso à documentação completa de como incluir esta funcionalidade em sua solução, acesse o link .

Tipos de análise de risco:

A ClearSale disponibiliza dois tipos de análise:

1. Realtime: Processo instantâneo recomendado para negócios com entrega imediata, como softwares e cursos online. Análise ágil para aprovação ou rejeição de pedidos. Pedidos reprovados podem, ocasionalmente, passar por análise manual de até 3 dias úteis, especialmente pedidos de alto risco.
2. Total Garantido: Ideal para vendas onde a liberação instantânea não é crucial. Análise minuciosa para garantir alta aprovação de pedidos genuínos. Aprovação automática em até 3 horas. Oferece reembolso de até R$ 10.000,00 por pedido em caso de chargeback.

OrderInput:

Junto com o SessionID, deve ser enviada informações sobre o carrinho de compras, que deve ser preenchido com informações precisas, evitando descrições subjetivas e/ou genéricas. Isso é fundamental para aprimorar a eficácia da análise de risco realizada. Essa informação é obrigatória para a análise da ClearSale.

Caso a sua integração não trate com produtos físicos, busque identificar algum serviço prestado relacionado a esta cobrança.

Parâmetros

Formatação dos Dados

Em algumas partes da documentação (principalmente em Objetos) apontamos o tipo dos dados para determinada informação. A seguir estão os padrões para tais tipos

Cobrança

Charge

Create

Aqui você poderá criar cobranças de boleto, cartão e PIX.

A chamada é a mesma (ChargeCreate), mas nem todos os campos funcionam para cada um dos métodos. Aqui separamos as chamadas de forma a identificar o que precisa ser enviado para cada um.

Você notará que alguns inputs estão repetidos, mas julgamos mais fácil de entender quando separamos as chamadas por método na documentação.

Boleto

POST | ChargeCreateBillet

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation chargeCreate ($input: ChargeCreateInput!) {\n chargeCreate (input: $input)'

Parâmetros BilletConditionInput

Parâmetros PaymentProfileInput

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeCreate ($input: ChargeCreateInput!) {
    chargeCreate (input: $input) {
        errors {
            field
            message
            code
        }
        charge {
            created
            modified
            id
          	referenceCode
            amount
            chargeType
            chargeStatus
            extraInfo
            transactions{
                edges{
                    node{
                        id
                        transactionState
						amount
                      	billingAt
                        billedAt
                      	dueAt
                      	paidAt
                      	paidAmount
                      	voidReason
                        printUrl
                        billetInfo{
                            digitableLine
                            barCode
                            pixCopyPaste
                        }
                        payoutRule{
                            id
                            
                        }
                    }
                }
            }
        }
    }
}

                      
json



{
	"input": {
		"companyId": 1014,
		"rrule": "DTSTART:20230610T000000 RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1",
		"amount": "1",
        "submethod": "HYBRID", 
		"paymentProfileInput": {
			"method": "BILLET",
			"billingAddressInput": {
				"street": "Rua 3",
				"number": "Numero 3",
				"district": "Bairro 3",
				"city": "Cidade 3",
				"state": "SC",
				"zipCode": "89225845",
				"additionalDetails": "Detalhes Adicionais 3"

			},
            "shippingAddressInput": {
				"street": "Rua 3",
				"number": "Numero 3",
				"district": "Bairro 3",
				"city": "Cidade 3",
				"state": "SC",
				"zipCode": "89201420",
				"additionalDetails": "Detalhes Adicionais -ship.3"

			},
			"customerInput": {
				"name": "Nome",
				"email": "test@gmail.com",
				"documentType": "CPF",
				"document": "12235241913",
				"phone": "4791824793",
				"persist": true
			}
		},
		"billetConditionInput": {
			"interestType": "PERCENT",
			"interestValue": "1",
			"fineType": "VALUE",
			"fine": "0.1",
            "discountType":"VALUE",
            "discountValue1": "0.98",
            "discountDateDelta1": "0",
            "name": "sicoob_test",
            "message": "Test billet discount",
            "informativeText": "Texto informativo"
		},
        "payoutRuleInput":{
            "persist": false,
            "ruleItems":[
                {
				"bankAccountId": 1235,
				"isLiable": true,
				"proportion": "100",
				"scheduleInput": {
					"automaticAdvance": false,
					"scheduleType": "MONTHLY",
					"scheduleAnchor": 2
				}

                }
            ]

        },
		"extraInfo": "informação Extra",
		"emitAllBillets": true
	}
}
}

Crédito

POST | ChargeCreateCard

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation chargeCreateCard ($input: ChargeCreateInput!) {\n chargeCreate (input: $inp'

Parâmetros PaymentProfileInput

Parâmetros ccInput (dados do Cartão de Crédito)

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

Parâmetros OrderInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeCreateCard ($input: ChargeCreateInput!) {
    chargeCreate (input: $input) {
        errors {
            field
            message
            code
        }
        charge {
            created
            modified
            id
            amount
          	referenceCode
            chargeType
            chargeStatus
            extraInfo
            rrule
            ipAddress
            voidAt
            voidReason
            manualCapture
            billingCycleTotal
            billingCyclesPaid
            billingCyclesProcessed
            ipAddress
          	billDaysInAdvance
            extraInfo
            paymentProfile{
                cardNumber
                token
                billingAddress{
                    additionalDetails
                }
            }
            transactions{
                edges{
                    node{
                        id
                        transactionState
                        captureMedium
                        billingAt
                        cardInfo{
                            cardNumber
                            brand
                        }
                    }
                }
            }
        }
    }
}

                      
json



{
	"input": {
		"companyId": 1013,
		"paymentProfileInput": {
			"method": "CARD",
            "billingAddressInput":{
             "street":"Rua teste",
             "number":"10",
             "district":"district",
             "city":"city",
             "state":"SC",
             "zipCode":"89225845",
             "additionalDetails":"Details here"
            },
			"customerInput": {
				"name": "Nome",
				"email": "testbsbank@gmail.com",
				"documentType": "CPF",
				"document": "12235241913",
				"phone": "9999999999",
				"persist": true
			},
            
			"ccInput": {
				"cardNumber": "5970100300000067",
				"expiryMonth": 12,
				"expiryYear": 2030,
				"cardHolderName": "PEDRO",
				"securityCode": "123"
			}
		},
        "orderInput":{
            "orderItems":[ {
                "productInput":{
                    "name": "Teste product",
                    "amount": 10
            }
            }]
        },
		"amount": "1500",
		"billDaysInAdvance": 0,
		"installmentNumber": 12,
		"extraInfo": "extra information"
	}
}

Pix

POST | CreateChargePix

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation chargeCreate ($input: ChargeCreateInput!) {\n chargeCreate (input: $input)'

Parâmetros PixConditionInput

Parâmetros PaymentProfileInput

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeCreate ($input: ChargeCreateInput!) {
    chargeCreate (input: $input) {
        errors {
            field
            message
            code
        }
        charge {
            created
            modified
            id
          	referenceCode
            amount
            chargeType
            chargeStatus
            extraInfo
			paymentProfile{
					method
						}
            transactions{
                edges{
                    node{
                        id
                        transactionState
						amount
                      	billingAt
                        billedAt
                      	dueAt
                      	paidAt
                      	paidAmount
                      	rejectedReason
                      	voidReason
                        printUrl
						dueAt
                        pixInfo{
                            pixCopyPaste
                        }
                    }
                }
            }
        }
    }
}
}

                      
json



{
	"input": {
		"companyId": "1014",
        "rrule":"",
		"amount": "125.37",
		"paymentProfileInput": {
			"method": "PIX",
			"billingAddressInput": {
				"street": "Rua",
				"number": "Numero",
				"district": "Bairro",
				"city": "Cidade",
				"state": "SC",
				"zipCode": "89201420",
				"additionalDetails": "Detalhes Adicionais"
			},
			"customerInput": {
				"name": "Nome",
				"email": "fake@example.com",
				"documentType": "CPF",
				"document": "12235241913",
				"phone": "9999999999",
				"persist": true
			}
		},
		"pixConditionInput": {
			"interestValueType": "PERCENT",
			"interestType": "DAYS",            
			"interestValue": "5",
			"fineValueType": "VALUE",
			"fineValue": "10",
			"discountType": "DAYS",
			"discountValue": "1",
			"discountValueType": "PERCENT",
            "persist": false
		},
		"extraInfo": "informação Extra",
		"emitAllBillets": false
	}
}

Com Split de Pagamento

Aqui demonstramos como utilizar o input de PayoutRule na criação da cobrança para configurar o split para uma cobrança específica.

O envio da PayoutRule é independente do método utilizado. Neste exemplo o foco é no envio do PayoutRule e esta parte do input pode ser facilmente acrescentada às demais chamadas.

No caso de boleto e PIX, a liquidação é sempre em D+1, portanto a configuração de atencipação "não terá efeito", mas funcionará normalmente para cartão de crédito.

IMPORTANTE: O estabelecimento precisa ter a funcionalidade de seleção de split habilitada, impactando tanto o envio do payoutRuleId quanto payoutRuleInput.

POST | ChargeCreateWithPayoutRule

https://api.sandbox.netcredbrasil.com.br/graphql

Obs.: os demais campos são descritos nas chamadas para cada método

Parâmetros PayoutRuleInput

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation chargeCreate ($input: ChargeCreateInput!) {\n chargeCreate (input: $input) {\n'

Parâmetros RuleItemInput

Parâmetros ScheduleInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeCreate ($input: ChargeCreateInput!) {
    chargeCreate (input: $input) {
        errors {
            field
            message
            code
        }
        charge {
            created
            modified
            id
            amount
          	referenceCode
            chargeType
            chargeStatus
            extraInfo
            rrule
            ipAddress
            voidAt
            voidReason
            manualCapture
            billingCycleTotal
            billingCyclesPaid
            billingCyclesProcessed
            ipAddress
          	billDaysInAdvance
            extraInfo
            paymentProfile{
                cardNumber
                token
                billingAddress{
                    additionalDetails
                }
            }
            transactions{
                edges{
                    node{
                        id
                        transactionState
                        captureMedium
                        billingAt
                        cardInfo{
                            cardNumber
                            brand
                        }
                    }
                }
            }
        }
    }
}

                      
json



{
	"input": {
		"companyId": 1013,
		"paymentProfileId": 99,
		"amount": "1500",
		"installmentNumber": 12,
        "payoutRuleInput": {
            "name": "Novo split",
            "isPrimary": false,
            "persist": true,
            "ruleItems": [
                {
                    "splitType": "PERCENTAGE",
                    "proportion": "100.0",
                    "bankAccountId": 10,
                    "scheduleInput": {
                        "scheduleType": "DAILY",
                        "scheduleAnchor": 1,
                        "automaticAdvance": true
                    }
                }
            ]
        }
	}
}

Void

POST | ChargeVoid

https://api.sandbox.netcredbrasil.com.br/graphql

A mutation ChargeVoid pode ser aplicada em Charges com status ONGOING, e tem com intuito cancelar todas as Transactions SCHEDULED desta Charge.

A Charge e as Transactions afetadas retornarão com o status VOIDED.

Esta chamada é agnóstica ao método (Boleto, Cartão ou Pix) utilizado.

Caso seja necessário cancelar Transactions emitidas ou autorizadas (BILLED), ou agendada individualmente, utilize a chamada TransactionVoid em cada uma.

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation chargeVoid ($input: ChargeVoidInput!) {\n chargeVoid (input: $input) {\n'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeVoid ($input: ChargeVoidInput!) {
    chargeVoid (input: $input) {
        errors {
            field
            message
            code
        }
        charge {
            id
          	referenceCode
            amount
            chargeType
            chargeStatus
            extraInfo
            transactions{
                edges{
                    node{
                        id
                        transactionState
                    }
                }
            }
        }
    }
}

                      
json



{
	"input": {
		"chargeId": 262273
}
}

Transaction

Void

POST | transactionVoid

https://api.sandbox.netcredbrasil.com.br/graphql

Esta chamada cancela uma transação antes do pagamento.

A mutation TransactionVoid pode ser aplicada em Transactions com os status BILLED (emitida/autorizada) ou SCHEDULED (agendada)

A Transaction retornará com o status VOIDED.

Esta chamada é agnóstica ao método (Boleto, Cartão ou Pix) utilizado.

É possível cancelar todas as Transactions agendadas (SCHEDULED) de uma mesma Charge utilizandoa mutation ChargeVoid.

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation transactionVoid ($input: TransactionVoidInput!) {\n transactionVoid (input: $in'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation transactionVoid ($input: TransactionVoidInput!) {
    transactionVoid (input: $input) {
            errors {
                field
                message
                code
            }
            transaction {
                id
                amount
                transactionState
        }
    }
}

                      
json



{
	"input": {
		"transactionId": 262273,
        "voidReason": "Motivo do cancelamento"
}
}

Refund

POST | transactionRefund

https://api.sandbox.netcredbrasil.com.br/graphql

Esta chamada estorna um valor de uma Transaction que ainda possui algum valor pago. Isso quer dizer que uma Transaction pode ter mais de um estorno associado a ela.

A mutation TransactionRefund pode ser aplicada em Transactions com os status PAID (paga) ou PARTIALLY_REFUNDED (parcialmente estornada)

A Transaction retornará com o status REFUNDED (se o valor total estiver estornado) ou PARTIALLY_REFUNDED (se o valor pago paidAmount ainda for maior que o valor estornado refundedAmount).

Esta chamada pode ser usada em transações de Cartão ou PIX feitas online, ou seja, que não originaram de POS.

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation transactionRefund ($input: TransactionRefundInput!) {\n    transactionRefund (input: $input) {\n            errors {\n                field\n                message\n                code\n            }\n            transaction {\n                id\n                amount\n                paidAmount\n                refundedAmount\n                transactionState\n        }\n    }\n}","variables":{"input":{"transactionId":262273}}}'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation transactionRefund ($input: TransactionRefundInput!) {
    transactionRefund (input: $input) {
            errors {
                field
                message
                code
            }
            transaction {
                id
                amount
                paidAmount
                refundedAmount
                transactionState
        }
    }
}

                      
json



{
	"input": {
		"transactionId": 262273
}
}

Customer

Create

POST | CustomerCreate

https://api.sandbox.netcredbrasil.com.br/graphql

Esta chamada cria um novo Customer, o pagador das cobranças, para o estabelecimento indicado.

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation CustomerCreate ($input:CustomerCreateInput!) {\n    customerCreate (input:$input) {\n        errors {\n            field\n            message\n            code\n        }\n        customer {\n            name\n            email\n            document\n        }\n    }\n}","variables":{"input":{"companyId":1015,"document":"73155243554","documentType":"CPF","name":"Customer - Teste","email":"teste@example.com","phone":"47912341234","birthDate":"2000-05-12","gender":"FEMALE"}}}'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation CustomerCreate ($input:CustomerCreateInput!) {
    customerCreate (input:$input) {
        errors {
            field
            message
            code
        }
        customer {
            name
            email
            document
        }
    }
}

                      
json



{
	"input": {
		"companyId": 1015,
		"document": "73155243554",
		"documentType": "CPF",
		"name": "Customer - Teste",
        "email": "teste@example.com",
        "phone": "47912341234",
        "birthDate": "2000-05-12",
        "gender": "FEMALE"
	}
}

PaymentProfile

Um "payment profile", em termos gerais, é um registro seguro de informações de pagamento associadas a um cliente ou conta em um sistema de processamento de pagamentos.

O objetivo principal de um "payment profile" é permitir transações mais seguras e eficientes. Em vez de solicitar repetidamente os detalhes de pagamento a cada transação, o sistema pode usar o "payment profile" para acessar essas informações de forma segura e rápida. Isso proporciona conveniência tanto para os clientes quanto para os comerciantes, reduzindo a necessidade de inserir manualmente os detalhes do pagamento a cada compra.

Além disso, os "payment profiles" podem ser usados para facilitar pagamentos recorrentes, onde os detalhes do pagamento são armazenados uma vez e utilizados para cobranças automáticas em intervalos regulares, como mensalidades de serviços de assinatura.

Em resumo, um "payment profile" é uma ferramenta essencial em sistemas de pagamento online, permitindo a gestão segura e eficiente das informações de pagamento dos clientes.

Create

Crédito

Na cobrança de crédito o paymentProfile exerce um papel fundamental, ajudando na segurança e agilidade em pagamentos recorrentes. As principais vantagens são:

1. Segurança: Armazenar os detalhes do cartão de crédito de um cliente de forma segura é fundamental para proteger informações sensíveis. Ao criar um "payment profile", o sistema geralmente não armazena os detalhes do cartão de crédito do cliente diretamente, mas sim um token único que representa esses detalhes. Isso reduz significativamente o risco de exposição a fraudes ou violações de dados, já que os detalhes do cartão não estão armazenados no sistema.
2. Facilidade de uso: Uma vez que um "payment profile" é criado com sucesso, o token associado a ele pode ser usado para realizar transações futuras sem a necessidade de solicitar novamente os detalhes do cartão de crédito do cliente. Isso proporciona uma experiência conveniente para os clientes, pois não precisam inserir repetidamente as informações do cartão a cada compra.
3. Recorrência e Pagamentos Automáticos: Em modelos de negócios baseados em assinatura ou pagamentos recorrentes, como serviços de streaming, academias online ou planos de software, os "payment profiles" são essenciais. Uma vez que o cliente tenha fornecido os detalhes do cartão e concordado com os termos do serviço, um "payment profile" é criado e utilizado para cobranças automáticas futuras. Isso simplifica o processo de pagamento para o cliente e garante uma receita recorrente para o fornecedor do serviço.
4. Melhoria da Conveniência do Cliente: Ao evitar que os clientes tenham que inserir repetidamente os detalhes do cartão, você está melhorando a experiência do cliente, tornando o processo de compra mais rápido e fácil. Isso pode aumentar as taxas de conversão e a satisfação do cliente.

As chaves que diferenciam um PaymentProfile de cartão são:

• cardNumber
• customer
• expiryYear
• expiryMonth

Caso tente-se criar um um novo PaymentProfile com as chaves de um já existente, o PaymentProfile existente será retornado, ao invés de criar um novo.

POST | createPaymentProfileCard

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros PaymentProfileInput

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation paymentProfileCreateCard ($input:PaymentProfileCreateInput!) {\n  paymentProfileCreate (input:$input) {\n    errors {\n      field\n      message\n      code\n    }\n    paymentProfile {\n        id\n        method\n        isActive\n        cardNumber\n        expiryMonth\n        expiryYear\n        brand\n        cardHolderName\n        token\n        rejectedReason\n        customer{\n            id\n            name\n            documentType\n            document\n        }\n    }\n  }\n}","variables":{"input":{"method":"CARD","customerInput":{"companyId":1014,"name":"Nome","email":"email@email.com","documentType":"CPF","document":"12235241913","phone":"9999999999","persist":true},"ccInput":{"cardNumber":"4970100000000048","expiryMonth":10,"expiryYear":2027,"securityCode":"123","cardHolderName":"Card Holder Name"}}}}\'

Parâmetros ccInput (dados do Cartão de Crédito)

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation paymentProfileCreateCard ($input:PaymentProfileCreateInput!) {
  paymentProfileCreate (input:$input) {
    errors {
      field
      message
      code
    }
    paymentProfile {
        id
        method
        isActive
        cardNumber
        expiryMonth
        expiryYear
        brand
        cardHolderName
        token
        rejectedReason
        customer{
            id
            name
            documentType
            document
        }
    }
  }
}

                      
json



{
	"input": {
		"method": "CARD",
		"customerInput": {
			"companyId": 1014,
			"name": "Nome",
			"email": "email@email.com",
			"documentType": "CPF",
			"document": "12235241913",
			"phone": "9999999999",
			"persist": true
		},
		"ccInput": {
			"cardNumber": "4970100000000048",
			"expiryMonth": 10,
			"expiryYear": 2027,
			"securityCode": "123",
			"cardHolderName": "Card Holder Name"
		}
	}
}

Boleto

A chaves que diferenciam um PaymentProfile de boleto são:

• customer
• billingAddress
• shippingAddress

Caso tente-se criar um um novo PaymentProfile com as chaves de um já existente, o PaymentProfile existente será retornado, ao invés de criar um novo.

POST | createPaymentProfileBillet

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation paymentProfileCreateBillet($input:PaymentProfileCreateInput!) {\n  paymentProfileCreate (input:$input) {\n    errors {\n      field\n      message\n      code\n    }\n    paymentProfile {\n        id\n        method\n        isActive\n        customer{\n            id\n            document\n            documentType\n            name\n        }\n        billingAddress{\n            number\n            street\n            city\n        }\n    }\n  }\n}","variables":{"input":{"method":"BILLET","customerInput":{"companyId":1014,"name":"Nome","email":"email@email.com","documentType":"CPF","document":"12235241913","phone":"47999999999","persist":true},"billingAddressInput":{"number":"10","street":"Rua","district":"Bairro","city":"Cidade","state":"SC","persist":true}}}}\'

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation paymentProfileCreateBillet($input:PaymentProfileCreateInput!) {
  paymentProfileCreate (input:$input) {
    errors {
      field
      message
      code
    }
    paymentProfile {
        id
        method
        isActive
        customer{
            id
            document
            documentType
            name
        }
        billingAddress{
            number
            street
            city
        }
    }
  }
}

                      
json



{
	"input": {
		"method": "BILLET",
		"customerInput": {
			"companyId": 1014,
			"name": "Nome",
			"email": "email@email.com",
			"documentType": "CPF",
			"document": "12235241913",
			"phone": "47999999999",
			"persist": true
		},
		"billingAddressInput": {
            "number": "10",
            "street": "Rua",
            "district": "Bairro",
            "city": "Cidade",
            "state": "SC",
            "persist": true
        }
	}
}

Pix

A chaves que diferenciam um PaymentProfile de Pix são:

• customer
• billingAddress
• shippingAddress

Caso tente-se criar um um novo PaymentProfile com as chaves de um já existente, o PaymentProfile existente será retornado, ao invés de criar um novo.

POST | createPaymentProfilePix

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation paymentProfileCreatePix($input:PaymentProfileCreateInput!) {\n  paymentProfileCreate (input:$input) {\n    errors {\n      field\n      message\n      code\n    }\n    paymentProfile {\n        id\n        method\n        isActive\n        customer{\n            id\n            document\n            documentType\n            name\n        }\n        billingAddress{\n            number\n            street\n            city\n        }\n    }\n  }\n}","variables":{"input":{"method":"PIX","customerInput":{"companyId":1014,"name":"Nome","email":"email@email.com","documentType":"CPF","document":"12235241913","phone":"47999999999","persist":true},"billingAddressInput":{"number":"10","street":"Rua","district":"Bairro","city":"Cidade","state":"SC","persist":true}}}}\'

Parâmetros BillingAddressInput e ShippingAddressInput

Parâmetros CustomerInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation paymentProfileCreatePix($input:PaymentProfileCreateInput!) {
  paymentProfileCreate (input:$input) {
    errors {
      field
      message
      code
    }
    paymentProfile {
        id
        method
        isActive
        customer{
            id
            document
            documentType
            name
        }
        billingAddress{
            number
            street
            city
        }
    }
  }
}

                      
json



{
	"input": {
		"method": "PIX",
		"customerInput": {
			"companyId": 1014,
			"name": "Nome",
			"email": "email@email.com",
			"documentType": "CPF",
			"document": "12235241913",
			"phone": "47999999999",
			"persist": true
		},
		"billingAddressInput": {
            "number": "10",
            "street": "Rua",
            "district": "Bairro",
            "city": "Cidade",
            "state": "SC",
            "persist": true
        }
	}
}

Void

POST | paymentProfileVoid

https://api.sandbox.netcredbrasil.com.br/graphql

Esta chamada desativa um PaymentProfile, de forma que este não poderá mais ser utilizado futuramente. No caso do método CARD também apaga o token salvo.

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation paymentProfileVoid ($input: PaymentProfiçeVoidInput!) {\n    paymentProfileVoid (input: $input) {\n            errors {\n                field\n                message\n                code\n            }\n            paymentProfile {\n                id\n                isActive\n                token\n        }\n    }\n}","variables":{"input":{"paymentProfileId":99}}}'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation paymentProfileVoid ($input: PaymentProfiçeVoidInput!) {
    paymentProfileVoid (input: $input) {
            errors {
                field
                message
                code
            }
            paymentProfile {
                id
                isActive
                token
        }
    }
}

                      
json



{
	"input": {
		"paymentProfileId": 99
}
}

ChargeLink - Link de Pagamento

O ChargeLink é um link de pagamento, que pode ser configurado para ser utilizável apenas uma vez, ou admitindo múltiplos pagamentos. O link também pode ser expirado após determinado tempo é permancer ativo indifinitavemente.

Um link admite os seguintes métodos para pagamento:

• Cartão.
• Boleto normal ou híbrido (permite pagamento via PIX).
• Pix.
• Cartão recorrente.

Caso seja utilizado o método "cartão recorrente" todos os outros métodos deverão ser enviados como false, visto que se trata de outro tipo de transação.

Considerando esses aspectos, é crucial entender que o propósito principal do ChargeLink não é ser um método de pagamento (como boleto, cartão, PIX, etc.), mas sim emitir solicitações de pagamento. Um link ocasionará, após o seu preenchimento, a criação de uma Charge.

Criar ChargeLink

POST | ChargeLinkCreate

https://api.sandbox.netcredbrasil.com.br/graphql

Parâmetros

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation chargeLinkCreate ($input: ChargeLinkCreateInput!) {\r\n    chargeLinkCreate (input: $input) {\r\n        errors {\r\n            field\r\n            message\r\n            code\r\n        }\r\n		chargeLink{\r\n			id\r\n			isActive\r\n			baseAmount\r\n			billetAllowed\r\n			\r\n		}\r\n        \r\n        }\r\n    }\r\n}","variables":{"input":{"companyId":"1031","rrule":"DTSTART:20230725T000000 FREQ=MONTHLY;INTERVAL=1;COUNT=1","baseAmount":"125.37","expiryDate":"2023-07-29T19:50:19.577Z","billetAllowed":true,"billetType":"NORMAL","billetConditionInput":{"interestType":"PERCENT","interestValue":"5","fineType":"VALUE","fine":"10","discountType":"VALUE","advanceDiscountValue":"1"},"cardSingleAllowed":true,"cardRecurringAllowed":false,"pixAllowed":false,"maxInstallments":3}}}'

Parâmetros BilletConditionInput

Parâmetros PixConditionInput

Parâmetros OrderInput

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeLinkCreate ($input: ChargeLinkCreateInput!) {
    chargeLinkCreate (input: $input) {
        errors {
            field
            message
            code
        }
		chargeLink{
			id
			isActive
			baseAmount
			billetAllowed
			
		}
        
        }
    }

                      
json



{
	"input": {
		"companyId": "1031",
		"rrule": "DTSTART:20230725T000000 FREQ=MONTHLY;INTERVAL=1;COUNT=1",
		"baseAmount": "125.37",
		"expiryDate": "2023-07-29T19:50:19.577Z",
		"billetAllowed": true,
        "billetType": "NORMAL",
		"billetConditionInput": {
			"interestType": "PERCENT",
			"interestValue": "5",
			"fineType": "VALUE",
			"fine": "10",
			"discountType": "VALUE",
			"advanceDiscountValue": "1"
		},
        "cardSingleAllowed": true,
        "cardRecurringAllowed":false,
        "pixAllowed": false,
        "maxInstallments": 3
       
	}
}

Enviar ChargeLink

Após a criação do ChargeLink deve-se utilizar o método ChargeLinkSend para enviar aos destinatários desejados o link de cobrança que possuirá uma página onde os mesmos poderão preencher os dados e realizar a emissão da cobrança conforme as configurações feitas anteriormente.

ChargeLinkSend

curl --location '' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"mutation chargeLinkSend ($input: ChargeLinkSendInput!) {\r\n    chargeLinkSend(input: $input) {\r\n        errors {\r\n            field\r\n            message\r\n            code\r\n        }\r\n		\r\n\r\n        \r\n        }\r\n    }\r\n}","variables":{"input":{"chargeLinkId":"230","email":"douglas@cliente.com.br"}}}'

POST | ChargeLinkCreate

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation chargeLinkSend ($input: ChargeLinkSendInput!) {
    chargeLinkSend(input: $input) {
        errors {
            field
            message
            code
        }
		

        
        }
    }

                      
json



{
	"input": {
		"chargeLinkId": "230",
		"email": "douglas@cliente.com.br"
	}
}

Usando RRule

A RRule("Regra de recorrência" em tradução livre) é um campo opcional presente em nossos métodos CreateChargeBillet, CreateChargeCard e CreateChargePix, destinado a transações que ocorrem repetidamente em intervalos específicos, como diários, semanais, mensais, entre outros.

Usando RRule

Parametros que podem ser utilizados:

• DTSTART: data e hora em que a aplicação da regra dará inicio.
• ULTIL: data e hora em que a regra será finalizada.
• FREQ: frequencia com o qual a geração de charge irá ocorrer.
• INTERVAL: intervalo de dias entre a geração.
• COUNT: quantidade de charges a serem geradas.
• BYDAY: dia da semana em que será gerado a charge (SU,MO,TU,WE,TH,FR,SA).

Os parametros não são obrigatórios e deverão ser utilizados de acordo com a necessidade para atender determinado objetivo de geração de transações.

Abaixo estão alguns exemplos de uso da rrule:

Usando Webhook

Webhook permitem que o seu sistema receba notificações sobre as cobranças em nossa API. Eles são úteis, por exemplo, para atualizar o status de um boleto que foi pago.

Eventos para Webhook e o momento de sua chamada:

Requisições enviadas

Aqui definimos os formatos dos Webhooks que são enviados

Existem 3 tipos de formato: Charge, Transaction e PaymentProfile

Uma chamada de exemplo é apresentada para cada, incluindo os headers enviados. Abaixo também estão listados os headers, comuns a todas as chamadas de Webhook

Headers

Chave	Exemplo	Descrição
X-NETCRED-Event	"TRANSACTION_UPDATE"	"Evento que causou o envio. Os tipos possíveis são descritos aqui"
X-NETCRED-Domain	"https://api.sandbox.netcredbrasil.com.br"	Domínio do qual foi enviado o Webhook. Sempre será um domínio Netcred
X-NETCRED-Signature	"87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd"	"Hash SHA256 gerado com o corpo da requisição, utilizando a secretKey informda na criação do WebhookEste hash pode ser refeito do seu lado para garantir a veracidade e integridade dos dados contidos no Webhook"

Formatos

Transaction

Formato TransactionPayload

Nome	Exemplo	Descrição
id	1234	Identificador único da Transaction
uuid	"f6412196-35fb-4716-b308-0e2cfea7c970"	Identificador único da Transaction em formato UUID
transaction_state	"PAID"	Estado da Transaction
amount	"10.0"	Valor total
refunded_amount	"0.0"	Valor estornado
paid_amount	"10.0"	Valor pago
installment_number	2	Número de parcelas de crédito
company	99	ID da Company
charge		Dados da charge associada
charge.id	16486	Identificador único da Charge
charge.reference_code	"CHARGE0001"	Código de idempotência
charge.charge_link_id	16128	Identificador único do ChargeLink criador da Charge
billet_info		**Somente presente para o método BILLET** **Dados de Boleto**
billet_info.id	1684	Identificador único do billet_info
billet_info.bar_code	"74897937700000099891122224595067890312345109"	Código de barras do Boleto
billet_info.digitable_line	"74891121150012026789503123451084787040000000015"	Linha digitável do Boleto
pix_info		**Somente presente para o método PIX** **Dados de PIX**
pix_info.id	6126	Identificador único do pix_info
pix_info.pix_type	"WITH_DUE_DATE"	Tipo do PIX Conforme conforme documentação de Transaction
pix_info.pix_copy_paste	"00020126930014br.gov.bcb.pix2571pix-qrcode-h.sicredi.com.br/qr/v2/cobv/a938ad9546364b5e9c535056c3c457a45204000053039865802BR5903PIX6006Cidade62070503*\_63043ECD"	Código PIX copia e cola
pix_info.e2eid	"E0379324270230530145747wFS3U4uG8"	Identificador do pagamento PIX
pix_info.expires_at	"2023-05-26T03:47:20.628345Z"	Data e hora de expiração do PIX, caso tipo IMMEDIATE
capture_medium	"ONLINE"	Meio de captura: ONLINE ou TERMINAL
method	"CARD"	Método: BILLET, PIX ou CARD
billing_at	"2023-05-26"	Data quando será feita a emissão/autorização
billed_at	"2023-05-26T03:47:20.628345Z"	Data e hora quando foi feta a emissão/autorização
due_at	"2023-05-30"	Data quando será feita a captura para CARD e data de vencimento para BILLET e PIX
paid_at	"2023-05-30T03:47:20.628345Z"	Data e hora quando foi feito o pagamento Obs.: no caso do boleto a hora não é confiável
attempts	1	Número de tentativas de autorização, pode ser maior que 1 para CARD
is_disputed	FALSE	Se atransação está em processo de chargeback
operations		Pode estar vazio quando a transação estiver SCHEDULED Lista de operations de gateway, como emissão/autorização, captura e cancelamento
operations.id	16984	Identificador único da Operation
operations.message	"Erro crítico"	Mensagem de erro resumida
operations.message_detail	"Erro ao valida dados"	Mensagem de erro mais detalhada
operations.operation_status	"FAILURE"	Status da Operation: - SUCCESS: concluido com sucesso - REJECTED: concluido com sucesso mas retornou recusa - FAILURE: ocorreu alguma falha no gateway
operations.operation_date	"2023-05-30T03:47:20.628345Z"	Date e hora quando ocorreu a Operation
operations.operation_type	"EMISSION"	Tipo da Operation: - AUTHORIZE - CAPTURE - VOID - TOKENIZE - UPDATE - REFUND - IMPORT - EMISSION - RISK_ANALYSIS
payment_profile	Objeto PaymentProfilePayload	Pode ser nulo Dados do PaymentProfile

Charge

Formato ChargePayload

Nome	Exemplo	Descrição
id	99916	Identificador único da Charge
reference_code	"CHARGE0001"	Código de idempotência
charge_type	"SINGLE"	Tipo da Charge: - RECURRING - SINGLE
charge_status	"ONGOING"	Estado da Charge: - ONGOING - ENDED - VOIDED
company	99	ID da Company
payment_profile	223	Pode ser nulo ID do payment_profile utilizado
installment_number	12	Número de parcelas do crédito
bill_days_in_advance	0	Quantos dias antes do vencimentos as Transactions serão emitidas/autorizadas
charge_link_id	27	ID do ChargeLink, caso a Charge tenha sido criada a partir de um
extra_info	"Contrato X"	Informações extras da Charge
rrule	"DTSTART:20230529T000000 FREQ=DAILY;INTERVAL=1;COUNT=1"	rrule usada na criação da Charge
transactions	Lista de objetos TransactionPayload	Lista de Transactions associadas à Charge

PaymentProfile

Formato PaymentProfilePayload

Nome	Exemplo	Descrição
id	16182	Identificador único do PaymentProfile
method	"BILLET"	method: CARD, BILLET ou PIX
is_active	TRUE	Se o PaymentProfile está ativo
card_number	"497010XXXXXX0048"	Obrigatório Número do cartão de crédito
expiry_month	6	Obrigatório Mês de expiração do cartão de crédito
expiry_year	2028	Obrigatório Ano de expiração do cartão de crédito
brand	"VCC"	brand do cartão de crédito, em formato arranjo de pagamento
card_holder_name	"Dono Cartão"	Obrigatório Nome do titular do cartão
void_at	"2023-05-30T03:47:20.628345Z"	Date e hora do cancelamento do PaymentProfile
last_operation_at	"2023-05-30T03:47:20.628345Z"	Date e hora da última Operation do PaymentProfile
rejected_reason	"Erro na validação dos dados"	Motivo da recusa do PaymentProfile
company	99	ID da Company

POST | TransactionWebhook

{{targetUrl}}

Formato HEADERS

Content-Type	application/json
X-NETCRED-Event	TRANSACTION_UPDATE
X-NETCRED-Domain	https://api.sandbox.netcredbrasil.com.br
X-NETCRED-Signature	87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd

curl

curl --location -g '{{targetUrl}}' \
--header 'Content-Type: application/json' \
--header 'X-NETCRED-Event: TRANSACTION_UPDATE' \
--header 'X-NETCRED-Domain: https://api.sandbox.netcredbrasil.com.br' \
--header 'X-NETCRED-Signature: 87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd' \
--data '{
    "id": 123456,
    "uuid": "f6412196-35fb-4716-b308-0e2cfea7c970",
    "transaction_state": "PAID",
    "amount": "10.00",
    "refunded_amount": "0.00",
    "paid_amount": "10.00",
    "installment_number": 1,
    "company": 99,
    "charge": {
        "id": 44892,
        "reference_code": null,
        "charge_link_id": 1684
    },
    "billet_info": {
        "id": 89418,
        "bar_code": "74897937700000099891122224595067890312345109",
        "digitable_line": "74891121150012026789503123451084787040000000015"
    },
    "pix_info": null,
    "capture_medium": "ONLINE",
    "method": "BILLET",
    "billing_at": "2023-05-26",
    "billed_at": "2023-05-26T03:47:20.628345Z",
    "due_at": "2023-05-28",
    "paid_at": "2023-05-26T04:00:00Z",
    "attempts": 1,
    "is_disputed": false,
    "operations": [
        {
            "id": 21852,
            "message": null,
            "message_detail": null,
            "operation_status": "SUCCESS",
            "operation_date": "2023-05-26T03:47:20.628204Z",
            "operation_type": "EMISSION"
        }
    ],
    "payment_profile": {
        "id": 161258,
        "method": "BILLET",
        "is_active": true,
        "card_number": null,
        "expiry_month": null,
        "expiry_year": null,
        "brand": null,
        "card_holder_name": null,
        "void_at": null,
        "last_operation_at": null,
        "rejected_reason": "",
        "company": 99,
        "customer": 1614008
    }
}'

Body raw (json)

                      
json

{
    "id": 12125,
    "method": "CARD",
    "is_active": false,
    "card_number": "497010XXXXXX0048",
    "expiry_month": "8",
    "expiry_year": "2023",
    "brand": "VCC",
    "card_holder_name": "Senhor Titular",
    "void_at": null,
    "last_operation_at": "2023-05-30T16:18:28.811372Z",
    "rejected_reason": "Token creation failed",
    "company": 99,
    "customer": 22125
}

POST | ChargeWebhook

{{targetUrl}}

Formato HEADERS

Content-Type	application/json
X-NETCRED-Event	CHARGE_CREATE
X-NETCRED-Domain	https://api.sandbox.netcredbrasil.com.br
X-NETCRED-Signature	87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd

curl

curl --location -g '{{targetUrl}}' \
--header 'Content-Type: application/json' \
--header 'X-NETCRED-Event: CHARGE_CREATE' \
--header 'X-NETCRED-Domain: https://api.sandbox.netcredbrasil.com.br' \
--header 'X-NETCRED-Signature: 87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd' \
--data '{
    "id": 22014,
    "reference_code": null,
    "charge_type": "RECURRING",
    "charge_status": "ONGOING",
    "company": 99,
    "payment_profile": 31485,
    "installment_number": 1,
    "bill_days_in_advance": 0,
    "charge_link_id": null,
    "billet_condition": null,
    "extra_info": "Parcela 89",
    "rrule": "DTSTART:20230613T000000 RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1",
    "transactions": [
        {
            "id": 11842,
            "uuid": "f6412196-35fb-4716-b308-0e2cfea7c970",
            "transaction_state": "SCHEDULED",
            "amount": "200.80",
            "refunded_amount": "0.00",
            "paid_amount": "0.00",
            "installment_number": 1,
            "company": 99,
            "charge": {
                "id": 22014,
                "reference_code": null,
                "charge_link_id": null
            },
            "billet_info": null,
            "pix_info": null,
            "capture_medium": "ONLINE",
            "method": "CARD",
            "billing_at": "2023-06-13",
            "billed_at": null,
            "due_at": "2023-06-13",
            "paid_at": null,
            "attempts": 0,
            "is_disputed": false,
            "operations": [],
            "payment_profile": {
                "id": 31485,
                "method": "CARD",
                "is_active": true,
                "card_number": "497010XXXXXX0048",
                "expiry_month": "12",
                "expiry_year": "2028",
                "brand": "VCC",
                "card_holder_name": "Senhor Titular",
                "void_at": null,
                "last_operation_at": "2023-05-30T15:59:42.786090Z",
                "rejected_reason": "",
                "company": 99,
                "customer": 1123
            }
        ]
}'

Body raw (json)

                      
json

{
    "id": 22014,
    "reference_code": null,
    "charge_type": "RECURRING",
    "charge_status": "ONGOING",
    "company": 99,
    "payment_profile": 31485,
    "installment_number": 1,
    "bill_days_in_advance": 0,
    "charge_link_id": null,
    "billet_condition": null,
    "extra_info": "Parcela 89",
    "rrule": "DTSTART:20230613T000000 RRULE:FREQ=DAILY;INTERVAL=1;COUNT=1",
    "transactions": [
        {
            "id": 11842,
            "uuid": "f6412196-35fb-4716-b308-0e2cfea7c970",
            "transaction_state": "SCHEDULED",
            "amount": "200.80",
            "refunded_amount": "0.00",
            "paid_amount": "0.00",
            "installment_number": 1,
            "company": 99,
            "charge": {
                "id": 22014,
                "reference_code": null,
                "charge_link_id": null
            },
            "billet_info": null,
            "pix_info": null,
            "capture_medium": "ONLINE",
            "method": "CARD",
            "billing_at": "2023-06-13",
            "billed_at": null,
            "due_at": "2023-06-13",
            "paid_at": null,
            "attempts": 0,
            "is_disputed": false,
            "operations": [],
            "payment_profile": {
                "id": 31485,
                "method": "CARD",
                "is_active": true,
                "card_number": "497010XXXXXX0048",
                "expiry_month": "12",
                "expiry_year": "2028",
                "brand": "VCC",
                "card_holder_name": "Senhor Titular",
                "void_at": null,
                "last_operation_at": "2023-05-30T15:59:42.786090Z",
                "rejected_reason": "",
                "company": 99,
                "customer": 1123
            }
        }
    ]
}

POST | PaymentProfileWebhook

{{targetUrl}}

Formato HEADERS

Content-Type	application/json
X-NETCRED-Event	PAYMENT_PROFILE_TOKENIZE
X-NETCRED-Domain	https://api.sandbox.netcredbrasil.com.br
X-NETCRED-Signature	87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd

curl

curl --location -g '{{targetUrl}}' \
--header 'Content-Type: application/json' \
--header 'X-NETCRED-Event: PAYMENT_PROFILE_TOKENIZE' \
--header 'X-NETCRED-Domain: https://api.sandbox.netcredbrasil.com.br' \
--header 'X-NETCRED-Signature: 87e99e04539c6588b8ee9b8e716a7a5f68426542b1b017b83d93e31b3a2e54cd' \
--data '{
    "id": 12125,
    "method": "CARD",
    "is_active": false,
    "card_number": "497010XXXXXX0048",
    "expiry_month": "8",
    "expiry_year": "2023",
    "brand": "VCC",
    "card_holder_name": "Senhor Titular",
    "void_at": null,
    "last_operation_at": "2023-05-30T16:18:28.811372Z",
    "rejected_reason": "Token creation failed",
    "company": 99,
    "customer": 22125
}'

Body raw (json)

                      
json

{
    "id": 12125,
    "method": "CARD",
    "is_active": false,
    "card_number": "497010XXXXXX0048",
    "expiry_month": "8",
    "expiry_year": "2023",
    "brand": "VCC",
    "card_holder_name": "Senhor Titular",
    "void_at": null,
    "last_operation_at": "2023-05-30T16:18:28.811372Z",
    "rejected_reason": "Token creation failed",
    "company": 99,
    "customer": 22125
}

POST | CreateWebhook

https://api.sandbox.netcredbrasil.com.br

Ao criar um Webhook, você indica que determinados eventos na nossa API devem ser enviados para um URL especificada.

Parâmetros

Nome	Exemplo	Descrição
companyId	99	Obrigatório Company dona do link, para qual as cobranças do mesmo serão enviadas Obs.: os eventos estão vinculados a uma empresa. Desta forma, se for necessário obter os eventos de várias empresas de um Marketplace, sugere-se criar o Webhook para este Marketplace, que pode ""ver"" todos os eventos das empresas
targetUrl	"https://example.com/webhook"	Obrigatório Endpoint que receberá o envio do webhook por uma chama POST Deve ser um endpoint protegido por SSL
isActive	TRUE	Default: true Indica se o Webhook está imediatamente ativo na criação
secretKey	"senha123"	Esta chave é utilizada para gerar um hash SHA256 com o corpo da requisição Este hash pode ser refeito do seu lado para garantir a veracidade e integridade dos dados contidos no Webhook
events		Obrigatório. Deve ser especificado pelo menos 1 evento Eventos possíveis: - ANY - CHARGE_CREATE - CHARGE_UPDATE - CHARGE_VOID - TRANSACTION_CREATE - TRANSACTION_CAPTURE - TRANSACTION_EXPIRED - TRANSACTION_UPDATE - TRANSACTION_VOID - TRANSACTION_REFUND - TRANSACTION_DISPUTE - TRANSACTION_AUTHORIZE - PAYMENT_PROFILE_TOKENIZE - PAYMENT_PROFILE_UPDATE - PAYMENT_PROFILE_DELETE - PAYMENT_PROFILE_EXPIRING - WEBHOOK_PING Os seus significados são apresentados na descrição de Webhook
maskUserAgent	TRUE	Para casos onde o seu firewall possa estar bloqueando nosso webhook, temos esse campo para mascarar o user_agent simulando uma requisição vinda de navegador.

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation webhookCreate ($input:WebhookCreateInput!) {\n  webhookCreate (input:$input) {\n    errors {\n      field\n      message\n      code\n    }\n    webhook {\n      id\n      name\n      targetUrl\n      isActive\n      secretKey\n      events {\n        totalCount\n      }\n      company {\n        name\n      }\n    }\n  }\n}","variables":{"input":{"name":"webhook_test","targetUrl":"https://webhook.site/55d29380-8a6d-404a-a392-e5052462b509","events":"CHARGE_CREATE","companyId":"1014","isActive":true,"maskUserAgent":true,"secretKey":""}}}'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation webhookCreate ($input:WebhookCreateInput!) {
  webhookCreate (input:$input) {
    errors {
      field
      message
      code
    }
    webhook {
      id
      name
      targetUrl
      isActive
      secretKey
      events {
        totalCount
      }
      company {
        name
      }
    }
  }
}

GraphQL Variables

                      
json



{
	"input": {
		"name": "webhook_test",
		"targetUrl": "https://webhook.site/55d29380-8a6d-404a-a392-e5052462b509",
		"events": "CHARGE_CREATE",
		"companyId": "1014",
		"isActive": true,
        "maskUserAgent": true,
		"secretKey": ""
	}
}

POST | DeleteWebhook

https://api.sandbox.netcredbrasil.com.br

Permite que um Webhook seja excluído

Parâmetros

Nome	Exemplo	Descrição
webhookId	99	Obrigatório ID do Webhook que será deletado

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation webhookDelete ($input: WebhookDeleteInput!) {\n    webhookDelete (input: $input) {\n        errors {\n            field\n            message\n        }\n    }\n}","variables":{"input":{"webhookId":20}}}'

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation webhookDelete ($input: WebhookDeleteInput!) {
    webhookDelete (input: $input) {
        errors {
            field
            message
        }
    }
}

GraphQL Variables

                      
json



{
	"input": {
		"webhookId": 20
	}
}

POST | PingWebhook

https://api.sandbox.netcredbrasil.com.br

Permite que uma chamada teste seja feito ao Webhook, para testar se ele pode ser atingido.

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"mutation webhookPing ($input: WebhookPingInput!) {\n    webhookPing (input: $input) {\n        errors {\n            field\n            message\n        }\n        result\n        statusCode\n    }\n}","variables":{"input":{"webhookId":20}}}'

Parâmetros

Nome	Exemplo	Descrição
webhookId	99	Obrigatório ID do Webhook que será testado

Saída

Nome	Exemplo	Descrição
statusCode	"200"	Código de status HTTP retornado pelo endpoint

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

mutation webhookPing ($input: WebhookPingInput!) {
    webhookPing (input: $input) {
        errors {
            field
            message
        }
        result
        statusCode
    }
}

GraphQL Variables

                      
json



{
	"input": {
		"webhookId": 20
	}
}

Consultas (queries)

Introdução

A API GraphQL oferece dois tipos principais de operações: queries (consultas) e mutations. Nessa seção vamos explicar e exemplificar as queries. Mas primeiro é importante ressaltar a diferença entre uma query e uma mutation.

1. Queries (Consultas): As queries são utilizadas para buscar dados da API. Ao enviar uma query, você especifica os campos que deseja receber como resposta. Em geral, as queries são usadas para recuperar informações de consulta, como dados de leitura de um banco de dados. Para fazer uma query, você pode enviar vários campos para filtrar os dados de acordo com sua necessidade. Por exemplo, você pode buscar por transações específicas usando filtros como datas, tipos de transação ou outros critérios relevantes. Ao usar o GraphQL Playground da nossa API, você pode explorar as queries disponíveis e os filtros que podem ser aplicados a elas.

2. Mutations (Mutação): As mutations são utilizadas para modificar dados na API. Ao enviar uma mutation, você especifica as operações que deseja realizar, como criar, atualizar ou excluir dados. Cada mutation na nossa API, como o ChargeCreate, recebe um campo de entrada (input) específico para aquela operação. Por exemplo, ao criar uma nova cobrança, você precisa fornecer os detalhes necessários, como o valor da cobrança, o cliente associado e outros dados relevantes.

Ao entender a distinção entre queries e mutations, você poderá interagir de forma eficaz com a nossa API GraphQL, buscando dados com queries e modificando-os conforme necessário com mutations.

Quase todos os Objetos da nossa API possuem uma query colocando-se o nome do objeto no plural, e.g. charges é a query para o objeto Charge.

POST | billetsPastDueAt

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query billetsPastDueAt($dueAt_Lte: Date, $method: String, $state: String, $last: Int){\n  transactions(dueAt_Lte: $dueAt_Lte, method: $method, transactionState: $state, last: $last){\n    edges{\n      node{\n        id\n        method\n        transactionState\n        dueAt\n        amount\n        billingInfo{\n          customerName\n          customerEmail\n          customerDocument\n        }\n      }\n    }\n  }\n}","variables":{"dueAt_Lte":"2023-05-30","state":"BILLED","method":"BILLET","last":5}}}'

Variáveis:

As variáveis desempenham um papel crucial na personalização da consulta GraphQL. No exemplo fornecido:

• $dueDate_Lte: Esta variável é passada para o filtro de data de vencimento chamado dueDate_Lte. Ela filtra datas de vencimento menores ou iguais à data informada. No exemplo, estamos simulando a data de hoje para encontrar boletos com datas de vencimento igual ou anterior a essa data.

• $method: Ao ser passada para o filtro method, esta variável define o método de pagamento desejado. No exemplo, atribuímos o valor "BILLET", indicando que estamos interessados apenas em boletos.

• $state: Passada para o filtro transactionState, esta variável determina o estado das transações a serem retornadas. No exemplo, atribuímos o valor "BILLED" para buscar apenas transações que foram emitidas.

• $last: Este é um filtro opcional passado para o filtro last, que define o número máximo de transações mais recentes a serem retornadas. No exemplo, definimos como 5, o que significa que as últimas 5 transações serão retornadas.

Essas variáveis permitem ajustar dinamicamente os critérios da consulta conforme necessário.

Estrutura de Conexão (Edge e Node):

No GraphQL, as conexões são fundamentais para lidar com listas de objetos. Cada conexão possui arestas (edges), que contêm os objetos reais (nodes). No exemplo da consulta:

• Edges e Nodes: Ao acessar as conexões, utilizamos a estrutura de edges e nodes para navegar pelos resultados da consulta. As arestas (edges) representam as conexões entre os nós (nodes), que, neste caso, representam as transações retornadas. Essa estrutura permite acessar as informações específicas de cada transação de forma eficiente.

Personalização da Consulta:

Ao construir uma consulta GraphQL, é essencial selecionar apenas os campos necessários para minimizar a quantidade de dados transferidos e otimizar o desempenho da API. No exemplo fornecido:

• Seleção de Campos: Especificamos os campos do objeto Transaction que desejamos receber como resposta. Isso garante que obtenhamos apenas as informações relevantes para atender às necessidades do sistema que consome a API. Por exemplo, estamos buscando campos como id, method, transactionState, dueDate, amount e informações de billing para cada transação retornada.

Essa personalização da consulta permite obter apenas as informações necessárias, tornando-a mais eficiente e eficaz.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query billetsPastDueAt($dueAt_Lte: Date, $method: String, $state: String, $last: Int){
  transactions(dueAt_Lte: $dueAt_Lte, method: $method, transactionState: $state, last: $last){
    edges{
      node{
        id
        method
        transactionState
        dueAt
        amount
        billingInfo{
          customerName
          customerEmail
          customerDocument
        }
      }
    }
  }
}

GraphQL Variables

                      
json



{
  "dueAt_Lte": "2023-05-30",
  "state": "BILLED",
  "method": "BILLET",
  "last": 5
}

POST | paymentProfileByCustomer

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br/graphql' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query paymentProfilesByCustomer($customerId: String){\n paymentProfiles(customerId:$customerId){\n edges{\n\t\t\tnode{\n\t\t\t\tid\n                cardHolderName\n                cardNumber\n                expiryYear\n                expiryMonth\n                brand\n				company{\n					id\n					name\n				}\n				customer{\n					email\n				}\n\n			}\n		}\n }\n}\n","variables":{"customerId":"1001"}}}'

Para realizar a consulta do paymentProfile é preciso passar as variáveis que se deseja filtrar, estruturar a query e personalizar a consulta para ter retorno apenas dos campos desejados.

Variáveis:

Nesta consulta GraphQL, usamos variáveis para filtrar os resultados da busca de maneira personalizada:

• $customerId: Esta variável é importante porque nos permite identificar o cliente específico para o qual estamos buscando os perfis de pagamento. No exemplo, o valor "1001" é usado como o ID do cliente, garantindo que obtenhamos os perfis de pagamento corretos para esse cliente.

Basicamente, as variáveis são como "configurações ajustáveis" que nos permitem mudar quem ou o que estamos procurando na consulta. Isso torna a consulta mais flexível, pois podemos adaptá-la para atender às necessidades específicas de diferentes situações.

Estrutura de Conexão (Edge e Node):

No GraphQL, as conexões são fundamentais para lidar com listas de objetos. Neste caso, a estrutura de edges e nodes é usada para acessar os perfis de pagamento:

• Edges e Nodes: As arestas (edges) representam as conexões entre os nós (nodes), que, neste caso, são os perfis de pagamento retornados. Isso permite acessar as informações específicas de cada perfil de pagamento de forma eficiente.

Personalização da Consulta:

Ao construir a consulta GraphQL, é crucial selecionar apenas os campos necessários para otimizar a transferência de dados e o desempenho da API. No exemplo fornecido:

• Seleção de Campos: A consulta específica os campos do perfil de pagamento que desejamos receber como resposta. Isso garante que recebamos apenas as informações relevantes para atender às necessidades do sistema consumidor da API, como o id, nome do titular do cartão, dígitos do cartão truncado, mês e ano de expiração, bandeira do cartão, id e nome da empresa associada e email do cliente.

Essa personalização da consulta permite obter apenas as informações necessárias, tornando-a mais eficiente e eficaz para recuperar os perfis de pagamento do cliente desejado.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query paymentProfilesByCustomer($customerId: String){
  paymentProfiles(customerId:$customerId){
    edges{
			node{
				id
                cardHolderName
                cardNumber
                expiryYear
                expiryMonth
                brand
				company{
					id
					name
				}
				customer{
					email
				}

			}
		}
  }
}

GraphQL Variables

                      
json



{
  "customerId":"1001"
}

POST | FilteredTransactionsByPaymentState

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetPaidTransactions($first: Int!, $state: String!) {\n  transactions(first: $first, transactionState: $state) {\n    id\n    amount\n    customerName\n    transactionState\n  }\n}\n","variables":{"first":5,"state":"PAID"}}}'

Nesta consulta, você pode filtrar transações com base no estado de pagamento, como "PAGO", "PENDENTE", "CANCELADO", entre outros. Isso permite obter transações com um estado específico de pagamento, fornecendo insights sobre o status financeiro das transações no sistema.

• Variáveis utilizadas:

  • first: Limita o número de resultados retornados.

  • transactionState: Filtra transações com o estado de pagamento especificado.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query GetPaidTransactions($first: Int!, $state: String!) {
  transactions(first: $first, transactionState: $state) {
    id
    amount
    customerName
    transactionState
  }
}

GraphQL Variables

                      
json



{
  "first": 5,
  "state": "PAID"
}

POST | TransactionsInRangeByAmount

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetTransactions($first: Int!, $amountGte: String!, $amountLte: String!) {\n  transactions(first: $first, amount_Gte: $amountGte, amount_Lte: $amountLte) {\n    id\n    amount\n    captureMedium\n    transactionState\n  }\n}\n","variables":{"first":10,"amountGte":"50.00","amountLte":"200.00"}}}'

Ao utilizar os parâmetros amount_Gte e amount_Lte, é possível encontrar transações com valores dentro de um determinado intervalo. Isso é útil para analisar transações com valores específicos ou realizar segmentações financeiras com base nos montantes das transações.

• Variáveis utilizadas:

  • first: Limita o número de resultados retornados.

  • amount_Gte: Filtra transações com valor igual ou superior a este montante.

  • amount_Lte: Filtra transações com valor igual ou inferior a este montante.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query GetTransactions($first: Int!, $amountGte: String!, $amountLte: String!) {
  transactions(first: $first, amount_Gte: $amountGte, amount_Lte: $amountLte) {
    id
    amount
    captureMedium
    transactionState
  }
}

GraphQL Variables

                      
json



{
  "first": 10,
  "amountGte": "50.00",
  "amountLte": "200.00"
}

POST | getPayoutRules

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetPayoutRules(\n $first: Int\n $companyId: String\n $isActive: String\n) {\n payoutRules(\n     first: $first\n     companyId: $companyId\n     isActive: $isActive\n )\n {\n     id\n     companyId\n     isActive\n }\n}\n","variables":{}}'

A consulta payoutRules traz objetos PayoutRule e é como uma ferramenta de pesquisa que ajuda empresas a encontrar e entender as diferentes formas de pagamento que podem utilizar. Ao usar a informação da sua empresa (companyId) e o status de ativação (isActive), você pode ver quais regras de pagamento estão prontas para serem usadas e como cada uma delas pode afetar suas transações financeiras.

O parâmetro companyId ajuda a selecionar a empresa específica para a qual você está buscando regras de pagamento, enquanto o parâmetro isActive permite focar nas regras de pagamento que estão atualmente ativas. Com essa consulta, você pode explorar e compreender melhor suas opções de pagamento, ajudando na escolha daquelas que melhor atendem às necessidades e operações financeiras da sua empresa.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query GetPayoutRules(
  $first: Int
  $companyId: String
  $isActive: String
) {
  payoutRules(
    first: $first
    companyId: $companyId
    isActive: $isActive
  ) {
    id
    companyId
    isActive
  }
}

GraphQL Variables

                      
json



{
  "first": 10,
  "companyId": "512",
  "isActive": "true"
  // Adicione outras variáveis conforme necessário
}

POST | getBankAccounts

https://api.sandbox.netcredbrasil.com.br

curl

curl --location 'https://api.sandbox.netcredbrasil.com.br' \
--header 'Authorization: JWT ' \
--header 'Content-Type: application/json' \
--data '{"query":"query GetBankAccounts(\n $first: Int\n $companyId: String\n $isActive: Boolean\n) {\n bankAccounts(\n     first: $first\n     companyId: $companyId\n     isActive: $isActive\n )\n {\n     id\n     companyId\n     isActive\n }\n}\n","variables":{"first":10,"companyId":"512","isActive":true}}}'

A consulta bankAccount, que traz objetos BankAccount, mostra as contas bancárias conectadas a uma empresa específica. Ao utilizar o identificador da sua empresa (companyId) e o status de ativação (isActive), você pode visualizar as diferentes contas bancárias disponíveis e como cada uma delas está atualmente configurada para transações.

• companyId identifica a empresa para a qual você está buscando contas bancárias

• isActive permite focar nas contas bancárias que estão ativas no momento

Com esta consulta, é possível explorar e compreender melhor as opções de contas bancárias associadas à empresa, auxiliando na escolha das contas mais adequadas para suas necessidades financeiras e operacionais.

HEADERS

Authorization JWT

Body graphql

Query

                      
graphql

query GetBankAccounts(
  $first: Int
  $companyId: String
  $isActive: Boolean
) {
  bankAccounts(
    first: $first
    companyId: $companyId
    isActive: $isActive
  ) {
    id
    companyId
    isActive
  }
}

GraphQL Variables

                      
json



{
  "first": 10,
  "companyId": "512",
  "isActive": true
}

Transactions

Neste quadrante iremos demonstrar todos os filtros disponiveis para a realização de queries na tabela de transactions

Filtros

offset(Int): Define o deslocamento (quantidade de registros a serem ignorados) na consulta.

before(String): Filtra registros antes de uma determinada referência, identificada pela string fornecida.

after(String): Filtra registros após uma determinada referência, identificada pela string fornecida.

first(Int): Limita o número de registros retornados, começando do início da lista.

last(Int): Limita o número de registros retornados, começando do final da lista.

created_Gte(DateTime): Filtra registros com data de criação maior ou igual a data e hora especificadas.

created_Lte(DateTime): Filtra registros com data de criação menor ou igual da data e hora especificadas.

billingAt_Gte(Date): Filtra registros com data de cobrança maior ou igual a data especificada.

billingAt_Lte(Date): Filtra registros com data de cobrança menor ou igual da data especificada.

billedAt_Gte(DateTime): Filtra registros com data de faturamento maior ou igual a data e hora especificadas.

billedAt_Lte(DateTime): Filtra registros com data de faturamento menor ou igual da data e hora especificadas.

paidAt_Gte(DateTime): Filtra registros com data de pagamento maior ou igual a data e hora especificadas.

paidAt_Lte(DateTime): Filtra registros com data de pagamento menor ou igual da data e hora especificadas.

dueAt_Gte(Date): Filtra registros com data de vencimento maior ou igual a data especificada.

dueAt_Lte(Date): Filtra registros com data de vencimento menor ou igual da data especificada.

voidAt_Gte(DateTime): Filtra registros com data de anulação maior ou igual a data e hora especificadas.

voidAt_Lte(DateTime): Filtra registros com data de anulação menor ou igual da data e hora especificadas.

installmentNumber(Int): Filtra registros com o número de parcela especificado.

transactionState(String): Filtra registros pelo estado da transação.

authorizationCode(String): Filtra registros pelo código de autorização.

isDisputed(Boolean): Filtra registros com base em se há uma disputa associada ou não.

captureMedium(String): Filtra registros pelo meio de captura.

id(String): Filtra registros pelo ID específico.

id_In([String]): Filtra registros cujos IDs estão presentes na lista fornecida.

orderBy(String): Especifica a ordem de classificação dos resultados (Lista no próximo tópico).

method(String): Filtra registros pelo método de pagamento.

customerId(String): Filtra registros pelo ID do cliente.

customerName(String): Filtra registros pelo nome do cliente.

customerDocument(String): Filtra registros pelo documento do cliente.

companyId(String): Filtra registros pelo ID da empresa.

companyId_In([String]): Filtra registros cujos IDs de empresa estão presentes na lista fornecida.

companyMarketplaceId(String): Filtra registros pelo ID do marketplace da empresa (caso disponível).

companyMarketplaceId_In([String]): Filtra registros cujos IDs de marketplace da empresa estão presentes na lista fornecida (caso disponível).

brand(String): Filtra registros pela bandeira do cartão.

cardNumber(String): Filtra registros pelo número do cartão.

cardMode(String): Filtra registros pelo modo do cartão.

chargeType(String): Filtra registros pelo tipo de cobrança.

chargeId(String): Filtra registros pelo ID da cobrança.

contractId(String): Filtra registros pelo ID do contrato.

contractId_IsNull(Boolean): Filtra registros com ou sem ID de contrato especificado.

contractId_In([String]): Filtra registros cujos IDs de contrato estão presentes na lista fornecida.

contractIdentifier(String): Filtra registros pelo identificador de contrato.

printUrl(String): Filtra registros pela URL de impressão.

transactionState_In([String]): Filtra registros cujos estados de transação estão presentes na lista fornecida.

installmentNumber_Gte(String): Filtra registros com número de parcela maior ou igual que o valor especificado.

installmentNumber_Lte(String): Filtra registros com número de parcela menor ou igual que o valor especificado.

billingCycle_Gte(String): Filtra registros com ciclo de cobrança maior ou igual que o valor especificado.

billingCycle_Lte(String): Filtra registros com ciclo de cobrança menor ou igual que o valor especificado.

amount_Gte(String): Filtra registros com valor maior ou igualque o valor especificado.

amount_Lte(String): Filtra registros com valor menor ou igualque o valor especificado.

chargeLinkId(String): Filtra registros pelo ID de link de cobrança.

terminalSerialNumber(String): Filtra registros pelo número de série do terminal.

terminalId(String): Filtra registros pelo ID do terminal.

extraInfo(String): Filtra registros por informações extras.

chargeServiceCode_In([String]): Filtra registros cujos códigos de serviço de cobrança estão presentes na lista fornecida.

protestedStatus(String): Filtra registros pelo status de protesto.

protestedStatus_In([String]): Filtra registros cujos status de protesto estão presentes na lista fornecida.

negativeListedStatus(String): Filtra registros pelo status de lista negativa.

negativeListedStatus_In([String]): Filtra registros cujos status de lista negativa estão presentes na lista fornecida.

Order by

Os campos possiveis de ordenação são os seguintes:

id: Ordena registros pelo ID específico.

created: Ordena registros pela data de criação.

method: Ordena registros pelo método de pagamento.

customer_id: Ordena registros pelo ID do cliente.

customer__name: Ordena registros pelo nome do cliente.

customer__document: Ordena registros pelo documento do cliente.

company_id: Ordena registros pelo ID da empresa.

company__name: Ordena registros pelo nome da empresa.

capture__medium: Ordena registros pelo meio de captura.

company__marketplace_id: Ordena registros pelo ID do marketplace da empresa (caso disponível).

brand: Ordena registros pela bandeira do cartão.

card_number: Ordena registros pelo número do cartão.

card_mode: Ordena registros pelo modo do cartão.

charge__charge_type: Ordena registros pelo tipo de cobrança.

charge_id: Ordena registros pelo ID da cobrança.

charge__extra_info: Ordena registros por informações extras relacionadas à cobrança.

contract_id: Ordena registros pelo ID do contrato.

contract__identifier: Ordena registros pelo identificador de contrato.

transaction_state: Ordena registros pelo estado da transação.

installment_number: Ordena registros pelo número da parcela.

billing_cycle: Ordena registros pelo ciclo de cobrança.

amount: Ordena registros pelo valor da transação.

charge_link_id: Ordena registros pelo ID do link de cobrança.

terminal__serial_number: Ordena registros pelo número de série do terminal.

terminal_id: Ordena registros pelo ID do terminal.

billing_at: Ordena registros pela data de cobrança.

billed_at: Ordena registros pela data de faturamento.

paid_at: Ordena registros pela data de pagamento.

due_at: Ordena registros pela data de vencimento.

void_at: Ordena registros pela data de cancelamento.

company: Ordena registros pela empresa.

is_disputed: Ordena registros com base em se há uma disputa associada ou não.

Objetos

Esta sessão tem o intuito de explicar os dados contidos nos vários objetos utilizados pela nossa API. Os objetos são divididos em algumas categorias para facilitar entender o seu propósito.

Charge (Cobrança)

Objetos no grupo Charge estão mais fortemente ligados às Cobranças.

Charge

A Charge é a Cobrança é si. Ela é, essencialmente, um agrupamento de Transactions. As suas configurações são repassadas para essas Transactions na criação.

Formato Campos da Charge

Nome	Tipo	Descrição
id	Inteiro	ID único
uuid	UUID	ID único em formato UUID
referenceCode	String	Pode ser nulo Referência externa idempotente
amount	Decimal	Valor
method	String	method: - BILLET: Boleto - PIX - CARD: Cartão de crédito
submethod	String	submethod, conforme tabela abaixo.
rrule	String	A rrule define a "frequência" para a geração das datas de vencimento (dueAt) das Transactions dessa Charge.
ipAddress	String	IP de onde foi gerada a cobrança
customerIpAddress	String	IP do usuário final que requisitou a cobrança
voidAt	Datetime	Data e hora do cancelamento
voidReason	String	Motivo do cancelamento
chargeType	String	chargeType: - SINGLE: a emissão aconteceu na hora da criação - RECURRING: foi criada com pelo menos uma Transaction SCHEDULED (agendada)
chargeStatus	String	chargeStatus atual da cobrança: - ONGOING: ainda tem Transactions pendentes - ENDED: todas as Transactions atingiram um estado final - VOIDED: foi cancelada
installmentNumber	Inteiro	Apenas para o método CARD Número de parcelas do crédito
extraInfo	String	Texto com informações adicionais
manualCapture	Boolean	Apenas para o método CARD Se a captura será manual, i.e. não ocorrerá de forma automática
billingCycleTotal	Inteiro	Total de Transactions desta Charge
billingCyclePaid	Inteiro	Total de Transactions desta Charge no estado PAID
billingCyclesProcessed	Inteiro	Total de Transactions desta Charge em um estado diferente de SCHEDULED
company	Objeto Company	Estabelecimento dono desta Charge
customer	Objeto Customer	Pagador
paymentProfile	Objeto PaymentProfile	Informações de cobrança para a Charge
billetCondition	Objeto BilletCondition	Apenas para o método BILLET Configurações de boleto
pixCondition	Objeto PixCondition	Apenas para o método PIX Configurações de PIX
chargeLink	Objeto ChargeLink	chargeLink associado, caso a Charge tenha sido criada a partid de um
payoutRule	Objeto PayoutRule	Mutuamente exclusivo com contract Split de pagamento
contract	Objeto Contract	Mutuamente exclusivo com payoutRule contract associado a esta cobrança. Ele vai direcionar os recebíveis para um Financiador

Tabela de submethod

Método	Nome	Descrição
BILLET	NORMAL	Boleto sem QRCode PIX
BILLET	HYBRID	Boleto com QRCode PIX
PIX	IMMEDIATE	PIX que expira em um curto período de tempo. Criado a partir do ChargeLink
PIX	WITH_DUE_DATE	PIX semelhante a boleto, com data de vencimento e configurações. Criado pelo ChargeCreate
PIX	STATIC	PIX pago por QRCode estático
PIX	TERMINAL	PIX pago por terminal POS
CARD	NOT_APPLICABLE	Apenas para o campo não ficar vazio no método CARD

Transaction

A Transaction são os 'pagamentos' de fato, ela corresponde a um boleto, PIX ou pagamento de cartão.

Os objetos [nome]Info acrescentam à Transaction informações mais específicas de cada método (Cartão, Pix ou Boleto). Esses objetos contêm informações "repetidas" de outros, isso acontece porque um PaymentProfile, por exemplo, pode mudar o seu billingAddress, enquanto os dados do billingInfo permanecem estáticos depois que uma transação é emitida/autorizada. Os objetos Info também são apresentados nesta seção.

Campos da Transaction

Nome	Tipo	Descrição
id	Inteiro	Identificador único
uuid	String	Identificador único em formato UUID
amount	Decimal	Valor nominal
paidAmount	Decimal	Valor pago Pode ser diferente do amount em boleto e PIX, devido a descontos ou acréscimos
refundedAmount	Decimal	Valor estornado É menor ou igual ao valor pago
transactionState	String	Estado da Transaction: - SCHEDULED - REJECTED - VOIDED - BILLED - EXPIRED - PAID - PARTIALLY_REFUNDED - REFUNDED - IN_ANALYSIS - MANUAL_ANALYSIS Para mais informações sobre cada uma consulte a tabela abaixo.
method	String	method: - BILLET: Boleto - PIX - CARD: Cartão de crédito
installmentNumber	Inteiro	Apenas para o método CARD Número de parcelas de crédito
captureMedium	String	Método de 'captura': - ONLINE: transações criadas a partir da API - TERMINAL: transações provenientes de terminais POS ou QRCode estático
rejectedReason	String	Motivo da recusa
billingAt	Date	Data na qual ocorrerá a emissão/autorização
billedAt	Datetime	Data e hora na qual ocorreu a emissão/autorização
dueAt	Date	Data na qual ocorrerá a captura, no método CARD. Data de vencimento para BILLET e PIX.
paidAt	Datetime	Data e hora no qual ocorreu o pagamento/captura. Obs.: no caso do boleto, pode ser que a hora não esteja correta, pois apenas temos acesso à data do pagamento.
processedAt	Datetime	Data e hora do processamento da transação, normalmente é igual/proximo a paidAt. Essa data é usada como base para a geração das liquidações
voidAt	Datetime	Data e hora na qual ocorreu o cancelamento desta Transaction
voidReason	String	Motivo do cancelamento
manualCapture	Boolean	Apenas para o método CARD Se a captura será manual, i.e. não ocorrerá de forma automática
isDisputed	Boolean	Se a Transaction está em processo de chargeback
attempts	Inteiro	Apenas para o método CARD Numero de tentativas de autorização efetuadas
billExpiryDate	Date	Apenas para os métodos BILLET e PIX Data na qual uma emissão irá expirar após a data de vencimento (dueAt) Após esta data a transação passa para o estado EXPIRED
refundMaxDate	Date	Data máxima na qual a transação poderá ser estornada
billingCycle	Inteiro	Número sequencial da Transaction dentro da Charge
printUrl	String	Apenas para o método BILLET Link encurtado para download do boleto
charge	Objeto Charge	Cobrança a qual esta Transaction pertence
company	Objeto Company	Estabelecimento dono desta Transaction
customer	Objeto Customer	Pagador
paymentProfile	Objeto PaymentProfile	Informações de cobrança para a Transaction
billetCondition	Objeto BilletCondition	Apenas para o método BILLET Configurações de boleto
pixCondition	Objeto PixCondition	Apenas para o método PIX Configurações de PIX
chargeLink	Objeto ChargeLink	ChargeLink associado, caso a Charge tenha sido criada a partid de um
payoutRule	Objeto PayoutRule	Mutuamente exclusivo com contract Split de pagamento
contract	Objeto Contract	Mutuamente exclusivo com payoutRule Contrato associado a esta cobrança. Ele vai direcionar os recebíveis para um Financiador
cardInfo	Objeto CardInfo	Apenas para o método CARD Informações específicas sobre o cartão, como a número do cartão truncado e a bandeira
billetInfo	Objeto BilletInfo	Apenas para o método BILLET Informações específicas sobre o boleto, incluindo configurações de juros e afins
pixInfo	Objeto PixInfo	Apenas para o método PIX Informações específicas sobre o PIX, incluindo configurações de juros e afins
billingInfo	Objeto BillingInfo	Informações de cobrança, como endereço e pagador

Estados da Transaction

Estado	Descrição
SCHEDULED	Agendada, será emitida/autorizada em billingAt
REJECTED	Apenas para CARD Rejeitada na autorização, e.g. falta de fundos
VOIDED	Cancelada
BILLED	Emitida/Autorizada
EXPIRED	"Vencida", a data de vencimento (dueAt) passou de determinada número de dias Para todos os efeitos é equivalente a VOIDED
PAID	Paga
PARTIALLY_REFUNDED	Parcialmente estornada 0 < refundedAmount < paidAmount
REFUNDED	Totalmente estornada refundedAmount = paidAmount
IN_ANALYSIS	Em análise de risco Irá será aprovada ou rejeitada automaticamento em até 2h
MANUAL_ANALYSIS	Em análise manual BS Bank está verificando os dados e irá aprovar ou rejeitar em breve

Fluxos de estado da Transction por método

Campos do BillingInfo

Nome	Tipo	Descrição
billingAddressNumber	String	Número do endereço
billingAddressStreet	String	Rua do endereço
billingAddressDistrict	String	Bairro/Distrito do endereço
billingAddressCity	String	Cidade do endereço
billingAddressState	String	Sigla do estado do endereço
billingAddressAdditionalDetails	String	Informações adicionais do endereço, e.g. número do apartamento
billingAddressZipCode	String	CEP do endereço, apenas números
shippingAddressNumber	String	Número do endereço
shippingAddressStreet	String	Rua do endereço
shippingAddressDistrict	String	Bairro/Distrito do endereço
shippingAddressCity	String	Cidade do endereço
shippingAddressState	String	Sigla do estado do endereço
shippingAddressAdditionalDetails	String	Informações adicionais do endereço, e.g. número do apartamento
shippingAddressZipCode	String	CEP do endereço, apenas números
customerName	String	Nome do pagador
customerEmail	String	Email do pagador
customerDocumentType	String	Tipo do documento do pagador (CPF ou CNPJ)
customerDocument	String	Documetno do pagador
customerPhone	String	Número de telefone do pagador
customerBirthDate	Date	Data de nascimento do pagador
customerGender	String	Gênero do pagador

Campos do CardInfo (Cartão)

Nome	Tipo	Descrição
cardNumber	String	Número do cartão truncado, e.g. "497010XXXXXX0048"
cardMode	String	"Modo" do cartão utlizado: - CREDIT: Crédito - DEBIT: Débito (apenas de terminal) - PRE_PAID: Crédito pré-pago
cardHolderName	String	Titular do cartão
expiryMonth	Inteiro	Mês de expiração do cartão de crédito
expiryYear	Inteiro	Ano de expiração do cartão de crédito
brand	String	brand do cartão É usado o formato de arranjo de pagamento, e.g. Visa Crédito = "VCC"

Campos do BilletInfo (Boleto)

Nome	Tipo	Descrição
billetType	String	Tipo do boleto: - NORMAL: sem QRCode PIX - HYBRID: com QRCode PIX
digitableLine	String	digitableLine Preenchido após a emissão
barCode	String	barCode Preenchido após a emissão
txid	String	Identificador associado ao PIX do boleto Preenchido após a emissão
pixCopyPaste	String	pixCopyPaste Preenchido após a emissão Obs.: para gerar a imagem do QRCode basta usar este código em uma biblioteca de QRCode
interestType	String	Tipo do juros: - PERCENT - VALUE
interestValue	Decimal	Valor do juros, em relação ao interestType
fineType	String	Tipo da multa: - PERCENT - VALUE
fine	Decimal	Valor da multa, em relação ao fineType
discountType	String	Tipo do desconto: - PERCENT - VALUE
advanceDiscountValue	String	Não preenchido junto de outros camposdiscount****, além de discountType Desconto aplicado por dias corridos antes do vencimento, em relação a discountType
discountValue1	Decimal	Sempre preenchido junto de discountDateDelta1 Valor do desconto até discountDateDelta1 dias antes do vencimento, em relação a discountType
discountDateDelta1	Integer	Sempre preenchido junto de discountValue1 Número de dias antes do vencimento até o qual o desconto discountValue1 será aplicado
discountValue2	Decimal	Sempre preenchido junto de discountDateDelta2 Valor do desconto até discountDateDelta2 dias antes do vencimento, em relação a discountType
discountDateDelta2	Integer	Sempre preenchido junto de discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue2 será aplicado
discountValue3	Decimal	Sempre preenchido junto de discountDateDelta3 Valor do desconto até discountDateDelta3 dias antes do vencimento, em relação a discountType
discountDateDelta3	Integer	Sempre preenchido junto de discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue3 será aplicado

Campos do PixInfo (PIX)

Nome	Tipo	Descrição
pixType	String	Tipo do PIX: - IMMEDIATE: expira em pouco tempo (gerado no ChargeLink) - WITH_DUE_DATE: Semelhante a boleto, com configurações de multa e etc (gerado no ChargeCreate) - STATIC: pagamento por QRCode estático do estabelecimento - TERMINAL: pagamento por terminal POS
e2eid	String	Identificador único do pagametno PIX no Bacen Preenchido após o pagamento
pixCopyPaste	String	Código PIX copia e cola Preenchido após a emissão Obs.: para gerar a imagem do QRCode basta usar este código em uma biblioteca de QRCode
expiresAt	Datetime	Data e hora de expiração do PIX se o pixType for IMMEDIATE
interestType	String	Sempre preenchido junto dos campos interestValueTypee interestValue Tipo do juros: - DAYS - DAYS_MONTHLY - DAYS_ANNUALLY - WORKING_DAYS - WORKING_DAYS_MONTHLY - WORKING_DAYS_ANNUALLY Para a explicação de cada um, consulte a documentação de PixCondition
interestValueType	String	Sempre preenchido junto dos campos interestTypee interestValue TIpo do valor do juros: PERCENT ou VALUE
interestValue	Decimal	Sempre preenchido junto dos campos interestTypee interestValueType Valor do juros, com duas casas decimais
fineValueType	String	Sempre preenchido junto do campo fineValue Tipo do valor da multa: PERCENT ou VALUE
fineValue	Decimal	Sempre preenchido junto do campo fineValueType Valor da multa
discountType	String	Sempre preenchido junto de outros campos discount Tipo do desconto: - FIXED_DATES - DAYS - WORKING_DAYS Para a explicação de cada um, consulte a documentação de PixCondition
discountValueType	String	Tipo do valor do desconto: PERCENT ou VALUE
discountValue	Decimal	Sempre preenchido sediscountType for DAYS ou WORKING_DAYS Valor do desconto cobrado ao dia
discountValue1	Decimal	Sempre preenchido junto dos campos discountDateDelta1 e discountType=FIXED_DATES Valor do desconto até discountDateDelta1 dias antes do vencimento, em relação a discountType
discountDateDelta1	Inteiro	Sempre preenchido junto dos campos discountDateDelta1 e discountType=FIXED_DATES Número de dias antes do vencimento até o qual o desconto discountValue1 será aplicado
discountValue2	Decimal	Sempre preenchido junto do campo discountDateDelta2 Valor do desconto até discountDateDelta2 dias antes do vencimento, em relação a discountType
discountDateDelta2	Inteiro	Sempre preenchido junto do campo discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue2 será aplicado
discountValue3	Decimal	Sempre preenchido junto do campo discountDateDelta3 Valor do desconto até discountDateDelta3 dias antes do vencimento, em relação a discountType
discountDateDelta3	Inteiro	Sempre preenchido junto do campo discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue3 será aplicado

PaymentProfile

O PaymentProfile associa o Customer (pagador) com informações de cobrança, como endereço de cobrança e dados do cartão.

Um PaymentProfile único é definido pelas chaves (por método):

• Cartão: Número do cartão (truncado), data de expiração e CPF/CNPJ do Customer

• PIX: CPF/CNPJ do Customer, endereço de cobrança e endereço do entrega

• Boleto: CPF/CNPJ do Customer, endereço de cobrança e endereço do entrega

Campos PaymentProfile

Nome	Tipo	Descrição
id	Integer	Identificador único
method	String	method: - CARD - BILLET - PIX
isActive	Boolean	Se o PaymentProfile está ativo
company	Objeto Company	Estabelecimento dono do PaymentProfile
customer	Objeto Customer	Pagador associado a este PaymentProfile
billingAddress	Objeto Address	Endereço de cobrança
shippingAddress	Objeto Address	Endereço de entrega
cardNumber	String	Apenas para o método CARD Número truncado do cartão de crédito
expiryMonth	Integer	Apenas para o método CARD Mês de expiração do cartão de crédito
expiryYear	Integer	Apenas para o método CARD Ano de expiração do cartão de crédito
brand	String	Apenas para o método CARD brand do cartão É usado o formato de arranjo de pagamento, e.g. Visa Crédito = "VCC"
cardHolderName	String	Apenas para o método CARD Nome do titular do cartão de crédito
token	String	Apenas para o método CARD token utilizado para reutilizar este cartão em cobranças futuras Permite utilizar o cartão sem ter os dados salvos diretamente
voidAt	Datetime	Data e hora do cancelamento deste PaymentProfile
rejectedReason	String	Apenas para o método CARD Motivo de rejeição da Tokenização

BilletCondition

Um BilletCondition guarda configurações de um boleto, como a multa ou desconto a serem aplicados. Se as configuração estiver salva em um BilletICondition, seu ID pode ser utilizado para aplicá-la a novos boletos no ChargeCreate.

Campos do BilletCondition

Nome	Tipo	Descrição
name	String	Obrigatório caso persist=true Nome da condição
description	String	description da condição. Esse campo só faz sentido caso persist=true
company	Objeto Company	Estabelecimento dono dessa condição
interestType	String	Tipo do juros: - PERCENT - VALUE
interestValue	Decimal	Valor do juros, em relação ao interestType
fineType	String	Tipo da multa: - PERCENT - VALUE
fine	Decimal	Valor da multa, em relação ao fineType
discountType	String	Tipo do desconto: - PERCENT - VALUE
advanceDiscountValue	String	Não preenchido junto de outros campos discount****, além de discountType Desconto aplicado por dias corridos antes do vencimento, em relação a discountType
discountValue1	Decimal	Sempre preenchido junto de discountDateDelta1 Valor do desconto até discountDateDelta1 dias antes do vencimento, em relação a discountType
discountDateDelta1	Integer	Sempre preenchido junto de discountValue1 Número de dias antes do vencimento até o qual o desconto discountValue1 será aplicado
discountValue2	Decimal	Sempre preenchido junto de discountDateDelta2 Valor do desconto até discountDateDelta2 dias antes do vencimento, em relação a discountType
discountDateDelta2	Integer	Sempre preenchido junto de discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue2 será aplicado
discountValue3	Decimal	Sempre preenchido junto de discountDateDelta3 Valor do desconto até discountDateDelta3 dias antes do vencimento, em relação a discountType
discountDateDelta3	Integer	Sempre preenchido junto de discountValue2 Número de dias antes do vencimento até o qual o desconto discountValue3 será aplicado

BilletCondition

Um PixCondition guarda configurações de um PIX, como a multa ou desconto a serem aplicados. Se a configuração estiver salva em um BilletICondition, seu ID pode ser utilizado para aplicá-la a novos boletos no ChargeCreate.

Campos do PixCondition

Valor	Descrição
DAYS	Juros aplicado proporcional ao número de dias corridos
DAYS_MONTHLY	Admite apenas interestValueType PERCENT Juros mensal aplicado proporcional ao número de dias corridos após vencimento
DAYS_ANNUALLY	Admite apenas interestValueType PERCENT Juros anual aplicado proporcional ao número de dias corridos após o venciomento
WORKING_DAYS	Juros aplicado proporcional ao número de dias úteis após o vencimento
WORKING_DAYS_MONTHLY	Admite apenas interestValueType PERCENT Juros mensal aplicado proporcional ao número de dias úteis após vencimento
WORKING_DAYS_ANNUALLY	Admite apenas interestValueType PERCENT Juros anual aplicado proporcional ao número de dias úteis após o venciomento

Valores para o campo interestType

Valor	Descrição
DAYS	Juros aplicado proporcional ao número de dias corridos
DAYS_MONTHLY	Admite apenas interestValueType PERCENT Juros mensal aplicado proporcional ao número de dias corridos após vencimento
DAYS_ANNUALLY	Admite apenas interestValueType PERCENT Juros anual aplicado proporcional ao número de dias corridos após o venciomento
WORKING_DAYS	Juros aplicado proporcional ao número de dias úteis após o vencimento
WORKING_DAYS_MONTHLY	Admite apenas interestValueType PERCENT Juros mensal aplicado proporcional ao número de dias úteis após vencimento
WORKING_DAYS_ANNUALLY	Admite apenas interestValueType PERCENT Juros anual aplicado proporcional ao número de dias úteis após o venciomento

Valores para o campo discountType

Valor	Descrição
DAYS	Campo discountValue deve ser preenchido Desconto aplicado proporcional ao número de dias corridos antes do vencimento
WORKING_DAYS	Campo discountValue deve ser preenchido Desconto aplicado proporcional ao número de dias úteis antes do vencimento
FIXED_DATES	Campos discountValue[1..3] e discountDateDelta[1..3] devem ser preenchidos Permite que até 3 deltas em relação ao vencimento sejam informados, cada intervalo aplicando um valor de desconto distindo. Pelo menos discountDateDelta1 e discountValue1 devem estar preenchidos Obs.: discountDateDelta1 sempre deve ser o maior valor (mais distante antes do vencimento) e discountDateDelta3 sempre deve ser o menor valor (mais próximo antes do vencimento)

ChargeLink

O ChargeLink é um link de pagamento, que pode ser configurado para ser utilizável apenas uma vez, ou admitindo múltiplos pagamentos. O link também pode ser expirado após determinado tempo é permancer ativo indifinitavemente.

Parâmetros

Nome	Tipo	Descrição
id	Integer	ID unico
isActive	Boolean	Link está ativo
baseAmount	Decimal	valor base da cobrança se estiver vazio deve ser informado no momento do pagamento
unique	Boolean	Link unique ou não
timesUsed	Integer	Quantidade de vezes que o Link foi usado
billetAllowed	Boolean	pagamento por boleto habilitado
cardSingleAllowed	Boolean	pagamento por cartão habilitado
cardRecurringAllowed	Boolean	pagamento por cartão de forma recorrente habilitado
pixAllowed	Boolean	pagamento por PIX habilitado
companyName	String	Define se o método de pagamento boleto pode ser utilizado
company	Objeto Company	Estabelecimento dono desta ChargeLink
expiryDate	DateTime	Data e hora que expira o link de pagamento
maxInstallments	Integer	Maximo de parcelas
url	String	url gerado para a ChargeLink
billetCondition	Objeto BilletCondition	Apenas para BILLET Configurações de boleto
order	Objeto OrderInput
pixExpiringSeconds	Integer	Tempo de expiração do PIX
billetType	String	"NORMAL" ou "HYBRID"

Tipos de boleto

Método	Nome	Descrição
billletType	NORMAL	Boleto sem QRCode PIX
billletType	HYBRID	Boleto com QRCode PIX

Company (Estabelecimento)

Objetos no grupo Company estão mais ligados aos estabelecimentos.

Customer

O Customer é o pagador das cobranças, podendo ser tanto uma pessoa física quanto jurídica.

Campos Customer

Nome	Tipo	Descrição
id	Inteiro	ID único
company	Objeto Company	Empresa para a qual este Customer foi cadastrado Obs.: ele pode estar ""repetido"" em várias empresas
name	String	Nome do pagador
email	String	Email
documentType	String	Tipo do documento: CPF ou CNPJ
document	String	Número do CPF/CNPJ
phone	String	Telefone ou celular
birthDate	Date	Data de nascimento
gender	String	Gênero do pagador: - MALE - FEMALE - OTHER

Company

A Company é um empresa. As empresas são divididas nos seguintes tipos, indicados também pelo campo companyType:

• FACILITATOR: Sub-adquirente, responsável pelo gerenciamento e liquidação dos recebíveis (é o caso do BS Bank)

• MARKETPLACE: Marketplaces possuem várias empresas abaixo de si, para as quais usuários deste Marketplace podem criar cobranças. Um Marketplace pode ter sub-marketplaces e vice-versa.

• FINANCIER: Financiador, responsável por financiar operações de crédito através de Contracts, que trocam a titularidades de recebíveis a seu favor

• MERCHANT: Estabelecimento que possuem cobranças e os únicos para os quais cobranças podem ser criadas

• REFERRER: Empresa que indica outras e ganha uma comissão das vendas geradas por elas

Campos de Company

Nome	Tipo	Descrição
id	Inteiro	ID único
companyType	String	companyType: - FACILITATOR - MARKETPLACE - FINANCIER - MERCHANT - REFERRER
companyState	String	companyState: - ACTIVE - INACTIVE - SUSPENDED - ONGOING - AWAITING_APPROVAL - DENIED
name	String	Nome fantasia
legalName	String	Razão social
cnae	String	Código de Atividade Econômica (CNAE)
documentType	String	documentType: CPF ou CNPJ
document	String	Número do document
email	String	email principal da empresa
phone	String	phone principal da empresa

BankAccount

Um objeto BankAccount guarda os dados de uma conta bancária da Company. Normalmente elas são utilizadas em PayoutRules para formar um split de pagamento.

Campos BankAccount

Nome	Tipo	Descrição
id	Inteiro	Identificador único
bank	Objeto Bank	Banco da conta bancária
bank.ispb	String	Código ISPB do banco
bank.compe	String	Código COMPE do banco
documentType	String	Tipo do documento do titular da conta: CPF ou CNPJ
holderDocument	String	holderDocument do titular da conta
holderName	String	holderName do titular da conta
agency	String	Codigo da agência, com dígito verificador
number	String	Número da conta, com dígito verificador
accountType	String	Tipo da conta: - CC: Conta Corrente - CD: Conta de Depósito - PG: Conta de Pagamento - PP: Conta Poupança
transferFee	Decimal	Taxa de transferência
pixKeyType		Tipo da chave PIX: - EMAIL - CPF - CNPJ - PHONE - RANDOM_KEY
pixKey		Chave PIX

Payout (Liquidação)

PayoutRule

O objeto PayoutRule define um split de pagamento associado a uma Company. Uma empresa pode ter vários splits, mas um deles será o primário (marcado pelo campo isPrimary), que será utilizado sempre que um for necessário mas não informado.

Toda PayoutRule deve ter pelo menos um RuleItem com splitType PERCENTAGE e a soma dos proportions de RuleItems PERCETAGE deve ser igual a "100.0".

Campos PayoutRule

Nome	Tipo	Descrição
id	Inteiro	Identificador único
company	Objeto Company	Empresa a qual este split pertence
isActive	Boolean	Se esse split está ativo e pode ser utilizado
isPrimary	Boolean	Se esse split é o padrão Apenas um split pode ser padrão em uma empresa
ruleItems	Lista de objetos RuleItem	Lista de ""destinos"" do split. Consulte a tabela a baixo para ver os campos de um RuleItem

Campos RuleItem

Nome	Tipo	Descrição
splitType	String	Tipo de split para essa conta: - PERCENTAGE: uma porcetagem (proportion) será repassada para esta conta - FIXED_AMOUNT: este valor (amount) será repassado para esta conta, se for possível
proportion	Decimal	Sempre preenchido quando splitType for PERCENTAGE Proporção repassada à conta
amount	Decimal	Sempre preenchido quando splitType for FIXED_AMOUNT Valor repassado à conta
isLiable	Boolean	Se esta conta irá arcar com débitos (como taxas de aluguél e estornos) Taxas associadas diretamente á transação (como MDR e antecipação) são descontadas independente deste campo
bankAccount	Objeto BankAccount	Conta bancária para esta parte do split
schedule	Objeto Schedule	Configuração das opções de antecipação Consulte na tabela abaixo o seu formato

Campos Schedule

Nome	Tipo	Descrição
scheduleType	String	Se automaticAdvance for false esse campo é ignorado, mas ainda estará preenchido Tipo da antecipação aplicada: - DAILY - WEEKLY - MONTHLY
scheduleAnchor	Inteiro	Se automaticAdvance for false esse campo é ignorado, mas ainda estará preenchido Indica o ""dia"" da antecipação em relacão ao scheduleType: - DAILY: o scheduleAnchor será um valor entre 1 e 31, indicando quantos dias depois do processamento será liquidado - WEEKLY: o scheduleAnchor será um valor de 0 a 6, onde 0 é segunda-feira e 6, domingo - MONTHLY: o scheduleAnchor será um valor entre 1 e 31, indicando o dia do mês quando ocorrerá as liquidações
automaticAdvance	Boolean	Se automaticAdvance está habilitada. Caso true, a liquidação será feita conforme indicado pelos campos scheduleType e scheduleAnchor, acarretando em uma taxa de antecipação Caso contrário, as datas padrão de liquidação serão utilizada

Core (Comuns)

Address

Este objeto descreve o formato para endereços em geral na nossa API.

Campos Address

Nome	Tipo	Descrição
number	String	Número do endereço
street	String	Rua do endereço
district	String	Bairro/Distrito do endereço
city	String	Cidade do endereço
state	String	Sigla do estado do endereço
additionalDetails	String	Informações adicionais do endereço, e.g. número do apartamento
zipCode	String	CEP do endereço, apenas números

Marketplace

Possuímos algumas particularidades para o melhor funcionamento dos marketplaces em nosso sistema, abaixo iremos listar as diferenças:

Tratamos marketplaces e estabelecimentos comerciais como um mesmo objeto Company, com a diferença de:

• Estabelecimento Comercial (EC) é uma Company do tipo MERCHANT

• Marketplace é uma Company do tipo MARKETPLACE

PaymentProfile

Para acessar a documentação completa de paymentProfile onde ensinamos a criar e modificar paymentProfiles criados clique aqui.

Em marketplaces temos duas opções de inclusão de PaymentProfiles:

• A partir de um estabelecimento comercial específico, o que resultará em um PaymentProfile de uso exclusivo para o EC em questão, para isso deve ser passado o CompanyID do EC em questão.

• A partir do próprio marketplace, o que resultará em um PaymentProfile que poderá ser usado por todos os EC's cujo o marketplace é proprietário, para isso deve ser passado o CompanyID do próprio marketplace.

Fornecemos essas opções pensando em ocasiões onde seu EC opera de forma mais isolada e também para EC's fortemente acoplados ao marketplace.

Customer

Para acessar a documentação completa de customer clique aqui.

Em marketplaces temos duas opções de inclusão de customer:

• A partir de um estabelecimento comercial específico, o que resultará em um Customer de uso exclusivo para o EC em questão, para isso deve ser passado o CompanyID do EC em questão.

• A partir do próprio marketplace, o que resultará em um Customer que poderá ser usado por todos os EC's cujo o marketplace é proprietário, para isso deve ser passado o CompanyID do próprio marketplace.

Fornecemos essas opções pensando em ocasiões onde seu EC opera de forma mais isolada e também para EC's fortemente acoplados ao marketplace.