SANDBOX- v2.3.4 - 2026-01-16

🚀 Sandbox Update Going Live 🎉

This release brings improvements to API security, smarter fee setup, stronger data validation, and new webhook types to keep you better informed of key user events — all while supporting more currencies and streamlining KYC.

✨ What’s New

✅ Bank account confirmation letter download now tied to a specific bank account

✅ Fee setup made clearer with required % values and optional flat/minimum fees

✅ New webhook alerts: user status changes, OTP delivery issues, and refunds

✅ Phone number validation tightened to prevent bad data

✅ One-click KYC form links now available via new API

✅ Nigerian Naira (NGN) added to supported currencies

✅ New REFUNDED status for webhook events tied to canceled transactions

⚠️ Breaking Change: GET /user-kyc-applicant-token

The GET /user-kyc-applicant-token endpoint has changed how the user context is provided.

What changed

The user_uuid query parameter has been removed
The endpoint now reads the user context from request headers instead

New behavior

You must now authenticate using one of the following headers:

unblock_session_id
user_uuid

Requests that still send user_uuid as a query parameter will fail.

Action required

If you are using this endpoint:

Remove user_uuid from the query parameters
Pass the user context via request headers instead

This change improves consistency across authentication modes and enables sessionless usage.

🔐 Bank Statement Endpoints Now Use Account UUIDs

To avoid retrieving the wrong document, bank account confirmation letters now require the specific account UUID.

Before (deprecated):

GET /user/bank-account/unblock/statement

Now:

GET /user/bank-account/unblock/{account_uuid}/statement

📌 Action required: Update your API calls to use the new path. Account UUIDs can be retrieved via the bank account details endpoint.

💰 Better Fee Configuration: More Control, Less Ambiguity

When setting transaction fees via API, the following fields are now required:

fee — A % value (e.g. 0.005 = 0.5%)
direction — Either "ONRAMP" or "OFFRAMP"
fee_op_type — Whether the fee is "add"ed or "subtract"ed

Optional fields:

minimum_fee — Lowest possible fee charged
minimum_fee_currency — Currency used for the minimum
fixed_fee — Flat fee added to the percentage-based fee

📌 Why this matters: This structure makes it easier to define fees correctly, avoids errors, and ensures consistency across your platform.

🔔 New Webhook Types: Stay Updated with Key User Events

You can now receive real-time notifications for the following:

1. `entityStatusUpdate` Webhook

Get alerted when a user's access status changes.

Subtypes:

BLOCKED: User can’t perform actions due to compliance or system block
UNBLOCKED: User is re-enabled after a previous block
MISSING_TERMS_AND_CONDITIONS_SIGNED: KYC is approved, but required documents haven’t been signed

Note: This webhook applies only to merchants who collect signed Terms & Conditions via API by sending signature hashes during onboarding.

📌 Use case: Helps you track which users are restricted and why, so your support team is in the loop.

2. `otpNotification` Webhook

Know when OTP delivery via email fails.

Subtype:

EMAIL_DELIVERY_FAILED: The OTP email bounced (invalid or unreachable address)

📌 Use case: Useful for diagnosing why users can't log in or verify — catch email delivery issues early.

3. Transaction Refund Webhook

A new subtype REFUNDED has been added to:

cryptoToFiat
fiatToCrypto

📌 Use case: Helps you detect when a transfer is canceled and funds are refunded — great for customer support and reconciliation.

✅ Tighter Data Validation: Clean Data = Fewer Issues

Phone Number Rules

US users: Must have a valid US (+1) number in E.164 format (e.g., +1234567890)
Non-US users: Optional, but must be valid if provided

📌 Why this matters: Prevents bad data from being stored, which can lead to failed verifications, webhook errors, or support tickets later on.

🆕 New Endpoint: One-Click KYC Form

You can now generate a direct KYC form link for a user:

Endpoint:

GET /user/kyc/applicant/url

Returns a short-lived, secure URL that lets users complete their KYC without building a full frontend flow.

📌 Use case: Perfect for support teams or portals that want to guide users through identity verification quickly and securely.

🗑️ Deprecated Endpoint: Open Banking Payment Initiation via Plaid

The following endpoint has been removed due to lack of usage and a more reliable replacement:

Deprecated:

POST /user/open-banking/payment

This endpoint previously initiated a fiat deposit via Plaid by generating a link_token, used to launch Plaid Link for account connection and payment authorization.

📌 Why it was removed:

No active integrations were using this flow, and it has been superseded by a more robust approach.

✅ Use Instead:

POST /user/linked-bank-account/pull

This is the new, recommended way to initiate a fiat deposit via Plaid-linked bank accounts. It supports a more consistent and secure experience.

👉 If you were testing or planning to use the old Plaid initiation flow, please migrate to the new pull-based endpoint.

🌍 Currency Expansion: NGN Support Added

You can now use Nigerian Naira (NGN) as a base currency in transactions and fee setups, joining EUR, GBP and USD.

🛠 Other Notable Fixes & Enhancements

Better error messages when exporting KYC applicants (e.g., token invalid or data mismatch)

Improved error messages when exporting KYC applicants (e.g. token invalid or applicant data mismatch)
New 400 error returned when user and applicant data do not match during export

👏 Thanks for Building with Peermanent!

This release focuses on clarity, compliance, and control — giving you better tooling and insight into your users' lifecycle, transaction state, and fee structures.

Need help integrating these updates? Reach out — we’re happy to support!