Payments to Companies

We elevate our integrators' experience by offering services that go beyond conventional transactions. Next, we present the integration endpoints for external payments to companies, made from your account with us.

As a Merchant, first, you need to authenticate with your specific Api Keys.
- If you are not aware of the process, please refer to the first part of our Integration Flow Guide as well as the Athentication Endpoint.
- We strongly recommend you create new API Keys, exclusive for this purpose.
Request the list of registered Receivers. In our platform, the Receiver is a company registered by the merchant exclusivelly to receive payments. This request is important to get the Receiver Id, to be used in the payment request.
- Note: Receivers are registered manually via Admin Portal. We intend to publish receivers registration endpoints soon.
- Be aware that the desired receiver must be approved by our team.
Based on the Receiver Id, request the list of registered bank accounts for that receiver.
- Note: Receivers' Bank Accounts are registered manually via Admin Portal, and are part of the necessary for review approval. We intend to publish bank accounts endpoints soon.
Request a payment for a specific bank account of a registered and approved receiver, you will need to provide both the receiver id and the account id.
To upload the payment invoice, you need to ask for a secure upload URL. For such, you will use the recently created payment request id. Upload the invoice via code using the returned upload URL.

Next, we present the set of endpoints to allow you executing these operations via API.

Listing the Receivers

Reference Endpoint

GET /partners-int/receivers

This endpoint allows you to list a paginated set of receivers based on the approval status.

The Request Params (Useful Example)

/partners-int/receivers?dataset.limit=10&dataset.offset=0&receiverStatus=Approved

Path Param	Type	Required	Description
dataset.limit	number	true	The pagination size as one of: 5, 10 or 20.
dataset.offset	number	true	The pagination offset, starting from 0.
receiverStatus	string	false	The approval status of the desired receivers, as one of: Pending, Approved, Denied

The Request Response (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,
            }
        ]
    }
}

Field Name	Type	Description
limit	number	The pagination size, as provided in the request.
offset	number	The pagination offset, as provided in the request
total	string	The number of receivers found.
items	array	The set of receivers found.
id	string	The receiver id.
creationDate	string	The receiver creation date.
receiverStatus	string	The receiver status, as one of: Pending, Approved or Rejected
companyFantasyName	string	The company fantasy name. Fantasy names are commercial names company may chose in their social contract. Typically, this is how the company is popularly known.
companyCNPJ	string	The Company CNPJ. In Brazil, CNPJ is a unique identification number assigned to legal entities, such as companies, organizations, and businesses.
reviewNote	string	Any note a reviewer added when reviewing this receiver registration.

Retrieving a Specific Receiver

Reference Endpoint

GET /partners-int/receivers/{receiverId}

This endpoint allows you to get a specific receiver by providing the receiverId. For the example bellow, consider the receiver id 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c.

The Request Params (Useful Example)

/partners-int/receivers/6f8a7e7e-b1b2-498f-82b8-9c999fe7451c

Path Param	Type	Required	Description
receiverId	string	true	The receiver id as returned when listing the receivers.

The 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,
            }
        ]
    }
}

Field Name	Type	Description
limit	number	The pagination size, in this case, 50 by default
offset	number	The pagination offset, in this case, 0 by default.
total	string	The number of receivers found, in this case, 1 by default.
items	array	The set of receivers found, in this case, containing a single.
id	string	The receiver id.
creationDate	string	The receiver creation date.
receiverStatus	string	The receiver status, as one of: Pending, Approved, Rejected.
companyFantasyName	string	The company fantasy name. Fantasy names are commercial names company may chose in their social contract. Typically, this is how the company is popularly known.
companyCNPJ	string	The Company CNPJ. In Brazil, CNPJ is a unique identification number assigned to legal entities, such as companies, organizations, and businesses.
reviewNote	string	Any note a reviewer added when reviewing this receiver registration.

Retrieving the Receiver Accounts

Reference Endpoint

GET /partners-int/receivers/{receiverId}/accounts

This endpoint allows you to get a specific receiver bank account by providing the receiverId. For the example bellow, consider the receiver id 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c.

The Request Params (Useful Example)

/partners-int/receivers/6f8a7e7e-b1b2-498f-82b8-9c999fe7451c/accounts?offset=0&limit=10

Path Param	Type	Required	Description
receiverId	string	true	The receiver id as returned when listing the receivers.

The Request Response (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	The set of bank account found.
id	string	The bank account id.
bankCode	string	The bank code as registered in Brazilian Central Bank.
bankName	string	The bank name.
accountAgency	string	The bank agency of this account.
accountNumber	string	The bank account number.
accountOwnerDocNumber	string	The owner's document number. In this case, the CNPJ number.
pixKey	string	The PIX Key, a CNPJ value.
pixKeyType	string	The PIX key type, in this case CNPJ is mandatory.

Creating a Company Payment

Reference Endpoint

POST /partners-int/accounts/transaction-requests

This endpoint allows you to create a payment request to a specific receiver bank account by providing the refReceiver, the receiver id, and the refBankAccount, the bank account id.

For the example bellow, consider the receiver id 6f8a7e7e-b1b2-498f-82b8-9c999fe7451c, and the bank account id bd90f915-ce89-4cc8-9f20-5d622bdfd2b3.

The Request Params (Useful Example)

{
    "amount": "10000.00",
    "description": "Monthly services payment",
    "refReceiver": "6f8a7e7e-b1b2-498f-82b8-9c999fe7451c",
    "refBankAccount": "bd90f915-ce89-4cc8-9f20-5d622bdfd2b3"
}

Field Name	Type	Required	Description
amount	string	true	The value to be paid.
description	string	true	The payment description.
refReceiver	string	true	The reference receiver id.
refBankAccount	string	true	The reference bank account id.

The Request Response (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	The recently created transaction request id.
amount	string	The payment value.
status	string	The approval status as one of: Pending, Approved or Rejected.
pixKey	string	The PIX key, the CNPJ provided in the request
pixKeyType	string	The PIX key type, in this case CNPJ.
description	string	The description provided in the request.
refReceiver	string	The reference receiver provided in the request.
refBankAccount	string	The reference bank account provided in the request.
refTransaction	string	The banking transaction id, the one to be found in the Sales list.
referencesInfo.receiverName	string	The company (receiver) fantasy name.
referencesInfo.customerName	string	The merchant (requestor) name.

All Payment Requests created via API also follow the approval flow as if created via Admin Portal. Notice that it is possible to Cancel a Payment Request while it was not Approved and Executed.

When Approved, the Payment Request are associated to a transaction object with its own Transaction Lifecycle. State changes in the transaction lifecycle are promptly notified via webhooks notification.

Requesting a Document Upload URL

Reference Endpoint

POST /partners-int/documents

This endpoint allows you to get an upload URL where to you will upload the payment invoice.

The Request Payload (Useful Example)

{
    "properties": {
        "name" : "August Invoice"
    },
    "ownerType" : "Transaction",
    "owner" : "f8c4f1c9-7366-4330-8f77-63b8a73884a8",
    "type": "Invoice",
    "fileName": "Invoice.pdf"
}

Field Name	Type	Required	Description
properties.name	string	true	Any name the partner might want to be presented in the Admin Portal for the document
ownerType	string	true	Transaction, as mandatory string.
owner	string	true	The transaction request id.
type	string	true	Invoice, as mandatory string.
fileName	string	true	The file name that will be uploaded.

The Request Response (201 - Created)

{
    "statusCode": "Done",
    "data": "https://pagfast-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	Type	Required	Description
data	string	true	The upload URL where you should upload the invoice to.

The endpoints that follow are not mandatory to complete a payment request, but might be useful for integrators.

Canceling a Company Payment Request

Reference Endpoint

PUT /partners-int/accounts/transaction-requests/cancel/{trId}

This endpoint allows you to cancel a specific transaction request based on the trId, the transaction request id.

The Request Params (Useful Example)

/partners-int/accounts/transaction-requests/cancel/b35967b8-1d11-4612-9394-7c076b49ea48

Path Param	Type	Required	Description
trId	string	true	The transaction request id as returned when creating a payment request.

The Request Response (200 - OK)

{
    "statusCode": "Done"
}

Listing Company Payments

Reference Endpoint

GET /partners-int/accounts/transaction-requests

This endpoint allows you to list a paginated set of payment requests.

The Request Params (Useful Example)

/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	The pagination size as one of: 5, 10 or 20.
dataset.offset	number	true	The pagination offset, starting from 0.
status	string	true	The approval status of the desired transaction, as one of: Pending, Approved, Denied
startDate	string	true	The start date where to search the transaction requests.
endDate	string	true	The end date where to search the transaction requests.

The 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"
                }
            }
        ]
    }
}

Field Name	Type	Description
limit	number	The pagination size, as provided in the request.
offset	number	The pagination offset, as provided in the request
total	number	The number of requests found.
items	array	The set of requests found
id	string	The transaction request id.
amount	string	The payment value.
status	string	The approval status as one of: Pending, Approved or Rejected.
pixKey	string	The PIX key, the CNPJ provided in the request
pixKeyType	string	The PIX key type, in this case CNPJ.
description	string	The description provided in the request.
executionState	string	The execution state of this transaction, after its approval.
executionCreatedDate	string	The timestamp when this request execution was initiated.
executionRegisteredDate	string	The timestamp when this request execution was registered with the Banking System. Null if not in Approved approval status.
executionCompletedDate	string	The timestamp when this request execution was finished with the Banking System. Null if still processing or not in Approved approval status
refReceiver	string	The reference receiver provided in the request.
refBankAccount	string	The reference bank account provided in the request.
refTransaction	string	The banking transaction id, the one to be found in the Sales list.
referencesInfo.receiverName	string	The company (receiver) fantasy name.
referencesInfo.customerName	string	The merchant (requestor) name.

Detailing a Company Payment

Reference Endpoint

GET /partners-int/accounts/transaction-requests/{tdId}

This endpoint allows you to detail a specific transaction request based on the trId, the transaction request id.

The Request Params (Useful Example)

/partners-int/accounts/transaction-requests/b35967b8-1d11-4612-9394-7c076b49ea48

Path Param	Type	Required	Description
trId	string	true	The transaction request id as returned when creating a payment request.

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
            }
        ]
    }
}

Field Name	Type	Description
entity	string	The request entity object
entity.id	string	The payment request id.
entity.amount	string	The payment value.
entity.status	string	The approval status as one of: Pending, Approved or Rejected.
entity.pixKey	string	The PIX key, the CNPJ provided in the request
entity.pixKeyType	string	The PIX key type, in this case CNPJ.
entity.description	string	The description provided in the request.
entity.refReceiver	string	The reference receiver provided in the request.
entity.refBankAccount	string	The reference bank account provided in the request.
entity.refTransaction	string	The banking transaction id, the one to be found in the Sales list.
entity.referencesInfo.receiverName	string	The company (receiver) fantasy name.
entity.referencesInfo.customerName	string	The merchant (requestor) name.
executionState	string	The execution state of this transaction, after its approval.
executionCreatedDate	string	The timestamp when this request execution was initiated.
executionRegisteredDate	string	The timestamp when this request execution was registered with the Banking System. Null if not in Approved approval status.
executionCompletedDate	string	The timestamp when this request execution was finished with the Banking System. Null if still processing or not in Approved approval status
flows	string	The approval flow objects, detailing the approval steps status.
flow.id	string	The flow step id.
flow.date	string	When the step was started.
flow.userFullName	string	The user who started the approval step.
flow.userRealm	string	Partner, because the request starts from you, a business Partner
status	string	The approval status of a flow step.
comment	string	The approval comment of a flow step.

Listing Documents

Reference Endpoint

GET /partners-int/documents

This endpoint allows you to list the documents for a given transaction request, informed as the owner.

The Request Payload (Useful Example)

partners-int/documents?type=Invoice&ownerType=Transaction&owner=f8c4f1c9-7366-4330-8f77-63b8a73884a8

Field Name	Type	Required	Description
ownerType	string	true	Transaction, as mandatory string.
type	string	true	Invoice, as mandatory string.
owner	string	true	The transaction request id

The Request Response (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"
            }
        ]
    }
}

Deleting Company Payment Documents

Reference Endpoint

DELETE /partners-int/documents/{documentId}

This endpoint allows you to delete an uploaded document.

The Request Payload (Useful Example)

partners-int/documents/0b2968ef-6104-4468-bb60-0fc91f5efd95

Field Name	Type	Required	Description
documentId	string	true	The document id, as provided in the documents listing.

The Request Response (200 - OK)

{
    "statusCode": "Done"
}