🚀 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

🚀 New API

Counterparties & Payout Methods API
Manage your recipients and how to pay them in a first-class way with the new Counterparties and Payout Methods API. Learn more here.

⭐ Enhancements

USDT Payins on the Tron Blockchain
USDT Tron payin methods are now available via the Accounts API, allowing users to fund their accounts using the Tron network. Reach out to learn more and get this feature enabled.

Transactions API Enhancements
The Transactions API now includes ACH trace numbers for applicable transactions, improving transparency and traceability. Reference the API here.

Terms of Service “Reliance” Model
Simplify onboarding for your users by embedding Mural’s Terms of Service directly into your own flow using the “Reliance” model. Checkout our documentation on this feature to learn more.

🐛 Bug Fixes

• Fixed an issue that caused blockchain payout methods to not appear in the Payout Methods search endpoint
• Fixed an issue that prevented USD payouts to China from being created
• Fixed an issue that resulted in certain Webhooks not being sent

🚀 New API

getTransaction endpoint
You can now query for a specific Transaction via the Transactions API

🌐 New Routes

USD Payouts to Panama

You can now send USD to banks in Panama

⭐ Enhancements

Custom Developer Fees for Payins
Earn custom fees on Payins made into your users’ accounts. This gives developers more flexibility to monetize their payment flows. Learn more here.

Expanded Webhook Event Types
Get real-time updates for business verification (KYC) status changes via newly added webhook event types. Learn more here.