Pagnovo

https://portal.pagnovo.com/docs
Admin
Pagnovo is a fintech API platform for payment processing and financial services, offering PIX...
Tokens:5,918
Snippets:32
Trust Score:4.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Successful Withdrawal Response

Source: https://portal.pagnovo.com/docs/api/get-withdraw

This is an example of a successful response when a withdrawal is found. The `nullable` timestamps indicate the withdrawal's lifecycle events. A `status` of 'INCONSISTENT' requires opening a support ticket.

```json
{
  "id": "withdraw-id-1234",
  "createdAt": "2026-04-08T15:00:00.000Z",
  "approvedAt": "2026-04-08T15:00:12.451Z",
  "rejectedAt": null,
  "returnedAt": null,
  "institution": "ITAÚ UNIBANCO",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "receiverPix": "maria@example.com",
  "totalAmount": 10050,
  "amount": 10000,
  "costTax": 25,
  "costFee": 25,
  "status": "WITHDRAW_APPROVED",
  "externalId": "payout-789",
  "end2End": "E98765432202604081500123456789012",
  "errorMessage": null,
  "voucher": "https://voucher.pagnovo.com/receipt?token=..."
}
```

--------------------------------

### Initiate Cash-out via PIX Key

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

Sends a PIX transfer to the recipient's PIX key. Supports CPF, CNPJ, phone, email, and random keys. The transfer is settled in real time through Bacen's SPI. IP allowlist is required for this endpoint.

```APIDOC
## POST /withdraws/cash-out

### Description
Sends a PIX transfer to the recipient's PIX key. Supports CPF, CNPJ, phone, email, and random keys. The transfer is settled in real time through Bacen's SPI.

### Method
POST

### Endpoint
`/withdraws/cash-out`

### Authentication
HTTP Basic Auth. Send Basic {base64(secret:YOUR_SECRET_KEY)} in the header.

### Parameters
#### Request Body
- **amount** (number) - Required - Withdrawal amount in cents. Minimum 1.
  Example: `10000`
- **pixKey** (string) - Required - The recipient's PIX key. The format depends on `pixType`.
  Example: `maria@example.com`
- **pixType** (string) - Required - Type of the PIX key. Allowed values: 'CPF', 'CNPJ', 'PHONE', 'EMAIL', 'RANDOM'.
  Example: `EMAIL`
- **document** (string) - Optional - Expected CPF/CNPJ of the recipient. If `restrictReceiverDocument` is true, the transfer is only executed when the document returned by DICT matches this value.
  Example: `98765432100`
- **restrictReceiverDocument** (boolean) - Optional - When true, requires the recipient's DICT-resolved CPF/CNPJ to match the `document` field. Default: false.
  Example: `true`
- **externalId** (string) - Optional - Your reference for this withdrawal (payout ID, batch ID, etc). Echoed in webhooks and on `GET /withdraws/collect/:id?searchBy=externalId`.
  Example: `payout-789`
- **postbackUrl** (string) - Optional - Webhook URL for events on this withdrawal. If omitted, the global webhook URL is used.
  Example: `https://your-domain.com/webhook`

### Request Example
```json
{
  "amount": 10000,
  "pixKey": "maria@example.com",
  "pixType": "EMAIL",
  "document": "98765432100",
  "restrictReceiverDocument": true,
  "externalId": "payout-789"
}
```

### Responses
#### Success Response (201)
- **id** (string) - Unique identifier for the withdrawal.
- **externalId** (string) - Your reference for this withdrawal.
- **status** (string) - Initial status of the withdrawal (e.g., `WITHDRAW_REQUEST`).
- **amount** (number) - Withdrawal amount in cents.
- **totalAmount** (number) - Total amount including fees, in cents.
- **institution** (string) - The financial institution of the receiver.
- **receiverPix** (string) - The recipient's PIX key.
- **receiverName** (string) - The recipient's full name.
- **receiverDocument** (string) - The recipient's CPF or CNPJ.
- **postbackUrl** (string) - The webhook URL configured for this withdrawal.
- **createdAt** (string) - Timestamp when the withdrawal was created.

#### Response Example (201)
```json
{
  "id": "withdraw-id-1234",
  "externalId": "payout-789",
  "status": "WITHDRAW_REQUEST",
  "amount": 10000,
  "totalAmount": 10050,
  "institution": "ITAÚ UNIBANCO",
  "receiverPix": "maria@example.com",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "postbackUrl": "https://your-domain.com/webhook",
  "createdAt": "2026-04-08T15:00:00.000Z"
}
```

#### Error Responses
- **400** Invalid body, insufficient balance, IP not allowlisted, or `restrictReceiverDocument: true` mismatch.
  Example: `{"statusCode": 400, "message": "IP unauthorized"}`
- **401** Invalid or missing API key.
  Example: `{"statusCode": 401, "message": "Unauthorized"}`
- **403** API key lacks `createWithdraw` permission.
  Example: `{"statusCode": 403, "message": "You do not have permission to access this resource"}`
```

--------------------------------

### Error Response (403 Forbidden)

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

This response indicates a 403 Forbidden error, meaning the API key lacks the necessary 'createWithdraw' permission.

```json
{
  "statusCode": 403,
  "message": "You do not have permission to access this resource"
}
```

--------------------------------

### Error Response (400 Bad Request)

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

This response indicates a 400 Bad Request error, which could be due to an invalid request body, insufficient balance, IP address not being allowlisted, or a mismatch when `restrictReceiverDocument` is true.

```json
{
  "statusCode": 400,
  "message": "IP unauthorized"
}
```

--------------------------------

### Send PIX Cash-out Request (cURL)

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

Use this cURL command to send a PIX transfer request to a recipient's PIX key. Ensure your API key is properly authenticated with Basic Auth and includes the 'createWithdraw' permission. IP allowlisting is required for this endpoint.

```curl
curl -X POST "https://api.pagnovo.com/withdraws/cash-out" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "pixKey": "maria@example.com",
    "pixType": "EMAIL",
    "document": "98765432100",
    "restrictReceiverDocument": true,
    "externalId": "payout-789"
  }'
```

--------------------------------

### Successful Withdrawal Response

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

This JSON object represents a successful PIX cash-out request acceptance. The initial status is 'WITHDRAW_REQUEST', and the final status will be communicated via webhook.

```json
{
  "id": "withdraw-id-1234",
  "externalId": "payout-789",
  "status": "WITHDRAW_REQUEST",
  "amount": 10000,
  "totalAmount": 10050,
  "institution": "ITAÚ UNIBANCO",
  "receiverPix": "maria@example.com",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "postbackUrl": "https://your-domain.com/webhook",
  "createdAt": "2026-04-08T15:00:00.000Z"
}
```

--------------------------------

### Error Response: Withdrawal Not Found

Source: https://portal.pagnovo.com/docs/api/get-withdraw

This response is returned when the specified withdrawal ID (internal, external, or end-to-end) does not exist in the system.

```json
{
  "statusCode": 404,
  "message": "Withdraw not found"
}
```

--------------------------------

### Error Response (401 Unauthorized)

Source: https://portal.pagnovo.com/docs/api/cashout-pix-key

This response indicates a 401 Unauthorized error, typically due to an invalid or missing API key.

```json
{ "statusCode": 401, "message": "Unauthorized" }
```

--------------------------------

### Lookup Withdrawal by External ID (cURL)

Source: https://portal.pagnovo.com/docs/api/get-withdraw

Use this cURL command to retrieve withdrawal details when you have your own external ID. The `searchBy` parameter must be set to `externalId`. Ensure your secret key is correctly base64 encoded in the Authorization header.

```curl
curl -X GET "https://api.pagnovo.com/withdraws/collect/payout-789?searchBy=externalId" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)"
```

--------------------------------

### Lookup Withdrawal by Internal ID (cURL)

Source: https://portal.pagnovo.com/docs/api/get-withdraw

Use this cURL command to retrieve withdrawal details when you have the internal withdrawal ID. Ensure your secret key is correctly base64 encoded in the Authorization header.

```curl
curl -X GET "https://api.pagnovo.com/withdraws/collect/withdraw-id-1234" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)"
```

--------------------------------

### Lookup Withdrawal by ID

Source: https://portal.pagnovo.com/docs/api/get-withdraw

Retrieves the full state of a withdrawal using its internal ID. This includes status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL.

```APIDOC
## GET /withdraws/collect/:withdrawId

### Description
Returns the full state of a withdrawal: status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL. Look up by internal ID, your `externalId`, or the PIX `end2End`.

### Method
GET

### Endpoint
`/withdraws/collect/:withdrawId`

### Parameters
#### Path Parameters
- **withdrawId** (string) - Required - The lookup value. Internal ID, externalId, or end2End — selected by `searchBy`.

#### Query Parameters
- **searchBy** ('id' | 'externalId' | 'end2End') - Optional - Which field to look up by. Defaults to `id`.

### Request Example
```curl
curl -X GET "https://api.pagnovo.com/withdraws/collect/withdraw-id-1234" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the withdrawal.
- **createdAt** (string) - The timestamp when the withdrawal was created.
- **approvedAt** (string | null) - The timestamp when the withdrawal was approved.
- **rejectedAt** (string | null) - The timestamp when the withdrawal was rejected.
- **returnedAt** (string | null) - The timestamp when the withdrawal bounced back.
- **institution** (string) - The name of the financial institution.
- **receiverName** (string) - The name of the withdrawal recipient.
- **receiverDocument** (string) - The document number of the withdrawal recipient.
- **receiverPix** (string) - The PIX key of the withdrawal recipient.
- **totalAmount** (integer) - The total amount of the withdrawal in cents.
- **amount** (integer) - The net amount of the withdrawal in cents.
- **costTax** (integer) - The tax cost of the withdrawal in cents.
- **costFee** (integer) - The fee cost of the withdrawal in cents.
- **status** (string) - The current status of the withdrawal (e.g., "WITHDRAW_APPROVED").
- **externalId** (string) - Your external identifier for the withdrawal.
- **end2End** (string) - The PIX end-to-end identifier.
- **errorMessage** (string | null) - An error message if the withdrawal failed.
- **voucher** (string) - The URL for the withdrawal voucher.

#### Response Example
```json
{
  "id": "withdraw-id-1234",
  "createdAt": "2026-04-08T15:00:00.000Z",
  "approvedAt": "2026-04-08T15:00:12.451Z",
  "rejectedAt": null,
  "returnedAt": null,
  "institution": "ITAÚ UNIBANCO",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "receiverPix": "maria@example.com",
  "totalAmount": 10050,
  "amount": 10000,
  "costTax": 25,
  "costFee": 25,
  "status": "WITHDRAW_APPROVED",
  "externalId": "payout-789",
  "end2End": "E98765432202604081500123456789012",
  "errorMessage": null,
  "voucher": "https://voucher.pagnovo.com/receipt?token=..."
}
```

#### Error Response (400)
- **statusCode** (integer) - The status code, which will be 400.
- **message** (string) - A message indicating the error, e.g., "Invalid searchBy value".

#### Error Response Example (400)
```json
{
  "statusCode": 400,
  "message": "Invalid searchBy value"
}
```

#### Error Response (404)
- **statusCode** (integer) - The status code, which will be 404.
- **message** (string) - A message indicating the withdrawal was not found.

#### Error Response Example (404)
```json
{
  "statusCode": 404,
  "message": "Withdraw not found"
}
```
```

--------------------------------

### Lookup Withdrawal by PIX End-to-End ID

Source: https://portal.pagnovo.com/docs/api/get-withdraw

Retrieves the full state of a withdrawal using the PIX end-to-end ID. This includes status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL.

```APIDOC
## GET /withdraws/collect/:withdrawId

### Description
Returns the full state of a withdrawal: status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL. Look up by internal ID, your `externalId`, or the PIX `end2End`.

### Method
GET

### Endpoint
`/withdraws/collect/:withdrawId`

### Parameters
#### Path Parameters
- **withdrawId** (string) - Required - The lookup value. Internal ID, externalId, or end2End — selected by `searchBy`.

#### Query Parameters
- **searchBy** ('id' | 'externalId' | 'end2End') - Optional - Which field to look up by. Defaults to `id`.

### Request Example
```curl
curl -X GET "https://api.pagnovo.com/withdraws/collect/E98765432202604081500123456789012?searchBy=end2End" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the withdrawal.
- **createdAt** (string) - The timestamp when the withdrawal was created.
- **approvedAt** (string | null) - The timestamp when the withdrawal was approved.
- **rejectedAt** (string | null) - The timestamp when the withdrawal was rejected.
- **returnedAt** (string | null) - The timestamp when the withdrawal bounced back.
- **institution** (string) - The name of the financial institution.
- **receiverName** (string) - The name of the withdrawal recipient.
- **receiverDocument** (string) - The document number of the withdrawal recipient.
- **receiverPix** (string) - The PIX key of the withdrawal recipient.
- **totalAmount** (integer) - The total amount of the withdrawal in cents.
- **amount** (integer) - The net amount of the withdrawal in cents.
- **costTax** (integer) - The tax cost of the withdrawal in cents.
- **costFee** (integer) - The fee cost of the withdrawal in cents.
- **status** (string) - The current status of the withdrawal (e.g., "WITHDRAW_APPROVED").
- **externalId** (string) - Your external identifier for the withdrawal.
- **end2End** (string) - The PIX end-to-end identifier.
- **errorMessage** (string | null) - An error message if the withdrawal failed.
- **voucher** (string) - The URL for the withdrawal voucher.

#### Response Example
```json
{
  "id": "withdraw-id-1234",
  "createdAt": "2026-04-08T15:00:00.000Z",
  "approvedAt": "2026-04-08T15:00:12.451Z",
  "rejectedAt": null,
  "returnedAt": null,
  "institution": "ITAÚ UNIBANCO",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "receiverPix": "maria@example.com",
  "totalAmount": 10050,
  "amount": 10000,
  "costTax": 25,
  "costFee": 25,
  "status": "WITHDRAW_APPROVED",
  "externalId": "payout-789",
  "end2End": "E98765432202604081500123456789012",
  "errorMessage": null,
  "voucher": "https://voucher.pagnovo.com/receipt?token=..."
}
```

#### Error Response (400)
- **statusCode** (integer) - The status code, which will be 400.
- **message** (string) - A message indicating the error, e.g., "Invalid searchBy value".

#### Error Response Example (400)
```json
{
  "statusCode": 400,
  "message": "Invalid searchBy value"
}
```

#### Error Response (404)
- **statusCode** (integer) - The status code, which will be 404.
- **message** (string) - A message indicating the withdrawal was not found.

#### Error Response Example (404)
```json
{
  "statusCode": 404,
  "message": "Withdraw not found"
}
```
```

--------------------------------

### Lookup Withdrawal by External ID

Source: https://portal.pagnovo.com/docs/api/get-withdraw

Retrieves the full state of a withdrawal using your external ID. This includes status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL.

```APIDOC
## GET /withdraws/collect/:withdrawId

### Description
Returns the full state of a withdrawal: status, timestamps for each lifecycle event, recipient details, costs, and the voucher URL. Look up by internal ID, your `externalId`, or the PIX `end2End`.

### Method
GET

### Endpoint
`/withdraws/collect/:withdrawId`

### Parameters
#### Path Parameters
- **withdrawId** (string) - Required - The lookup value. Internal ID, externalId, or end2End — selected by `searchBy`.

#### Query Parameters
- **searchBy** ('id' | 'externalId' | 'end2End') - Optional - Which field to look up by. Defaults to `id`.

### Request Example
```curl
curl -X GET "https://api.pagnovo.com/withdraws/collect/payout-789?searchBy=externalId" \
  -H "Authorization: Basic $(echo -n 'secret:YOUR_SECRET_KEY' | base64)"
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the withdrawal.
- **createdAt** (string) - The timestamp when the withdrawal was created.
- **approvedAt** (string | null) - The timestamp when the withdrawal was approved.
- **rejectedAt** (string | null) - The timestamp when the withdrawal was rejected.
- **returnedAt** (string | null) - The timestamp when the withdrawal bounced back.
- **institution** (string) - The name of the financial institution.
- **receiverName** (string) - The name of the withdrawal recipient.
- **receiverDocument** (string) - The document number of the withdrawal recipient.
- **receiverPix** (string) - The PIX key of the withdrawal recipient.
- **totalAmount** (integer) - The total amount of the withdrawal in cents.
- **amount** (integer) - The net amount of the withdrawal in cents.
- **costTax** (integer) - The tax cost of the withdrawal in cents.
- **costFee** (integer) - The fee cost of the withdrawal in cents.
- **status** (string) - The current status of the withdrawal (e.g., "WITHDRAW_APPROVED").
- **externalId** (string) - Your external identifier for the withdrawal.
- **end2End** (string) - The PIX end-to-end identifier.
- **errorMessage** (string | null) - An error message if the withdrawal failed.
- **voucher** (string) - The URL for the withdrawal voucher.

#### Response Example
```json
{
  "id": "withdraw-id-1234",
  "createdAt": "2026-04-08T15:00:00.000Z",
  "approvedAt": "2026-04-08T15:00:12.451Z",
  "rejectedAt": null,
  "returnedAt": null,
  "institution": "ITAÚ UNIBANCO",
  "receiverName": "Maria Souza",
  "receiverDocument": "98765432100",
  "receiverPix": "maria@example.com",
  "totalAmount": 10050,
  "amount": 10000,
  "costTax": 25,
  "costFee": 25,
  "status": "WITHDRAW_APPROVED",
  "externalId": "payout-789",
  "end2End": "E98765432202604081500123456789012",
  "errorMessage": null,
  "voucher": "https://voucher.pagnovo.com/receipt?token=..."
}
```

#### Error Response (400)
- **statusCode** (integer) - The status code, which will be 400.
- **message** (string) - A message indicating the error, e.g., "Invalid searchBy value".

#### Error Response Example (400)
```json
{
  "statusCode": 400,
  "message": "Invalid searchBy value"
}
```

#### Error Response (404)
- **statusCode** (integer) - The status code, which will be 404.
- **message** (string) - A message indicating the withdrawal was not found.

#### Error Response Example (404)
```json
{
  "statusCode": 404,
  "message": "Withdraw not found"
}
```
```

--------------------------------

### Error Response: Invalid SearchBy Value

Source: https://portal.pagnovo.com/docs/api/get-withdraw

This response indicates an invalid value was provided for the `searchBy` parameter. Ensure you use one of the allowed values: 'id', 'externalId', or 'end2End'.

```json
{
  "statusCode": 400,
  "message": "Invalid searchBy value"
}
```
Tokens:
Raw