1. Reference
Partner API
  • Getting Started
    • Introduction
    • Authentication
    • Business Use Cases
  • API References
    • Partner Operations
      • Balances & Transaction History
        • Get Balances
        • Get Transaction History
        • Create Wallet
      • Currency Exchange
        • Retrieve Exchange Rate
        • Retrieve Exchange Rate and Create a Lock
        • Create and Finalize an Exchange
        • Retrieve Detailed Exchange Information
      • SEPA Transfers
        • Get SEPA Deposit Info
        • Get SEPA Deposit Contact List
        • Create a SEPA Transfer
        • Get SEPA Transfer Details
      • Crypto Withdrawal
        • Get Network Fee
        • Create Crypto Withdrawal
        • Get Crypto Withdrawal Details
      • Crypto Deposits
        • Update Travel Rule
      • Orders
        • Get Rates
        • Retrieve Order Rate and Create a Lock
        • Create and Finalize an Order
        • Get Order Details
      • Payment link & Checkout Link
        • Generate Payment Link
        • Generate Hosted Checkout
        • Get Payment Link Details
    • User Operations
      • Onboarding & KYC Flow
        • Create User Account
        • Method A: Add KYC File
        • Method B: Creating KYC Verification
        • Method B: Redirect to Verification
        • Method B: Get KYC Status
        • Add User Verification
        • Add POA File
      • Account Management
        • Update Existing User
        • Delete User
        • Suspend User
        • Unsuspend User
      • Balances & Transaction History
        • Get User Balances
        • Get User Transaction History
      • Currency Exchange
        • Retrieve Exchange Rate
        • Retrieve Exchange Rate and Create a Lock
        • Create and Finalize an Exchange
        • Retrieve Detailed Exchange Information
      • SEPA Transfers
        • Get SEPA Deposit Info
        • GET SEPA Deposit Contact List
        • Create a SEPA Transfer
        • Get SEPA Transfer Details
      • Crypto Withdrawal
        • Get Network Fee
        • Create Crypto Withdrawal
        • Get Crypto Withdrawal Details
      • Crypto Deposits
        • Update Travel Rule
      • Internal Transfers
        • Create a Transfer
        • Get Transfer Details
      • Virtual Cards
        • Create Virtual Card
        • Get All User Cards
        • Get Card Details
        • Update Card PIN
        • Block Card
        • Unblock Card
        • Get Card Limits
        • Update Card Limits
        • Delete Card
  • Integration
    • SDKs & Integration Guides
    • Transaction Processing
    • Error Handling
    • Rate Limiting
    • Webhooks
      • User & KYC Webhooks
        • User Balance Generation Webhook
        • KYC File Added Webhook
        • POA Verification Status Webhook
        • KYC Verification Status Webhook
        • Create Wallet Webhook
        • High Risk KYC Verification Webhook
      • Transfers & Payments Webhooks
        • Internal Transfer Webhook
        • IBAN Status Webhook
        • Partner SEPA Transfer Webhook
        • User SEPA Transfer Webhook
        • SEPA Deposit Webhook
        • Crypto Withdrawal Webhook
        • Crypto Deposit Webhook
        • Exchange Webhook
        • Card Transaction Webhook
        • Order Status Webhook
        • Payment Link Webhook
      • Card Webhooks
        • Card 3DS Code Webhook
        • Card Activation Code Webhook
  • Reference
    • Supported Countries
    • Supported Currencies
    • Fees
    • FAQ
    • Changelog
    • Support
  1. Reference

FAQ

Quick answers to common questions about using the Fintegence Partner API.
This page focuses on the most common onboarding, authentication, KYC, payments, and webhook questions that appear during integration.

General and Authentication#

How do I get API credentials?
To access the Fintegence Partner API, you need to complete the partner onboarding process.
1.
Contact support@fintegence.com and request partner onboarding.
2.
Our team reviews your setup and onboarding details.
3.
After approval, your Business Account is prepared.
4.
You receive:
a staging API key,
a production API key,
a webhook security token.
What is the difference between staging and production?
EnvironmentBase URLPurposeData
Staginghttps://stage-api.fintegence.ioDevelopment and testingTest data
Productionhttps://api.fintegence.ioLive operationsReal funds and transactions
Best practices:
always validate full flows in staging first,
never mix staging keys with production URLs,
keep environment switching configurable in your backend.
Why am I getting 401 Unauthorized?
This usually means there is an API key or environment mismatch.
Check the following:
the request includes the x-api-key header,
the key has no leading or trailing spaces,
the key belongs to the same environment as the URL,
in production, your server IP is whitelisted.
Typical causes:
xo1: API key not provided,
xo2: API key invalid,
xo3: production request comes from a non-whitelisted IP.
Does a 2xx response mean the transaction succeeded?
No. In the Fintegence API, a 2xx response usually means the request was accepted into the processing queue.
The final outcome is determined later during background processing, for example after balance checks, compliance validation, or risk review. Always confirm the final state through:
the relevant webhook, or
the matching details endpoint.

User Management and KYC#

How do I know when a new user balance is ready?
User balances and wallet configuration are not considered ready immediately after Create User.
The operational signal is the User Balance Generation Webhook. Once that webhook is emitted, the user has passed the required checks and the balance structure is active for use.
Typical flow:
1.
Create the user.
2.
Complete KYC using Method A or Method B.
3.
Complete POA only if required.
4.
Wait for the User Balance Generation Webhook.
5.
Then call the user balances endpoint.
What is POA and when is it required?
POA means Proof of Address.
It is optional by default, but becomes mandatory when the Create User Account response indicates:
"poaRequiredForExtended": true
In that case you must:
1.
upload POA documents,
2.
wait for the POA approval webhook,
3.
only then finalize the user verification flow.
Common POA examples:
utility bill,
bank statement,
government-issued official letter,
tax bill.
Can a user change country of residence later?
No. Country of residence cannot be changed after account creation.
If a user must operate under a different country, the existing account should be offboarded and a new user should be created under the correct jurisdiction.
Where do I check supported countries and supported currencies?
Use the reference guides for operational scope checks:
Supported Countries for KYC jurisdiction coverage and POA requirements,
Supported Currencies for currently documented fiat, stablecoin, and crypto assets and their networks.
Treat those pages as reference lists when preparing onboarding and transaction flows.

SEPA and Internal Transfers#

Why can not a user withdraw EUR to any bank account?
User SEPA withdrawals follow a closed-loop verification model.
The destination IBAN must first be verified through an incoming deposit flow:
1.
Call Get User SEPA Info and display the virtual IBAN and mandatory title reference.
2.
The user sends a verification deposit from their own bank account.
3.
The system compares the sender name with the user verified KYC name.
4.
If the check passes, the IBAN becomes approved and appears in the Contact List.
5.
Only approved IBANs can be used for later user SEPA withdrawals.
Important: the title reference must be included exactly as provided, otherwise automatic verification and crediting may fail.
How do internal transfers work?
Internal Transfers move funds between partner and user accounts.
Supported directions:
Partner to User: provide destinationExternalUserId,
User to Partner: provide sourceExternalUserId.
Important rules:
direct user-to-user transfers are not supported,
internal transfers are currently for cryptocurrency and stablecoin flows,
fiat transfers such as EUR are not currently supported,
these transfers are treated as fee-free in the current standard model,
requests are still processed asynchronously, so final confirmation should come from webhook or details status.

Exchange, Payments, and Travel Rule#

What is the difference between Get Rates and Create a Lock?
Get Rates is informational. It gives you an indicative market price.
Create a Lock gives you an executable rate that is reserved for a short time window, approximately 60 seconds in the current documented exchange flow.
Typical pattern:
1.
show an estimate with Get Rates,
2.
request a final executable quote with Create a Lock,
3.
use the returned lockId immediately for execution.
What is the difference between Standard Payment Link and Hosted Checkout?
Standard Payment Link uses the global Fintegence standard configuration.
Hosted Checkout uses your dedicated partner configuration and brand identity.
In practice:
Standard Payment Link is the faster standard setup,
Hosted Checkout is the more tailored white-label setup,
Hosted Checkout requires onboarding-time configuration for things such as branding, lock durations, and underpayment windows.
What is the Travel Rule and when do I need to act?
Travel Rule handling becomes relevant when a crypto deposit enters WAITING_FOR_TR_DATA.
At that point:
the deposit remains locked,
you must submit the required originator data,
compliance review must pass before the funds are released.
Use the crypto deposit webhook to detect the status transition and use the Update Travel Rule endpoint to provide the required sender details.
How should I think about fees?
Treat fees as a commercial layer defined by your agreement with Fintegence.
At a high level:
pricing may apply across exchanges, SEPA withdrawals, crypto withdrawals, KYC-related services, and other enabled product operations,
internal transfers are the current fee-free exception,
for crypto withdrawals, the operational cost view may include both configured withdrawal fee data from balances and the current dynamic network fee.
For implementation guidance, use the dedicated Fees page rather than hardcoding assumptions from examples.

Webhooks and Operational Reliability#

How do I verify webhook authenticity?
Every webhook request includes your shared secret in the Authorization header.
Recommended process:
1.
read the Authorization header,
2.
compare it with your stored webhook secret,
3.
return 401 for missing or invalid values,
4.
only process payloads that pass verification.
What happens if my webhook endpoint fails?
Webhook delivery is retried automatically when your endpoint fails or does not acknowledge the request correctly.
Current documented retry model:
AttemptDelay After Previous Failure
1stInitial delivery
2nd~8 seconds
3rd~16 seconds
4th~32 seconds
5th~64 seconds
Retry is triggered by non-2xx responses or timeouts. Each request times out after approximately 10 seconds.
Your webhook consumer should be idempotent, because the same event may be delivered more than once.
Are card services currently available?
Current documentation marks card services and card webhooks as suspended.
If your commercial agreement mentions card-related capabilities, treat them as inactive unless Fintegence explicitly re-enables that module for your environment.
Previous
Fees
Next
Changelog
Built with