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 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 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

Use separate API keys for each environment

Never use production keys in development/testing

❌ Getting "401 Unauthorized - Access Denied. xo1" error

This specific error indicates an API key authentication problem:

✅ Quick Fix Checklist:

Common Issues:

❌ Missing x-api-key header

❌ Wrong environment (staging key on production URL)

❌ Copy-paste errors (extra spaces/characters)

Debug Steps:

Verify header name: x-api-key (not X-API-Key)

Check environment URL matches your key type

Ensure no trailing whitespace in key value

Where should I store my API key securely?

🚫 Never Do:

Hard-code in source code

Commit to version control

Store in client-side applications

Share in plain text communications

✅ Recommended Approaches:

Environment Variables:

Cloud Secret Managers:

AWS Secrets Manager

HashiCorp Vault

Azure Key Vault

Google Secret Manager

Server Configuration:

User Management & KYC

So, how do I get a user's balance for the first time?

Since balances are only created after a successful verification, you should not call the Get User Balances endpoint immediately after creating a user.

The correct, event-driven flow is:

Create a user and submit their documents for verification.

Listen for the /webhook/user/status webhook. You will receive this notification when verification is successful and the user's account status becomes ACTIVE. The webhook payload will look like this:

{
  "externalUserId": "bca65c48-df49-4831-a7b2-de7903321581",
  "status": "ACTIVE"
}

After receiving the webhook confirming the ACTIVE status, you can now safely call GET /v1/user/balances/{externalUserId} to retrieve the user's newly generated balances.

This approach ensures you only request balances when you are certain they exist, preventing unnecessary errors.

What's the difference between KYC flows?

You can onboard a user through two distinct KYC (Know Your Customer) processes.

1. Partner-Provided KYC Flow
Use this flow when you already have the user's KYC documents.

This is a three-step process where you send us the user's information and documents directly.

2. P100 KYC Flow
Use this flow when you want to redirect the user to our secure portal to complete verification.

This is a four-step process where you initiate the verification and we handle the document collection.

What is POA and when is it required?

POA = Proof of Address

Required document that verifies user's residential address for compliance purposes.

POA is required only in these cases:

When extending a user to Extended Balance Service
You will know if POA is needed for a user if the Create User response contains the flag:

"poaRequiredForExtended": true

When the account to be extended belongs to a country where POA is mandatory
The list of such countries can be verified here: Supported Countries

Acceptable Documents:

Utility bills (gas, electricity, water)

Bank statements

Government correspondence

Rental agreements

Document Requirements:

Must be issued within last 3 months

Clearly show full name and address

From recognized institution/provider

Transactions (Transfers, Exchange, Withdrawals)

Transaction created successfully but balance unchanged?

This is normal behavior - P100 transactions are asynchronous.

Transaction Lifecycle:

Process Flow:

Immediate Response → Transaction queued with ID

Background Processing → Compliance checks, balance validation

Final Status → Receive a webhook notification with the final status.

✅ How to Track Status (Recommended Method):

The best way to track the final status of a transaction is by listening for our real-time webhook notifications. This is more efficient than repeatedly calling the details endpoint.

See the Webhooks for a full list of transaction-related events.

Difference between get-rate vs get-lock?

The key difference is that get-rate provides an indicative, non-guaranteed market price, while get-lock provides a guaranteed, executable rate for a specific transaction.

Use get-rate for informational purposes.
Think of it as a live market snapshot. It's perfect for displaying an estimated conversion rate in your user interface. This rate is not tied to a user and can change at any moment.

Use get-lock to prepare for a transaction.
This endpoint provides a guaranteed exchange rate for a specific user that is locked for 60 seconds. You should call this immediately before you intend to create the exchange to ensure the user gets the exact rate they were quoted.

Rule of Thumb:

Show the user an estimate using get-rate.

When the user is ready to confirm the exchange, call get-lock to get a final, guaranteed rate.

Immediately use the response from get-lock to create the transaction.

What is the Travel Rule and when do I need it?

Travel Rule = Anti-Money Laundering Regulation

Requires sharing sender information for crypto transactions above certain thresholds.

When Travel Rule Applies:

Crypto deposits > $1,000 USD equivalent

From exchanges/custodial services

Cross-border transactions

Webhook Notification:

{
  "event_type": "crypto_deposit.status_changed",
  "data": {
    "cryptoDepositId": "dep_123",
    "status": "WAITING_FOR_TR_DATA",
    "amount": "0.05",
    "currency": "btc"
  }
}

Required Information:

Virtual Cards

❌ Virtual card creation rejected?

🚫 Common Rejection Reasons:

Geographic Restrictions:

User from unsupported country

See Supported Countries for card availability

Account Limits Exceeded:

Account Issues:

Account suspended

User not enabled for Extended Services: Virtual cards require the user to have a fully verified status).

✅ Pre-Creation Validation:

How to delete a virtual card?

⚠️ Unusual Endpoint Design:
Unlike most endpoints, card deletion requires data in the request body, not URL path.

✅ Correct Implementation:

Security Note: Card deletion is irreversible. Always confirm user intent before proceeding.

Webhooks

How to verify webhook authenticity?

Verifying every webhook is a critical security measure to ensure that the data originates from our system and has not been tampered with. You must always validate the request's authenticity before processing its payload.

Our system uses a secret token for authentication. Every webhook request we send includes an Authorization HTTP header containing your unique secret token.

The verification process on your server should follow these steps:

Extract the Token: Read the value from the Authorization header of the incoming request.

Compare with Your Secret: Securely compare the received token with the secret token provided to you during setup and stored in your system's configuration.

Validate and Respond:

If the tokens match, the webhook is authentic. You can proceed with processing the payload and should return a 200 OK status to acknowledge receipt.

If the tokens do not match or the Authorization header is missing, you must discard the request immediately and return a 401 Unauthorized error.

Security Best Practice: Your secret token is a sensitive credential. Always store it securely (for example, as an environment variable) and never expose it in any client-side code.

What happens if my server is down during webhook delivery?

Automatic Retry System

P100 implements exponential backoff retry strategy:

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 responses

Connection timeouts (30s)

DNS resolution failures

SSL/TLS errors

Monitoring Failed Webhooks:

Check P100 dashboard for delivery status

Implement health check endpoint: /webhook/health

Monitor server uptime and response times

Set up alerts for webhook failures

Need Help?

📖 FAQ

Find answers to the most common questions about our API.

💬 Support

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

General & Authentication#

User Management & KYC#

Transactions (Transfers, Exchange, Withdrawals)#

Virtual Cards#