End-to-End Payment Journey

[!NOTE] Who is this for? This guide demonstrates the standard Direct Integration (1st-Party / Own Funds) flow. If you are an Atlas platform partner executing payments on behalf of sub-accounts, use the platform-specific sub-account and payout guides instead.

Use this flow when you need to fund a payout from your own wallet, create or validate a beneficiary, convert currency if required, and track the payment through to its final state.

✅ Before you start

Complete these steps before you run the payment flow:

Authenticate with the merged Login service and store the returned token and companyId.
Make sure the source wallet exists and has enough availableBalance.
Gather the beneficiary bank or stablecoin wallet details for the target corridor.
Decide whether the payment needs FX conversion before payout.
Register a webhook endpoint so you can track final payout or FX state changes.
Generate a unique paymentId or idempotency key for write requests.

Use Environments to configure the service-specific sandbox hosts for Login, Wallet, Beneficiary, Exchange, and Onboarding.

📚 Use this page with the recipe

This guide explains when to use the direct payout flow and the minimum sequence. For the full implementation walkthrough, use the recipe:

End-to-End Payment Flow Recipe →

🛣️ The Execution Fork (B2B vs. C2B)

Depending on your payout destination, Verto routes funds differently:

Trajectory	Entity Type	Data Requirements	Speed
B2B (Business-to-Business)	Paying a supplier or corporate vendor.	Requires Company Registration numbers and complete corporate addresses.	Standard SWIFT/Local timelines.
C2B/C2C (Consumer Payouts)	Paying a contractor, freelancer, or gig worker.	Requires personal ID (National ID/Passport) data in certain high-risk corridors.	Often eligible for Instant Rails (e.g., M-Pesa, FPS).

sequenceDiagram
    participant A as Your App
    participant V as Verto API
    participant B as Bank Rail

    A->>V: 1. Login and store token + companyId
    V-->>A: token, companyId
    A->>V: 2. Create or fetch beneficiary
    V-->>A: beneficiary id + verificationState
    A->>V: 3. Get FX rate when conversion is required
    V-->>A: rate + vfx_token
    A->>V: 4. Create FX trade or payout
    V-->>A: paymentId + trade reference
    V->>B: Dispatch Funds
    B-->>V: Status: COMPLETED
    V-->>A: 5. Webhook or status update

The direct payout workflow

This use case follows a simple sequence:

Authenticate with Login, then store token and companyId.
Confirm the source wallet with Get all Wallets or create one with Create wallet.
Create or fetch the beneficiary with Create beneficiary or Fetch beneficiary by ID.
Check beneficiary readiness before payout selection.
Fetch the FX rate with Get FX rate if the payout currency differs from the source wallet currency.
Create the FX trade or payout with Create FX trade before the vfx_token expires.
Track final state through webhooks and, for FX-backed payouts, Get FX trade details.

Check these beneficiary readiness fields before you move funds:

Field	What to check
`verificationState`	Use `approved` beneficiaries for payment flows.
`isAccountActive`	Do not use inactive beneficiary accounts.
`isArchived`	Do not show archived beneficiaries for selection.
`isUpdateRequired`	Route beneficiaries needing updates into remediation before payout.
`paymentMode`	Confirm the beneficiary supports the payout route you need.

What makes this use case different?

Unlike the platform payout flows, this guide is for direct integrations where:

you operate from your own wallet context
you do not need X-Sub-Account-Id to scope the transaction
beneficiary creation, FX conversion, and payout all happen under your primary integration identity
company-scoped wallet calls use the companyId returned by login

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Success indicators

Status or field	Meaning
`paymentId`	Your unique request identifier for duplicate prevention and reconciliation.
`reference`	Verto FX trade reference returned after trade creation.
`state`	Current FX trade or payout state.
`inwardSettlementTime`	Time when source-side settlement occurred.
`outwardSettlementTime`	Time when destination-side settlement occurred.

Only mark the payment as final in your application when the webhook-driven state or retrieved trade status reaches the completed outcome your business logic requires.

Troubleshooting

Issue	What to check
Beneficiary creation fails	Verify the routing fields, stablecoin wallet details, currency, and country data for the payout corridor.
Beneficiary cannot be used	Check `verificationState`, `isAccountActive`, `isArchived`, and `isUpdateRequired`.
Conversion cannot be booked	Confirm the `vfx_token` is still valid and the source wallet has enough `availableBalance`.
Payout request times out	Reconcile using the original `paymentId` or idempotency key before retrying with a new identifier.
Payment stays in an intermediate state	Check webhook deliveries and confirm whether compliance review, RFI handling, or route-specific settlement timing is delaying completion.

Next steps


Sub-Accounts → See the platform pattern for isolated downstream customer ledgers and receiving details.	Handle RFIs and Compliance Exceptions → Pause review-blocked payments safely and avoid duplicate retries.