📢  Announcements

Developers!

We are writing to announce two API deprecations, both of which will be removed by June 18, 2026:

1. A small removal of the account.balances field → you should be using account.balancesV2 going forward. More information on this can be found here.
2. Deprecating Organization Verifications in favor of Compliance Reviews (see more on that below)

We wanted to reach out to let you know that our organization verification KYC onboarding endpoints (this and this) are now deprecated. We have released new Compliance Review endpoints for general access and ask that you transition over to this flow as soon as possible.

Compliance Reviews get you:

1. Pre-submission validations applied to attestation submission so you and your user can catch user-input problems before submitting to our compliance team, avoiding unnecessary back and forth after submission.
2. Pave the way for what we are calling “Programmatic RFIs” — this API will soon faciliate the back and forth between our compliance team and you/your users, so no one needs to rely on pesky emails

When do I need to transition by?

We will be shutting off the legacy organization verification endpoint EOD on June 17, 2026, so all requests made to this endpoint will fail as of June 18, 2026.

How do I migrate to Compliance Reviews?

The new migration guides for using the new flow can be found here

Where can I find more information on Compliance Reviews?

You can find everything you need regarding Compliance Reviews as a concept here

Please reach out to [email protected] if you have any questions!

⚠️ Deprecations

1. Legacy Business Verification flow is deprecated, will be removed by June 18 — you can see old documentation here. You should be using Compliance Reviews
2. Reminder: In the Accounts API, accountDetails.balances is now deprecated in favor of balancesV2 . This new field can support both fiat and blockchain based balances
   1. Target removal date: June 18, 2026
   2. June 18, 2026

🚀 New APIs

1. Compliance Reviews are now GA! See walkthrough on how to get your organizations approved and ready for production usage — Compliance Review Guide
   1. Compliance Review API now Generally Available! Compliance Reviews are your new entry point for organization compliance onboarding. API Reference
   2. Associated Persons API now Generally Available! Associated Persons contain the compliance information for beneficial owners and control persons required for Business Compliance Reviews. API Reference
   3. Documents API now Generally Available! The Documents API is used to generate pre-signed upload URLs and document IDs used in the Attestations for Compliance Reviews. API Reference
   4. Business Compliance Reviews — the INTERNATIONAL_STANDARD compliance tier has been renamed to FULL. Please update any integration that references the INTERNATIONAL_STANDARD tier value
2. New sandbox endpoint to bypass compliance review for testing: POST /api/sandbox/simulate/complianceReview. Approves a test organization through compliance in staging so you can iterate on downstream flows without waiting for review.

🌐 New Routes

1. USD wire and ACH payouts directly from USD fiat balances — previously USD fiat balances could only pay out to blockchain destinations. You can now send wire/ACH payouts directly from a USD fiat balance.
2. Inbound USDC on Solana — your Mural Accounts can now receive USDC deposits on Solana, in addition to the existing supported chains.

⭐ Enhancements

1. Compliance Reviews — individualTaxInfo is now its own attestation.
2. Compliance Reviews — nationality is now optional on the KYC Light attestation.
3. USD Payin methods in the Accounts API — the DBA ("doing business as") name is now used as the beneficiary on the payin method when set, falling back to the legal name otherwise.

🐛 Bug Fixes

1. Ramp-fee input validation now returns 400 instead of 500 for invalid input.
2. Improved post-fee minimum enforcement and terminal-failure handling on payout and deposit flows
3. Sandbox — simulated WIRE payins now include an IMAD so senderMetadata renders correctly

⚠️ Deprecations

1. In the Accounts API, accountDetails.balances is now deprecated in favor of balancesV2. This new field can support both fiat and blockchain-based balances. More on that below in the "New APIs" section!
   1. Target removal date: June 18, 2026

🚀 New APIs

1. Select Mural Accounts can now hold FDIC-insured, USD fiat balances in addition to existing on-chain stablecoin balances. Please reach out to [email protected] for more information.
2. New Payin Status Webhook Event: payin_status_changed. Subscribe to payin lifecycle changes instead of polling GET /payins/{id} — see here for more information on this new event category.
3. The Payin model in the Payins API now contains more metadata about your Payin — payinRail, settlementStrategy, sourceAmount, settlementDetails, fees, and senderMetadata — see details here.
4. Introducing Sandbox Simulation Endpoints — because we know testing your integration in a staging environment can be difficult. We plan on building this out over the next month:
   1. Ability to simulate ACH, Wire, SPEI, CVU, and PIX Payins to your Mural Accounts in our sandbox environment — see here for API reference.

🌐 New Routes

1. USD payouts to external blockchain wallets from USD — customers can now send USD fiat balances to third-party blockchain wallet destinations, either via inline wallet addresses or a blockchain payout method. Supports payouts to Ethereum and Solana blockchains. Reach out to [email protected] if you are interested in this functionality.
   1. Note: this is only supported for payouts that originate from a USD fiat balance (see New APIs above)

⭐ Enhancements

1. The Mural Account response now includes a new balances field, balancesV2. This field supports both fiat and blockchain balances, and you should use this field going forward.
   1. Note: we have started to return fiat and blockchain balances as strings to avoid precision loss.
2. COP Payins via PSE Links can now onramp onto USDT/Polygon and USDC/Ethereum.
3. Mural account wallet provisioning latency reduced — time-to-provision your Mural account after KYC gets approved was reduced from 60 seconds to 14 seconds.
4. Create Payout Request API now throws PayoutComplianceValidationFailedError, which will indicate if additional information is required in the payout request — see here for details.
5. Added expiresInSeconds parameter to the Create Payin endpoint for COP PSE link creation — check it out here.
6. Postal-code validation for Chile, Argentina, and a universal format check.
7. Encrypted PDFs are now rejected at the KYC upload boundary with a surfaced error.
8. Blockchain mismatch error now includes both expected and provided values.

🐛 Bug Fixes

1. Fixed an issue resulting in out-of-date USD fiat balances associated with Mural Accounts that held USD balances.
2. Payout Requests involving fiat payouts — initiatedAt now properly set on PENDING → COMPLETED transitions.
3. Fixed race condition blocking compliance review completion for Individual Light Tier compliance reviews.
4. Fixed an issue where the GET /tos-link endpoint for child-org would return an expired TOS link.

🚀 New APIs

1. Documents API (Beta) — generate signed upload URLs to upload documents, which are required for the new Compliance Review API

⭐ Enhancements

1. Add idempotency key support to the compliance review endpoints
2. Business Verifications
   1. UBOs now require Proof of Address and validated at creation time. This was always required, but we didn't correctly validate.
   2. Now possible to provide selfie photo for Argentine individuals. This was originally required but there was no way to provide the information.
3. MuralServiceException outlined in the Errors documentation page are now included in our Open API Spec and API Reference. If an endpoint throws a typed MuralServiceException, it will appear on the specific endpoint’s API Reference.
4. Improved Colombian postal code validation upon Business Verification submission
5. For End-user-custodial organizations, we now support the ability to configure the company name included in the ‘challenge’ email your users receive. For more information on this, please reach out to [email protected].
6. Relaxed PDF page count constraint for Business Verification
7. Improved API key authentication error messages in the response

🐛 Bug Fixes

1. Search organizations endpoint now throws correct 4xx responses when invalid filters are supplied
2. Payin exchange rate endpoint now correctly throws a 400 instead of 500 for unsupported payin currencies
3. Improved error handling for invalid document inputs when submitting business verifications

🔜 Coming soon

1. Cross-chain bridging and token swaps API— A new Transfers API that will let you move funds across blockchains (Polygon and Ethereum) as well as convert USDT-USDC within your Mural Account. If you are curious about the progress here or want to be an early adopter, please reach out at [email protected]

🌐 New Routes

1. MXN (Mexican Peso) pay-ins via new MXN Named Virtual Accounts — Your Mural Accounts now include MXN pay-in method details. Fund accounts via SPEI using the provided CLABE number — returned automatically in the Account's payinMethods array. No Payins API call needed. your users initiate transfers directly through their bank.
2. BRL (Brazilian Real) pay-ins via new BRL named Virtual Accounts — Your Mural Accounts now include BRL pay-in method details. Fund accounts via PIX using the provided PIX BR code — returned automatically in the Account's payinMethods array. No Payins API call needed. Your users initiate transfers directly through their bank.

🚀 New APIs

1. Beta: introducing KYC “Tiers” and a New Compliance API - see here for API documentation and here for an overview of Compliance Tiers. Note, this is only available for beta users. If you would like to try this out, please contact the mural team at [email protected]
2. Validate Bre-B bank account keys for COP payouts with a new utilities endpoint - see here

⭐ Enhancements

2. We now filter out ERC20 dust/spam transactions from user-facing views and Transactions API, filters out anything under .01 USDC/T
3. Error handling improvements across the board on Payouts and Accounts APIs, before where we were throwing generic Internal Server Error , we are now throwing debuggable 4xx errors
4. We now expose exchange rate on the Payin and Transaction models
5. Updated South Africa province names to show the correct English province names (before we showed iTlhagwini-Kapa instead of Northern Cap)

🐛 Bug Fixes

1. Relaxed COP bank account validation in the Payouts API and Payout Methods API to accept account numbers with leading zeros (6-18 digits) and updated Cédula de Extranjería (CE) document validation to accept 6-12 alphanumeric characters. These changes resolve cases where valid Colombian bank accounts or CE document numbers were incorrectly rejected during payout method creation.
2. Fix Account creation race condition that returned a 4xx error erroneously

🔜 Coming soon

1. Named Payin Virtual Account support for new currencies in LATAM! These will appear as new payinMethods in the Accounts API for all Mural Accounts. If you would like to be part of our Beta release of these features, please reach out to the team at [email protected].
   1. MXN
   2. BRL
   3. ARS
2. KYC Light. We are going to be rolling out a new KYC API that also allows for uploading a minimal set of compliance information for your users (Managed Organizations). This 'KYC Light' mode will result in volume restrictions, but is a great way to get your users approved and using the infrastructure as soon as possible. If you would like to be part of our Beta release of this feature, please reach out to the team at [email protected].

⚠️ Deprecations

1. GET /organizations/:id/kyc-link (KYC Link V1) has been removed. Migrate to the v2 endpoint for hosting KYC links.

⭐ Enhancements

1. COP Payins now accept an optional redirectUrl field to redirect end users back to your app after payment completion. See Payins API for details.
2. Idempotency key support for payout requests. Payout endpoints now accept an optional idempotency-key header. Sending the same key on a retry returns the original cached response with an idempotency-replayed: true response header. See the Idempotency documentation for details.
3. (Beta) Customer-named payouts for USD Wire — for your recipient, sender name will now show as the name of the sending Organization. Reach out if this is something you would like to enable!

🐛 Bug Fixes

1. The memo field on payout request creation now enforces a maximum length
2. Fixed a race condition in government ID verification processing causing Verifications to fail
3. Invalid fiatRailCode values for the Payouts API now return a 400 Bad Request instead of a 500 Internal Server Error
4. Invalid Payin rail types for developer fees in the Accounts API now return a 400 Bad Request instead of a 500 Internal Server Error

⚠️ Deprecations

1. The GET /organizations/{id}/kyc-link (v1) endpoint has been removed from documentation (still works but will be removed in our next release)

🔜 Coming Soon

1. LATAM onramp support — We're adding onramp support for MXN (Mexican Peso), BRL (Brazilian Real), and ARS (Argentine Peso). Stay tuned!

🚀 New APIs

1. Archive endpoints for https://developers.muralpay.com/docs/counterparties-and-payout-methods and Payout Methods — soft-delete resources you no longer need:

• POST /api/counterparties/counterparty/{id}/archive
• POST /api/counterparties/{id}/payout-methods/{payoutMethodId}/archive

2. Bre-B COP external pay-ins (COP virtual accounts using Bre-B keys). The keys can be fetched using the account details endpoint.

⭐ Enhancements

1. Expanded KYC coverage — Added 20+ new government ID types across 50+ countries, including Residence Permits, Voter IDs, PAN Cards (India), My Number Cards (Japan), and more
2. MaxLength validation on payout request memo field — The memo field now enforces a maximum length, returning a clear validation error if exceeded
3. Bank account owner name validation — Added upfront validation requiring both first and last name for LATAM and regional currencies, preventing downstream payout failures
4. Panama NATIONAL_ID validation relaxed — Updated from exactly 8 digits to 5-12 digits, supporting Colombian nationals with Bancolombia Panama accounts
5. PayoutDestinationError — New structured error (HTTP 412) when a payout method is unavailable. Returns payoutMethodId and payoutIndex so you can programmatically identify which payout failed — https://developers.muralpay.com/docs/errors#payoutmethoderror
6. Improved payout error messages — Validation errors on payout creation (e.g., unsupported routing number for wire) now surface the specific error message instead of a generic error

🐛 Bug Fixes

1. Fixed a 500 error on payout creation when physicalAddress was missing — now correctly returns 400 validation error
2. Fixed contact creation error propagation — validation errors (e.g., invalid bank account numbers) now return their specific message instead of a generic "Unable to create contact"
3. Fixed floating-point precision issue in developer fee percent calculations
4. Added global string sanitization to prevent encoding errors from special characters in request inputs
5. Improved UUID validation across blockchain transaction endpoints — invalid formats now return 400 instead of 500

Happy new year to our developer family! We hope you all had an amazing holiday season. We hit the ground running in 2026 and are excited to share some new updates with you all. Read one for specifics.

⚠️ Deprecations

Note: deprecations are a warning of removal of functionality. The target removal date for each indicates the date in which functionality will cease to exist

1. The endpoint: /organizations/{id}/kyc-link request for Retrieve a KYC Link endpoint is deprecated in favor of endpoint: /organizations/{id}/kyc-link/v2
   1. Target removal date: January 23, 2026
   
   

🌐 New Routes

1. COP Bre-B support via the Payouts/PayoutMethods APIs. Please reach out to get this enabled for your organization.

🚀 New APIs

1. Archive endpoints for the Counterparties and PayoutMethods APIs. Check out the new endpoints here and here.
2. We have a new endpoint for fetching the link to the KYC Form. This request generates a new token on every request. This token will auto-expire after 24 hours for additional security.

⭐ Enhancements

1. Bank name change via the bank accounts API: Giros y Finanzas → Banco Union
2. Performance improvements to the Transactions API
3. TOS reliance is enabled by default in our Sandbox environment
4. Improved error handling
   1. Added InsufficientBalanceError for better insufficient balance error handling - docs here
   2. Improved Payout Request execution error handling when payouts fail due to recipient bank account issues
   
   

🐛 Bug Fixes

1. Fixed an issue that resulted in usd payin methods to not be generated for Mural Accounts

⭐ Enhancements

1. New webhook event type! You can now subscribe to webhook events that fire when your payout request or individual payout changes status — see docs here
2. Explicit refund statuses for all Payouts is now live — see docs here. Previously, refunded payouts would simply be marked as failed.
   1. fiatPayoutStatus: refundInProgress
   2. fiatPayoutStatus: refunded (this is a terminal state)
3. New RefundedPayoutMetadata type returned for transactionDetails when the Transaction pertains to a refund in Transactions API — includes original payout details in refund transaction responses. See the specific sub-type documentation in the response here

⚠️ Announcements

1. After December 19th, 2025 at 5:00 PM EST, any Payouts that fail will no longer be marked as failed. The Payout will transition through two new statuses. This is an improvement we know a lot of you have asked for, and we hope this more clarity to where your clients’ funds are when payouts fail. If you explicitly handle the existing failed fiat payout status, you will want to handle the two new statuses as well before the release date.
   1. fiatPayoutStatus: refundInProgress
   2. fiatPayoutStatus: refunded (this is a terminal state)
   3. For any questions, please do not hesitate to reach out to [email protected]

⭐ Enhancements

1. Documentation released for new Fiat Payout Statuses to explicitly track refunds: refundInProgress and refunded. While the documentation is released for these new statuses, we will not actually return these new statuses until December 19th, 2025 at 5:00 PM EST (see announcement above for more information). You can see these new fiat payout statuses in the response of getPayout here.
2. New webhook event type! You can now subscribe to webhook events that fire when your organization has signed our Terms of Service — see docs here for more information.
3. Ability to set the destination token and blockchain for fiat payins into a specific Mural Account via the new destinationToken field — see docs here. Note: EUR payins are only supported with a destination token of USDC.
4. Updated our Payout validations
   1. Updated China USD validations to allow 9-25 digits account numbers see here for more information.

🐛 Bug Fixes

1. Fixed an issue preventing the creation of ‘end user custodial’ organizations with only one Approver

🚀 New APIs

1. We now have a new individualV2 request type for the create Business Verification endpoint which supports providing Source of Funds information as well as an enhanced Government ID support. Use this type going forward when creating business verifications for your individual organizations. See deprecations note below.

⭐ Enhancements

1. Improved Payment Method validations:
   1. CPF and CNPJ verification digit validation for BRL Payment Methods validations (see here for specifics)
   2. Enhanced bank account owner name validations
2. Child organizations underneath a parent organization now must have a unique email addresses
3. No longer send email notifications to orgs with rejected Business Verifications
4. Enforce unique alias constraints per-counterparty across all payout method types

🌐 New Routes

1. (Beta) Can now payout USD to banks domiciled in Hong Kong — reach out to the team to get enabled for this flow!

⚠️ Deprecations

Note: Deprecations are a warning of removal of functionality. The target removal date for each indicates the date in which functionality will cease to exist.

1. The type: individual request for the create business verification endpoint is deprecated in favor of type: individualV2
   1. Target removal date: December 12, 2025

🐛 Bug Fixes

1. Fix single query parameter handling for /supported-banks endpoint
2. Fixed an issue resulting USDT/tron deposits into Mural Accounts not appearing in the Payins API
3. Fixed an issue resulting in Transactions sometimes not appearing in the Transactions API