HomeGuidesRecipesAPI ReferenceChangelog
Log In
Changelog
Start typing to search…
Back to All

SANDBOX- v2.3.4 - 2026-01-16

about 1 month ago by Marc Cimiotta Ferrando

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