### BSPay API QR Code Generation Response Examples

Source: https://doc.bspay.co/financeiro/gerar-qrcode

Examples of successful and error responses when generating a QR Code via the BSPay API. A successful response (200) includes transaction details, status, and the QR code. An unauthorized response (401) indicates an issue with the API key or authentication.

```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/..."
}
```

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

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

### Example API Error Response (JSON)

Source: https://doc.bspay.co/introducao/respostas-http

This JSON object represents a typical error response from the Bspay API, indicating an unauthorized access attempt due to invalid credentials. It includes a status code and a descriptive error message.

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

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

### Generate Pix QR Code with Postback URL

Source: https://doc.bspay.co/introducao/webhooks

This snippet shows how to generate a Pix QR code using the BS PAY API. It includes creating an order in the database and then making a POST request to the BS PAY API with the order details and a postback URL for payment confirmations.

```javascript
app.post('/payment', async (req, res) => {
  try {
    const order = await Order.create({ ... });

    const response = await axios.post('https://api.bspay.co/v2/pix/qrcode', {
      amount: 100.00,
      external_id: order.id,
      postbackUrl: 'https://yourdomain.com/webhook/callback',     }, {
      headers: {
        Authorization: 'Basic ' + process.env.BSPAY_TOKEN,
        'Content-Type': 'application/json',
      },
    });

    return res.status(200).send('OK');
  }
  catch (err) {
    console.error('Erro ao gerar QR Code:', err);
    return res.status(500).send('Erro ao gerar QR Code');
  }
});

```

```php
use Illuminate\Support\Facades\Route;
use Illuminate\Support\Facades\Http;
use Illuminate\Http\Request;
use App\Models\Order;

Route::post('/payment', function (Request $request) {
    $order = Order::create([
        'user_id' => auth()->user()->id,
        'amount' => 100.00,
        'status' => 'PENDING',
    ]);

    $response = Http::withHeaders([
        'Authorization' => 'Basic ' . env('BSPAY_TOKEN'),
        'Content-Type'  => 'application/json',
    ])->post('https://api.bspay.co/v2/pix/qrcode', [
        'amount'       => 100.00,
        'external_id'  => $order->id,
        'postbackUrl'  => 'https://yourdomain.com/webhook/callback',     ]);

    return [
        'status' => 'OK',
        'qrcode' => $response['qrcode'],
    ];
});

```

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

### POST /v2/pix/payment

Source: https://doc.bspay.co/financeiro/fazer-pagamento

Allows you to make a Pix transfer to a specific key. Requires authentication.

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

### Description
Allows you to make a Pix transfer to a specific key. Requires authentication.

### Method
POST

### Endpoint
https://api.bspay.co/v2/pix/payment

### Parameters
#### Request Body
- **amount** (float) - Required - Transaction amount.
- **description** (string) - Required - Description for the transaction.
- **external_id** (string) - Required - External transaction ID generated by you.
- **creditParty** (object) - Required - This object represents the recipient.
  - **name** (string) - Required - Full name of the customer or business name associated with the key.
  - **keyType** (string) - Required - Type of Pix key reported in the summary.
  - **key** (string) - Required - The Pix key of the destination bank account.
  - **taxId** (string) - Required - The fiscal identification number of the customer (CPF for individual customers or CNPJ for business customers).

### Request Example
```json
{
  "amount": 100.00,
  "description": "Pagamento de teste",
  "external_id": "123456789",
  "creditParty": {
    "name": "João da Silva",
    "keyType": "CPF",
    "key": "12345678909",
    "taxId": "12345678909"
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Transaction status.
- **message** (string) - Transaction message.
- **data** (object) - Transaction details.

#### Response Example
```json
{
  "status": "success",
  "message": "Payment successful",
  "data": {
    "transactionId": "txn_123abc",
    "status": "completed",
    "amount": 100.00
  }
}
```
```

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

### POST /v2/pix/qrcode

Source: https://doc.bspay.co/introducao/webhooks

Allows you to create a Pix QR Code for payment collection. You can specify a postback URL to receive notifications about the payment status.

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

### Description
Allows you to create a Pix QR Code for payment collection. You can specify a postback URL to receive notifications about the payment status. This endpoint is used to generate payment instructions for your customers.

### Method
POST

### Endpoint
/v2/pix/qrcode

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Basic authentication token for API access. Format: 'Basic YOUR_BSPAY_TOKEN'.
- **Content-Type** (string) - Required - Specifies the request body format. Must be 'application/json'.

#### Request Body
- **amount** (number) - Required - The amount for the Pix payment.
- **external_id** (string) - Required - Your unique identifier for the transaction. This ID will be sent back in webhook notifications.
- **postbackUrl** (string) - Required - The URL where BS PAY will send payment status notifications.

### Request Example
```json
{
  "amount": 100.00,
  "external_id": "order_12345",
  "postbackUrl": "https://yourdomain.com/webhook/callback"
}
```

### Response
#### Success Response (200)
- **qrcode** (string) - The generated Pix QR Code data.
- **message** (string) - Confirmation message, e.g., 'OK'.

#### Response Example
```json
{
  "qrcode": "00020126580014br.gov.bcb.pix0114+5561999990000520400005303986540410005802BR5913Nome da Empresa6009Nova Iguaçu62070503***6304B204",
  "message": "OK"
}
```
```

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

### Generate Pix QR Code with BSPay API

Source: https://doc.bspay.co/financeiro/gerar-qrcode

This snippet demonstrates how to generate a Pix QR Code using the BSPay API. It requires authentication and specifies transaction details like amount and a postback URL for payment notifications. The 'split' parameter can be used to distribute transaction amounts to multiple accounts.

```curl
curl --request POST \
  --url https://api.bspay.co/v2/pix/qrcode \
  --header 'Authorization: Bearer [SUA_CHAVE_API]' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data-raw '{ \
    "amount": 100.00, \
    "postbackUrl": "https://example.com/webhook/callback" \
  }'
```

```javascript
fetch('https://api.bspay.co/v2/pix/qrcode', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer [SUA_CHAVE_API]',
    'accept': 'application/json',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    postbackUrl: 'https://example.com/webhook/callback'
  })
});
```

```php
use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'Authorization' => 'Bearer [SUA_CHAVE_API]',
    'Accept' => 'application/json',
    'Content-Type' => 'application/json',
])->post('https://api.bspay.co/v2/pix/qrcode', [
    'amount' => 100.00,
    'postbackUrl' => 'https://example.com/webhook/callback',
]);

$data = $response->json();
```

```python
import requests

url = 'https://api.bspay.co/v2/pix/qrcode'
headers = {
    'Authorization': 'Bearer [SUA_CHAVE_API]',
    'Accept': 'application/json',
    'Content-Type': 'application/json'
}
data = {
    'amount': 100.00,
    'postbackUrl': 'https://example.com/webhook/callback'
}

response = requests.post(url, data=data, headers=headers)

# Para acessar a resposta JSON:
result = response.json()
print(result)
```

```ruby
require 'net/http'
require 'uri'
require 'json'
 uri = URI.parse('https://api.bspay.co/v2/pix/qrcode')

headers = {
  'Authorization' => 'Bearer [SUA_CHAVE_API]',
  'Accept' => 'application/json',
  'Content-Type' => 'application/json'
}

data = {
  amount: 100.00,
  postbackUrl: 'https://example.com/webhook/callback'
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri, headers)
request.set_form_data(data)

response = http.request(request)

# Para acessar a resposta JSON
result = JSON.parse(response.body)
puts result
```

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

### Exemplo de Payload JSON para Evento de Transferência (Cash-out)

Source: https://doc.bspay.co/webhooks/cashout

Este é um exemplo do payload JSON que é enviado para o 'postbackUrl' quando um evento de transferência (cash-out) é confirmado. Ele contém detalhes da transação como tipo, ID, valor e status.

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

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

### Generate QR Code with Split Transactions (JSON)

Source: https://doc.bspay.co/financeiro/split

This JSON payload demonstrates how to include the 'split' object to automatically and instantly redirect parts of a transaction to other BS PAY accounts. Ensure the total percentage does not exceed 95% and individual percentages are at least 1%.

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

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

### POST /v2/balance

Source: https://doc.bspay.co/financeiro/consultar-saldo

Retrieves the current account balance. Requires Bearer authentication.

```APIDOC
## POST /v2/balance

### Description
Utilize essa rota para obter o saldo atual da sua conta por meio da api.
Requer autenticação.

### Method
POST

### Endpoint
https://api.bspay.co/v2/balance

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed, only authentication header."
}
```

### Response
#### Success Response (200)
- **statusCode** (integer) - The status code of the response.
- **message** (object) - Contains the balance information.
  - **balance** (string) - The current account balance.

#### Error Response (401)
- **statusCode** (integer) - The status code of the response.
- **message** (string) - Error message indicating unauthorized access.

#### Response Example (Success)
```json
{
  "statusCode": 200,
  "message": {
    "balance": "10000.00"
  }
}
```

#### Response Example (Error)
```json
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```
```

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

### POST /v2/pix/qrcode

Source: https://doc.bspay.co/financeiro/gerar-qrcode

Generates a Pix QR code for payment collection. This endpoint allows you to create a copy-pasteable code and a Pix QR code for your customers to make payments. It supports transaction details, payer information, and split payments.

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

### Description
Generates a Pix QR code for payment collection. This endpoint allows you to create a copy-pasteable code and a Pix QR code for your customers to make payments. It supports transaction details, payer information, and split payments.

### Method
POST

### Endpoint
https://api.bspay.co/v2/pix/qrcode

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (float) - Required - The transaction amount.
- **external_id** (string) - Optional - An external ID for the transaction generated by you.
- **postbackUrl** (string) - Required - Webhook URL to receive payment information.
- **payer** (object) - Optional - Information about the payer.
  - **name** (string) - Required - Full name of the customer or business name.
  - **document** (string) - Required - Customer's tax identification number (CPF for individuals or CNPJ for businesses).
  - **email** (string) - Optional - Customer's personal or business email.
- **payerQuestion** (string) - Optional - Description related to the transaction.
- **split** (array of objects) - Optional - Percentage for distributing value among internal accounts.
  - **username** (string) - Required - The username who will receive a percentage of the transaction.
  - **percentageSplit** (string) - Required - The percentage the user above will receive.

### Request Example
```json
{
  "amount": 100.00,
  "external_id": "YOUR_EXTERNAL_ID",
  "postbackUrl": "https://example.com/webhook/callback",
  "payer": {
    "name": "John Doe",
    "document": "12345678900",
    "email": "john.doe@example.com"
  },
  "payerQuestion": "Payment for invoice #123",
  "split": [
    {
      "username": "user1",
      "percentageSplit": "50"
    },
    {
      "username": "user2",
      "percentageSplit": "50"
    }
  ]
}
```

### Response
#### Success Response (200)
- **transactionId** (string) - The unique ID of the transaction.
- **external_id** (string) - The external ID provided in the request.
- **status** (string) - The current status of the transaction (e.g., PENDING, PAID).
- **amount** (string) - The transaction amount.
- **calendar** (object) - Information about the payment schedule.
  - **expiration** (integer) - The expiration time in seconds.
  - **dueDate** (string) - The due date of 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/..."
}
```

#### Error Response (401)
- **statusCode** (integer) - The HTTP status code (e.g., 401).
- **message** (string) - A message describing the error (e.g., "Unauthorized").

#### Error Response Example
```json
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```
```

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

### Exemplo de Payload JSON para Notificação de Recebimento PIX (Cash-in)

Source: https://doc.bspay.co/webhooks/cashin

Este é um exemplo do payload JSON enviado para o 'postbackUrl' quando um pagamento via PIX é recebido e confirmado pelo sistema BSPay. Ele contém detalhes da transação, informações das partes envolvidas e o status do pagamento.

```json
{
    "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"
    }
}
```

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

### POST /webhook/callback

Source: https://doc.bspay.co/introducao/webhooks

This endpoint receives real-time payment status updates from BS PAY. It's designed to be used as a postback URL for payment events.

```APIDOC
## POST /webhook/callback

### Description
This endpoint receives real-time payment status updates from BS PAY. It's designed to be used as a postback URL for payment events. When a payment status changes (e.g., to 'PAID'), BS PAY sends a notification to this endpoint.

### Method
POST

### Endpoint
/webhook/callback

### Parameters
#### Request Body
- **status** (string) - The current status of the payment (e.g., 'PAID', 'PENDING').
- **external_id** (string) - The unique identifier for the order or transaction, used to link the payment notification back to your system.

### Request Example
```json
{
  "status": "PAID",
  "external_id": "order_12345"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates that the notification was received and processed successfully. Common responses include 'OK' or 'Received'.

#### Response Example
```json
{
  "message": "OK"
}
```
```

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

### Payment Event (Cash-in) Webhook

Source: https://doc.bspay.co/webhooks/cashin

This event is sent to the 'postbackUrl' associated with each transaction once the payment is confirmed by our system. It notifies about received PIX payments.

```APIDOC
## POST /websites/doc_bspay_co/payment-event

### Description
This endpoint receives notifications for successful PIX payments (Cash-in) via a webhook.

### Method
POST

### Endpoint
/websites/doc_bspay_co/payment-event

### Request Body
- **transactionType** (string) - Required - Type of transaction, expected to be 'RECEIVEPIX'.
- **transactionId** (string) - Required - Unique identifier for the transaction.
- **external_id** (string) - Required - External reference ID for the transaction.
- **amount** (number) - Required - The amount of the payment.
- **paymentType** (string) - Required - The type of payment, expected to be 'PIX'.
- **status** (string) - Required - The status of the payment, expected to be 'PAID'.
- **dateApproval** (string) - Required - The date and time when the payment was approved (YYYY-MM-DD HH:MM:SS).
- **creditParty** (object) - Required - Information about the party receiving the funds.
  - **name** (string) - Required - Name of the credit party.
  - **email** (string) - Required - Email of the credit party.
  - **taxId** (string) - Required - Tax ID of the credit party.
- **debitParty** (object) - Required - Information about the party making the payment.
  - **bank** (string) - Required - Name of the bank involved in the debit.
  - **taxId** (string) - Required - Tax ID of the debit party.

### Request Example
```json
{
    "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"
    }
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the webhook was received.

#### Response Example
```json
{
  "message": "Webhook received successfully."
}
```

#### Error Response (400)
- **error** (string) - Description of the error if the payload is invalid or missing required fields.
```

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

### POST /v2/consult-transaction

Source: https://doc.bspay.co/financeiro/consultar-transacao

Retrieve detailed information about a specific transaction using its Pix ID. This endpoint requires authentication.

```APIDOC
## POST /v2/consult-transaction

### Description
Retrieve detailed information about a specific transaction using its Pix ID. This endpoint requires authentication.

### Method
POST

### Endpoint
https://api.bspay.co/v2/consult-transaction

### Parameters
#### Request Body
- **pix_id** (string) - Required - The ID of the transaction you wish to consult.

### Request Example
```json
{
  "pix_id": "[ID_DA_TRANSACAO]"
}
```

### Response
#### Success Response (200)
- **pix_id** (string) - The ID of the transaction that was consulted.

#### Response Example
```json
{
  "pix_id": "[ID_DA_TRANSACAO]"
}
```
```

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

### Transfer Event Notification (Cash-out)

Source: https://doc.bspay.co/webhooks/cashout

This event is sent to the 'postbackUrl' associated with each transaction once the payment is confirmed by our system. It notifies about the completion of a cash-out operation.

```APIDOC
## POST /event/transfer

### Description
Receives a notification when a transfer (cash-out) transaction is confirmed.

### Method
POST

### Endpoint
/event/transfer

### Request Body
- **transactionType** (string) - Required - Type of transaction, expected to be 'PAYMENT' for this event.
- **transactionId** (string) - Required - Unique identifier for the transaction.
- **external_id** (string) - Required - External reference ID for the transaction.
- **amount** (number) - Required - The amount of the transfer.
- **dateApproval** (string) - Required - The date and time when the payment was approved, in 'YYYY-MM-DD HH:MM:SS' format.
- **statusCode** (object) - Required - Object containing the status of the transaction.
  - **statusId** (integer) - Required - Numeric status code.
  - **description** (string) - Required - Textual description of the status.

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

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Notification received successfully"
}
```
```

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

### Payment Event Notification (Cash-in)

Source: https://doc.bspay.co/webhooks/cashout

This event is sent to notify about the receipt of a payment via PIX (cash-in).

```APIDOC
## POST /event/payment

### Description
Receives a notification when a payment (cash-in) is received via PIX.

### Method
POST

### Endpoint
/event/payment

### Request Body
*Details for the payment event payload are not provided in the source text. Please refer to specific PIX integration documentation for the exact structure.*

### Request Example
*Example payload not available in the provided text.*

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Notification received successfully"
}
```
```

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

### Handle Payment Confirmation Webhook

Source: https://doc.bspay.co/introducao/webhooks

This snippet demonstrates how to create a webhook endpoint to update order status to 'PAID' upon receiving a payment confirmation from BS PAY. It expects a JSON payload with a 'status' field and an 'external_id'.

```javascript
import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhook/callback', async (req, res) => {
  if (req.body.status !== 'PAID') {
    return res.status(200).send('Received'); // Ignora notificações que não são de pagamento
  }

  try {
    const id = req.body.external_id;
    const order = await Order.find(id);

    await order.update({
      status: 'PAID',
    });

    return res.status(200).send('OK');
  }
  catch (err) {
    console.error('Erro ao gerar QR Code:', err);
    return res.status(500).send('Erro ao gerar QR Code');
  }
});

app.listen(3000, () => console.log('🚀 Servidor rodando na porta 3000'));

```

```php
use Illuminate\Support\Facades\Route;
use Illuminate\Http\Request;
use App\Models\Order;

Route::post('/payment', function (Request $request) {
    if ($request->get('status') !== 'PAID') {
        return response('Received', 200);
    }

    $id = $request->get('external_id');
    $order = Order::findOrFail($id);

    $order->update([
        'status' => 'PAID',
    ]);

    return response('Received', 200);
});

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.