Send Your First Payment with V2

Create an entity, open a wallet, create a beneficiary with V2 field discovery, and submit your first payment.

Before you begin

1. Get your API key and user ID, then verify authentication with the Authentication reference.
2. Have your platform_id ready for createBusinessEntity or createPersonalEntity.
3. Decide whether your sender is a business or personal entity.
4. Decide the destination country, destination currency, beneficiary type, and preferred payment method for your first payout.

This guide uses resourceCorridorsV2 and beneficiaryRequiredFieldsV2 for corridor and beneficiary setup. Entity, wallet, and transfer submission still use the current entity and transfer mutations documented in the API reference.

1. Verify your API key

Start by confirming your bearer token works. Use the request on the Authentication page and make sure the myUser query returns your user record.

Save the id from myUser. You will use that value as user_id in later mutations.

2. Set up webhooks before you onboard or send funds

Create webhook subscriptions with createWebhookSubscription so your application receives status changes without polling.

Create subscriptions for these event types first:

• entity
• beneficiary
• transfer

Use these webhook events to know when an entity is approved, when a beneficiary is verified, and when a transfer changes state.

3. Pick a supported payout corridor with V2

Run resourceCorridorsV2 to see which destination countries and currencies are available, along with the supported payment methods for each corridor.

For each corridor, the response shows:

• country
• currency
• supported paymentMethod values such as local, swift, mobile, and fedwire
• supported beneficiary types under each payment method (personal and business)
• min, max, and timeline values for each supported route

Use this step to choose the corridor you want to support before you collect beneficiary banking details.

4. Create your sender entity

Every payment flow in your docs depends on an entity_id, so create the sender first.

Business entity flow

1. Run entityRequiredFields with the sender's country, entity_type, and business_type.
2. Review the returned fields, documents, and requires_representatives values.
3. Submit createBusinessEntity with the required business and contact fields.
4. If documents are required, upload them with singleUpload using entity_id.

createBusinessEntity requires these core inputs:

Personal entity flow

1. Run entityRequiredFields with the sender's country and entity_type.
2. Submit createPersonalEntity with the required personal details.

createPersonalEntity requires these core inputs:

If representatives are required

If entityRequiredFields returns requires_representatives, continue with representative onboarding before finalizing the entity.

1. Run representativeRequiredFields.
2. Create each required owner or authorized representative with createRepresentative.
3. Mark one representative as the signer by setting is_signer to true.
4. Upload representative documents with singleUpload using representative_id.

5. Finalize the entity and wait for approval

When the entity record, documents, and representatives are complete, call finalizeEntity with the entity_id.

Do not create a wallet or beneficiary until the entity has passed onboarding. Use your entity webhook subscription to watch for status changes.

6. Create a wallet for the approved entity

Run createWallet after the entity is approved.

createWallet requires:

Create the wallet in the currency you plan to use to fund the payment flow.

7. Get beneficiary requirements with V2

Run beneficiaryRequiredFieldsV2 with:

The V2 response groups requirements by payment method:

• local
• swift
• mobile
• fedwire

Inside each payment method, review the requirements for the beneficiary type you are creating:

• personal
• business

Collect the fields from the exact branch you plan to use. For example, if you are sending a local payment to a business beneficiary, use local.business.

8. Create the beneficiary

Use the fields returned by beneficiaryRequiredFieldsV2 to build the beneficiary creation request.

• Use createBusinessBeneficiary for companies.
• Use createPersonalBeneficiary for individuals.

Both mutations require user_id, entity_id, email, bank details, currency, and bank_country. The exact required fields depend on the corridor and payment method you selected in the previous step.

Some beneficiary attributes cannot be edited after creation, including:

• type
• bank_country
• currency
• creator
• entity

After creation, wait until the beneficiary is approved or reaches a verified state before creating the transfer.

9. Create the transfer

Run createTransfer after you have:

• a verified entity_id
• a wallet_id
• a verified beneficiary_id

createTransfer supports these key inputs:

Save the returned transfer_id. You will use it to quote, finalize, and track the payment.

Optional: lock an FX quote before you send the payment

If the transfer includes a currency conversion, call getTransferQuote before finalizing.

getTransferQuote:

• locks the rate for a limited time
• returns the fee for the payment
• lets you send either source_amount or destination_amount, but not both

Use this when you want to show the sender the exact quoted rate and fee before you execute the transfer.

Sandbox rates do not represent real-world pricing.

10. Finalize the transfer

When the transfer details are ready, call finalizeTransfer with the transfer_id.

This is the step that initiates execution of the transfer.

11. Track the payment after submission

Use the transfer query and your transfer webhook subscription to monitor the payment after finalization.

The transfer response includes useful operational fields such as:

• state
• source_amount
• source_currency
• destination_amount
• destination_currency
• fee
• rate
• expected_delivery_date
• funding_instructions

Use States to map each transfer status in your application. A successful transfer can move through states such as Accepted, Finalized, Initiated, Processing, Sent, and Completed.

Optional: handle review and document requests

If a transfer enters In Review, upload supporting documents with upload-transfer-document.

Your docs note that you can attach up to three documents to a transfer. Use this step if Routefusion requests additional information during compliance review.

If a transfer reaches Returned, the beneficiary bank sent the funds back and may require additional information. Check the transfer state and follow up with Support as needed.

Next steps

After your first payment succeeds, you can improve the flow by:

• creating more webhook handlers for operational updates
• storing corridor and beneficiary requirement selections in your application
• quoting FX before finalization for converted payments
• using the transferReceipt query when you need a PDF receipt