fintoc 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2b6fd84b01a0debcf2e3641566db792081bc9d101a4aa7c16c5de4833e573fca
-  data.tar.gz: 72ae1022ebe59fb82ce5ce68ca4327d70975fbe87f64b4b20df6d0d30705f7ec
+  metadata.gz: 2ce93ceec460af064e29aa8b4108858087ab74c623ba328785f160165c8a8b2f
+  data.tar.gz: a3f1f7dce733d2a9fbdbba43176467d95c03aa60407e2cfef2cce897fea6341c
 SHA512:
-  metadata.gz: d5d6354afddadc96ddd7b4795e6d7b6d4679fb9838378f0b6f3a130442a35505e518394aabf3ebc543d6b9dad7071f5141853e747a7832e2bc8920a57d719cd6
-  data.tar.gz: 9d98cb9b5f113793b62458d55e6f425ff7dc3f8a811a7f664fdf09630e7bcbcfa3234a95ebb903648ba3053981e4acfd9bfb76471ae49c44c0d670bb368518ce
+  metadata.gz: 8e33500d7c444114ed0d8d8fbd7e50179b1789faefe70f4e87e9b38badf0a9458f97a3c8fb46bea6a73e50b10225aa263d86ae045ee7fe1db050e5742ecd4427
+  data.tar.gz: 848d3e8b713c20c6ca4d01060aafbb8672f9607f17332e1ff55bb443df19bb14ae8ba2b25eb69394c9b06410ce978c1a78cad9a530cfd4904bacc4ffd6c23b26

data/.github/pull_request_template.md

@@ -44,4 +44,3 @@ Ej.:
 
 ¿Es seguro hacer rollback?
 ¿Cuáles son los pasos para hacer rollback?
-****

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 1.1.0 - 2025-09-15
+
+### 🚀 New Features
+
+- **Idempotency Key Support**: Added comprehensive idempotency key support across all V2 API operations to help prevent duplicate operations during network issues or retries
+  - **Accounts**: `create` and `update` methods now accept the `idempotency_key` parameter
+  - **Account Numbers**: `create` and `update` methods support idempotency keys
+  - **Transfers**: `create` and `return` operations support idempotency keys
+  - **Account Verifications**: `create` method supports idempotency keys
+  - **Simulation**: `receive_transfer` method supports idempotency keys
+  - **Resource-level methods**: Instance methods like `account.update`, `transfer.return_transfer`, and `account.simulate_receive_transfer` all support idempotency keys
+
 ## 1.0.0 - 2025-09-05
 
 ### 🚀 New Features
@@ -12,7 +24,7 @@
 
 - **V2 Client - Transfers API Implementation**: Partial implementation of Transfers API endpoints in `Fintoc::V2::Client`
   - **Entities**: List and retrieve business entities
-  - **Transfer Accounts**: Create, read, update, and list transfer accounts
+  - **Accounts**: Create, read, update, and list accounts
   - **Account Numbers**: Manage account numbers/CLABEs
   - **Transfers**: Create, retrieve, list, and return transfers
   - **Simulation**: Simulate receiving transfers for testing
@@ -42,4 +54,4 @@
 
 Initial version
 
-* Up to date with the [2020-11-17](https://docs.fintoc.com/docs/api-changelog#2020-11-17) API version
+- Up to date with the [2020-11-17](https://docs.fintoc.com/docs/api-changelog#2020-11-17) API version

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fintoc (1.0.0)
+    fintoc (1.1.0)
       http
       money-rails
       tabulate

data/README.md

@@ -28,11 +28,19 @@ Do yourself a favor: go grab some ice cubes by installing this refreshing librar
       - [Get movements](#get-movements)
     - [Transfers API Examples](#transfers-api-examples)
       - [Entities](#entities)
-      - [Transfer Accounts](#transfer-accounts)
+      - [Accounts](#accounts)
       - [Account Numbers](#account-numbers)
       - [Transfers](#transfers)
       - [Simulate](#simulate)
       - [Account Verifications](#account-verifications)
+  - [Idempotency Keys](#idempotency-keys)
+    - [Idempotency Examples](#idempotency-examples)
+      - [Account Methods with Idempotency Key](#account-methods-with-idempotency-key)
+      - [Account Number Methods with Idempotency Key](#account-number-methods-with-idempotency-key)
+      - [Transfer Methods with Idempotency Key](#transfer-methods-with-idempotency-key)
+      - [Simulation with Idempotency Key](#simulation-with-idempotency-key)
+      - [Account Verification with Idempotency Key](#account-verification-with-idempotency-key)
+    - [About idempotency keys](#about-idempotency-keys)
   - [Development](#development)
     - [Dependencies](#dependencies)
     - [Setup](#setup)
@@ -107,7 +115,7 @@ client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
 entities = client.v2.entities.list
 entity = client.v2.entities.get('entity_id')
 
-# Transfer Accounts
+# Accounts
 accounts = client.v2.accounts.list
 account = client.v2.accounts.get('account_id')
 account = client.v2.accounts.create(entity_id: 'entity_id', description: 'My Account')
@@ -265,14 +273,14 @@ You can also list entities with pagination:
 entities = client.v2.entities.list(limit: 10, starting_after: 'entity_id')
 ```
 
-#### Transfer Accounts
+#### Accounts
 
 ```ruby
 require 'fintoc'
 
 client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
 
-# Create a transfer account
+# Create an account
 account = client.v2.accounts.create(
   entity_id: 'entity_id',
   description: 'My Business Account'
@@ -378,6 +386,116 @@ account_verification = client.v2.account_verifications.get('account_verification
 account_verifications = client.v2.account_verifications.list
 ```
 
+## Idempotency Keys
+
+The Fintoc API supports [idempotency](https://docs.fintoc.com/reference/idempotent-requests) for safely retrying requests without accidentally performing the same operation twice. This is particularly useful when creating transfers, account numbers, accounts, or other resources where you want to avoid duplicates due to network issues.
+
+To use idempotency keys, provide an `idempotency_key` parameter when making POST/PATCH requests:
+
+### Idempotency Examples
+
+#### Account Methods with Idempotency Key
+
+Create and update methods support the use of idempotency keys to prevent duplication:
+
+```ruby
+require 'fintoc'
+require 'securerandom'
+
+client = Fintoc::Client.new('api_key', jws_private_key: 'jws_private_key')
+
+idempotency_key = SecureRandom.uuid
+account = client.v2.accounts.create(
+  entity_id: 'entity_id', description: 'My Business Account', idempotency_key:
+)
+
+idempotency_key = SecureRandom.uuid
+updated_account = client.v2.accounts.update(
+  'account_id', description: 'Updated Description', idempotency_key:
+)
+```
+
+Simulation of transfers can also be done with idempotency key:
+
+```ruby
+idempotency_key = SecureRandom.uuid
+account.simulate_receive_transfer(amount: 1000, idempotency_key:)
+```
+
+#### Account Number Methods with Idempotency Key
+
+Create and update methods support the use of idempotency keys as well:
+
+```ruby
+idempotency_key = SecureRandom.uuid
+account_number = client.v2.account_numbers.create(
+  account_id: 'account_id', description: 'Main account number', idempotency_key:
+)
+
+idempotency_key = SecureRandom.uuid
+updated_account_number = client.v2.account_numbers.update(
+  'account_number_id', description: 'Updated description', idempotency_key:
+)
+```
+
+Simulation of transfers can also be done with idempotency key:
+
+```ruby
+account_number.simulate_receive_transfer(amount: 1000, currency: 'MXN', idempotency_key:)
+```
+
+#### Transfer Methods with Idempotency Key
+
+Creating and returning transfers support the use of idempotency keys:
+
+```ruby
+idempotency_key = SecureRandom.uuid
+transfer = client.v2.transfers.create(
+  amount: 10000, currency: 'CLP', account_id: 'account_id', counterparty: { ... }, idempotency_key:
+)
+
+idempotency_key = SecureRandom.uuid
+returned_transfer = client.v2.transfers.return('transfer_id', idempotency_key:)
+```
+
+Returning a transfer as an instance method also supports the use of idempotency key:
+
+```ruby
+idempotency_key = SecureRandom.uuid
+transfer.return_transfer(idempotency_key:)
+```
+
+#### Simulation with Idempotency Key
+
+For simulating transfers, the use of idempotency keys is also supported:
+
+```ruby
+idempotency_key = SecureRandom.uuid
+simulated_transfer = client.v2.simulate.receive_transfer(
+  account_number_id: 'account_number_id', amount: 5000, currency: 'CLP', idempotency_key:
+)
+```
+
+#### Account Verification with Idempotency Key
+
+```ruby
+idempotency_key = SecureRandom.uuid
+account_verification = client.v2.account_verifications.create(
+  account_number: 'account_number', idempotency_key:
+)
+```
+
+### About idempotency keys
+
+- Idempotency keys can be up to 255 characters long
+- Use consistent unique identifiers for the same logical operation (e.g. order IDs, transaction references). If you set them randomly, we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions.
+- The same idempotency key will return the same result, including errors
+- Keys are automatically removed after 24 hours
+- Only POST and PATCH requests currently support idempotency keys
+- If parameters differ with the same key, an error will be raised
+
+For more information, see the [Fintoc API documentation on idempotent requests](https://docs.fintoc.com/reference/idempotent-requests).
+
 ## Development
 
 ### Dependencies

data/lib/fintoc/base_client.rb

@@ -23,25 +23,25 @@ module Fintoc
     end
 
     def get(version: :v1)
-      request('get', version: version)
+      request('get', version:)
     end
 
     def delete(version: :v1)
-      request('delete', version: version)
+      request('delete', version:)
     end
 
-    def post(version: :v1, use_jws: false)
-      request('post', version: version, use_jws: use_jws)
+    def post(version: :v1, use_jws: false, idempotency_key: nil)
+      request('post', version:, use_jws:, idempotency_key:)
     end
 
-    def patch(version: :v1, use_jws: false)
-      request('patch', version: version, use_jws: use_jws)
+    def patch(version: :v1, use_jws: false, idempotency_key: nil)
+      request('patch', version:, use_jws:, idempotency_key:)
     end
 
-    def request(method, version: :v1, use_jws: false)
+    def request(method, version: :v1, use_jws: false, idempotency_key: nil)
       proc do |resource, **kwargs|
         parameters = params(method, **kwargs)
-        response = make_request(method, resource, parameters, version: version, use_jws: use_jws)
+        response = make_request(method, resource, parameters, version:, use_jws:, idempotency_key:)
         content = JSON.parse(response.body, symbolize_names: true)
 
         if response.status.client_error? || response.status.server_error?
@@ -91,7 +91,13 @@ module Fintoc
       use_jws && @jws && %w[post patch put].include?(method.downcase)
     end
 
-    def make_request(method, resource, parameters, version: :v1, use_jws: false)
+    def should_use_idempotency_key?(method, idempotency_key)
+      idempotency_key && %w[post patch put].include?(method.downcase)
+    end
+
+    def make_request(
+      method, resource, parameters, version: :v1, use_jws: false, idempotency_key: nil
+    )
       # this is to handle url returned in the link headers
       # I'm sure there is a better and more clever way to solve this
       if resource.start_with? 'https'
@@ -99,15 +105,20 @@ module Fintoc
       end
 
       url = build_url(resource, version:)
+      request_client = client
 
       if should_use_jws?(method, use_jws)
         request_body = parameters[:json]&.to_json || ''
         jws_signature = @jws.generate_signature(request_body)
 
-        return client.headers('Fintoc-JWS-Signature' => jws_signature).send(method, url, parameters)
+        request_client = request_client.headers('Fintoc-JWS-Signature' => jws_signature)
+      end
+
+      if should_use_idempotency_key?(method, idempotency_key)
+        request_client = request_client.headers('Idempotency-Key' => idempotency_key)
       end
 
-      client.send(method, url, parameters)
+      request_client.send(method, url, parameters)
     end
 
     def params(method, **kwargs)

data/lib/fintoc/v2/managers/account_numbers_manager.rb

@@ -8,8 +8,10 @@ module Fintoc
           @client = client
         end
 
-        def create(account_id:, description: nil, metadata: nil, **params)
-          data = _create_account_number(account_id:, description:, metadata:, **params)
+        def create(account_id:, description: nil, metadata: nil, idempotency_key: nil, **params)
+          data = _create_account_number(
+            account_id:, description:, metadata:, idempotency_key:, **params
+          )
           build_account_number(data)
         end
 
@@ -22,20 +24,22 @@ module Fintoc
           _list_account_numbers(**params).map { |data| build_account_number(data) }
         end
 
-        def update(account_number_id, **params)
-          data = _update_account_number(account_number_id, **params)
+        def update(account_number_id, idempotency_key: nil, **params)
+          data = _update_account_number(account_number_id, idempotency_key:, **params)
           build_account_number(data)
         end
 
         private
 
-        def _create_account_number(account_id:, description: nil, metadata: nil, **params)
+        def _create_account_number(
+          account_id:, description: nil, metadata: nil, idempotency_key: nil, **params
+        )
           request_params = { account_id: }
           request_params[:description] = description if description
           request_params[:metadata] = metadata if metadata
           request_params.merge!(params)
 
-          @client.post(version: :v2).call('account_numbers', **request_params)
+          @client.post(version: :v2, idempotency_key:).call('account_numbers', **request_params)
         end
 
         def _get_account_number(account_number_id)
@@ -46,8 +50,9 @@ module Fintoc
           @client.get(version: :v2).call('account_numbers', **params)
         end
 
-        def _update_account_number(account_number_id, **params)
-          @client.patch(version: :v2).call("account_numbers/#{account_number_id}", **params)
+        def _update_account_number(account_number_id, idempotency_key: nil, **params)
+          @client.patch(version: :v2, idempotency_key:)
+                 .call("account_numbers/#{account_number_id}", **params)
         end
 
         def build_account_number(data)

data/lib/fintoc/v2/managers/account_verifications_manager.rb

@@ -8,8 +8,8 @@ module Fintoc
           @client = client
         end
 
-        def create(account_number:)
-          data = _create_account_verification(account_number:)
+        def create(account_number:, idempotency_key: nil)
+          data = _create_account_verification(account_number:, idempotency_key:)
           build_account_verification(data)
         end
 
@@ -24,8 +24,9 @@ module Fintoc
 
         private
 
-        def _create_account_verification(account_number:)
-          @client.post(version: :v2, use_jws: true).call('account_verifications', account_number:)
+        def _create_account_verification(account_number:, idempotency_key: nil)
+          @client.post(version: :v2, use_jws: true, idempotency_key:)
+                 .call('account_verifications', account_number:)
         end
 
         def _get_account_verification(account_verification_id)

data/lib/fintoc/v2/managers/accounts_manager.rb

@@ -8,8 +8,8 @@ module Fintoc
           @client = client
         end
 
-        def create(entity_id:, description:, **params)
-          data = _create_account(entity_id:, description:, **params)
+        def create(entity_id:, description:, idempotency_key: nil, **params)
+          data = _create_account(entity_id:, description:, idempotency_key:, **params)
           build_account(data)
         end
 
@@ -22,15 +22,16 @@ module Fintoc
           _list_accounts(**params).map { |data| build_account(data) }
         end
 
-        def update(account_id, **params)
-          data = _update_account(account_id, **params)
+        def update(account_id, idempotency_key: nil, **params)
+          data = _update_account(account_id, idempotency_key:, **params)
           build_account(data)
         end
 
         private
 
-        def _create_account(entity_id:, description:, **params)
-          @client.post(version: :v2).call('accounts', entity_id:, description:, **params)
+        def _create_account(entity_id:, description:, idempotency_key: nil, **params)
+          @client.post(version: :v2, idempotency_key:)
+                 .call('accounts', entity_id:, description:, **params)
         end
 
         def _get_account(account_id)
@@ -41,8 +42,8 @@ module Fintoc
           @client.get(version: :v2).call('accounts', **params)
         end
 
-        def _update_account(account_id, **params)
-          @client.patch(version: :v2).call("accounts/#{account_id}", **params)
+        def _update_account(account_id, idempotency_key: nil, **params)
+          @client.patch(version: :v2, idempotency_key:).call("accounts/#{account_id}", **params)
         end
 
         def build_account(data)

data/lib/fintoc/v2/managers/simulate_manager.rb

@@ -8,16 +8,18 @@ module Fintoc
           @client = client
         end
 
-        def receive_transfer(account_number_id:, amount:, currency:)
-          data = _simulate_receive_transfer(account_number_id:, amount:, currency:)
+        def receive_transfer(account_number_id:, amount:, currency:, idempotency_key: nil)
+          data = _simulate_receive_transfer(
+            account_number_id:, amount:, currency:, idempotency_key:
+          )
           build_transfer(data)
         end
 
         private
 
-        def _simulate_receive_transfer(account_number_id:, amount:, currency:)
+        def _simulate_receive_transfer(account_number_id:, amount:, currency:, idempotency_key: nil)
           @client
-            .post(version: :v2)
+            .post(version: :v2, idempotency_key:)
             .call('simulate/receive_transfer', account_number_id:, amount:, currency:)
         end
 

data/lib/fintoc/v2/managers/transfers_manager.rb

@@ -8,8 +8,10 @@ module Fintoc
           @client = client
         end
 
-        def create(amount:, currency:, account_id:, counterparty:, **params)
-          data = _create_transfer(amount:, currency:, account_id:, counterparty:, **params)
+        def create(amount:, currency:, account_id:, counterparty:, idempotency_key: nil, **params)
+          data = _create_transfer(
+            amount:, currency:, account_id:, counterparty:, idempotency_key:, **params
+          )
           build_transfer(data)
         end
 
@@ -22,16 +24,18 @@ module Fintoc
           _list_transfers(**params).map { |data| build_transfer(data) }
         end
 
-        def return(transfer_id)
-          data = _return_transfer(transfer_id)
+        def return(transfer_id, idempotency_key: nil)
+          data = _return_transfer(transfer_id, idempotency_key:)
           build_transfer(data)
         end
 
         private
 
-        def _create_transfer(amount:, currency:, account_id:, counterparty:, **params)
+        def _create_transfer(
+          amount:, currency:, account_id:, counterparty:, idempotency_key: nil, **params
+        )
           @client
-            .post(version: :v2, use_jws: true)
+            .post(version: :v2, use_jws: true, idempotency_key:)
             .call('transfers', amount:, currency:, account_id:, counterparty:, **params)
         end
 
@@ -43,8 +47,9 @@ module Fintoc
           @client.get(version: :v2).call('transfers', **params)
         end
 
-        def _return_transfer(transfer_id)
-          @client.post(version: :v2, use_jws: true).call('transfers/return', transfer_id:)
+        def _return_transfer(transfer_id, idempotency_key: nil)
+          @client.post(version: :v2, use_jws: true, idempotency_key:)
+                 .call('transfers/return', transfer_id:)
         end
 
         def build_transfer(data)

data/lib/fintoc/v2/resources/account.rb

@@ -44,11 +44,11 @@ module Fintoc
         refresh_from_account(fresh_account)
       end
 
-      def update(description: nil)
+      def update(description: nil, idempotency_key: nil)
         params = {}
         params[:description] = description if description
 
-        updated_account = @client.accounts.update(@id, **params)
+        updated_account = @client.accounts.update(@id, idempotency_key:, **params)
         refresh_from_account(updated_account)
       end
 
@@ -68,7 +68,7 @@ module Fintoc
         @mode == 'test'
       end
 
-      def simulate_receive_transfer(amount:)
+      def simulate_receive_transfer(amount:, idempotency_key: nil)
         unless test_mode?
           raise Fintoc::Errors::InvalidRequestError, 'Simulation is only available in test mode'
         end
@@ -76,7 +76,8 @@ module Fintoc
         @client.simulate.receive_transfer(
           account_number_id: @root_account_number_id,
           amount:,
-          currency: @currency
+          currency: @currency,
+          idempotency_key:
         )
       end
 

data/lib/fintoc/v2/resources/account_number.rb

@@ -42,13 +42,13 @@ module Fintoc
         refresh_from_account_number(fresh_account_number)
       end
 
-      def update(description: nil, status: nil, metadata: nil)
+      def update(description: nil, status: nil, metadata: nil, idempotency_key: nil)
         params = {}
         params[:description] = description if description
         params[:status] = status if status
         params[:metadata] = metadata if metadata
 
-        updated_account_number = @client.account_numbers.update(@id, **params)
+        updated_account_number = @client.account_numbers.update(@id, idempotency_key:, **params)
         refresh_from_account_number(updated_account_number)
       end
 
@@ -68,7 +68,7 @@ module Fintoc
         @mode == 'test'
       end
 
-      def simulate_receive_transfer(amount:, currency: 'MXN')
+      def simulate_receive_transfer(amount:, currency: 'MXN', idempotency_key: nil)
         unless test_mode?
           raise Fintoc::Errors::InvalidRequestError, 'Simulation is only available in test mode'
         end
@@ -76,7 +76,8 @@ module Fintoc
         @client.simulate.receive_transfer(
           account_number_id: @id,
           amount:,
-          currency:
+          currency:,
+          idempotency_key:
         )
       end
 

data/lib/fintoc/v2/resources/transfer.rb

@@ -62,8 +62,8 @@ module Fintoc
         refresh_from_transfer(fresh_transfer)
       end
 
-      def return_transfer
-        returned_transfer = @client.transfers.return(@id)
+      def return_transfer(idempotency_key: nil)
+        returned_transfer = @client.transfers.return(@id, idempotency_key:)
         refresh_from_transfer(returned_transfer)
       end
 

data/lib/fintoc/version.rb

@@ -1,3 +1,3 @@
 module Fintoc
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fintoc
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Juan Ca Sardin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2025-09-08 00:00:00.000000000 Z
+date: 2025-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: http