FAQ

Quick answers to common questions about using the P100 Partner API

Find solutions to the most frequently encountered issues and questions during API integration.

🔐 General & Authentication

How do I get an API key?

To access the P100 Partner API, you'll need a P100 Business Account:

Apply for a Business Account → Visit P100.io

Account Review → Our team will review your application.

Onboarding → Once approved, you'll receive:

Staging API key (partner-api-stage.p100.io)

Production API key (partner-api.p100.io)

Integration documentation and dedicated support

What's the difference between staging and production environments?

Environment	URL	Purpose	Data
Staging	`https://partner-api-stage.p100.io`	Development & Testing	Test data, no real money
Production	`https://partner-api.p100.io`	Live Operations	Real transactions & funds

Best Practices:

Always test thoroughly in staging before production deployment.

Never use production keys in development/testing.

Ensure your backend dynamically switches the URL based on the environment.

❌ Getting "401 Unauthorized" error?

This indicates an API key authentication problem. Check the following:

✅ Quick Fix Checklist:

Common Issues:

❌ Header Name — Must be exactly x-api-key (all lowercase).

❌ Key Value — Ensure there are no leading or trailing spaces.

❌ Environment Mismatch — Using a staging key on a production URL will result in a 401.

👤 User Management & KYC

How do I get a user's balance for the first time?

Balances and crypto wallets are not created immediately when you create a user account. They are generated only after the user passes full compliance verification.

The Event-Driven Flow:

Create User — Provide externalUserId and mandatory citizenship.

Submit KYC — Use Method A (Direct API) or Method B (Hosted Page).

Wait for Approval — Our system performs automated and manual reviews.

Listen for Webhook — Once approved, we send the User Balance Generation Webhook.

Success — This webhook confirms that balances and wallet addresses are ready. You can now call GET /v1/user/balances/{externalUserId}.

What is POA and when is it required?

POA = Proof of Address

A document (e.g., utility bill, bank statement) that verifies the user's residential address for AML compliance purposes.

When is it required?
POA is optional by default. However, it becomes strictly mandatory if a user is flagged as High Risk by our AML system. If the Create User Account response or a subsequent webhook indicates poaRequired: true, you must submit a POA file to proceed.

Acceptable Documents:

Utility bills (gas, electricity, water)

Bank statements

Official government correspondence

Can a user change their country of residence?

No. Due to strict AML regulations, once a user account is created, the country of residence cannot be modified.

If a user needs to change their country, you must:

Delete the existing user account.

Create a new account with a fresh KYC process for the new jurisdiction.

🏦 SEPA & Internal Transfers

Why can't my user withdraw to their bank account?

P100 operates on a Closed Loop policy. Users can only withdraw EUR to a bank account (IBAN) that has been previously verified through a deposit.

The IBAN Whitelisting Flow:

Retrieve Details — Call Get SEPA Deposit Info to get the unique IBAN and Reference (REF) assigned to the user.

Verification Deposit — The user sends a small amount from their personal bank account to that IBAN.

Manual Matching — We verify that the Sender's Name strictly matches the P100 Account Name.

Webhook — You receive an IBAN Status Webhook once the IBAN is approved.

Withdraw — You can now call Create a SEPA Transfer to that specific IBAN.

How do Internal Transfers work?

Use the Internal Transfers module to move funds between your Partner Master Wallet and your users:

Direction	Description
Funding	Move funds from Partner balance → User balance
Collection	Move funds (commissions/fees) from User balance → Partner balance

Key Properties:

✅ Transfers are instant.

✅ Occur off-chain — no blockchain network fees.

📈 Exchange & Payments

Difference between Get Rates and Create a Lock?

The key difference is that Get Rates provides an indicative, non-guaranteed market price, while Create a Lock provides a guaranteed, executable rate for a specific transaction.

Use Get Rates for informational purposes.
Think of it as a live market snapshot. It's ideal for displaying an estimated conversion rate in your UI.

Use Create a Lock to prepare for an actual transaction.
This endpoint provides a guaranteed exchange rate for a specific user, locked for 60 seconds. You must use the lockId from this response to execute the actual exchange.

Rule of Thumb:

Show the user an estimate using Get Rates.

When the user is ready to confirm, call Create a Lock to get a final rate.

Immediately use the lockId to execute the transaction.

What's the difference between Standard Payment Link and Hosted Checkout?

Feature	Standard Payment Link	Hosted Checkout
Configuration	Generic P100 checkout	Follows your dedicated Partner configuration
Branding	Standard P100 branding	Custom branding available
Settlement	All crypto payments auto-converted to EUR, settled to your balance	Specific settlement rules per Partner config
Use Case	Quick, one-size-fits-all payment collection	Tailored checkout experience for your brand

What is the Travel Rule and when does it apply?

The Travel Rule is a global Anti-Money Laundering (AML) regulation that requires sharing sender and recipient information for crypto transactions above certain thresholds.

When it applies:

Large crypto deposits (e.g., from custodial exchanges).

Transactions flagged by our compliance systems.

What happens:
The deposit is held with status WAITING_FOR_TR_DATA.

How to resolve:
Use the Update Travel Rule endpoint to submit the sender's details and release the funds:

📡 Webhooks

How do I verify webhook authenticity?

Verifying every webhook is a critical security measure. Every webhook request includes an Authorization HTTP header containing your unique secret token.

Verification Process:

Extract Token — Read the value from the Authorization header.

Compare Secret — Securely compare the received token with the secret provided during account setup.

Validate:

Tokens match → Process the payload and return 200 OK.

Tokens do not match (or header is missing) → Discard the request and return 401 Unauthorized.

What happens if my webhook endpoint fails?

Automatic Retry System
P100 uses an exponential backoff retry strategy for failed webhooks (non-2xx responses):

Attempt	Delay After Previous Failure
1st	— (Initial delivery)
2nd	~8 seconds
3rd	~16 seconds
4th	~32 seconds
5th	~64 seconds

Retry Conditions:

Non-2xx HTTP response from your server.

Connection timeout.

DNS resolution failures or SSL/TLS errors.

Important: Ensure your webhook endpoint is idempotent — it should handle duplicate notifications gracefully, as the same event may be delivered more than once.

Need Help?

💬 Support

Can't find what you're looking for? Contact our support team for assistance.

🔐 General & Authentication#

👤 User Management & KYC#

🏦 SEPA & Internal Transfers#

📈 Exchange & Payments#