From a0628e9116e72c99688f7c3e1a236f5036fda399 Mon Sep 17 00:00:00 2001 From: Francisca Otero Date: Mon, 16 Nov 2026 12:05:33 +0000 Subject: [PATCH] Add crossborder transfer cancel/simulate_credit and evm_address beneficiaries Co-authored-by: fin-compose[bot] <255610621+fin-compose[bot]@users.noreply.github.com> --- README.md | 13 +++ lib/fintoc/errors.rb | 5 ++ .../crossborder_beneficiaries_manager.rb | 8 +- .../managers/crossborder_transfers_manager.rb | 13 +++ .../v2/resources/crossborder_beneficiary.rb | 19 ++++- lib/fintoc/v2/resources/crossborder_quote.rb | 6 +- spec/fixtures/v2/crossborder_beneficiary.json | 4 + spec/fixtures/v2/crossborder_quote.json | 1 + spec/fixtures/v2/crossborder_transfer.json | 4 + spec/lib/fintoc/base_client_spec.rb | 7 +- .../v2/managers/crossborder_manager_spec.rb | 84 +++++++++++++++++++ 11 files changed, 151 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index e1be30b..653d123 100644 --- a/README.md +++ b/README.md @@ -596,6 +596,14 @@ beneficiary = client.v2.crossborder.beneficiaries.create( beneficiaries = client.v2.crossborder.beneficiaries.list(limit: 10) client.v2.crossborder.beneficiaries.delete(beneficiary.id) # archives the beneficiary +wallet = client.v2.crossborder.beneficiaries.create( + holder_type: 'business', + business_name: 'Acme LLC', + account_scheme: 'evm_address', + network: 'polygon', + account_identifier: '0x52908400098527886E0F7030069857D2E4169EE7' +) + quote = client.v2.crossborder.quotes.create(direction: 'mx_to_usd', source_amount: 200001) quote = client.v2.crossborder.quotes.get(quote.id) @@ -605,6 +613,11 @@ transfer = client.v2.crossborder.transfers.create( transfer.funding_instructions[:clabe] transfers = client.v2.crossborder.transfers.list(status: %w[pending_funds failed], direction: 'mx_to_usd') transfer = client.v2.crossborder.transfers.get('crossborder_transfer_id') + +# usdt_to_mx transfers waiting for their USDT can be canceled +client.v2.crossborder.transfers.cancel('crossborder_transfer_id') +# Test mode only: simulates the arrival of the pesos of a usdt_to_mx transfer +client.v2.crossborder.transfers.simulate_credit('crossborder_transfer_id') ``` #### Simulate diff --git a/lib/fintoc/errors.rb b/lib/fintoc/errors.rb index 95f9466..e013714 100644 --- a/lib/fintoc/errors.rb +++ b/lib/fintoc/errors.rb @@ -96,6 +96,7 @@ class NotSupportedRefundableResourceTypeError < FintocError; end class SplitFlatNotAllowedInIndexedSubscriptionError < FintocError; end class SplitNotAvailableError < FintocError; end class SplitSumMismatchError < FintocError; end + class CreditSimulationUnavailableError < FintocError; end # 401 Unauthorized Errors class AuthenticationError < FintocError; end @@ -185,6 +186,9 @@ class ChargeInProgressError < FintocError; end class CheckoutSessionNotInProgressError < FintocError; end class NoCardSubmittedError < FintocError; end class QuoteAlreadyAcceptedError < FintocError; end + class CreditAlreadySimulatedError < FintocError; end + class TransferNotCancellableError < FintocError; end + class UsdtCollectionAlreadyOpenError < FintocError; end # 422 Unprocessable Entity Errors class AccountBlockedForDirectDebitError < FintocError; end @@ -231,6 +235,7 @@ class OnboardingNotAvailableError < FintocError; end class OrganizationWithoutOperationalRootEntityError < FintocError; end class PaymentCancellationNotSupportedError < FintocError; end class PaymentMethodInactiveError < FintocError; end + class PaymentMethodCanceledError < FintocError; end class PaymentMethodTypeNotAvailableError < FintocError; end class PaymentMethodTypeNotSupportedError < FintocError; end class PaymentMethodUnavailableError < FintocError; end diff --git a/lib/fintoc/v2/managers/crossborder_beneficiaries_manager.rb b/lib/fintoc/v2/managers/crossborder_beneficiaries_manager.rb index 70fa105..7667ded 100644 --- a/lib/fintoc/v2/managers/crossborder_beneficiaries_manager.rb +++ b/lib/fintoc/v2/managers/crossborder_beneficiaries_manager.rb @@ -8,13 +8,9 @@ def initialize(client) @client = client end - def create( - holder_type:, account_identifier:, routing_number:, bank_name:, address:, - idempotency_key: nil, **params - ) + def create(holder_type:, account_identifier:, idempotency_key: nil, **params) data = @client.post(version: :v2, idempotency_key:).call( - 'crossborder/beneficiaries', - holder_type:, account_identifier:, routing_number:, bank_name:, address:, **params + 'crossborder/beneficiaries', holder_type:, account_identifier:, **params ) build_beneficiary(data) end diff --git a/lib/fintoc/v2/managers/crossborder_transfers_manager.rb b/lib/fintoc/v2/managers/crossborder_transfers_manager.rb index 1f4a25c..240fff0 100644 --- a/lib/fintoc/v2/managers/crossborder_transfers_manager.rb +++ b/lib/fintoc/v2/managers/crossborder_transfers_manager.rb @@ -27,6 +27,19 @@ def get(transfer_id) build_transfer(data) end + def cancel(transfer_id, idempotency_key: nil) + data = @client.post(version: :v2, idempotency_key:) + .call("crossborder/transfers/#{transfer_id}/cancel") + build_transfer(data) + end + + # Test mode only. + def simulate_credit(transfer_id, idempotency_key: nil) + data = @client.post(version: :v2, idempotency_key:) + .call("crossborder/transfers/#{transfer_id}/simulate_credit") + build_transfer(data) + end + private def build_transfer(data) diff --git a/lib/fintoc/v2/resources/crossborder_beneficiary.rb b/lib/fintoc/v2/resources/crossborder_beneficiary.rb index c04e53b..cfa5829 100644 --- a/lib/fintoc/v2/resources/crossborder_beneficiary.rb +++ b/lib/fintoc/v2/resources/crossborder_beneficiary.rb @@ -1,20 +1,24 @@ module Fintoc module V2 class CrossborderBeneficiary - attr_reader :id, :object, :mode, :holder_type, :business_name, :first_name, :last_name, - :bank_name, :routing_number, :account_last4, :address, :archived_at, - :created_at + attr_reader :id, :object, :mode, :account_scheme, :currency, :network, :holder_type, + :business_name, :first_name, :last_name, :bank_name, :routing_number, + :account_identifier, :account_last4, :address, :archived_at, :created_at - def initialize( + def initialize( # rubocop:disable Metrics/MethodLength id:, object:, mode: nil, + account_scheme: nil, + currency: nil, + network: nil, holder_type: nil, business_name: nil, first_name: nil, last_name: nil, bank_name: nil, routing_number: nil, + account_identifier: nil, account_last4: nil, address: nil, archived_at: nil, @@ -24,12 +28,16 @@ def initialize( @id = id @object = object @mode = mode + @account_scheme = account_scheme + @currency = currency + @network = network @holder_type = holder_type @business_name = business_name @first_name = first_name @last_name = last_name @bank_name = bank_name @routing_number = routing_number + @account_identifier = account_identifier @account_last4 = account_last4 @address = address @archived_at = archived_at @@ -41,6 +49,9 @@ def archived? end def to_s + return "Crossborder beneficiary (#{@id}) - #{@network} #{@account_identifier}" if + @account_scheme == 'evm_address' + "Crossborder beneficiary (#{@id}) - #{@bank_name} ****#{@account_last4}" end end diff --git a/lib/fintoc/v2/resources/crossborder_quote.rb b/lib/fintoc/v2/resources/crossborder_quote.rb index c02ee04..b639aad 100644 --- a/lib/fintoc/v2/resources/crossborder_quote.rb +++ b/lib/fintoc/v2/resources/crossborder_quote.rb @@ -2,8 +2,8 @@ module Fintoc module V2 class CrossborderQuote attr_reader :id, :object, :mode, :status, :direction, :source_amount, :source_currency, - :target_amount, :target_currency, :exchange_rate, :fees, :transfer_id, - :expires_at, :created_at + :target_amount, :target_currency, :exchange_rate, :fees, :kind, + :transfer_id, :expires_at, :created_at def initialize( id:, @@ -17,6 +17,7 @@ def initialize( target_currency: nil, exchange_rate: nil, fees: nil, + kind: nil, transfer_id: nil, expires_at: nil, created_at: nil, @@ -33,6 +34,7 @@ def initialize( @target_currency = target_currency @exchange_rate = exchange_rate @fees = fees + @kind = kind @transfer_id = transfer_id @expires_at = expires_at @created_at = created_at diff --git a/spec/fixtures/v2/crossborder_beneficiary.json b/spec/fixtures/v2/crossborder_beneficiary.json index b21546c..c344bc7 100644 --- a/spec/fixtures/v2/crossborder_beneficiary.json +++ b/spec/fixtures/v2/crossborder_beneficiary.json @@ -2,12 +2,16 @@ "id": "xbb_2u6XjsX2BD3F8MzKQJf4Tr7Pcxw", "object": "crossborder_beneficiary", "mode": "live", + "account_scheme": "us_aba", + "currency": "USD", + "network": null, "holder_type": "business", "business_name": "Acme LLC", "first_name": null, "last_name": null, "bank_name": "JPMorgan Chase Bank, N.A.", "routing_number": "021000021", + "account_identifier": null, "account_last4": "6789", "address": { "street_line1": "100 Main St", diff --git a/spec/fixtures/v2/crossborder_quote.json b/spec/fixtures/v2/crossborder_quote.json index a1846a8..645897a 100644 --- a/spec/fixtures/v2/crossborder_quote.json +++ b/spec/fixtures/v2/crossborder_quote.json @@ -12,6 +12,7 @@ "currency": "MXN" } ], + "kind": "locked", "mode": "live", "source_amount": 200001, "source_currency": "MXN", diff --git a/spec/fixtures/v2/crossborder_transfer.json b/spec/fixtures/v2/crossborder_transfer.json index 33b24c5..5f397fa 100644 --- a/spec/fixtures/v2/crossborder_transfer.json +++ b/spec/fixtures/v2/crossborder_transfer.json @@ -21,12 +21,16 @@ "id": "xbb_2u6XjsX2BD3F8MzKQJf4Tr7Pcxw", "object": "crossborder_beneficiary", "mode": "live", + "account_scheme": "us_aba", + "currency": "USD", + "network": null, "holder_type": "business", "business_name": "Acme LLC", "first_name": null, "last_name": null, "bank_name": "JPMorgan Chase Bank, N.A.", "routing_number": "021000021", + "account_identifier": null, "account_last4": "6789", "address": { "street_line1": "100 Main St", diff --git a/spec/lib/fintoc/base_client_spec.rb b/spec/lib/fintoc/base_client_spec.rb index 20f57c3..5ea07d5 100644 --- a/spec/lib/fintoc/base_client_spec.rb +++ b/spec/lib/fintoc/base_client_spec.rb @@ -444,7 +444,12 @@ def expect_error(klass, status:, code:) 'card_confirmation_expired' => 'CardConfirmationExpiredError', 'charge_in_progress' => 'ChargeInProgressError', 'checkout_session_not_in_progress' => 'CheckoutSessionNotInProgressError', - 'no_card_submitted' => 'NoCardSubmittedError' + 'no_card_submitted' => 'NoCardSubmittedError', + 'credit_simulation_unavailable' => 'CreditSimulationUnavailableError', + 'credit_already_simulated' => 'CreditAlreadySimulatedError', + 'transfer_not_cancellable' => 'TransferNotCancellableError', + 'usdt_collection_already_open' => 'UsdtCollectionAlreadyOpenError', + 'payment_method_canceled' => 'PaymentMethodCanceledError' }.each do |code, klass| it "resolves the #{code} error" do expect(client.send(:error_class, code)).to eq(Fintoc::Errors.const_get(klass)) diff --git a/spec/lib/fintoc/v2/managers/crossborder_manager_spec.rb b/spec/lib/fintoc/v2/managers/crossborder_manager_spec.rb index 3c3cfa0..813cad0 100644 --- a/spec/lib/fintoc/v2/managers/crossborder_manager_spec.rb +++ b/spec/lib/fintoc/v2/managers/crossborder_manager_spec.rb @@ -7,6 +7,15 @@ let(:base_url) { 'https://api.fintoc.com/v2/crossborder' } let(:headers) { { 'Content-Type' => 'application/json' } } + let(:evm_wallet) { '0x52908400098527886e0f7030069857d2e4169ee7' } + let(:evm_payload) do + fixture('crossborder_beneficiary').merge( + account_scheme: 'evm_address', currency: 'USDT', network: 'polygon', + account_identifier: evm_wallet, account_last4: nil, bank_name: nil, + routing_number: nil, address: nil + ) + end + def fixture(name) JSON.parse(File.read("spec/fixtures/v2/#{name}.json"), symbolize_names: true) end @@ -27,6 +36,12 @@ def fixture(name) expect(resource.to_s).to eq("Crossborder #{name} (#{payload[:id]}) - #{summary}") end end + + it 'describes an evm_address beneficiary by its wallet' do + beneficiary = Fintoc::V2::CrossborderBeneficiary.new(**evm_payload) + expect(beneficiary.to_s) + .to eq("Crossborder beneficiary (#{evm_payload[:id]}) - polygon #{evm_wallet}") + end end describe '#beneficiaries' do @@ -52,6 +67,23 @@ def fixture(name) expect(manager.create(**params, idempotency_key: 'beneficiary-create')) .to be_a(Fintoc::V2::CrossborderBeneficiary).and have_attributes(payload) end + + context 'with an evm_address account' do + let(:params) do + { holder_type: 'business', account_identifier: evm_wallet, + account_scheme: 'evm_address', network: 'polygon', business_name: 'Acme LLC' } + end + + before do + stub_request(:post, collection_url) + .with(body: params.to_json) + .to_return(status: 201, body: evm_payload.to_json, headers: headers) + end + + it 'creates the beneficiary without bank details' do + expect(manager.create(**params)).to have_attributes(evm_payload) + end + end end describe '#list' do @@ -196,5 +228,57 @@ def fixture(name) .to be_a(Fintoc::V2::CrossborderTransfer).and have_attributes(expected_attributes) end end + + describe '#cancel' do + let(:canceled) do + payload.merge(direction: 'usdt_to_mx', status: 'canceled', beneficiary: nil, + funding_instructions: nil, canceled_at: '2026-11-09T12:00:00Z') + end + + before do + stub_request(:post, "#{collection_url}/#{payload[:id]}/cancel") + .with(headers: { 'Idempotency-Key' => 'transfer-cancel' }) + .to_return(body: canceled.to_json, headers: headers) + end + + it 'returns the canceled transfer' do + expect(manager.cancel(payload[:id], idempotency_key: 'transfer-cancel')) + .to be_a(Fintoc::V2::CrossborderTransfer).and have_attributes(canceled) + end + + context 'when the transfer cannot be canceled' do + before do + stub_request(:post, "#{collection_url}/xbt_funded/cancel").to_return( + status: 409, headers: headers, + body: { error: { type: 'invalid_request_error', code: 'transfer_not_cancellable', + message: 'Transfer not cancellable' } }.to_json + ) + end + + it 'raises the transfer not cancellable error' do + expect { manager.cancel('xbt_funded') } + .to raise_error(Fintoc::Errors::TransferNotCancellableError) { |error| + expect(error).to have_attributes(status: 409, code: 'transfer_not_cancellable') + } + end + end + end + + describe '#simulate_credit' do + let(:in_progress) do + payload.merge(mode: 'test', direction: 'usdt_to_mx', status: 'in_progress', + beneficiary: nil, funding_instructions: nil) + end + + before do + stub_request(:post, "#{collection_url}/#{payload[:id]}/simulate_credit") + .to_return(body: in_progress.to_json, headers: headers) + end + + it 'returns the transfer' do + expect(manager.simulate_credit(payload[:id])) + .to be_a(Fintoc::V2::CrossborderTransfer).and have_attributes(in_progress) + end + end end end