payzu-pix 2.0.0

data/docs/KeysAndDICTApi.md

@@ -0,0 +1,217 @@
+# PayZuPix::KeysAndDICTApi
+
+All URIs are relative to *https://api.payzu.processamento.com/v1*
+
+| Method | HTTP request | Description |
+| ------ | ------------ | ----------- |
+| [**get_pix_key**](KeysAndDICTApi.md#get_pix_key) | **GET** /pix/key | Pix key lookup (DICT) |
+| [**get_user_dict**](KeysAndDICTApi.md#get_user_dict) | **GET** /user/dict | Resolve DICT key |
+| [**post_pix_qrcode_read**](KeysAndDICTApi.md#post_pix_qrcode_read) | **POST** /pix/qrcode/read | Read QR Code |
+
+
+## get_pix_key
+
+> <PixKeyInfo> get_pix_key(pix_key)
+
+Pix key lookup (DICT)
+
+Query the DICT (Diretório de Identificadores de Contas Transacionais) to retrieve information about a Pix key before sending a payment. Returns the key owner's details and associated financial institution.  Token permission: `DEPOSIT` or `WITHDRAW`.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::KeysAndDICTApi.new
+pix_key = 'example@payzu.com.br' # String | The Pix key to lookup (CPF, CNPJ, email, phone, or EVP).
+
+begin
+  # Pix key lookup (DICT)
+  result = api_instance.get_pix_key(pix_key)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->get_pix_key: #{e}"
+end
+```
+
+#### Using the get_pix_key_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<PixKeyInfo>, Integer, Hash)> get_pix_key_with_http_info(pix_key)
+
+```ruby
+begin
+  # Pix key lookup (DICT)
+  data, status_code, headers = api_instance.get_pix_key_with_http_info(pix_key)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <PixKeyInfo>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->get_pix_key_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **pix_key** | **String** | The Pix key to lookup (CPF, CNPJ, email, phone, or EVP). |  |
+
+### Return type
+
+[**PixKeyInfo**](PixKeyInfo.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
+## get_user_dict
+
+> <DictConsultResponse> get_user_dict(key)
+
+Resolve DICT key
+
+Resolves a Pix key (DICT) to the holder details before paying. Requires WITHDRAW scope.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::KeysAndDICTApi.new
+key = 'john.doe@example.com' # String | Pix key to look up (CPF, CNPJ, email, phone or EVP).
+
+begin
+  # Resolve DICT key
+  result = api_instance.get_user_dict(key)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->get_user_dict: #{e}"
+end
+```
+
+#### Using the get_user_dict_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<DictConsultResponse>, Integer, Hash)> get_user_dict_with_http_info(key)
+
+```ruby
+begin
+  # Resolve DICT key
+  data, status_code, headers = api_instance.get_user_dict_with_http_info(key)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <DictConsultResponse>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->get_user_dict_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **key** | **String** | Pix key to look up (CPF, CNPJ, email, phone or EVP). |  |
+
+### Return type
+
+[**DictConsultResponse**](DictConsultResponse.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
+## post_pix_qrcode_read
+
+> <QRCodeReadResponse> post_pix_qrcode_read(post_pix_qrcode_read_request)
+
+Read QR Code
+
+Decode and extract information from a Pix QR Code (EMV format) before making a payment. Returns the parsed data including receiver details, amount (if present), and other QR Code metadata. PayZu processes both dynamic and static QR Codes.  Token permission: `DEPOSIT` or `WITHDRAW`.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::KeysAndDICTApi.new
+post_pix_qrcode_read_request = PayZuPix::PostPixQrcodeReadRequest.new({emv: '00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55'}) # PostPixQrcodeReadRequest | 
+
+begin
+  # Read QR Code
+  result = api_instance.post_pix_qrcode_read(post_pix_qrcode_read_request)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->post_pix_qrcode_read: #{e}"
+end
+```
+
+#### Using the post_pix_qrcode_read_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<QRCodeReadResponse>, Integer, Hash)> post_pix_qrcode_read_with_http_info(post_pix_qrcode_read_request)
+
+```ruby
+begin
+  # Read QR Code
+  data, status_code, headers = api_instance.post_pix_qrcode_read_with_http_info(post_pix_qrcode_read_request)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <QRCodeReadResponse>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling KeysAndDICTApi->post_pix_qrcode_read_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **post_pix_qrcode_read_request** | [**PostPixQrcodeReadRequest**](PostPixQrcodeReadRequest.md) |  |  |
+
+### Return type
+
+[**QRCodeReadResponse**](QRCodeReadResponse.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: application/json
+

data/docs/ListUserReports200Response.md

@@ -0,0 +1,22 @@
+# PayZuPix::ListUserReports200Response
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **total** | **Integer** | Number of report requests of the user that match the filters. | [optional] |
+| **pages** | **Integer** | Number of pages for the limit provided, computed from total rounded up. | [optional] |
+| **reports** | [**Array<ReportJob>**](ReportJob.md) | Report requests of the requested page, with id, status and dates. | [optional] |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::ListUserReports200Response.new(
+  total: null,
+  pages: null,
+  reports: null
+)
+```
+

data/docs/PixKeyInfo.md

@@ -0,0 +1,36 @@
+# PayZuPix::PixKeyInfo
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **pix_key** | **String** | The Pix key that was looked up. | [optional] |
+| **document** | **String** | CPF or CNPJ of the owner (partially masked for privacy). | [optional] |
+| **name** | **String** | Name of the Pix key owner. | [optional] |
+| **branch** | **String** | Bank branch number (masked). | [optional] |
+| **account_number** | **String** | Account number (masked). | [optional] |
+| **person_type** | **String** | Type of person: PF, PJ, or empty when not informed. | [optional] |
+| **account_type** | **String** | Account type returned by DICT, such as CACC, SVGS, TRAN or SLRY. | [optional] |
+| **institution_ispb** | **String** | ISPB code of the financial institution. | [optional] |
+| **institution_code** | **String** | COMPE code of the financial institution. | [optional] |
+| **institution_name** | **String** | Name of the financial institution. | [optional] |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::PixKeyInfo.new(
+  pix_key: null,
+  document: null,
+  name: null,
+  branch: null,
+  account_number: null,
+  person_type: null,
+  account_type: null,
+  institution_ispb: null,
+  institution_code: null,
+  institution_name: null
+)
+```
+

data/docs/PixOperationsApi.md

@@ -0,0 +1,299 @@
+# PayZuPix::PixOperationsApi
+
+All URIs are relative to *https://api.payzu.processamento.com/v1*
+
+| Method | HTTP request | Description |
+| ------ | ------------ | ----------- |
+| [**get_pix**](PixOperationsApi.md#get_pix) | **GET** /pix | Retrieve Charge |
+| [**get_pix_qrcode**](PixOperationsApi.md#get_pix_qrcode) | **GET** /pix/qr-code/{transactionId} | Render Pix QR code (PNG) |
+| [**get_proof**](PixOperationsApi.md#get_proof) | **GET** /proof/{id} | Get Transaction Receipt |
+| [**post_pix**](PixOperationsApi.md#post_pix) | **POST** /pix | Create Charge (Pix deposit) |
+
+
+## get_pix
+
+> <Transaction> get_pix(opts)
+
+Retrieve Charge
+
+Get the latest status and details of a transaction of the account. Provide at least one of `id`, `clientReference`, or `endToEndId` (`virtualAccount` is also accepted). When more than one parameter is provided, they are combined as filters (AND).  Token permission: `DEPOSIT`.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::PixOperationsApi.new
+opts = {
+  id: 'PAYZU20260811R4TZ8WD1NC000000', # String | Transaction ID.
+  client_reference: 'order_12345', # String | External reference provided when creating the charge.
+  end_to_end_id: 'E00000000202508172159kZ8dQ2mNb1x', # String | Pix end-to-end ID.
+  virtual_account: 'loja-centro-01' # String | Virtual sub-account (up to 50 characters) used at creation. Accepted as an alternative lookup key.
+}
+
+begin
+  # Retrieve Charge
+  result = api_instance.get_pix(opts)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_pix: #{e}"
+end
+```
+
+#### Using the get_pix_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<Transaction>, Integer, Hash)> get_pix_with_http_info(opts)
+
+```ruby
+begin
+  # Retrieve Charge
+  data, status_code, headers = api_instance.get_pix_with_http_info(opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <Transaction>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_pix_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **id** | **String** | Transaction ID. | [optional] |
+| **client_reference** | **String** | External reference provided when creating the charge. | [optional] |
+| **end_to_end_id** | **String** | Pix end-to-end ID. | [optional] |
+| **virtual_account** | **String** | Virtual sub-account (up to 50 characters) used at creation. Accepted as an alternative lookup key. | [optional] |
+
+### Return type
+
+[**Transaction**](Transaction.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json
+
+
+## get_pix_qrcode
+
+> File get_pix_qrcode(transaction_id)
+
+Render Pix QR code (PNG)
+
+Render the Pix QR Code of a deposit as a binary PNG image  Token permission: `DEPOSIT`.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::PixOperationsApi.new
+transaction_id = 'PAYZU20260814T6NX1CV9MK000000' # String | Transaction ID.
+
+begin
+  # Render Pix QR code (PNG)
+  result = api_instance.get_pix_qrcode(transaction_id)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_pix_qrcode: #{e}"
+end
+```
+
+#### Using the get_pix_qrcode_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(File, Integer, Hash)> get_pix_qrcode_with_http_info(transaction_id)
+
+```ruby
+begin
+  # Render Pix QR code (PNG)
+  data, status_code, headers = api_instance.get_pix_qrcode_with_http_info(transaction_id)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => File
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_pix_qrcode_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **transaction_id** | **String** | Transaction ID. |  |
+
+### Return type
+
+**File**
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: image/png, application/json
+
+
+## get_proof
+
+> <ProofResponse> get_proof(id, opts)
+
+Get Transaction Receipt
+
+Returns the transaction receipt. By default (`type=pdf`) the response is the PDF file; with `type=base64` it is JSON with the `base64` field, the PDF as a data URI.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::PixOperationsApi.new
+id = 'PAYZU20260814T6NX1CV9MK000000' # String | Transaction ID.
+opts = {
+  type: 'pdf' # String | Return format.
+}
+
+begin
+  # Get Transaction Receipt
+  result = api_instance.get_proof(id, opts)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_proof: #{e}"
+end
+```
+
+#### Using the get_proof_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<ProofResponse>, Integer, Hash)> get_proof_with_http_info(id, opts)
+
+```ruby
+begin
+  # Get Transaction Receipt
+  data, status_code, headers = api_instance.get_proof_with_http_info(id, opts)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <ProofResponse>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->get_proof_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **id** | **String** | Transaction ID. |  |
+| **type** | **String** | Return format. | [optional][default to &#39;pdf&#39;] |
+
+### Return type
+
+[**ProofResponse**](ProofResponse.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: Not defined
+- **Accept**: application/json, application/pdf
+
+
+## post_pix
+
+> <Transaction> post_pix(post_pix_request)
+
+Create Charge (Pix deposit)
+
+Create a new Pix **deposit** (charge). Returns QR Code and transaction details.  Token permission: `DEPOSIT`.
+
+### Examples
+
+```ruby
+require 'time'
+require 'payzu-pix'
+# setup authorization
+PayZuPix.configure do |config|
+  # Configure Bearer authorization: BearerAuth
+  config.access_token = 'YOUR_BEARER_TOKEN'
+end
+
+api_instance = PayZuPix::PixOperationsApi.new
+post_pix_request = PayZuPix::PostPixRequest.new({amount: 10.9}) # PostPixRequest | 
+
+begin
+  # Create Charge (Pix deposit)
+  result = api_instance.post_pix(post_pix_request)
+  p result
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->post_pix: #{e}"
+end
+```
+
+#### Using the post_pix_with_http_info variant
+
+This returns an Array which contains the response data, status code and headers.
+
+> <Array(<Transaction>, Integer, Hash)> post_pix_with_http_info(post_pix_request)
+
+```ruby
+begin
+  # Create Charge (Pix deposit)
+  data, status_code, headers = api_instance.post_pix_with_http_info(post_pix_request)
+  p status_code # => 2xx
+  p headers # => { ... }
+  p data # => <Transaction>
+rescue PayZuPix::ApiError => e
+  puts "Error when calling PixOperationsApi->post_pix_with_http_info: #{e}"
+end
+```
+
+### Parameters
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **post_pix_request** | [**PostPixRequest**](PostPixRequest.md) |  |  |
+
+### Return type
+
+[**Transaction**](Transaction.md)
+
+### Authorization
+
+[BearerAuth](../README.md#BearerAuth)
+
+### HTTP request headers
+
+- **Content-Type**: application/json
+- **Accept**: application/json
+

data/docs/PostInternalTransferRequest.md

@@ -0,0 +1,30 @@
+# PayZuPix::PostInternalTransferRequest
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **payer_account_number** | **String** | Payer account number (6 digits). Must match the authenticated user's accountNumber. |  |
+| **receiver_account_number** | **String** | Destination account number (6 digits). |  |
+| **amount** | **Float** | Transfer amount in BRL, with at most 2 decimal places. |  |
+| **description** | **String** | Optional transfer description. | [optional] |
+| **callback_url** | **String** | URL for transaction notifications (http or https). | [optional] |
+| **client_reference** | **String** | External reference for idempotency / reconciliation. | [optional] |
+| **virtual_account** | **String** | Virtual sub-account (up to 50 characters) to correlate stores, branches, marketplaces. Returned in the callback. | [optional] |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::PostInternalTransferRequest.new(
+  payer_account_number: 000000,
+  receiver_account_number: 987654,
+  amount: 100.5,
+  description: Pagamento referente a fatura #1234,
+  callback_url: https://webhook.cool/,
+  client_reference: transfer_abc_123,
+  virtual_account: loja-centro-01
+)
+```
+

data/docs/PostPixQrcodeReadRequest.md

@@ -0,0 +1,18 @@
+# PayZuPix::PostPixQrcodeReadRequest
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **emv** | **String** | The EMV payload string from the Pix QR Code. |  |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::PostPixQrcodeReadRequest.new(
+  emv: 00020101021226770014br.gov.bcb.pix2555api.payzu/pix/qr/v2/013318d6-2d7d-479e-8bb3-b5c7b9da688c5204000053039865802BR5916PAYZU 6007SAOPAULO6217051320260118278956304EC55
+)
+```
+

data/docs/PostPixRequest.md

@@ -0,0 +1,32 @@
+# PayZuPix::PostPixRequest
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **amount** | **Float** | Amount in BRL. Must be >= 1. |  |
+| **callback_url** | **String** | URL for transaction notifications (http or https). | [optional] |
+| **generated_name** | **String** | Payer full name. Letters and spaces only. | [optional] |
+| **generated_email** | **String** | Payer email (optional). | [optional] |
+| **generated_document** | **String** | Payer CPF (11 digits) or CNPJ (14 digits), no punctuation, with valid check digits. | [optional] |
+| **expires_in** | **Float** | Seconds until the QR Code expires. | [optional] |
+| **client_reference** | **String** | External reference (order, invoice, etc.). A clientReference already used returns the transaction created with it. | [optional] |
+| **virtual_account** | **String** | Virtual sub-account (up to 50 characters) to correlate stores, branches, marketplaces. Returned in the callback. | [optional] |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::PostPixRequest.new(
+  amount: 10.9,
+  callback_url: https://webhook.cool/,
+  generated_name: John Doe,
+  generated_email: john.doe@example.com,
+  generated_document: 12345678901,
+  expires_in: 600,
+  client_reference: order_12345,
+  virtual_account: loja-centro-01
+)
+```
+

data/docs/PostUserReportRequest.md

@@ -0,0 +1,24 @@
+# PayZuPix::PostUserReportRequest
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **date_from** | **Time** | Start of the report period. |  |
+| **date_to** | **Time** | End of the report period. |  |
+| **status** | **Array<String>** | Transaction statuses included in the file. Empty or omitted: all. | [optional] |
+| **type** | **Array<String>** | Transaction types included in the file. Empty or omitted: all. | [optional] |
+
+## Example
+
+```ruby
+require 'payzu-pix'
+
+instance = PayZuPix::PostUserReportRequest.new(
+  date_from: 2026-07-01T00:00:00Z,
+  date_to: 2026-07-31T23:59:59Z,
+  status: null,
+  type: null
+)
+```
+