Pixup

https://pixup.readme.io/reference
Admin
Pixup is a payment API platform that enables PIX transactions, QR code generation, and webhook event...
Tokens:5,929
Snippets:22
Trust Score:9.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example JSON Error Response

Source: https://pixup.readme.io/reference/responses

This snippet demonstrates a typical JSON structure for an error response from the Pixup API. It includes a status code and a descriptive message indicating the nature of the error, such as invalid credentials.

```json
{
	"statusCode": 401,
	"message": "Credenciais Invalidas"
}
```

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

### HTTP Response Codes Overview

Source: https://pixup.readme.io/reference/responses

This section details the common HTTP status codes returned by the API, categorized into success, client errors, and server errors, along with their meanings and example use cases.

```APIDOC
## HTTP Response Codes Overview

### Description
This API uses standard HTTP response codes to communicate the result of a request. Codes are categorized into success (2xx), client errors (4xx), and server errors (5xx).

### Success Codes (2xx)

| Code | Description  | Example Use Cases                                                  |
| :----- | :--------- | :-------------------------------------------------------------- |
| 200    | OK         | The request was successful.                                 |
| 201    | Created    | A new resource was successfully created.                         |
| 204    | No Content | The request was successful, but there is no content to return. |

### Client Error Codes (4xx)

| Code | Description            | Example Use Cases                                                                     |
| :----- | :------------------- | :--------------------------------------------------------------------------------- |
| 400    | Bad Request          | A required parameter was omitted.                                              |
| 401    | Unauthorized         | Authentication failed or was not provided.                                        |
| 403    | Forbidden            | The user does not have permission to access the resource.                                |
| 404    | Not Found            | The requested resource could not be found.                                           |
| 422    | Unprocessable Entity | The request is well-formed but cannot be processed (e.g., invalid data). |

### Server Error Codes (5xx)

| Code | Description             | Example Use Cases                                                   |
| :----- | :-------------------- | :--------------------------------------------------------------- |
| 500    | Internal Server Error | An unexpected error occurred on the server.                          |
| 502    | Bad Gateway           | The server acting as a gateway received an invalid response. |
| 503    | Service Unavailable   | The service is temporarily unavailable.                     |

### Important Notes

*   **Detailed Error Messages:** Whenever possible, the API will return a detailed error message in the response body to indicate the cause of the problem.
*   **Server Status Check:** In case of a 5xx error, it is recommended to check the Bspay server status page for more information.

### Example Error Response

```json
{
	"statusCode": 401,
	"message": "Invalid Credentials"
}
```
```

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

### Authentication

Source: https://pixup.readme.io/reference/index

All requests require an access token in the request header. This section details how to generate credentials and the access token.

```APIDOC
## Authentication

### Description
Accessing the API requires an access token provided in the request header. This documentation guides you through generating the necessary credentials and obtaining the access token.

### Method
N/A (This is a conceptual guide, not a specific endpoint)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Generating Production Credentials

### Description
To generate an access token, you need your production credentials (client_id / client_secret). Obtain these by navigating to the API->Credentials menu.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A

## Obtaining Sandbox Access Credentials

### Description
To obtain your sandbox credentials, simply request them from our support team via your account manager.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
N/A
```

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

### POST /v2/pix/qrcode

Source: https://pixup.readme.io/reference/create-qrcode

Generates a PIX QR code for a given transaction amount and details.

```APIDOC
## POST /v2/pix/qrcode

### Description
Generates a PIX QR code for a given transaction amount and details. This endpoint is used to create a new PIX payment request.

### Method
POST

### Endpoint
https://api.pixupbr.com/v2/pix/qrcode

### Parameters
#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - Valor da transação
- **external_id** (string) - Optional - ID externo da transação gerado por você
- **postbackUrl** (string) - Optional - URL de webhook para receber as informações sobre o pagamento.
- **payerQuestion** (string) - Optional - Descrição referente a transação
- **payer** (object) - Optional - Este objeto representa o pagador.
  - **name** (string) - Optional - Nome completo do cliente ou nome comercial.
  - **document** (string) - Optional - O número de identificação fiscal do cliente (CPF para clientes individuais ou CNPJ para clientes empresariais)
  - **email** (string) - Optional - E-mail pessoal do cliente ou e-mail comercial

### Request Example
```json
{
  "amount": 15,
  "external_id": "your_external_id",
  "postbackUrl": "https://your.webhook.url/pix",
  "payerQuestion": "Payment for order #123",
  "payer": {
    "name": "John Doe",
    "document": "12345678900",
    "email": "john.doe@example.com"
  }
}
```

### Response
#### Success Response (200)
- **transactionId** (string) - The unique identifier for the transaction.
- **external_id** (string) - The external ID provided in the request.
- **status** (string) - The current status of the transaction (e.g., "PENDING").
- **amount** (integer) - The transaction amount.
- **calendar** (object) - Information about the transaction's calendar.
  - **expiration** (integer) - The expiration time in seconds.
  - **dueDate** (string) - The due date for the payment.
- **debtor** (object) - Information about the debtor.
  - **name** (string) - The name of the debtor.
  - **document** (string) - The document number of the debtor.
- **qrcode** (string) - The generated PIX QR code string.

#### Response Example
```json
{
  "transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
  "external_id": "",
  "status": "PENDING",
  "amount": 15,
  "calendar": {
    "expiration": 3000,
    "dueDate": "2024-10-07 04:41:05"
  },
  "debtor": {
    "name": "Monkey D. Luffy",
    "document": "12924586666"
  },
  "qrcode": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br\/qr\/v3\/at\/6ed39bf2-bdc2-42b8-a95b-13d2212146b25204000053039865802BR5925BS PAYMENTS SOLUTIONS LTD6008SALVADOR62070503***63048D9B"
}
```
```

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

### Modelo JSON do Payload do Evento de Pagamento

Source: https://pixup.readme.io/reference/evento-de-pagamento

Este é o modelo JSON do payload que será enviado via Webhook quando um pagamento (cash-in) for confirmado. Ele contém detalhes da transação, como tipo, ID, valor, status, datas e informações das partes envolvidas.

```json
{
    "requestBody": {
        "transactionType": "RECEIVEPIX",
        "transactionId": "c327ce8bee2a18565ec2m1zdu6px2keu",
        "external_id": "55aefd02e54e785fbb5a80faa19f8802",
        "amount": 15.00,
        "paymentType": "PIX",
        "status": "PAID",
        "dateApproval": "2024-10-07 16:07:10",
        "creditParty": {
            "name": "Monkey D. Luffy",
            "email": "monkeydluffy@gmail.com",
            "taxId": "999999999"
        },
        "debitParty": {
            "bank": "BSPAY SOLUCOES DE PAGAMENTOS LTDA",
            "taxId": "46872831000154"
        }
    }
}
```

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

### Gerar Cabeçalho de Autenticação Basic Auth

Source: https://pixup.readme.io/reference/criar-token-de-acesso

Gera o cabeçalho de autorização 'Authorization: Basic <base64_credentials>' concatenando client_id e client_secret com ':', codificando em base64 e prefixando com 'Basic '.

```php
// Defina o client_id e client_secret
$client_id = "usuarioteste_63c4ff6423765as";
$client_secret = "1759dd06464041b182f2a18abae597a";

// Concatene o client_id e client_secret com o símbolo ':'
$credentials = $client_id . ':' . $client_secret;

// Codifique a string resultante em base64
$base64_credentials = base64_encode($credentials);

// Crie o header de autenticação
$authorization_header = "Authorization: Basic " . $base64_credentials;

// Exiba o header para verificar o resultado
echo $authorization_header;
```

```javascript
// Defina o client_id e client_secret
const clientId = "usuarioteste_63c4ff6423765as";
const clientSecret = "1759dd06464041b182f2a18abae597a";

// Concatene o client_id e client_secret com o símbolo ':'
const credentials = `${clientId}:${clientSecret}`;

// Codifique a string resultante em Base64
const base64Credentials = btoa(credentials);

// Crie o header de autenticação
const authorizationHeader = `Authorization: Basic ${base64Credentials}`;

// Exiba o header para verificar o resultado
console.log(authorizationHeader);
```

```node
// Defina o client_id e client_secret
const clientId = "usuarioteste_63c4ff6423765as";
const clientSecret = "1759dd06464041b182f2a18abae597a";

// Concatene o client_id e client_secret com o símbolo ':'
const credentials = `${clientId}:${clientSecret}`;

// Codifique a string resultante em Base64 usando Buffer
const base64Credentials = Buffer.from(credentials).toString('base64');

// Crie o header de autenticação
const authorizationHeader = `Authorization: Basic ${base64Credentials}`;

// Exiba o header para verificar o resultado
console.log(authorizationHeader);
```

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

### Generate PIX QR Code OpenAPI Definition

Source: https://pixup.readme.io/reference/create-qrcode

This snippet defines the OpenAPI 3.1.0 specification for the PIX API's QR code generation endpoint. It details the request body schema, including required fields like 'amount' and optional fields such as 'external_id', 'postbackUrl', 'payerQuestion', and 'payer' details. The response schema outlines the structure of a successful QR code generation, including 'transactionId', 'status', 'amount', 'calendar' information, 'debtor' details, and the 'qrcode' string.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "PIX",
    "version": "2"
  },
  "servers": [
    {
      "url": "https://api.pixupbr.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/pix/qrcode": {
      "post": {
        "summary": "Gerar QRCode",
        "description": "",
        "operationId": "create-qrcode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "description": "Valor da transação",
                    "format": "float"
                  },
                  "external_id": {
                    "type": "string",
                    "description": "ID externo da transação gerado por você"
                  },
                  "postbackUrl": {
                    "type": "string",
                    "description": "URL de webhook para receber as informações sobre o pagamento."
                  },
                  "payerQuestion": {
                    "type": "string",
                    "description": "Descrição referente a transação"
                  },
                  "payer": {
                    "type": "object",
                    "description": "Este objeto representa o pagador.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Nome completo do cliente ou nome comercial."
                      },
                      "document": {
                        "type": "string",
                        "description": "O número de identificação fiscal do cliente (CPF para clientes individuais ou CNPJ para clientes empresariais)"
                      },
                      "email": {
                        "type": "string",
                        "description": "E-mail pessoal do cliente ou e-mail comercial"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"transactionId\": \"4392d1d7e408d3cec04fm1zf3gv7vkq1\",\n    \"external_id\": \"\",\n    \"status\": \"PENDING\",\n    \"amount\": 15,\n    \"calendar\": {\n        \"expiration\": 3000,\n        \"dueDate\": \"2024-10-07 04:41:05\"\n    },\n    \"debtor\": {\n        \"name\": \"Monkey D. Luffy\",\n        \"document\": \"12924586666\"\n    },\n    \"qrcode\": \"00020126850014br.gov.bcb.pix2563pix.voluti.com.br\\/qr\\/v3\\/at\\/6ed39bf2-bdc2-42b8-a95b-13d2212146b25204000053039865802BR5925BS PAYMENTS SOLUTIONS LTD6008SALVADOR62070503***63048D9B\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "transactionId": {
                      "type": "string",
                      "example": "4392d1d7e408d3cec04fm1zf3gv7vkq1"
                    },
                    "external_id": {
                      "type": "string",
                      "example": ""
                    },
                    "status": {
                      "type": "string",
                      "example": "PENDING"
                    },
                    "amount": {
                      "type": "integer",
                      "example": 15,
                      "default": 0
                    },
                    "calendar": {
                      "type": "object",
                      "properties": {
                        "expiration": {
                          "type": "integer",
                          "example": 3000,
                          "default": 0
                        },
                        "dueDate": {
                          "type": "string",
                          "example": "2024-10-07 04:41:05"
                        }
                      }
                    },
                    "debtor": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "example": "Monkey D. Luffy"
                        },
                        "document": {
                          "type": "string",
                          "example": "12924586666"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### Distribute Transaction Value with Split Object (JSON)

Source: https://pixup.readme.io/reference/split-object

This snippet demonstrates how to include the 'split' object in the payload for generating a QR Code. The 'split' object is an array of objects, where each object specifies a 'username' and the 'percentageSplit' for that user. This allows for automatic and instant redirection of transaction value to other accounts. Note that the minimum percentage split is 0.1% and the total sum of all splits cannot exceed 95%.

```json
{
    "amount": 15,
    "external_id": "",
    "payerQuestion": "",
    "payer": {
        "name": "Monkey D. Luffy",
        "document": "",
        "email": ""
    },
    "postbackUrl": "", 
    "split": [
        {
            "username": "usertest",
            "percentageSplit": "10" 
        },
        {
            "username": "usertest2",
            "percentageSplit": "5"
        }
    ]
}
```

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

### POST /v2/pix/payment

Source: https://pixup.readme.io/reference/fazer-um-pagamento

Initiates a PIX payment transaction. Requires payment amount and recipient details.

```APIDOC
## POST /v2/pix/payment

### Description
Initiates a PIX payment transaction. Requires payment amount and recipient details.

### Method
POST

### Endpoint
https://api.pixupbr.com/v2/pix/payment

### Parameters
#### Request Body
- **amount** (number) - Required - Valor da transação
- **description** (string) - Optional - Descrição referente a transação
- **external_id** (string) - Optional - ID externo da transação gerado por você
- **creditParty** (object) - Required - Este objeto representa o destinatário.
  - **name** (string) - Required - Nome completo do cliente ou nome comercial que pertence a chave.
  - **keyType** (string) - Required - Tipo de chave pix relatado no sumário
  - **key** (string) - Required - A chave PIX da conta bancária de destino
  - **taxId** (string) - Required - O número de identificação fiscal do cliente (CPF para clientes individuais ou CNPJ para clientes empresariais)

### Request Example
```json
{
  "amount": 100.50,
  "description": "Pagamento de serviço",
  "external_id": "unique-transaction-id-123",
  "creditParty": {
    "name": "Nome do Destinatário",
    "keyType": "CPF",
    "key": "12345678900",
    "taxId": "12345678900"
  }
}
```

### Response
#### Success Response (200)
- **(empty object)** - Description: Indicates a successful transaction. The specific response body might be an empty object or contain transaction details depending on the implementation.

#### Error Response (400)
- **(empty object)** - Description: Indicates a bad request, likely due to missing or invalid parameters.
```

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

### PIX API OpenAPI Definition (JSON)

Source: https://pixup.readme.io/reference/fazer-um-pagamento

The OpenAPI 3.1.0 definition for the PIX API. It details the '/v2/pix/payment' endpoint for initiating payments, including request body schema, response structures, and authentication methods.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "PIX",
    "version": "2"
  },
  "servers": [
    {
      "url": "https://api.pixupbr.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "Authorization",
        "x-bearer-format": "bearer"
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v2/pix/payment": {
      "post": {
        "summary": "Fazer um pagamento",
        "description": "",
        "operationId": "fazer-um-pagamento",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "amount",
                  "creditParty"
                ],
                "properties": {
                  "amount": {
                    "type": "number",
                    "description": "Valor da transação",
                    "format": "float"
                  },
                  "description": {
                    "type": "string",
                    "description": "Descrição referente a transação"
                  },
                  "external_id": {
                    "type": "string",
                    "description": "ID externo da transação gerado por você"
                  },
                  "creditParty": {
                    "type": "object",
                    "description": "Este objeto representa o destinatário.",
                    "properties": {
                      "name": {
                        "type": "string",
                        "description": "Nome completo do cliente ou nome comercial que pertence a chave."
                      },
                      "keyType": {
                        "type": "string",
                        "description": "Tipo de chave pix relatado no sumário"
                      },
                      "key": {
                        "type": "string",
                        "description": "A chave PIX da conta bancária de destino"
                      },
                      "taxId": {
                        "type": "string",
                        "description": "O número de identificação fiscal do cliente (CPF para clientes individuais ou CNPJ para clientes empresariais)"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true,
  "_id": "67084d150b8f11001128aec2:67084d150b8f11001128aebc"
}
```

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

### Webhook Payload para Evento de Transferência (JSON)

Source: https://pixup.readme.io/reference/evento-de-transfer%C3%AAncia-cash-out

Este snippet JSON representa o payload enviado por um Webhook quando um evento de transferência (cash-out) é confirmado. Inclui detalhes da transação como tipo, ID, valor, data de aprovação e status.

```json
{
  "requestBody": {
    "transactionType": "PAYMENT",
    "transactionId": "c327ce8bee2a18565ec2m1zdu6px2keu",
    "external_id": "55aefd02e54e785fbb5a80faa19f8802",
    "amount": 15.00,
    "dateApproval": "2024-10-07 16:10:07",
    "statusCode": {
      "statusId": 1,
      "description": "Pagamento aprovado"
    }
  }
}
```
Tokens:
Raw