Elevamos a experiência dos nossos integradores oferecendo serviços que vão além das transações convencionais. A seguir apresentamos os endpoints de integração para pagamentos externos a empresas, realizados a partir da sua conta.
- Como Merchant, primeiro, você precisa se autenticar com suas Chaves de API.
- Se você não conhece o processo, consulte a primeira parte do nosso Guia de Fluxo de Integração, bem como o Endpoint de Atenticação.
- Recomendamos fortemente que você crie novas API Keys, exclusivas para esse fim.
- Solicite a lista de Recebedores cadastrados. Em nossa plataforma, o Recebedor é uma empresa cadastrada pelo merchant exclusivamente para receber pagamentos. Esta solicitação é importante para obter o Receiver Id, a ser utilizado na solicitação de pagamento.
- Nota: Os recebedores são registrados manualmente através do Portal Administrativo. Pretendemos publicar endpoints de registro de Recebedores em breve.
- Esteja ciente de que o recebedor desejado deverá ser aprovado pela nossa equipe.
- Com base no ID do Recebedor, solicite a lista de Contas Bancárias cadastradas para esse Recebedor.
- Observação: as Contas Bancárias dos Recebedores são registradas manualmente via Portal Administrativo, e fazem parte do necessário para aprovação da revisão. Pretendemos publicar endpoints de Contas Bancárias em breve.
- Solicite um pagamento para uma Conta Bancária específica de um Recebedor registrado e aprovado. Você precisará fornecer o ID do Recebedor e o ID da Conta.
- Para fazer upload da nota fical você deverá solicitar uma URL segura de upload. Para tal, você utilizará o ID da solicitação de Pagamento recém-criada. Faça o upload da nota-fiscal do pagamento via código usando a URL retornada.
A seguir apresentamos o conjunto de endpoints que permitem executar essas operações via API.
Listando os Recebedores
Endpoint de Referência
GET /partners-int/receivers
Este endpoint permite listar um conjunto paginado de Recebedores baseado no seu status de aprovação.
- Request Params (Exemplo Útil)
/partners-int/receivers?dataset.limit=10&dataset.offset=0&receiverStatus=Approved
| Path Param | Tipo | Required | Descrição |
|---|---|---|---|
| dataset.limit | number | true | O tamanho da paginação como um de: 5, 10 ou 20. |
| dataset.offset | number | true | O offset da paginação, começando de 0. |
| receiverStatus | string | false | O status de aprovação para o Recebedor desejado, como um de: Pending, Approved ou Rejected |
- Resposta da Request (
200 - OK)
{
"statusCode": "Done",
"data": {
"limit": 20,
"offset": 0,
"total": 1,
"items": [
{
"id": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"creationDate": "2023-08-26T00:42:18.562Z",
"receiverStatus": "Approved",
"companyFantasyName": "Example Company Name",
"companyCNPJ": "21998536000118",
"reviewNote": null,
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
| limit | number | O tamanho da paginação, como provido na request. |
| offset | number | O offset da paginação, como provido na request. |
| total | string | O número de Recebedores encontrados. |
| items | array | O conjunto de Recebedores encontrados. |
| id | string | O Id do Recebedor |
| creationDate | string | A data de criação do Recebedor. |
| receiverStatus | string | O status do Recebedor, como um entre: Pending, Approved, Rejected |
| companyFantasyName | string | O nome de fantasia da empresa. |
| companyCNPJ | string | O CNPJ da empresa. |
| reviewNote | string | Qualquer nota que o revisor incluiu ao revisar esse Recebedor. |
Recuperando um Recebedor Específico
Endpoint de Referência
GET /partners-int/receivers/{receiverId}
Este endpoint permite que recuperar um Recebedor específico provendo o receiverId. Para o exemplo abaixo, considere o id de Recebedor 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c.
- Request Params (Exemplo Útil)
/partners-int/receivers/6f8a7e7e-b1b2-498f-82b8-9c999fe7451c
| Path Param | Tipo | Required | Descrição |
|---|---|---|---|
| receiverId | string | true | O id do Recebedor como retornado da listagem de Recebedores. |
- Request Response (
200 - OK)
{
"statusCode": "Done",
"data": {
"limit": 50,
"offset": 0,
"total": 1,
"items": [
{
"id": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"creationDate": "2023-08-26T00:42:18.562Z",
"receiverStatus": "Approved",
"companyFantasyName": "Company XPTO",
"companyCNPJ": "21998536000118",
"reviewNote": null,
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
| limit | number | O tamanho da paginação. Neste caso, 50 por default. |
| offset | number | O offset da paginação. Neste caso, 0 por default. |
| total | string | O número de Recebedores encontrados. Neste caso, 1 por default. |
| items | array | O conjunto de Recebedores encontrados. Neste caso, contendo apenas um. |
| id | string | O id do Recebedor. |
| creationDate | string | A data de criação do Recebedor. |
| receiverStatus | string | O status do Recebedor, como um entre: Pending, Approved e Rejected. |
| companyFantasyName | string | O nome de fantasia da empresa. |
| companyCNPJ | string | O CNPJ da empresa. |
| reviewNote | string | Qualquer nota que o revisor incluiu ao revisar esse Recebedor. |
Recuperando as Contas de Recebedores
Endpoint de Referência
GET /partners-int/receivers/{receiverId}/accounts
Este endpoint permite recuperar as Conta Bancárias de um Recebedor específico provendo o receiverId. Para o exemplo abaixo, considere o receiver id 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c.
- Request Params (Exemplo Útil)
/partners-int/receivers/6f8a7e7e-b1b2-498f-82b8-9c999fe7451c/accounts?offset=0&limit=10
| Path Param | Type | Required | Description |
|---|---|---|---|
| receiverId | string | true | O id do Recebedor como retornado na listagem de Recebedores. |
- Resposta da Request (
200 - OK)
{
"statusCode": "Done",
"data": [
{
"id": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3",
"bankCode": "001",
"bankName": "Banco do Brasil S.A.",
"accountAgency": "1591",
"accountNumber": "103096",
"accountOwnerDocNumber": "21998536000118",
"pixKey": "21.998.536/0001-18",
"pixKeyType": "CNPJ"
}
]
}
| Field Name | Type | Description |
|---|---|---|
| data | array | O conjunto de Contas Bancárias encontradas. |
| id | string | O id da Conta Bancária. |
| bankCode | string | O código bancário como registrado junto ao Banco Central do Brasil. |
| bankName | string | O nome do banco. |
| accountAgency | string | A agência do banco desta conta. |
| accountNumber | string | O número da conta bancária. |
| accountOwnerDocNumber | string | O número de documento do dono da conta. Neste caso, o número do CNPJ. |
| pixKey | string | A chave PIX, que deve ser o valor do CNPJ. |
| pixKeyType | string | A tipo da chave PIX, 'CNPJ' é obrigatório. |
Criando um Pagamento a Empresa
Endpoint de Referência
POST /partners-int/accounts/transaction-requests
Este endpoint permite criar solicitações de pagamento para uma conta bancária de um Recebedor específico, especificados através do refReceiver, o id do Recebedor, e o refBankAccount, id da Conta Bancária.
Para o exemplo abaixo, considere o id do Recebedor 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c, e o id da Conta Bancária bd90f915-ce89-4cc8-9f20-5d622bdfd2b3.
- Request Params (Exemplo Útil)
{
"amount": "10000.00",
"description": "Monthly services payment",
"refReceiver": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"refBankAccount": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3"
}
| Campo | Tipo | Required | Descrição |
|---|---|---|---|
| amount | string | true | O valor a pagar. |
| description | string | true | A descrição do pagamento. |
| refReceiver | string | true | O id de referência do Recebedor. |
| refBankAccount | string | true | O id de referência da Conta Bancária. |
- Resposta da Request (
201 - Created)
{
"statusCode": "Done",
"data": {
"id": "b35967b8-1d11-4612-9394-7c076b49ea48",
"amount": "10000.00",
"status": "Pending",
"pixKey": "21.998.536/0001-18",
"pixKeyType": "CNPJ",
"description": "Monthly services payment",
"refReceiver": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"refBankAccount": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3",
"refTransaction": "698050cb5a7c4f639385a831ed23c3db",
"referencesInfo": {
"receiverName": "Company XPTO",
"customerName": "Merchant X"
}
}
}
| Field Name | Type | Description |
|---|---|---|
| id | string | O id da solicitação recém-criada. |
| amount | string | O valor do pagamento. |
| status | string | O status de aprovação como um entre: Pending, Approved ou Rejected. |
| pixKey | string | A chave PIX, o CNPJ como provido na request. |
| pixKeyType | string | O tipo da chave PIX, nesse caso o CNPJ |
| description | string | A descrição provida na request. |
| refReceiver | string | O Recebedor de referência provido na request. |
| refBankAccount | string | A Conta Bancária de referência provida na request. |
| refTransaction | string | O id da transação bancária, como encontrada na lista de Vendas. |
| referencesInfo.receiverName | string | O nome de fantasia da empresa (Recebedor). |
| referencesInfo.customerName | string | O nome do merchant (solicitante). |
Todas as solicitações de pagamento criadas via API também seguem o fluxo de aprovação como se fossem criadas via Portal Administrativo. Observe que é possível Cancelar uma Solicitação de Pagamento enquanto ela não foi Aprovada e Executada.
Quando Aprovados, os Pedidos de Pagamento ficam associados a um objeto de Transação com Ciclo de Vida de Transação. As alterações de estado no ciclo de vida da transação são imediatamente notificadas por meio de notificação de webhooks.
Solicitando uma URL de Upload
Reference Endpoint
POST /partners-int/documents
Este endpoint permite solicitar uma URL segura de upload para entrega da nota fiscal do pagamento.
- Payload da Request (Useful Example)
{
"properties": {
"name" : "2023-August Invoice"
},
"ownerType" : "Transaction",
"owner" : "f8c4f1c9-7366-4330-8f77-63b8a73884a8",
"type": "Invoice",
"fileName": "Invoice.pdf"
}
| Campo | Tipo | Required | Descrição |
|---|---|---|---|
| properties.name | string | true | Qualquer nome que o parceiro queira definir para ser apresentada no Portal Administrativo para esse documento. |
| ownerType | string | true | Transaction, como string obrigatória. |
| owner | string | true | O id da solicitação de Pagamento. |
| type | string | true | Invoice, como string obrigatória. |
| fileName | string | true | O nome do arquivo que será enviado. |
- Resposta da Request (
201 - Created)
{
"statusCode": "Done",
"data": "https://paybrokers-platform-dev-storage.s3.us-east-1.amazonaws.com/Docs/Transaction/f8c4f1c9-7366-4330-8f77-63b8a73884a8/Invoice/0b2968ef-6104-4468-bb60-0fc91f5efd95?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAZVR4MXQ3UPZYCGVA%2F20230828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230828T024230Z&X-Amz-Expires=300&X-Amz-Signature=4e6fa8dbc1b70c1a2643a815a26a121d3ee2118df53b52052349f11ec452f31a&X-Amz-SignedHeaders=host&x-id=PutObject"
}
| Path Param | Tipo | Required | Descrição |
|---|---|---|---|
| data | string | true | A URL de upload para onde você deve entregar a invoice via código. |
Para ir além
Deste ponto em diante, apresentamos uma série de endpoints complementares, que podem ser úteis para sua integração, mas não são obrigatórios para uma solicitação de pagamento.
Cancelando uma Solicitação
Endpoint de Referência
PUT /partners-int/accounts/transaction-requests/cancel/{trId}
Este endpoint permite cancelar uma solicitação específica baseado no tfId, o id da transação.
- Request Params (Exemplo Útil)
/partners-int/accounts/transaction-requests/cancel/b35967b8-1d11-4612-9394-7c076b49ea48
| Path Param | Tipo | Required | Descrição |
|---|---|---|---|
| trId | string | true | O id da solicitação de pagamento como retornado na criação e listagem das solicitações. |
- Resposta da Request (
200 - OK)
{
"statusCode": "Done"
}
Listando Solicitações de Pagamento
Endpoint de Referência
GET /partners-int/accounts/transaction-requests
Este endpoint permite solicitar uma lista paginada de solicitações de pagamento.
- Request Params (Exemplo)
/partners-int/accounts/transaction-requests?dataset.limit=10&dataset.offset=0&status=Approved&startDate=2023-08-01T03:00:00.000Z&endDate=2023-08-31T03:00:00.000Z
| Path Param | Type | Required | Description |
|---|---|---|---|
| dataset.limit | number | true | O tamanho da paginação com um de: 5, 10 ou 20. |
| dataset.offset | number | true | O offset da paginação, começando de 0. |
| status | string | true | O status de aprovação do pagamento desejado, como um de: Pending, Approved, Rejected |
| startDate | string | true | A data inicial de onde buscar a solicitação. |
| endDate | string | true | A data final até onde buscar a solicitação. |
- Request Response (
200 - OK)
{
"statusCode": "Done",
"data": {
"limit": 10,
"offset": 0,
"total": 1,
"items": [
{
"id": "f8c4f1c9-7366-4330-8f77-63b8a73884a8",
"amount": "100000.00",
"status": "Pending",
"pixKey": "21.998.536/0001-18",
"description": "Monthly services payment",
"executionState": "Created",
"executionCreatedDate": "2023-08-27T01:56:40.675Z",
"executionRegisteredDate": null,
"executionCompletedDate": null,
"refTransaction": "a015caae-1926-4afe-8db8-8eda115de682",
"refReceiver": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"refBankAccount": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3",
"referencesInfo": {
"receiverName": "Solinov",
"customerName": "Startup J"
}
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
| limit | number | O tamanho da paginação, como provido na request. |
| offset | number | O offset da paginação, como provido na request. |
| total | number | O número de solicitações feitas. |
| items | array | O conjunto de solicitações. |
| id | string | O id da solicitação de pagamento. |
| amount | string | O valor para pagamento. |
| status | string | O status de aprovação como um entre: Pending, Approved ou Rejected. |
| pixKey | string | A chave PIX, o CNPJ provido na request. |
| pixKeyType | string | O tipo da PIX key, nesse caso o CNPJ. |
| description | string | A descrição provida na request. |
| executionState | string | O status de execução da transação associada a essa requisição. |
| executionCreatedDate | string | O timestamp de quando a execução da transação foi iniciada. |
| executionRegisteredDate | string | O timestamp de quando a execução da transação foi registrada junto ao sistema bancário. Será null se a solicitação não estiver em estado Approved. |
| executionCompletedDate | string | O timestamp de quando a execução da transação foi finalizada junto ao sistema bancário. Será null se a solicitação não estiver em estado Approved. |
| refReceiver | string | O id do Recebedor provido na request. |
| refBankAccount | string | A id da Conta Bancária provida na solicitação. |
| refTransaction | string | O id da Transação junto ao banco, que será encontrada na lista de Vendas. |
| referencesInfo.receiverName | string | O nome de fantasia da empresa (Recebedor). |
| referencesInfo.customerName | string | O nome do merchant (solicitante). |
Detalhando um Pagamento
Endpoint de Referência
GET /partners-int/accounts/transaction-requests/{tdId}
Este endpoint permite detalhar uma solicitação específica baseado no tdId, o id da solicitação.
- Request Params (Exemplo Útil)
/partners-int/accounts/transaction-requests/b35967b8-1d11-4612-9394-7c076b49ea48
| Path Param | Type | Required | Description |
|---|---|---|---|
| trId | string | true | O id da solicitação como retornado na criação ou listagem. |
- The Request Response (
200 - OK)
{
"statusCode": "Done",
"data": {
"entity": {
"id": "f8c4f1c9-7366-4330-8f77-63b8a73884a8",
"amount": "10.000000",
"status": "Pending",
"pixKey": "21.998.536/0001-18",
"pixKeyType": "CNPJ",
"description": "Monthly services payment",
"refReceiver": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
"refBankAccount": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3",
"refTransaction": "a015caae-1926-4afe-8db8-8eda115de682",
"referencesInfo": {
"receiverName": "Solinov",
"customerName": "Startup J"
},
"executionCreatedDate": "2023-08-28T01:56:40.675Z",
"executionCompletedDate": null,
"executionRegisteredDate": null,
"executionState": "Created"
},
"flows": [
{
"id": "31c1dfe1-30bf-4726-89d2-275244e2d2d3",
"date": "2023-08-28T01:56:40.654Z",
"userFullName": "Company Administrator",
"userRealm": "Partner",
"status": "Pending",
"comment": null
}
]
}
}
| Campos | Tipo | Descrição |
|---|---|---|
| entity | string | O objeto da solicitação |
| entity.id | string | O id da solicitação de pagamento. |
| entity.amount | string | O valor do pagamento. |
| entity.status | string | O status de aprovação como um entre: Pending, Approved ou Rejected. |
| entity.pixKey | string | A chave PIX, o CNPJ provido na request |
| entity.pixKeyType | string | O tipo de chave PIX, neste caso, CNPJ. |
| entity.description | string | A descrição provida na request. |
| entity.refReceiver | string | O id do Recebedor provido na request. |
| entity.refBankAccount | string | O id da Conta Bancária provida na request. |
| entity.refTransaction | string | O id da transação bancária, a ser encontrada na lista de Vendas. |
| entity.referencesInfo.receiverName | string | O nome da fantasia da empresa (Recebedor). |
| entity.referencesInfo.customerName | string | O nome do merchant (solicitante). |
| executionState | string | O status de execução da transação associada a essa requisição. |
| executionCreatedDate | string | O timestamp de quando a execução da transação foi iniciada. |
| executionRegisteredDate | string | O timestamp de quando a execução da transação foi registrada junto ao sistema bancário. Será null se a solicitação não estiver em estado Approved. |
| executionCompletedDate | string | O timestamp de quando a execução da transação foi finalizada junto ao sistema bancário. Será null se a solicitação não estiver em estado Approved. |
| flows | string | Os objetor do fluxo de aprovação, detalhando os passos de cada status de aprovação. |
| flow.id | string | O id do passo de aprovação. |
| flow.date | string | Quando o passo foi criado. |
| status | string | O status do passo do fluxo de aprovação. |
| comment | string | Um comentário opcional do revisor, nesse passo de aprovação. |
Listando Documentos
Reference Endpoint
GET /partners-int/documents
Este endpoint permite listar os documentos para uma dada solicitação, como informado no campo owner.
- Request Payload (Exemplos Úteis)
partners-int/documents?type=Invoice&ownerType=Transaction&owner=f8c4f1c9-7366-4330-8f77-63b8a73884a8
| Campo | Tipo | Required | Descrição |
|---|---|---|---|
| ownerType | string | true | Transaction, sempre. |
| type | string | true | Invoice, sempre. |
| owner | string | true | O id da solicitação. |
- Resposta da Request (
200 - OK)
{
"statusCode": "Done",
"data": {
"limit": 50,
"offset": 0,
"total": 1,
"items": [
{
"id": "0b2968ef-6104-4468-bb60-0fc91f5efd95",
"type": "Invoice",
"state": "Pending",
"properties": {
"name": "August Invoice",
"extension": "invoice"
},
"owner": "f8c4f1c9-7366-4330-8f77-63b8a73884a8",
"ownerType": "Transaction"
}
]
}
}
Removendo um Pagamento
Endpoint de Referência
DELETE /partners-int/documents/{documentId}
Este endpoint permite que remover um documento.
- Request Payload (Exemplo Útil)
partners-int/documents/0b2968ef-6104-4468-bb60-0fc91f5efd95
| Field Name | Type | Required | Description |
|---|---|---|---|
| documentId | string | true | O id do documento, como provido na listagem de documentos. |
- Request Response (
200 - OK)
{
"statusCode": "Done"
}