Pagloop Payment API

https://pagloop.tech/docs
Admin
The Pagloop Payment API facilitates integration with its payment and withdrawal system using PIX,...
Tokens:7,077
Snippets:45
Trust Score:4.2
Update:9 months ago
Show doc for...
Tokens:
Raw
### Recommended MED Webhook Logging Implementation

Source: https://pagloop.tech/docs/index

An example of a robust logging structure for MED webhooks, capturing essential details for auditing, debugging, and regulatory compliance. Recommended for all MED webhook processing.

```json
// Exemplo de log recomendado
{
  "timestamp": "2024-02-20T15:30:22Z",
  "webhook_type": "MED",
  "transaction_id": "id_da_transacao",
  "status": "RETIDO",
  "source_ip": "192.168.1.1",
  "processed_at": "2024-02-20T15:30:23Z",
  "processing_status": "SUCCESS"
}
```

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

### Get Balance API

Source: https://pagloop.tech/docs/index

Retrieves the available and pending balance of the user's account. It's recommended to synchronize balances periodically and cache them when possible, considering rate limits.

```APIDOC
## GET /api/balance/getBalance

### Description
Retrieves the available and pending balance of the user's account.

### Method
GET

### Endpoint
`/api/balance/getBalance`

### Parameters
No parameters are required for this endpoint.

### Request Example
Not applicable for GET requests without a body.

### Response
#### Success Response (200)
- **balance** (string) - The available balance.

#### Response Example
```json
{
  "balance": "334.80"
}
```
```

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

### Get Account Balance (API)

Source: https://pagloop.tech/docs/index

Fetches the available and pending balance for the authenticated user. It's recommended to synchronize balances periodically and consider rate limits when querying frequently.

```curl
curl -X GET https://api.pagloop.tech/api/balance/getBalance \
  -H "Authorization: Bearer seu_token"
```

```json
{
  "balance":"334.80"
}
```

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

### Get Transaction Status API

Source: https://pagloop.tech/docs/index

Retrieves the current status of a deposit transaction using its unique transaction ID. This endpoint is designed for real-time status checks and only supports deposit transactions.

```APIDOC
## GET /api/transactions/getStatusTransac/:transaction_id

### Description
Retrieves the current status of a deposit transaction.

### Method
GET

### Endpoint
`/api/transactions/getStatusTransac/:transaction_id`

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The unique identifier for the transaction.

### Request Example
Not applicable for GET requests without a body.

### Response
#### Success Response (200)
- **status** (string) - The current status of the transaction. Possible values: PENDING, COMPLETED, FAILED, RETIDO.

#### Response Example
```json
{
  "status": "COMPLETED"
}
```

#### Error Responses
- **404 Not Found**: Transaction not found.
  ```json
  {
    "error": "Transação não encontrada"
  }
  ```
- **500 Internal Server Error**: An error occurred while fetching the transaction.
  ```json
  {
    "error": "Erro ao buscar transação"
  }
  ```
```

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

### Get Deposit Transaction Status (API)

Source: https://pagloop.tech/docs/index

Retrieves the current real-time status of a deposit transaction using its unique transaction ID. Requires authentication. Returns PENDING, COMPLETED, or FAILED status.

```curl
curl -X GET https://api.pagloop.tech/api/transactions/getStatusTransac/TRANSACTION_ID_AQUI \
  -H "Authorization: Bearer seu_token"
```

```json
{
  "status": "PENDING" // Possíveis: PENDING | COMPLETED | FAILED | RETIDO
}
```

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

### PIX Deposit API

Source: https://pagloop.tech/docs/index

Creates a PIX deposit and generates a QR Code for payment. Ensures idempotency via `external_id` and sends automatic status update callbacks.

```APIDOC
## POST /api/payments/deposit

### Description
Creates a PIX deposit and generates a QR Code for payment. The system ensures idempotency through `external_id` and sends automatic callbacks about transaction status changes.

### Method
POST

### Endpoint
`https://api.pagloop.tech/api/payments/deposit`

### Parameters
#### Request Body
- **amount** (number) - Required - The deposit amount.
- **external_id** (string) - Required - Unique external transaction ID for idempotent control.
- **clientCallbackUrl** (string) - Required - URL to receive deposit status notifications.
- **payer** (object) - Required - Payer information.
  - **payer.name** (string) - Required - Payer's full name.
  - **payer.document** (string) - Required - Payer's CPF/CNPJ.
  - **payer.email** (string) - Required - Payer's email.
  - **payer.phone** (string) - Optional - Payer's phone number.

### Request Example
```json
{
  "amount": 100.00,
  "external_id": "id_unico_12345",
  "clientCallbackUrl": "https://seuservidor.com/callback",
  "payer": {
    "name": "João da Silva",
    "email": "joao@example.com",
    "document": "12345678901"
  }
}
```

### Response
*(Success response details for deposit creation are not provided in the input text, but would typically include a transaction ID, QR Code data, and status.)*

#### Success Response (201 - Created - Expected)
*(Details would be provided here if available)*

#### Response Example
*(Example response would be provided here if available)*

#### Error Responses
*(Potential error responses for deposit creation are not detailed in the input text, but could include validation errors, authentication failures, etc.)*
```

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

### POST /api/deposits/deposit

Source: https://pagloop.tech/docs/index

Initiates a deposit process by creating a new deposit record and providing a QR code for payment. It handles various payment gateways and ensures idempotency.

```APIDOC
## POST /api/deposits/deposit

### Description
This endpoint initiates a deposit, creating a new deposit record and returning a QR code for payment. It supports multiple payment gateways and ensures idempotency through an external ID.

### Method
POST

### Endpoint
/api/deposits/deposit

### Parameters
#### Query Parameters
- **amount** (number) - Required - The amount to be deposited.
- **external_id** (string) - Required - A unique identifier for the transaction to ensure idempotency.
- **clientCallbackUrl** (string) - Required - The URL to receive asynchronous status updates (callbacks).
- **payer** (object) - Required - Information about the payer. (Details not provided in the source text, assuming it's an object).

### Request Example
```json
{
  "amount": 100.50,
  "external_id": "unique_deposit_id_123",
  "clientCallbackUrl": "https://your.server.com/callback",
  "payer": {
    "name": "John Doe",
    "document": "12345678900"
  }
}
```

### Response
#### Success Response (201)
- **message** (string) - Confirmation message indicating successful deposit creation.
- **qrCodeResponse** (object) - Object containing details related to the generated QR code.
  - **transactionId** (string) - Unique ID of the transaction in the gateway.
  - **status** (string) - Initial status of the deposit (always "PENDING").
  - **qrcode** (string) - The PIX code for payment.
  - **amount** (number) - The confirmed deposit amount.

#### Response Example
```json
{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "abc123def456",
    "status": "PENDING",
    "qrcode": "00020126580014BR.GOV.BCB.PIX...",
    "amount": 100.50
  }
}
```

#### Error Responses
- **400 Bad Request**: Missing required fields (amount, external_id, clientCallbackUrl, payer) or unsupported gateway configuration.
- **401 Unauthorized**: Access token is missing or invalid.
- **403 Forbidden**: Token is expired or invalid.
- **404 Not Found**: Authenticated user not found in the database.
- **500 Internal Server Error**: Default gateway not configured, failure to generate Transaction ID, or other unexpected server errors.
```

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

### Error Handling Reference

Source: https://pagloop.tech/docs/index

This section outlines the standard HTTP status codes returned by the API to indicate the success or failure of an operation, along with common reasons for each error.

```APIDOC
## Error Handling Reference

### Description
This section outlines the standard HTTP status codes returned by the API to indicate the success or failure of an operation, along with common reasons for each error.

### Method
N/A (This is a reference, not an endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Common Error Status Codes
- **400 Bad Request** - Invalid data or missing required fields.
- **401 Unauthorized** - Invalid credentials or JWT token not sent.
- **403 Forbidden** - Access denied (unauthorized IP or banned account).
- **404 Not Found** - Resource not found.
- **500 Internal Server Error** - Server-side error.
```

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

### User Authentication API

Source: https://pagloop.tech/docs/index

Authenticates a user using client credentials and returns a JWT token valid for 1 hour for accessing protected API routes.

```APIDOC
## POST /api/auth/login

### Description
Authenticates a user using client credentials (client_id and client_secret) and returns a JWT token valid for 1 hour.

### Method
POST

### Endpoint
`https://api.pagloop.tech/api/auth/login`

### Parameters
#### Request Body
- **client_id** (string) - Required - The unique client ID provided by the system.
- **client_secret** (string) - Required - The client secret key provided by the system.

### Request Example
```json
{
  "client_id": "seu_cliente_id",
  "client_secret": "seu_cliente_secreto"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the login.
- **token** (string) - JWT token valid for 1 hour for authentication.
- **user** (object) - User information.
  - **user.id** (number) - Unique user ID in the system.
  - **user.name** (string) - User's full name.
  - **user.email** (string) - User's email.
  - **user.client_id** (string) - User's Client ID (confirmation).

#### Response Example
```json
{
  "message": "Authentication successful.",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 123,
    "name": "João Silva",
    "email": "joao@email.com",
    "client_id": "your_client_id_here"
  }
}
```

#### Error Responses
- **400 - Bad Request**: `"client_id and client_secret are required."` (Missing required fields)
- **401 - Unauthorized**: `"Invalid client_id or client_secret."` (Invalid credentials)
- **403 - Forbidden**: `"User account is banned."` (User account banned)
- **403 - Forbidden**: `"API keys (client_id or client_secret) are not configured for this user."` (API keys not configured)
- **500 - Internal Server Error**: `"Detailed error message"` (Internal server error)

#### How to Use the Token
Include the obtained token in the `Authorization` header as a Bearer token for subsequent requests:
```
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```
```

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

### Webhooks

Source: https://pagloop.tech/docs/index

Webhooks allow your system to receive real-time notifications about changes in the status of deposit and withdrawal transactions. Configure a callback URL to receive these updates.

```APIDOC
## Webhooks

### Description
Webhooks provide real-time notifications for transaction status changes (deposits and withdrawals) and MED (Medida Cautelar) events.

#### Callback of Deposit
This payload is sent upon changes to deposit transaction status.
```json
{
  "transaction_id": "id_da_transacao",
  "status": "COMPLETED",
  "amount": 100.00,
  "fee": -1.05,
  "net_amout": 98.95
}
```

#### Callback of Withdrawal
This payload is sent upon changes to withdrawal transaction status.
```json
{
  "transaction_id": "transaction-67890",
  "status": "COMPLETED",
  "amount": 50.00,
  "fee": -1.05,
  "ispb": 123456,
  "nome_recebedor": "Fulano Silva",
  "cpf_recebedor": "***212.43*-**"
}
```

#### Webhook of MED (Medida Cautelar)
This POST request is sent to your configured callback URL when a transaction is subjected to a precautionary blocking measure.
```json
{
  "transaction_id": "id_da_transacao",
  "status": "RETIDO"
}
```

##### Technical Recommendation
Implement robust logging for all received MED webhooks, including timestamp, source IP, full payload, and processing status, for auditing and compliance purposes.
```

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

### Autenticar Usuário - API Pagloop (cURL)

Source: https://pagloop.tech/docs/index

Autentica um usuário na API Pagloop usando client_id e client_secret para obter um token JWT. Este token é necessário para acessar outros endpoints protegidos e é válido por 1 hora. As credenciais são enviadas no corpo da requisição POST.

```curl
curl -X POST https://api.pagloop.tech/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "seu_cliente_id",
    "client_secret": "seu_cliente_secreto"
  }'
```

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

### Criar Depósito PIX - API Pagloop (cURL)

Source: https://pagloop.tech/docs/index

Cria um novo depósito PIX através da API Pagloop, gerando um QR Code para pagamento. A requisição inclui o valor, um ID externo para idempotência, a URL de callback para notificações e informações do pagador. Requer um token JWT válido no cabeçalho Authorization.

```curl
curl -X POST https://api.pagloop.tech/api/payments/deposit \
  -H "Authorization: Bearer seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "external_id": "id_unico_12345",
    "clientCallbackUrl": "https://seuservidor.com/callback",
    "payer": {
      "name": "João da Silva",
      "email": "joao@example.com",
      "document": "12345678901"
    }
  }'
```

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

### Deposit Callback Format JSON

Source: https://pagloop.tech/docs/index

This JSON structure outlines the format of the automatic callbacks sent after a deposit is created. It provides transaction details and the current status.

```json
{
  "transaction_id": "abc123def456",
  "status": "PENDING",
  "amount": 100.50,
  "type": "Deposit"
}
```

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

### Adicionar Token de Autenticação a Requisições - API Pagloop

Source: https://pagloop.tech/docs/index

Demonstra como incluir o token JWT obtido na autenticação no cabeçalho 'Authorization' de requisições subsequentes à API Pagloop. O formato esperado é 'Bearer [seu_token]'.

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

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

### Withdrawal Request cURL

Source: https://pagloop.tech/docs/index

This cURL command demonstrates how to make a withdrawal request via the Pagloop API. It includes all required parameters for initiating a PIX withdrawal.

```curl
curl -X POST https://api.pagloop.tech/api/withdrawals/withdraw \
  -H "Authorization: Bearer seu_token" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "external_id": "external-12345",
    "pix_key": "exemplo@pix.com",
    "key_type": "EMAIL",
    "description": "Saque referente ao pedido #123",
    "clientCallbackUrl": "https://seuservidor.com/callback"
  }'
```

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

### POST /api/withdrawals/withdraw

Source: https://pagloop.tech/docs/index

Initiates a withdrawal request using PIX keys. This endpoint performs automatic balance and authentication checks, ensuring idempotency with an external ID.

```APIDOC
## POST /api/withdrawals/withdraw

### Description
This endpoint allows withdrawal requests using PIX keys. The system performs automatic balance and authentication checks, ensuring idempotency through the `external_id`.

### Method
POST

### Endpoint
/api/withdrawals/withdraw

### Authentication
Requires Authentication. An `Authorization: Bearer seu_token` header is needed.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The withdrawal amount.
- **external_id** (string) - Required - Unique external ID for idempotent control.
- **pix_key** (string) - Required - The recipient's PIX key.
- **key_type** (string) - Required - Type of the PIX key: CPF, CNPJ, EMAIL, PHONE, RANDOM.
- **clientCallbackUrl** (string) - Required - URL for withdrawal status callbacks.
- **description** (string) - Optional - Description of the transaction.

### Request Example
```json
{
  "amount": 50.00,
  "external_id": "external-12345",
  "pix_key": "exemplo@pix.com",
  "key_type": "EMAIL",
  "description": "Saque referente ao pedido #123",
  "clientCallbackUrl": "https://seuservidor.com/callback"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message for successful withdrawal processing.
- **withdrawal** (object) - Object containing details of the withdrawal.
  - **transaction_id** (string) - Unique ID of the transaction.
  - **status** (string) - Status of the withdrawal: PENDING, COMPLETED, FAILED.
  - **amount** (number) - The requested withdrawal amount.
  - **fee** (number) - The fee charged for the withdrawal.

#### Response Example
```json
{
  "message": "Withdrawal processed successfully.",
  "withdrawal": {
    "transaction_id": "abc123def456",
    "status": "COMPLETED",
    "amount": 100.50,
    "fee": 3.25
  }
}
```

#### Withdrawal Statuses
- **PENDING**: Withdrawal created, awaiting processing.
- **COMPLETED**: Withdrawal approved and processed successfully.
- **FAILED**: Withdrawal rejected or failed during processing.

#### Important Note
Monitor status changes via callbacks sent to the configured `clientCallbackUrl`.

#### Possible Errors
(Specific error codes and messages for withdrawals are not detailed in the provided text, but would typically include issues like insufficient balance, invalid PIX key, authentication failures, etc.)
```

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

### Deposit Success Response (201) JSON

Source: https://pagloop.tech/docs/index

This JSON object represents a successful deposit creation response. It includes a confirmation message and details about the generated QR code for payment.

```json
{
  "message": "Deposit created successfully.",
  "qrCodeResponse": {
    "transactionId": "abc123def456",
    "status": "PENDING",
    "qrcode": "00020126580014BR.GOV.BCB.PIX...",
    "amount": 100.50
  }
}
```

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

### Withdrawal Success Response (200) JSON

Source: https://pagloop.tech/docs/index

This JSON object represents a successful withdrawal request response. It includes a confirmation message and details about the processed withdrawal.

```json
{
  "message": "Withdrawal processed successfully.",
  "withdrawal": {
    "transaction_id": "abc123def456",
    "status": "COMPLETED",
    "amount": 100.50,
    "fee": 3.25
  }
}
```

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

### Deposit Transaction Webhook Notification

Source: https://pagloop.tech/docs/index

A webhook POST request sent to the configured clientCallbackUrl to notify about changes in deposit transaction status. Includes transaction details and the new status.

```json
{
  "transaction_id": "id_da_transacao",
  "status": "COMPLETED",
  "amount": 100.00,
  "fee": -1.05,
  "net_amout": 98.95
}
```

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

### Withdrawal Transaction Webhook Notification

Source: https://pagloop.tech/docs/index

A webhook POST request sent to the configured clientCallbackUrl to notify about changes in withdrawal transaction status. Includes transaction details, financial information, and recipient details.

```json
{
  "transaction_id": "transaction-67890",
  "status": "COMPLETED",
  "amount": 50.00,
  "fee": -1.05,
  "ispb": 123456,
  "nome_recebedor": "Fulano Silva",
  "cpf_recebedor": "***212.43*-**"
}
```

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

### MED (Cautelary Measure) Webhook Notification

Source: https://pagloop.tech/docs/index

A POST webhook sent to the callback URL when a transaction is subjected to a cautionary measure (retention). This notifies about the transaction's hold status for compliance purposes.

```json
{
  "transaction_id": "id_da_transacao",
  "status": "RETIDO"
}
```
Tokens:
Raw