MatchMove Banking Operating System MatchMove Banking Operating System ## Sections • [Platform overview](https://developer.matchmove.com/matchmove-banking-operating-system/platform-overview.md): MatchMove Banking Operating System ™ Your one-stop solution for building flexible, embeddable finance use cases Put a Bank in Your App™ MatchMove offers a cutting-edge embedded finance platform that enables businesses to integrate financial services directly into their applications. By doing so, you can deliver a superior, personalized user experience while generating new revenue and improving customer engagement. The following guide outlines the key platform features available to address your specific business use cases. Getting Started Kick-start your value delivery from the MatchMove platform. Define program constructs Based on your use case, design the program constructs catered to your use case Understand regulations Understand the regulatory implications of your program construct. Integrate Start consuming MatchMove APIs to start offering financial products to your end user Go live Validate your integration and enable your team to scale the program in production. Explore products Select the product suite that is best suited for your use case to deliver a tailored embedded payment solution for your users. Core products These products serve as the fundamental building blocks for the platform, enabling compliant user acquisition and the delivery of core banking functionalities. Identity & Onboarding Onboard users to offer financial services Accounts Create accounts for your users to avail financial services Ledgers & Funds Control the movement of funds for your users' accounts Financial products Purpose-built products allow you to deliver additional financial services to your end users. Collections Receive funds from individuals and corporations worldwide Payouts Pay/transfer money to individuals and corporations worldwide Cards Issue cards for your users to spend globally. New to MatchMove? Contact our sales team at sales@matchmove.com to get started with your own product — and put a bank in your app. • [Use cases](https://developer.matchmove.com/matchmove-banking-operating-system/use-cases.md): Flexible platform for diverse use cases The MatchMove Banking Operating System™ is an adaptable platform engineered to support a diverse range of client applications. It provides the modular components necessary to achieve your specific use case while ensuring all compliance, regulatory, and security requirements are met. This enables partners to focus on their core business objectives for accelerated time-to-market and scalable growth. Leading Use Cases Here are some of the popular use cases that our partners have implemented to create tailored embedded finance experiences. Global card Issuance Whitelabel co-brand Issuance of virtual and physical cards Corporate expense management Digital First Real-Time Expense & Payroll Cards Marketplace payouts Programmatic control payments for your ecosystem with multiparty payments Global payouts & receivables Digital control of your payouts and receivables for accelerated operational efficiency Digital banking Digital control of your payouts and receivables for accelerated operational efficiency Lending on cards Digitize your line of credit by allowing spending on a card Buy now, pay later (BNPL) Universal BNPL Acceptance with Turnkey Card Issuance. Crypto cards Issue crypto/stablecoin-based Cards • [Buy Now Pay Later](https://developer.matchmove.com/matchmove-banking-operating-system/use-cases/buy-now-pay-later.md): Universal BNPL Acceptance with Turnkey Card Issuance Buy Now, Pay Later (BNPL) Providers, Digital Lenders, and Fintechs offering installment-based credit (with a focus on Product, Growth, and Partnership teams) Problem Statement Accelerate time to reach a critical mass of merchants For BNPL players, growth is directly tied to merchant acceptance. However, building and scaling a proprietary merchant network is a slow, resource-intensive, and technically complex process. The key challenges are significant Merchant Onboarding: Convincing thousands of individual merchants to adopt a new payment method is a major sales hurdle. Technical Integration: Each merchant requires a dedicated, often complex, technical integration into varied e-commerce platforms and Point-of-Sale (POS) systems. Infrastructure Compatibility: Ensuring your BNPL solution works with a diverse and fragmented landscape of existing payment gateways and processors is a constant challenge. This traditional, one-merchant-at-a-time approach fundamentally limits your speed to market and the utility of your service for consumers. The MatchMove Solution Bypass Merchant Integration, Go Straight to Market Shift your focus from the costly battle for merchant acceptance to what you do best: acquiring customers and managing credit. With MatchMove, your BNPL service is no longer restricted to a curated list of partnered stores. It's available everywhere your customers want to shop. This isn't just an incremental improvement; it's a new paradigm for BNPL growth and utility. Value Proposition With MatchMove, the payment experience becomes instant and invisible. You can now offer your users a powerful tool that allows them to spend at millions of online and offline merchants across the globe just as easily as with a traditional bank card. Shift your focus from the costly battle for merchant acceptance to what you do best: acquiring customers and managing credit. With MatchMove, your BNPL service is no longer restricted to a curated list of partnered stores. It's available everywhere your customers want to shop. This isn't just an incremental improvement; it's a new paradigm for BNPL growth and utility. Key Platform Benefits Instant Universal Acceptance: Gain immediate access to millions of existing merchants worldwide that already have card terminals and online checkouts. Your merchant network is instantly global. Eliminate Sales & Integration Overhead: Remove the need for a merchant sales team and a complex web of technical integrations. Your resources can be focused on growth. Drastically Faster Time-to-Market: Launch your BNPL offering or enter new markets in record time by eliminating the primary bottleneck of merchant acquisition. Superior Customer Freedom: Give your customers the ultimate flexibility to use their approved credit line anywhere they choose, dramatically increasing engagement and loyalty. Simplified Operations: Integrate once via our modern, developer-friendly APIs and let us handle the complexities of the payment rails. You manage the user and the credit; we manage the payment. MatchMove Products The following products serve as building blocks, allowing you to bridge the last-mile problem of enabling global commerce. Identity & Onboarding Onboard Users in a regulatory-compliant manner for your card program Accounts (JIT) Issue JIT accounts for your users to facilitate just-in-time asset conversion Cards Issue white-labeled physical and virtual cards for your user • [Global Card Issuance](https://developer.matchmove.com/matchmove-banking-operating-system/use-cases/global-card-issuance.md): Whitelabel Co-brand Issuance White-label virtual (unlimited issuance) and physical prepaid Mastercard/Visa cards issued from Singapore. They support international payments, Google Pay (included), and Apple Pay (separate approval/cost/volume). Cards can be reloadable and potentially used for payroll or expense management. Problem Statement The Crippling Complexity of Global Expansion Launching a card program in even one country is a major undertaking. Expanding that program across multiple regions is exponentially more difficult. Businesses face a wall of fragmented and localized challenges: Regulatory Mazes: Each country has its own unique financial regulations, licensing requirements, and compliance mandates (like KYC/AML) that must be navigated. Siloed Banking Partnerships: Companies are forced to source, contract with, and integrate separate local banking and processing partners in every single market. Fragmented Technology: This leads to a patchwork of disparate systems, creating immense technical debt and preventing a unified view of the business. Prohibitive Costs & Timelines: The financial investment and time required to overcome these legal and technical hurdles on a country-by-country basis make true global expansion impossible for all but the largest corporations. The MatchMove Solution The MatchMove BaaS platform removes these barriers by acting as your single, centralized layer for global card issuance. Instead of building a complex, fragmented network of local partners, you integrate with our platform once to unlock the world. Value Proposition Through a single API integration, you gain immediate access to our pre-built, compliant financial infrastructure across multiple countries. We provide processing capabilities to issue cards globally, all managed and unified through our core platform. MatchMove provides the essential infrastructure to make this a reality. MatchMove Products The products below serve as building blocks, allowing you to bridge the last-mile problem of enabling global commerce using crypto assets Identity & Onboarding Onboard Users in a regulatory-compliant manner for your card program Accounts Issue JIT accounts for your users to facilitate just-in-time asset conversion Cards Issue whitelabeled physical and virtual cards for your user • [Corporate Expense Management & Payroll](https://developer.matchmove.com/matchmove-banking-operating-system/use-cases/corporate-expense-management-and-payroll.md): Digital First Real-Time Expense & Payroll Cards Problem Statement Outdated and archaic processes For decades, corporate expense and payroll systems have been built on slow, inefficient, and fragmented processes that create friction for both the company and its employees. For Expense Management: The "reimburse and report" model is broken. It forces employees to pay out-of-pocket, then endure a slow, manual process of submitting receipts and waiting for repayment. For the business, this means a lack of real-time spending control, a high risk of out-of-policy purchases, and a heavy administrative burden on finance teams. For Payroll: Traditional payroll runs are rigid and slow, tied to biweekly or monthly batch processes. This model fails to meet the needs of a modern workforce that expects faster access to earnings. Furthermore, it presents a significant challenge for paying unbanked or underbanked employees, often reverting to costly and insecure methods like paper checks The MatchMove Solution Programmatic Control Over Every Corporate Dollar The MatchMove BaaS platform enables you to embed card issuance directly into your software, transforming these outdated processes into a modern, real-time system of control and disbursement. Value Proposition Integrate with our APIs once to create and manage two powerful solutions: Smart Corporate Expense Cards: Issue branded virtual and physical cards to employees. Instead of chasing reimbursements, your clients can proactively set granular, real-time spending controls (e.g., limit spending to specific merchants, set daily budgets, block categories). Every transaction is authorized against your rules, and data flows back to your platform instantly for automated reconciliation. Instant Payroll Cards: Issue branded payroll cards that serve as a primary account for employees. Your clients can disburse salaries and commissions or provide Earned Wage Access (EWA) instantly, 24/7. This provides immediate access to funds for all employees, including the unbanked, and drastically simplifies the disbursement process. Empower your clients to shift from "reporting on what was spent" to "controlling what is being spent" in real-time. Transform payroll from a rigid, bi-weekly event into a flexible, on-demand service. By embedding our tools, your platform becomes the strategic, real-time financial operating system for your clients' businesses. Key Platform Benefits Eliminate Expense Reports & Reimbursements: Improve employee satisfaction and corporate cash flow by providing company-funded cards with clear, pre-approved budgets. Gain Real-Time Spending Control: Allow your clients to enforce expense policies before the transaction happens, not after, virtually eliminating fraud and overspending. Fully Automate Reconciliation: Capture rich, categorized transaction data the moment a purchase is made, ending the need for manual receipt chasing. Deliver Instant, Flexible Payouts: Meet the demands of the modern workforce with on-demand earned wage access, instant commission payments, and flexible payroll. Promote Financial Inclusion: Provide every worker, regardless of their banking status, with a secure and powerful tool to receive, save, and spend their earnings. MatchMove Products The below products serve as building blocks, allowing you to bridge the last mile problem of enabling global commerce using fiat. Identity & Onboarding Onboard Users in a regulatory-compliant manner for your card program Accounts Issue accounts for your users serving as a full-fledged account. Cards Issue whitelabeled physical and virtual cards for your user Payouts Enable seamless domestic and cross-border disbursements for your users. Collections Streamline inbound payments and account funding for your users. • [Crypto Cards](https://developer.matchmove.com/matchmove-banking-operating-system/use-cases/crypto-cards.md): Issue Crypto/Stablecoin-based Cards We enable you to bring your crypto payment solutions to the mainstream with customized debit and credit cards. Problem Statement The Last-Mile Barrier for Digital Assets The adoption of cryptocurrencies and stablecoins is accelerating globally. However, for the average user, the utility of these digital assets in the real world remains limited. The process of converting crypto to fiat and then spending it is slow, involves multiple steps, and is often expensive. This friction creates a significant barrier, preventing digital assets from becoming a mainstream medium of exchange for everyday purchases. Your users hold valuable assets, but can't easily use them at the checkout counter. The MatchMove Solution Bridge Digital Assets to Global Commerce MatchMove provides the definitive solution to this problem with our advanced Banking as a Service (BaaS) platform. We empower you to instantly issue branded debit or credit cards that allow your users to spend their crypto or stablecoin holdings in real-time, anywhere in the world. Our core innovation, the MatchMove Just-in-Time Funding (mJIT™) mechanism, is the engine behind this seamless experience. Instead of requiring users to pre-convert and load a fiat balance, mJIT™ authorizes transactions by pulling the exact amount needed from the user's crypto wallet at the moment of purchase, converting it to fiat instantly. For Developers: This is handled through a single, clean API call. When a card transaction is initiated, our platform sends a request to your endpoint. Your system simply needs to approve or deny the transaction based on the user's crypto balance. If approved, you debit the user's crypto wallet, and we fund the transaction in fiat. It’s that direct. Value Proposition Stop thinking about crypto spending as a complex conversion process. With MatchMove, it becomes an instant, invisible part of the payment experience. You can now offer your users a powerful tool that unlocks the true value of their digital asset portfolio, allowing them to spend at millions of online and offline merchants across the globe just as easily as with a traditional bank card. Key Platform Benefits Go to Market Faster: Leverage our robust, API-first platform and regulatory licenses to launch your card program in a fraction of the time. Enhance User Loyalty: Provide a tangible, high-value service that transforms the utility of your users' assets and deeply integrates your platform into their daily financial lives. Simple Integration: Our clear documentation and developer-friendly APIs are designed for a straightforward and rapid integration process. Customized Branding: Issue cards that carry your brand, reinforcing your market presence with every single transaction. Future-Proof Your Platform: Position your exchange or wallet at the forefront of financial innovation by seamlessly connecting the world of digital assets with global commerce. MatchMove Products The below products serve as building block allowing you to bridge the last mile problem of enabling global commerce using crypto assets Identity & Onboarding Onboard Users in a regulatory-compliant manner for your card program Accounts (JIT) Issue JIT accounts for your users to facilitate just in time asset conversion Cards Issue white-labeled physical and virtual cards for your user • [Releases and updates](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates.md): Welcome to the home of innovation for the MatchMove banking platform. This feed is designed to keep our entire community—from the developers building on our APIs to the partners scaling their businesses—fully aligned with our latest features, refinements, and platform health. As the world of finance moves faster, so do we. Here, we document every step of our platform's evolution, ensuring you have the clarity and tools needed to build, launch, and manage seamless financial experiences. What to Expect Each update provides a comprehensive look at what’s new, why it matters, and how it impacts your integration: New Capabilities: Announcements of new financial modules, regional expansions, and product features designed to grow your offering. Platform Refinements: Technical enhancements to our APIs, SDKs, and dashboard to improve performance and developer experience. Compliance & Security: Vital updates on the regulatory landscape and security protocols to keep your operations and users protected. Documentation & Tools: Links to updated guides and recipes to accelerate your time-to-market and technical integrations. Stay in Sync To ensure you never miss a critical update, we recommend bookmarking this page. Critical platform updates will also be timely delivered to partners through other direct channels. Feature Tags Title Description #REGION feature or activity is available on all supported regions #IDENTITY user-related, due diligence or KYC-related feature or activity #ACCOUNT an account or wallet-related feature or activity #CARDS card-related feature or activity #COLLECTIONS transfer-in fund movement feature or activity #PAYOUTS cross-border and domestic payments or transfer-out fund movement feature or activity #PLATFORM platform-intrinsic feature or capability #ENVIRONMENT environment where the feature is live and testable • [Release notes v26.10.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-10-0.md): Release Date: October 15, 2026 🚀 What's New? API References (New): The MatchMove Banking API Specifications are now available on the developer portal. Each API reference covers its endpoints, the base URLs for the sandbox and production environments, and its webhooks. Onboarding API Accounts API Cards API Collections API Payouts API Platform API Reference: API References (New): https://developer.matchmove.com/matchmove-banking-api-specifications/onboarding-api #GLOBAL ✨ Enhancements Cross-Border Recipient Status Webhook (Updated): The payload of the PAYOUT.RECIPIENT.CROSSBORDER.STATUS webhook now carries the recipient state within an entities object, including a new sub_status field for granular lifecycle tracking. Partners should review the updated payload so their integrations continue to handle recipient status updates correctly. Field: sub_status (string) Description: Granular sub-status within PENDING . It is empty for non- PENDING states. Possible values: RISK_EVALUATION_IN_PROGRESS RISK_EVALUATION_PENDING_REVIEW RISK_EVALUATION_CLEAR COOLING_PERIOD_IN_PROGRESS COOLING_PERIOD_COMPLETED Reference: Create a Recipient for Cross-Border Payment (Updated): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/create-a-recipient-for-cross-border-payment #PAYOUTS #CROSS-BORERD #GLOBAL Source of Funds Document Type (New): SOURCE_OF_FUNDS is now supported as an additional document type for high-value cross-border transaction document requirements. Reference: Perform a Cross-Border Payment Using an Existing Recipient (Updated): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/perform-a-cross-border-payment-using-an-existing-recipient Perform a Cross-Border Payment Without an Existing Recipient (Updated): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/perform-a-cross-border-payment-without-an-existing-recipient PH Individual Onboarding – Improved Guidance (Updated): The Philippines individual onboarding guides for document-based and authentication-based verification now put more emphasis on one requirement: the user must be updated with all the information required by regulation before the KYC process can be initiated . This is a documentation update only, and platform behavior is unchanged. Missing required information: If the user profile has any gaps or missing information that is required before KYC, the missing fields are listed in the user.requirements object under immediately_due.required_attributes . Initiate verification step: The request to initiate verification is already marked optional for partners who are enabled for only a single primary KYC method. It is required only for partners with multiple KYC methods enabled. Guidance: Partners will need to follow the guides in the correct order throughout the individual onboarding workflow. References: 1. Register individual profile 2. Update individual profile (when needed or when required information gaps exist) 3. Submit individual KYC 3.A [PH] Document-based verification 3.B [PH] Authentication-based verification n 3.C Simulate individual KYC [Action Required]: Review your onboarding workflow according to the guide order. #IDENTITY #PHILIPPINES Enhanced Cross-Border Transaction Statuses (New): Every cross-border payout now follows one consistent lifecycle, whichever payment provider or rail carries it. Each payment provider's own statuses are translated into a single, unified set, so you integrate once and your logic keeps working as more payment providers are added. One set of statuses: No overlapping or ambiguous codes. Clear ownership: You can tell whether a transaction is waiting on MatchMove or on the payment provider. Predictable refunds: Every failure path ends with the user's funds returned or held for compliance. Deprecated to updated state mapping (first three shown; see the reference for the full list): Origin State Trigger Next State START Payment intent created INITIATED INITIATED Payload validation and user risk check PROCESSING PROCESSING A manual internal compliance check required PAYMENT_HOLD .. .. .. Reference: Cross-Border Payout Transaction Lifecycle (New): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts #PAYOUTS #CROSS-BORERD #GLOBAL PH Address – state_province Enumeration for Maguindanao (Updated): The Philippines state_province enumeration has changed for Maguindanao values. Values: MAGUINDANAO is deprecated to be replaced by MAGUINDANAO_DEL_NORTE and MAGUINDANAO_DEL_SUR city impact: The code values are unchanged. Cities that previously showed Maguindanao now show Maguindanao Del Norte or Maguindanao Del Sur in the description . Existing users: Active users and users who have already submitted KYC (PUT documents API call made) are unaffected and will continue using MAGUINDANAO . Rejected users using MAGUINDANAO need to correct their state_province address information to MAGUINDANAO_DEL_NORTE or MAGUINDANAO_DEL_SUR before resubmission. Users who have not yet submitted KYC, including newly registered users, users with a verified email or mobile number, and users who have only uploaded documents, will all be migrated to the new values. [Staging environment] – starting today, October 15, 2026: The new values are live in UAT. [Live environment] – roll-out date will be communicated to partners individually: Migrating Pre-KYC users needs careful planning before the new values go live in production. [Action Required]: Rejected users using MAGUINDANAO must correct their state_province to MAGUINDANAO_DEL_NORTE or MAGUINDANAO_DEL_SUR before resubmission. No action is required for all other users. #IDENTITY #PHILIPPINES Initiate KYC Capture API (New): Initiate KYC Capture API ( POST /{{entity_type}}/authentications/documents/verifications ) is an improved version of the Process KYC API. Applies to the following entities: Individuals: /users Businesses: /businesses Business associated parties: /associated_parties/ It still returns the href or redirect link to the eKYC web app, and it adds the optional callback parameters that let you send users from the eKYC capture screen back to your application once they complete or exit the eKYC flow. Include these (optional) parameters in your request: redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button, for example "Exit" or "Return". It applies only when redirect_mode is set to button . The Initiate KYC Capture API is now live in UAT. However, the optional callback feature (redirect_url) will only be enabled on Nov 1 . References: [SG] Document-based verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-document-based-verification [SG] Authentication-based verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-authentication-based-verification [SG] Partner-assisted verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-partner-assisted-verification [SG] Document-based verification (Businesses - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/business-ekyc/sg-document-based-verification #IDENTITY #GLOBAL ⚠️ Deprecations & Breaking Changes Legacy Cross-Border Transaction Statuses Deprecated: The legacy cross-border transaction statuses are deprecated in favor of the enhanced statuses. The previous statuses were too coarse to show where a user's money was, who was holding a payment up, or whether a refund had completed. The full deprecated-to-updated state mapping is available in the reference below. [Staging environment] – starting today to December 15, 2026 (Deprecation Period): The enhanced transaction statuses take effect immediately in the staging environment, and the legacy statuses will officially be retired on December 15. Partners who are currently in the implementation stage are required to update to the enhanced statuses immediately. [Live environment] – starting February 15, 2027 (Grace Period): The legacy statuses will be fully retired in the live environment. Partners must be migrated to the enhanced statuses to continue tracking cross-border transactions. [Action Required]: Please plan to update your applications to adopt the enhanced statuses and test your integration in the staging environment before the February 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: Cross-Border Payouts (Updated): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts #PAYOUTS #CROSS-BORDER #GLOBAL Legacy Remittance Transactions APIs Deprecated: The cross-border payout transactions (/payouts/remittances/transactions) APIs are deprecated and replaced by the enhanced cross-border payout payments (/payouts/remittances/payments) API. [Staging environment] – starting today to December 15, 2026 (Deprecation Period): The enhanced /payouts/remittances/payments API takes effect immediately in the staging environment, and the /payouts/remittances/transactions APIs will officially be retired on December 15. Partners who are currently in the implementation stage are required to use the new API immediately. [Live environment] – starting February 15, 2027 (Grace Period): The /payouts/remittances/transactions APIs will be fully retired in the live environment. Partners must be migrated to the /payouts/remittances/payments API to continue tracking cross-border payments. [Action Required]: Please plan to update your applications to adopt the new API and test your integration in the staging environment before the February 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: Track the Status of a Cross-Border Payment (Updated): https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/track-the-status-of-a-cross-border-payment #PAYOUTS #CROSS-BORDER #GLOBAL Process KYC API Deprecated: The Process KYC API ( POST /{{entity_type}}/authentications/documents/process ) is deprecated and replaced by the new Initiate KYC Capture API ( POST /{{entity_type}}/authentications/documents/verifications ). Applies to the following entities: Individuals: /users Businesses: /businesses Business associated parties: /associated_parties/ [Staging environment] – starting today to November 15, 2026 (Deprecation Period): The new Initiate KYC Capture API takes effect immediately in the staging environment, and the Process KYC API will officially be retired on November 15. Partners who are currently in the implementation stage are required to use the new API immediately. [Live environment] – starting January 15, 2027 (Grace Period): The Process KYC API will be fully retired in the live environment. Partners must be migrated to the Initiate KYC Capture API to continue capturing KYC. [Action Required]: Please plan to update your applications to adopt the new API and test your integration in the staging environment before the January 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. References: [SG] Document-based verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-document-based-verification [SG] Authentication-based verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-authentication-based-verification [SG] Partner-assisted verification (Individuals - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-partner-assisted-verification [SG] Document-based verification (Businesses - Updated): https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/business-ekyc/sg-document-based-verification #IDENTITY #GLOBAL Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.09.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-09-0.md): Release Date: September 15, 2026 🚀 What's New? Card Design Submission (New): New process documentation covering the end-to-end card design submission process — from artwork requirements through to approval and production. This gives partners a clear guide for getting card designs approved ahead of a program launch. Reference: Card Design Submission (New) #CARDS #GLOBAL On-Screen Digital Card Display (New): New documentation covering how to display a digital representation of a cardholder's card on-screen within a partner's application, including the required data and rendering guidance. Reference: On-Screen Digital Card Display (New) #CARDS #GLOBAL Glossary of Terms (New): A new glossary section is now available on the developer portal, containing definitions of jargon, banking terms, and platform-specific concepts used throughout the documentation. This helps partners and anyone exploring the platform quickly understand unfamiliar terminology without leaving the portal. Reference: Glossary of Terms (New) #PLATFORM #GLOBAL New Methods for SG-Configured Programs: Authentication-Based Verification and Document-Based Verification, previously available for PH-configured programs, are now available for SG-configured programs as well. [SG] Authentication-Based Verification: A hybrid verification model that uses SG Singpass trusted and verified data, and conducts risk verification on the collected user data. Action required: This is an opt-in feature that requires a configuration update to enable. If you're interested in enabling SG Singpass verification for your programs, please reach out to your MatchMove Account Manager for pricing details and the enablement process. Reference: [SG] Authentication-Based Verification (New) #IDENTITY #SINGAPORE [SG] Document-Based Verification: The Perform Individual KYC guide has been recategorized and renamed to [SG] Document-Based Verification, reflecting its use of eKYC to collect documents to verify the user profile and conduct risk verification on the user profile. No action required: If you are already implementing v2 Onboarding, this is the same guide document. Reference: [SG] Document-Based Verification (New) #IDENTITY #SINGAPORE ✨ Enhancements Individual eKYC (Updated): The Individual eKYC guide has been updated to reflect the new Document-Based and Authentication-Based Verification methods, giving partners a clearer picture of the available verification paths for individual users. Reference: Individual eKYC (Updated) #IDENTITY #SINGAPORE Capture Request Context Headers (Updated): As part of MatchMove's ongoing commitment to regulatory compliance and in response to evolving requirements from regulators in the region, this feature has been updated to include a new header, X-Auth-Actor , alongside the existing X-Auth-User-IP , X-Auth-Device-ID , and X-Auth-User-Agent headers. As previously announced, these content headers are now required parameters. X-Auth-User-IP , X-Auth-Device-ID , and X-Auth-User-Agent will only be required for user-initiated API calls. X-Auth-Actor will be required for all API calls, regardless of whether it is user-, system-, or operator-initiated. [Warning Period] – UAT/Staging environment, starting September 15, 2026: API calls not passing the required context headers will gradually start receiving validation warning messages . [Warning Period] – Production/Live environment, starting November 15, 2026: API calls not passing the required context headers will gradually start receiving validation warning messages . [Enforcement Period] – Production/Live environment, starting December 15, 2026: API calls not passing the required context headers will start receiving validation error messages, and requests will be rejected . [Action Required]: Please plan to update your applications and test them in the UAT environment before the December 15 production enforcement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: Capture Request Context Headers (Updated) #PLATFORM #GLOBAL Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.08.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-08-0.md): Release Date: August 14, 2026 🚀 What's New? Launching a Card Program: New end-to-end documentation covering the full card operational process—from program setup through to card issuance and management. This gives partners a comprehensive guide to launching and running a card program on the MatchMove platform. Reference: Launching a Card Program (New) #CARDS #GLOBAL MatchMove FAQs: A centralized knowledge base of the platform's most frequently asked questions and answers, covering integration, operational, and product topics—designed for existing and prospective partners and anyone exploring the MatchMove Banking Operating System. Reference: MatchMove FAQs (New) #PLATFORM #GLOBAL KYC Verification: Three new verification models are introduced, offering partners flexibility in how KYC is performed across different markets and use cases. 1. Partner-Assisted eKYC: A hybrid eKYC model where partners handle document uploads, and MatchMove performs liveness detection and Enhanced Due Diligence (EDD). This model gives partners control over the collection experience while relying on the platform for verification. Reference: Partner-Assisted eKYC (New) #IDENTITY #GLOBAL 2. Authentication-Based Verification: A hybrid verification model that uses PH National ID eVerify through the Banking Partner integration, combined with supporting document upload via the MatchMove Banking API. Reference: Authentication-Based Verification (New) #IDENTITY #PHILIPPINES 3. Document-Based Verification: An enhanced version of the existing KYC verification process where all document requirements are uploaded via the MatchMove Banking API, and the financial institution does the final verification. Reference: Document-Based Verification (New) #IDENTITY #PHILIPPINES ✨ Enhancements Card Transaction Fees (Updated): Updated documentation on card transaction fee structures, providing partners with clearer guidance on how fees are applied across different transaction types. Reference: Card Transaction Fees (Updated) #CARDS #GLOBAL Capture End User Context (New): To keep abreast of the growing threat landscape in the region and the increasing regulatory posture on transaction security, MatchMove is introducing new content headers for API usage. These headers enhance request traceability and security across the platform, supporting stronger audit trails and compliance readiness. The headers are currently optional. Partners are encouraged to begin including them now to ensure a smooth transition. [Staging environment] – starting September 15, 2026 (Warning Period): The API specification will begin reflecting in the documentation that context headers are required parameters. These context header requirements will also start to be enforced in the staging environment. API calls not passing these context headers will start receiving validation errors. [Live environment] – starting November 15, 2026 (Enforcement Period): The context header requirements will start to be enforced in the live environment. API calls not passing the required parameters will start receiving validation errors. [Action Required]: Please plan to update your applications and test them in the staging environment before the November 15 production enforcement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: Capture request context headers (New) #PLATFORM #GLOBAL ⚠️ Deprecations & Breaking Changes User and KYC Status Webhooks Deprecated (V2 Identity and Onboarding): The following webhooks are deprecated in favor of unified status events that carry revised payload structures and additional data. Partners should migrate to the replacement webhooks at the earliest opportunity. 1. PH-Configured Programs: Deprecated Webhook Replacement ACCOUNT.KYC.VERIFICATION_FAILED USER.DOCUMENT_VERIFICATION.STATUS Provides user and KYC status updates. ACCOUNT.KYC.VERIFICATION_APPROVED USER.DOCUMENT_VERIFICATION.STATUS Provides user and KYC status updates. ACCOUNT.KYC.VERIFICATION_REJECTED USER.DOCUMENT_VERIFICATION.STATUS Provides user and KYC status updates. [Staging environment] – starting today to September 15, 2026 (Deprecation Period): The new replacement webhooks will take effect immediately in the staging environment, and legacy webhooks will officially be retired on September 15. Partners who are currently in the implementation stage are required to update to the new webhooks immediately. [Live environment] – starting November 15, 2026 (Grace Period ) : The legacy webhooks will be fully retired in the live environment and will no longer send payloads. Partners must be migrated to the new webhooks to continue receiving event notifications. [Action Required]: Please plan to update your applications to adopt the new webhooks and test your integration in the staging environment before the November 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: [PH] Authentication-Based Verification (New) Reference: [ PH] Document-Based Verification (New) #IDENTITY #PHILIPPINES 2. SG-Configured and All Other Programs: Deprecated Webhook Replacement USER.DOCUMENT_VERIFICATION.STATUS (Individual and business users) USER.STATUS Provides user and KYC status updates. ASSOCIATED_PARTY.DOCUMENT_VERIFICATION.STATUS (Associated parties of a business user) ASSOCIATED_PARTIES.PROFILE.STATUS Provides associated party status updates. [Staging environment] – starting today to September 15, 2026 (Deprecation Period): The new replacement webhooks will take effect immediately in the staging environment, and legacy webhooks will officially be retired on September 15. Partners who are currently in the implementation stage are required to update to the new webhooks immediately. [Live environment] – starting November 15, 2026 (Grace Period) : The legacy webhooks will be fully retired in the live environment and will no longer send payloads. Partners must be migrated to the new webhooks to continue receiving event notifications. Action Required: Please plan to update your applications to adopt the new webhooks and test your integration in the staging environment before the November 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: [SG] Document-based Verification (Updated), formerly Perform Individual KYC (Renamed) Reference: Perform Business KYC (Updated) #IDENTITY #SINGAPORE #GLOBAL 3. Submit Individual KYC (v2) Deprecated: The current v2 - Submit Individual KYC guide and workflow are deprecated and will be removed from the developer portal after 60 days. It is retained only as a reference for past implementations. This legacy workflow will be replaced by the new D ocument-based verification and A uthentication-based verification methods. [Staging environment] – starting today to September 15, 2026 (Deprecation Period): Documentation-based verification : The new process will take effect in the staging environment, introducing minor changes to the KYC submission workflow . This is the direct replacement of the deprecated Submit Individual KYC process. Partners who are currently in the implementation stage are required to adopt the new document-based verification immediately. Authentication-based verification (Optional): The new alternative process will take effect in the staging environment, introducing a new way of verifying users via PH National ID through eVerify . As this new capability involves specific commercial terms, please connect with our Customer Growth team to explore pricing and integration steps. [Live environment] – starting November 15, 2026 (Grace Period): The legacy KYC process will be fully retired in the live environment. Partners must be migrated to the new document-based verification to continue processing user verifications. [Action Required] Please plan to update your applications to adopt the new Document-based verification process and test your integration in the staging environment before the November 15 production retirement date. Our Customer Growth and Implementation teams will be in contact with you to help plan your migration strategy and provide any needed support. Reference: (Legacy) Submit Individual KYC (Deprecated) Reference: Document-Based Verification (New) Reference: Authentication-Based Verification (New) #IDENTITY #PHILIPPINES 📝 Document Corrections Domestic Payment Cooling Period – Status Change Reverted: The recipient status field change announced in v26.07.0 ( PENDING_ACTIVATION → PENDING with SUB_STATUS handling) has been reverted for domestic payouts. Domestic payout recipients will continue to use PENDING_ACTIVATION as the status during the cooling-off period. Reference: Create a Recipient for Domestic Payout (Corrected) #PAYOUTS #GLOBAL Added Deprecation Period and Grace Period timing and advisory with respect to the deprecated platform features. Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.07.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-07-0.md): Release Date: July 15, 2026 🚀 What's New? Assisted 3DS Authentication – Biometric 2FA: Partners can now leverage mobile biometric user verification as an authentication method for card transactions. This adds a seamless, device-native layer of security that reduces friction for cardholders while maintaining strong customer authentication compliance. Reference: Assisted 3DS Authentication – Biometric 2FA (New) Reference: Simulate Assisted 3DS Authentication – Biometric 2FA (New) #CARDS #SINGAPORE #STAGING Card Personalization and Distribution: New process documentation covering the end-to-end process of card issuance, personalization, and distribution after physical cards have been manufactured. This provides partners with a clear understanding of how cards move from production to the cardholder's hands. Reference: Card Personalization and Distribution (New) #CARDS #GLOBAL ✨ Enhancements Assisted 3DS Webhook Payload - OTP 2FA (Updated): The webhook payload for Assisted 3DS authentication - OTP 2FA has been updated with newly published payload structures, providing partners with richer transaction authentication context for improved handling and decision-making. Reference: Assisted 3DS Authentication – OTP 2FA (Updated) #CARDS #GLOBAL #LIVE Card Order Serviceability API – Reduced Mandatory Fields (Updated): The Check User Address Serviceability API no longer requires address_1 , address_2 , address_4 (Region), and zipcode as mandatory fields. Partners can now check serviceability with fewer address inputs, simplifying the integration and improving coverage for users with limited address data. Reference: Check User Address Serviceability (Updated) #CARDS #PHILIPPINES #LIVE Cross-Border Payouts – Conditional Document Upload: Document upload is now only required when mandated by the payment rails. Partners no longer need to submit supporting documents for every transaction — only when the specific payment corridor or rails require it, streamlining the cross-border payment flow. Reference: Perform a Cross-Border Payment Using an Existing Beneficiary (Updated) #PAYOUTS #GLOBAL #LIVE KYC Simulation in Staging for PH Partners (Updated): Updated simulation instructions for PH partners to test KYC submission flows in the staging environment, enabling validation of the onboarding process before going live. Reference: Submit Individual KYC – Simulation in Staging (Updated) #IDENTITY #PHILIPPINES #STAGING ⚠️ Deprecations & Breaking Changes Recipient Cooling-Off Period – Status Field Change (Breaking): The recipient status handling for the cooling-off period has changed for both domestic (correction) and cross-border payouts. Previously: user.status == PENDING_ACTIVATION Now: user.status == PENDING , with additional handling for SUB_STATUS to determine the specific cooling-off or risk evaluation state. Scope: This change applies to both domestic and cross-border payout recipient flows. Action required: Update any integration logic that checks for PENDING_ACTIVATION to use PENDING with SUB_STATUS handling instead. Reference: Create Recipient for Domestic Payment (Updated) Reference: Create a Recipient for Cross-Border Payment (Updated) #PAYOUTS #GLOBAL #STAGING Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.06.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-06-0.md): Release Date: June 15, 2026 🚀 What's New? New Data Elements for Assisted Card Transaction Risk Management: Partners on the Shared Authorization model now receive an expanded set of transaction data elements in the OPENLOOP_PRE_AUTH webhook. These additions deliver richer fraud signals—from digital transaction metadata and shipping details to compromise alerts and on-behalf service results—enabling more precise real-time authorization decisions. DE 48.06 — Advanced Digital Transaction Data 1 (Phone Number) DE 48.08 — Advanced Digital Transaction Data 3 (Shipping Address) DE 48.39 — Account Data Compromise Information (ADC Alerts) DE 48.71 — On Behalf (OB) Services Results DE 23 — Card Sequence Number DE 48.32 — Mastercard Assigned ID DE 122.1.2 — Acceptor Country Subdivision Code Reference: Assisted Card Transaction Risk Management (Updated) Reference: Simulate Card Transactions (Updated) SWIFT Payment Rails Coverage Expansion for Cross-Border Payouts: Senders (both business and individual) can now initiate cross-border transfers to recipients in another country using SWIFT payment rails for both local and non-local currencies. This brings SWIFT and LOCAL payment rails together on one platform, significantly broadening payout reach. Recipients in a given country can now receive payments in multiple destination currencies—both local and non-local. For example, the United Arab Emirates (ARE) supports 27 currencies, including AED, USD, EUR, GBP, HKD, JPY, SGD, AUD, and others. Coverage expanded to 200+ countries and 110 unique currencies. Partners can now request and receive an MT103 file for every SWIFT transaction to track its status via Freshdesk. Enhanced Document API upload logic to support mandatory document upload for specific use cases. Reach out to your MatchMove implementation manager or the Customer Growth team to learn more. ⚠️ Deprecations & Breaking Changes Legacy Staging Base URL Sunsetting — https://beta-api.mmvpay.com Applicable: This sunsetting applies to partners who have upgraded to and are currently integrating the v2 Onboarding API . Effective: End of June 2026. The legacy unified staging base URL will be permanently decommissioned. Starting July 1, 2026: All partners integrating in UAT and staging environments must use the modularized, service-specific base URLs as described in the Begin Technical Integration guide. Action required: Migrate all staging and UAT API calls from https://beta-api.mmvpay.com to the appropriate modularized base URLs before June 30, 2026. Reference: Begin Technical Integration (Updated) ✨ Enhancements Card Order Serviceability API – line_4 (Region) Requirement Removed (Updated): The line_4 field is no longer required when checking user address serviceability for card delivery. This simplifies the address validation flow and reduces friction for partners integrating the card order delivery service. Reference: Check User Address Serviceability (Updated) ⚠️ Important Note The following changes were applied globally throughout the entire platform. There will be no program configuration upgrade needed for the following: New Card Transaction Data Elements and Risk Data Partners who are implementing the Shared Authorization model will be able to see the additional data and will be able to use it in their card authorization logic. Card Order Serviceability API Update Immediately in effect for subscribed partners. Updates and new capabilities not mentioned above will still require a program configuration upgrade. Our Implementation and Customer Growth teams will evaluate and will reach out to you individually when your program is identified as a candidate for this upgrade. Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.05.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-05-0.md): Release Date: May 15, 2026 🚀 What's New? Recipient Cooling-Off Period A mandatory waiting period is now enforced on newly created payout recipients before they become eligible for transactions. This fraud prevention measure provides a buffer window between recipient creation and activation, allowing suspicious activity to be detected and intercepted before funds can be sent. Domestic Payments: The cooling period will put the activation of a recipient on hold until the period is completed. Cross-Border Payments: The cooling period runs in parallel with risk evaluation — both must independently complete before a recipient reaches ACTIVE status. Reference: Cross-Border Payouts Overview (Updated) Reference: Domestic Payouts Overview (Updated) Onboard Users with Minimum Required Information: Partners can now create individual users, business users, and associated parties using only the minimum required fields. This enables faster onboarding by allowing users to get started on the platform sooner, with additional profile details collected progressively as needed. Reference: Register Individual Profile (Updated — Minimum Required Information) Reference: Register Business Profile & Associated Parties (Updated — Minimum Required Information) Additional Data Elements for Assisted Card Transaction Risk Management: Partners on the Shared Authorization model now receive expanded transaction context in the OPENLOOP_PRE_AUTH webhook. These additional data points provide richer cardholder authentication and transaction security details, enabling more informed real-time authorization decisions. DE 22, sub-element 2 — POS Entry Mode DE 48, sub-element 22.01 — Multi-Purpose Merchant Indicator DE 48, sub-element 22.02 — Cardholder/Card Verification Method DE 48, sub-element 22.05 — Terminal Compliance Indicator Reference: Assisted Card Transaction Risk Management (Updated) Reference: Simulate Card Transactions (Updated) ✨ Enhancements eKYC Simulation for High-Risk Onboarding (Updated): Updated simulation instructions now cover high-risk individual and business onboarding scenarios, allowing partners to test enhanced due diligence flows in the staging environment. Reference: eKYC Simulation for High-Risk Individuals (Updated) Reference: eKYC Simulation for High-Risk Businesses (Updated) Card Order Delivery – Webhook Availability (Updated): Partners subscribed to the card delivery service can now receive real-time notifications on card order status changes via the CARDS.ORDERS.UPDATE webhook event. This provides timely visibility into delivery progress without the need to poll the API. Reference: Retrieve Card Order Details (Updated) Card Order Delivery – User Address Serviceability Guidance (Updated): Updated documentation now includes usage guidance for both user-scope and admin-scope APIs when checking address serviceability, covering requirements for pre-KYC and post-KYC users. Reference: Check User Address Serviceability (Updated) ⚠️ Deprecations & Breaking Changes Cross-Border Recipient Status with regard to the Cooling-off Period –- DEACTIVATED and PENDING_REVIEW are deprecated: DEACTIVATED - Deprecated as of May 2025. Replaced by the INACTIVE status. PENDING_REVIEW - Deprecated as of May 2025. Replaced by the PENDING status. Action required: Update any recipient status handling logic that references DEACTIVATED or PENDING_REVIEW to use INACTIVE and PENDING respectively. Reference: Create a Recipient for Cross-Border Payment (Updated) ⚠️ Important Note The following changes were applied globally throughout the entire platform. There will be no program configuration upgrade needed for the following: Cooling-off Period for Recipients Partners who are subscribed to the Domestic and Cross-border Payout capability will be affected by this change. New Card Transaction Data Elements and Risk Data Partners who are implementing the Shared Authorization model will be able to see the additional data and will be able to use it in their card authorization logic. Updates and new capabilities not mentioned above will still require a program configuration upgrade. Our Implementation and Customer Growth teams will evaluate and will reach out to you individually when your program is identified as a candidate for this upgrade. Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.04.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-04-0.md): Release Date: April 17, 2026 🚀 What's New? Card Order & Delivery Module: A new module that validates delivery addresses before card production begins and provides end-to-end tracking — from order through to doorstep delivery. This helps reduce failed deliveries and wasted card stock. This feature is only available to Partners who are subscribed to the MatchMove Card Delivery service. Reference: Card Order & Delivery (New) DE 61 – Point-of-Service (POS) Data in Card Transaction: Partners on the Shared Authorization model now receive richer point-of-sale context during card authorization, enabling smarter, real-time fraud decisions. Reference: Assisted Card Transaction Risk Management (Updated — DE 61 POS Data) ✨ Enhancements PH Address – Barangay Enumeration Enablement: For Philippines-issued programs, the Barangay address field ( line_3 ) now supports standardized enumeration values. This improves data consistency, reduces onboarding errors for PH users, and supports card order delivery coverage matching. Reference: PH Region-Specific Onboarding (Updated — Barangay Enumerations) ⚠️ Deprecations & Breaking Changes Document requirement for high-value SWIFT transactions: The quote response for high-value SWIFT transactions now includes a structured document_requirements object with accepted file types and size limits, making it easier to build compliant document upload flows. Deprecated: document_required_types array in the Enquire Quotes response. Replaced by: document_requirements object, which includes types , accepted_formats , and max_file_size . Backward compatibility: The deprecated field will continue to be returned temporarily but may be removed in a future release. Action required: Update your integration to consume document_requirements instead. Reference: Get a Quote for Cross-Border Payment (Updated — SWIFT document_requirements ) ⚠️ Important Note Enabling these new capabilities requires a program configuration upgrade. Our Implementation and Customer Growth teams will evaluate and will reach out to you individually when your program is identified as a candidate for this upgrade. Need help? Reach out to your MatchMove integration partner or contact the support team. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.03.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-03-0.md): Release Date: March 16, 2026 🚀 What’s New? V2 Card Status API: We are launching an enhanced version of our Card Status API, offering more granular lifecycle management and improved performance. Program Eligibility: As of the moment, this version is restricted to JIT (Just-in-Time) configured programs. This allows for seamless synchronization between card states and your JIT authorization logic, enabling immediate status updates within the authorization window. Coming Soon: We are currently developing a Card Status Update Webhook that will deliver real-time notifications whenever a card status changes, ensuring your system stays in sync without manual polling. Reference: Suspend an active card (Updated) Reference: Reactivate a suspended card (Updated) Reference: Permanently block a card (Updated) ✨ Enhancements The Identity and Onboarding APIs have been updated to support new regional requirements for individual users and refined entity mapping for business users. V2 Philippine Onboarding: Individual Profile Updates: Regulatory Compliance: To stay aligned with the latest SEC and BSP standards for 2026, we have updated requirements for individual profiles to ensure data meets new digital reporting mandates. New Required Fields: The onboarding flow now includes mandatory fields for Place of Birth Address, and Name Suffix (where applicable) to ensure legal name and identity accuracy. Validation Refinements: We have refined our field validation patterns (Regex) to better support Philippine-specific data formats, reducing manual data corrections during onboarding. Reference: Region-specific Onboarding - Philippines (Updated) V2 Business Onboarding: Associated Party Roles: Role Mapping: As part of our V2 business onboarding rollout, we have refined role definitions to ensure they are correctly mapped to supported entity types. Entity Type Glimpse: Title Supported Types SHAREHOLDER Individual, Business INVESTOR Individual, Business UBO Individual .. more -- Reference: V2 Onboard Business Users (Updated — Associated Party Roles and types) ⚠️ Important Note Enabling these new capabilities requires a program configuration upgrade. Our Implementation and Customer Growth teams will evaluate and will reach out to you individually when your program is identified as a candidate for this upgrade. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.02.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-26-02-0.md): Release Date: February 13, 2026 🚀 What’s New? We are proud to introduce Identity and Onboarding v2 , a major upgrade designed to support complex business hierarchies and streamline compliance through automation. Complex Entity Management: You can now define intricate relationships between users, specifically creating parent-child structures where Sub-business Individuals and Businesses operate as child entities. End-to-End Automated eKYC: We have transitioned from manual workflows to a fully automated verification process. This update removes operational bottlenecks, allowing for real-time validation of user identities and corporate structures. Reference: v2 Onboard Individual User (New) Reference: v2 Onboard Business User (New) ✨ Enhancements The Identity and Onboarding APIs have been expanded to provide greater flexibility in how user entities and compliance are handled. Identity & Onboarding v2 API Updates: Parent-Child Relationships: Added the ability to create and manage parent-child relationships. Sub-business individuals and business entities can now be onboarded as children of a parent user entity. Associated Parties: New capabilities to create business-associated parties—such as Ultimate Beneficial Owners (UBOs), Directors, and Shareholders—and directly link them to a business entity. eKYC Capabilities: Individual Onboarding: Enabled fully automated processing for individual users. From document submission to liveness checks, the system now instantly verifies identity without requiring manual back-office approval. Business Onboarding: Enabled automated corporate verification . The system now automatically validates business registration details against reliable data sources, significantly reducing the time to activate business accounts. Business Associated Party KYC: Enabled automated screening for associated parties (UBOs, Directors, Shareholders). These individuals are now automatically screened against global sanctions and watchlist databases as part of the business onboarding workflow. ⚠️ Important Note Enabling these new capabilities requires a program configuration upgrade. Our Implementation and Customer Growth teams will evaluate and will reach out to you individually when your program is identified as a candidate for this upgrade. Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v26.01.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-notes-v26-01-0.md): Release Date: January 15, 2026 🚀 What’s New? We are introducing the Modularization of API Base URLs to enhance system performance, security, and scalability. By categorizing our services into dedicated base URLs, we ensure a more robust and specialized environment for each of our core banking modules. Improved Scalability: Dedicated environments for different API categories allow for better load handling and faster response times. Enhanced Reliability: Maintenance or updates to one API category will have minimal impact on others. Future-Proof Infrastructure: This modular approach paves the way for faster deployment of specialized features across our product suites. ✨ Enhancements To support this transition, we have updated our connectivity framework. This change moves away from a single "catch-all" endpoint to category-specific base URLs. Doc Update: The "Start your implementation" guide has been fully updated to reflect the new categorized URL structure. API Updates: Modular Base URLs: API endpoints are now grouped by category (e.g., Wallets, Cards, Payouts). Gradual Rollout: Migration to these new base URLs will be implemented gradually across all partners starting in Q1 2026 . Migration & Compliance: Migration Window: You do not need to take immediate action today. Your current implementation will remain unchanged and working . Our Implementation and Customer Growth teams will reach out to you individually (partners) to provide a convenient and tailored schedule for compliance. Support: During your scheduled migration window, our technical team will provide direct support to ensure a seamless transition of your environment variables to the new URLs. Reference: Begin technical integration Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Release notes v25.12.0](https://developer.matchmove.com/matchmove-banking-operating-system/releases-and-updates/release-note-dec-2025.md): Release Date: December 15, 2025 🚀 What’s New? We’ve launched our Cross-border Payout: SWIFT integration to give you broader, faster, and more affordable global reach. Massive Coverage: Send funds to over 11,000 financial institutions across 200+ countries. Faster Settlement: 90% of SWIFT payments now reach the destination bank within an hour. Cost Efficiency: Enjoy lower transaction fees and competitive exchange rates for high-value transfers. ✨ Enhancements The MatchMove Payouts API has been updated to give users options on which cross-border payment rail to choose for transfers. Doc Update: Cross-border payout guides are updated with LOCAL and SWIFT payment rail integration workflows. API Updates: Added new parameters ( payment_rail , charge_type ) to distinguish payment rail options for cross-border payments. Added new Payout document upload API: POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files to allow submission of supplementary documents for high-value transactions. Backward compatibility : Existing program partners using the existing MatchMove Payouts API will be unaffected by the new changes. A configuration update will be required to enable SWIFT payments for partners that have subscribed to the payout product. Reference: Cross-border Payouts Interested to learn more? Reach out to our Business Development and Customer Growth teams at [ sales@matchmove.com ]. • [Program overview](https://developer.matchmove.com/matchmove-banking-operating-system/program-overview.md): Program configuration determines which product capabilities are available to your end users based on your use case, jurisdiction, and business model. Each product capability you enable (Cards, Collections, and Payouts) inherits program configurations. Furthermore, depending on the product level, additional parameters may be set. What is your use case? Demographic and profile of users you onboard. Relationship of the end user with you Funds flow within the program and to external entities. In addition to the baseline configurations established for creating a compliant program construct, you can add additional controls or configurations that will be required to tailor the program to your specific use case. Related Links Program prefund Program virtual account Regulations • [Program prefund](https://developer.matchmove.com/matchmove-banking-operating-system/program-pre-fund.md): Fund management for your program Every product has a prefund, which serves as an operating account for financial payments made to end users. Depending on your product configuration, the debits made by the user can also be added to the product's prefund. Depending on the program region and currency, the product can be issued with a virtual product account that can be used to facilitate collections or pre-fund top-ups via the banking channels. Program prefund The program prefund serves as an account used to manage the funding capabilities of users in the product. Every time an end-user wallet is funded, it will create a debit record on the product prefund. In addition, every credit for the end-user also adds a credit entry to the debit prefund. Debit prefund Debit prefund serves as a ledger that monitors the total amount of funds available for end users' accounts to spend. Related Links Program overview Program virtual account Regulations Anti-scam measures High-risk countries Prohibited countries Prohibited industries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Program virtual account](https://developer.matchmove.com/matchmove-banking-operating-system/program-virtual-account.md): The Program Virtual Account section enables partners to manage a dedicated virtual bank account linked to their program. It facilitates the receipt of incoming transfers, allowing partners to top up or fund the program as needed. If no fund addition is required, usage of this virtual account can be optional. Adding funds to your program Go to your MatchMove Adminet dashboard, then click on “View details” from the program prefund card under program info. Alternatively, you can click on "Accounts" and click on “Program accounts." This will list down the details you need to initiate payments to your program's prefund. The screen will show: Account number Account holder name Bank Name Bank SWIFT code Bank Address (Optional—only required for the USD program for SWIFT transactions) Program Virtual Account (sample) From your own bank account, you can add the account details listed above as a beneficiary. After adding the beneficiary, you can transfer funds that are added to the program prefund account. Once we receive the funds, they are automatically added to your program prefund account Related Links Program overview Program prefund Regulations • [Regulations](https://developer.matchmove.com/matchmove-banking-operating-system/regulations.md): The Regulations section summarizes how regulatory requirements are configured by product in the MatchMove Banking Operating System and guides partners to complete their own due diligence to remain compliant with their program obligations. Use this page to: Understand which regulatory controls the platform configures for each product category. Identify what you, as a partner, must implement and document. Prepare evidence for audits, program reviews, and regulator inquiries. Important: This page outlines product-level configurations and responsibilities. It is not legal advice. Engage your legal counsel for jurisdiction-specific interpretation. Core Concepts Product : A functional capability offered by the platform (for example, Identity and onboarding, Cards, Payouts, Collections). Product names match the left‑nav taxonomy. Program : Your specific deployment of one or more products under a defined commercial and regulatory framework. Jurisdiction : The country or region whose laws and regulations apply to your program and end users. Regulatory configuration : Controls and settings enforced by the platform to meet policy and program requirements (for example, KYC verification policies, transaction monitoring rules, and card usage restrictions). Roles and responsibilities : The division of obligations between the platform, licensed issuer(s), and you as a partner Related Links Program overview Program prefund Program virtual account Anti-scam measures High-risk countries Prohibited countries Prohibited industries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Anti-scam measures](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/anti-scam-measures.md): Background The Monetary Authority of Singapore (MAS) published a circular on Anti-scam measures in October 2024. The regulator has proposed and defined frameworks and guidelines on how to safeguard further financial transactions made on e-money payment accounts issued by Major Payment Institution (MPI) licensees such as MatchMove. Following the circular, MatchMove will gradually and continuously implement upgrades to bolster the security and safety of the platform. As valued partners and consumers of our ecosystem, we prioritize your compliance and readiness for regulatory changes and a disruption-free experience for your customers. Preparing in advance for new regulations, it's imperative that you continuously enhance your applications and customer workflows to adhere to these regulatory guidelines. Anti-scam preventive measures to be implemented in the Partner apps 1 Restriction on sending of clickable links or QR codes A responsible financial institution should not send clickable links or QR codes via email or SMS to customers, unless they link to: An informational website that asks for an access code The webpage should not require the user to input their access code or one-time PIN (OTP) to complete a payment transaction. A platform to download and install applications It can be a landing page to download the partner application or a universal link to an app store application. No unwanted phone numbers Phone numbers should not be added in the message unless the customer is expecting it. Current MatchMove customer communications sent to customers: OTP sent via mobile for ECOM transactions that require a 3D Secure (3DS) authentication. Token activation request sent for cards to be tokenized on Google Pay or Apple Pay. Token lifecycle event sent for update of token statuses, which are tokenized by the end user. Action Required: As a platform user, you are urged to take an inventory of all the SMS and email communications that are currently being sent to your end users. Ensuring that these messages adhere to the guidelines on using clickable links and QR codes in the message content. 2 Add additional metadata to outgoing transactions made in an account To enhance transaction auditing and tracking, some additional metadata will need to be added to the transactions made in a user account. These additional metadata are the following: Amount of the transaction The amount transacted, whether credited or debited from the user account, should be displayed prominently and must be easily identifiable by the end user. Details of the transaction The payment details may include the transaction type, source of funds, comments, and notes on the transaction. Adding this data will help the end user and auditors identify and confirm transaction authenticity. Action Required: Prepare and add the following metadata to transaction API calls for audit and tracking. These additional metadata may also be used for the transaction notification content that will be sent to the customers later. The MatchMove API provides a way to add custom metadata to transactions initiated via the API. We can utilize the details field available in the fund transfer API and use that to carry the custom metadata. The details field can accept a JSON string object with the following definition: details.pp - Payment processor, which identifies which type of payment was processed or executed details.transaction_comments - Any message or internal comments on the transaction details.payment_ref - The payment reference identifier generated by the payment service provider details.source_account - The fund source account or card number for the debit or credit details.source_bank_name - The fund source bank name or the bank issuer of the card (when available) details.source_network_name - The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available) Various types of financial transactions can be made on the MatchMove platform. However, these are the credit and debit transaction types that we need to focus on: Credit type details.pp details.transaction_comments details.payment_ref details.source_account details.source_bank_name details.source_network_name Top-up done via debit card DEBIT_CARD_TOPUP — Payment reference generated by the service provider The masked card number of the debit card The issuing bank name, when available Card network name, when available Top-up done via credit card CREDIT_CARD_TOPUP — Payment reference generated by the service provider Masked card number of the credit card The issuing bank name, when available Card network name, when available Top-up done via internet banking INTERNET_BANKING_TOPUP — Payment reference generated by the service provider number of the source account The name of the originating bank account — Top-up done via cash over the counter CASH_OVER_COUNTER_TOPUP — Payment reference generated by the cash over-the-counter agent — — — A line of credit is given to the user LINE_OF_CREDIT — Partner Reference ID from the LMS or internal reference number — — — Working capital loan given to the user WORKIN_CAPITAL_LOAN — Partner Reference ID from the LMS or internal reference number — — — Generic credit CREDIT — Partner Reference ID from the LMS or internal reference number — — — Cashback is given to the user CASHBACK Human-readable comment that can be displayed to the user, enumerating details of the cashback Partner reference ID for the transaction — — — Load done by partner PARTNER_CREDIT Human-readable comment that can be displayed to the user, enumerating details of the credit done by the partner and its purpose Partner reference ID for the transaction — — — Cash / Credit note given by the partner in place of grievances PARTNER_CREDIT_NOTE Human-readable comment that can be displayed to the user, enumerating details of the credit note done by the partner and its purpose Partner reference ID for the transaction — — — Equivalent fiat top-up done for crypto loads CRYPTO_REDEMPTION — Partner reference ID for the transaction — — — Debit type details.pp details.transaction_comments details.payment_ref details.source_account details.source_bank_name details.source_network_name Debit done for goods and services MERCHANT_PAYMENT Details of goods and services offered Partner reference ID for the transaction The merchant name for which the debit was initiated The issuing bank name, when available Card network name, when available Debit done for fees FEES The type of fee charged Partner reference ID for the transaction — The issuing bank name, when available Card network name, when available Debit done for other financial services FINANCIAL_SERVICES_PAYMENT Details of the financial service utilized Partner reference ID for the transaction — The name of the originating bank account — Debit done for crypto purchase CRYPTO_PURCHASE Details of the purchase Partner reference ID for the transaction — — — 3 Notify your customers regarding transaction activities in their accounts You are required to deliver timely notifications to your end users on every outgoing transactional activity done in the system. The table below highlights the list of recommended transaction notifications to the user, including the mapping of message content to the transaction details stored in the ledger. Transaction Type Delivery Channel and Timing Message Template Expected Action from Partner Removal of funds Push notification if available SMS or email Type: MERCHANT_PAYMENT Successful merchant payment: <amt> to <details.merchant_name> on <time and date> . If unauthorized, please reach out to <Partner hotline/support> immediately. Type: FEES Successful Fee deduction: <amt> for <details.transaction_comments> on <time and date> . If unauthorised, please reach out to <Partner hotline/support> imme diately. Type: FINANCIAL_SERVICES_PAYMENT Successful deduction: <amt> for <details.transaction_comments> on <time and date> . If unauthorised, please reach out to <Partner hotline/support> immediately. Type: CRYPTO_PURCHASE Successful deduction: <amt> for <details.transaction_comments> on <time and date> . If unauthorized, please reach out to <Partner hotline/support> immediately. On successful response of DELETE users/wallets/funds, trigger the notification to the end user P2P transfer initiated for the user within the platform Push notification if available SMS or email Successful transfer: <amt> to <recipient.email/recipient.sms> on <time and date> . If unauthorised, please reach out to <Partner hotline/support> immediately. On successful response of POST users/wallets/funds, trigger notification to the end user Bank transfer initiated Push notification if available SMS or email Successful transfer: <amt> to <bank holder name> ( < masked bank account number >) on <time and date> . If unauthorized, please reach out to <Partner hotline/support> immediately. On successful response of POST /users/wallets/fund_transfers/credit, trigger notification to the end user M ap the fields as response.bank_account.bank_holder_name to <bank holder name> response.bank_account.bank_account_number to <masked bank account number> Card transactions completed Push notification if available SMS or email Type: POS & ECOM transactions Successful Payment: <amt> to <merchant_name> using <last four digits of card number> on <time and date>. If unauthorized, please reach out to <Partner hotline/support> immediately. Type: ATM withdrawal Successful withdrawal: <amt> via <merchant_name> using <last four digits of card number> on <time and date> . If unauthorized, please reach out to <Partner hotline/support> immediately. Subscribe to the webhook: OPENLOOP_POST_AUTH Upon receiving the webhook, process the payload message, then trigger a notification to the end user Map the fields as: transaction . authorization . total_amount + transaction . authorization . total_currency to <amt> payment_instrument . masked_number to <last four digits of the card number> time_stamp to <time and date> Remittance transactions completed Push notification if available SMS or email Successful remittance: <amt> to <account holder name> ( <account number> ) on <time and date> . If unauthorised, please reach out to <Partner hotline/support> immediately. On success response of POST oauth/consumer/funds/transfers/overseas, trigger notification to end user. *<Partner hotline/support> refers to the 24/7 partner support channels, made available to customers for incident reporting. Action Required: Notify your end users on any channel available for these types of transactions: A completed removal (debit) of funds from a customer account A completed P2P transfer between users or with the prefund Any bank transfers to and from bank accounts / mobile wallets A completed card transaction A submitted remittance transaction For audit purposes, you are required to maintain logs that demonstrate the delivery and receipt of these notifications to end users. Along with the timestamps, the message content should also be included in the log. This log must be accessible, keeping a record of the last 12 months (this log period may be subject to change). 4 Alert customers before performing a high-risk activity To safeguard users and ensure that they are adequately informed that they are about to perform a high-risk transaction. It is also vital that they are made aware of the associated risks attached to the transaction that they will be performing. Identified high-risk activities Update of Personal Information, specifically: email mobile number address 2. Addition of new beneficiaries for: Cross-Border Payouts a) Mobile Wallets b) Banks c) Cash pickup to a new individual Domestic Payouts a) Addition of a new Bank Account as a beneficiary b) Addition of a new Mobile wallet as a beneficiary Guidance for the alert message content Call out the activity by following alert activities as per the application UI scheme Call out a caution to the end user Have a clear explanation of the risks in the activity Give the user an immediate option to reject the action Explicitly request the user's consent before proceeding with the activity 5 Set up a 24/7 customer support channel Partners are required to ensure that a 24/7 channel is available to customers, accessible at all times, for consumers to report unauthorized transactions. Action Required: Partners should have one or more of the following: Manned telephone line Dedicated phone number Messaging app channels, e.g., WhatsApp, Telegram Helpdesk portal for raising requests, digitally manned by a live agent Monitored email address Social media channels (if applicable) In addition, the partner should have a Standard Operating Procedure (SOP) in place for addressing expedited resolution requests. 6 Self-service “kill-switch” feature Aside from the available customer support channels, the partner must have an application feature that allows customers to temporarily suspend or disable their accounts ("kill-switch") on their own. In conjunction with this, partners must also have a clear SOP for re-enabling or unsuspension of a customer account. Proper verification and authentication of the customer must be completed before the reenablement. This reenablement may be done through the administrator dashboard, Adminnet, or orchestrated using the API. This “kill-switch" application feature should provide the customer with an immediate corrective action in cases where the customer suspects that a scam or fraud is in progress or has taken place. Action Required: Implement an application feature that allows: self-service account suspension or disablement Set up an SOP for: customer verification and authentication before allowing account unsuspension or re-enabling Related Links Program overview Program prefund Program virtual account Regulations High-risk countries Prohibited countries Prohibited industries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [High-risk countries](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/high-risk-countries.md): As per the regulation, MatchMove requires entities from the following countries will have to undergo an Enhanced Due Diligence (EDD) process. The continuation of the business relationship is subject to compliance checks and review processes. High risk countries Algeria Angola Bulgaria Burkina Faso Cameroon Côte d’Ivoire Croatia Guinea-Bissau Haiti Kenya Lebanon Monaco Mozambique Myanmar Namibia Nigeria Philippines Russia (residents are prohibited, while citizens of Russia residing in other countries will be required to complete EDD) South Africa Tanzania Turkey Ukraine Vietnam Related Links Program overview Program prefund Program virtual account Regulations Anti-scam measures Prohibited countries Prohibited industries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Prohibited countries](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/prohibited-countries.md): According to the regulation, MatchMove doesn't allow entities from the following regions to be onboarded onto the platform. Prohibited countries Afghanistan Belarus Central African Republic (CAR) Canada * China * Cuba Democratic People's Republic of Korea (DPRK) Democratic Republic of Congo (DRC) Ethiopia India * Iran Iraq Libya Mali Rwanda Sierra Leone Somalia South Sudan Sudan Syria United States of America * Venezuela Yemen *Due to issuing restrictions in the home country. Related Links Program overview Program prefund Program virtual account Regulations Anti-scam measures High-risk countries Prohibited industries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Prohibited industries](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/prohibited-industries.md): As per the regulation, MatchMove doesn't allow businesses operating in the following industries to be onboarded onto the platform. Please note that this list is representative and may change as the regulatory landscape evolves. Prohibited industries Shell company Shell banks Atomic power Unregulated charities Red-light business/adult entertainment Marijuana Gambling Non-regulated banking and finance in non-FATF member jurisdictions Illegal wildlife trade Illegal logging and timber trade Waste trafficking and illegal storage/disposal Related Links Program overview Program prefund Program virtual account Regulations Anti-scam measures High-risk countries Prohibited countries High-risk industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [High-risk industries](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/high-risk-industries.md): As per the regulation, MatchMove requires businesses operating in the following industries to undergo an Enhanced Due Diligence (EDD) process. The continuation of the business relationship is subject to compliance checks and review processes. High risk industries Money or Value Transfer Services (MVTS) / Money Service Business (MSB) Customers Includes Money Changing and Remittance Services Regulated casinos and casino junkets Virtual Currencies Corporate Services Providers Correspondent Banks Payment Service Provider Art/antique dealers, auction houses, or dealers and traders in high-value goods Arms, defense, military Precious metals and stones Non-Profit Organizations (includes regulated charities, foundations, cultural associations, private educational institutions, religious organizations, private health institutions, voluntary welfare organizations) Non-Government Organizations Embassies/Consulates PEP Nexus / PEP Related / PEP Close Associate Regulated banking and finance entities in non-FATF member jurisdictions Real Estate Licensed Trust Companies External Asset Managers Related Links Program overview Program prefund Program virtual account Regulations Anti-scam measures High-risk countries Prohibited countries Prohibited industries Virtual account restrictions Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Virtual account restrictions](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/virtual-account-restrictions.md): To uphold regulatory standards and risk management protocols, the creation or issuance of Virtual Accounts is strictly prohibited for the following categories: Money Service Businesses (MSBs) Money Service Operators (MSOs) Licensed Financial Institutions (FIs) Cryptocurrency exchanges or trading platforms Entities domiciled in jurisdictions or engaged in industries classified as prohibited or high-risk This policy is implemented to ensure compliance with applicable legal, regulatory, and internal risk frameworks. Applications from such entities will be automatically declined. Clients and partners are expected to perform due diligence to ensure adherence to this policy before initiating any Virtual Account requests. This provision is enforced to ensure adherence to regulatory requirements and to maintain the integrity of financial transactions. The Register of Prohibited and High-Risk Countries can be referenced via the provided hyperlink here and should be used as a primary source for identifying restricted jurisdictions. Related Links Program overview Program prefund Program virtual account Regulations Anti-scam measures High-risk countries Prohibited countries Prohibited industries High-risk industries Prohibited countries for card transactions Prohibited currencies for card transactions Prohibited MCCs for card transactions • [Region-specific onboarding](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/region-specific-onboarding.md): Learn about the unique onboarding requirements for users in different countries. Understand the regional variations in the KYC and KYB processes that you need to be aware of. Navigating a Multi-Regional Compliance Landscape Customer onboarding is the regulated entry point to a business relationship. For global entities, this process transforms into a complex, multi-layered regulatory gauntlet where basic identity checks must coexist with high-stakes financial crime prevention and strict data protection laws. I. KYC and AML Know Your Customer (KYC) and Anti-Money Laundering (AML) regulations are the bedrock of compliance. They mandate that businesses not only verify a customer's identity but also assess the risks they pose. This is where regional variance creates the first point of friction. Title Description Title Compliance Component Regional Complexity & Nuance Impact on Onboarding Customer Identification Program (CIP) The types of accepted documents differ vastly. US might require a Social Security Number (SSN); the EU mandates government-issued IDs for electronic KYC (e-KYC); while some APAC nations require physical presence or video verification for certain risk profiles. Fragmented Workflow: Businesses cannot use a single digital process. They must maintain and support multiple document validation and verification methods, slowing down global rollout and increasing system complexity. Customer Due Diligence (CDD) The threshold for determining Ultimate Beneficial Ownership (UBO) varies. Some regions may require identification of all owners with $>10\%$ stake, while others stick to $>25\%$. Furthermore, the required documents for corporate customers (e.g., Certificates of Incorporation, local tax IDs) are unique to each jurisdiction. UBO Opacity: Corporate onboarding becomes a time-consuming manual process, especially when dealing with complex, multi-layered entities or shell companies prevalent in high-risk regions, leading to significant delays and friction. Record-Keeping & Reporting Local AML laws dictate how long customer data must be retained (e.g., 5-7 years after the relationship ends) and the format. Additionally, the process and timeline for filing Suspicious Activity Reports (SARs) or Suspicious Transaction Reports (STRs) are unique to each national financial intelligence unit. Operational Overhead: Requires complex data retention policies and IT architecture to segment and manage customer files based on local compliance timelines, ensuring data is kept for the required period—but not longer than permitted by privacy laws. II. Sanctions, High-Risk Jurisdictions, and PEPs The complexity escalates when screening for financial crime risks. The Risk-Based Approach (RBA) requires that onboarding intensity be scaled up for high-risk customers, triggering Enhanced Due Diligence (EDD) . Title Description Title Risk Factor Regulatory Challenge Impact on EDD Onboarding Global Sanctions Screening Sanctions are imposed by numerous global (UN) and national bodies ( OFAC , EU ). A company must screen against all lists that could claim jurisdiction over them (e.g., a non-US company transacting in USD is subject to OFAC). The lists are constantly updated, requiring real-time compliance. False Positive Crisis: High volumes of name matches (false positives) from sanctions lists require manual compliance review (an alert disposition process ), which is time-consuming and a major choke point in fast onboarding. High-Risk Geographies Entities like the Financial Action Task Force (FATF) designate high-risk and monitored jurisdictions. Onboarding from these areas often necessitates mandatory EDD, including an extensive check of the customer's Source of Funds (SoF) and Source of Wealth (SoW) . Intrusive Documentation: Customers are asked for tax returns, audited statements, and proof of income. This intrusive process is often met with resistance and high abandonment rates and is frequently impossible to complete in jurisdictions with poor public record infrastructure. Politically Exposed Persons (PEPs) Identifying PEPs (and their Relatives and Close Associates - RCAs ) is critical because of the heightened risk of corruption. The definition of a "prominent public function" can vary by country, complicating screening. Senior Approval Mandate: Onboarding a PEP usually requires approval from the business’s Senior Management and implementation of a costly enhanced ongoing monitoring plan from day one, adding significant internal bureaucracy to the sales cycle. III. Data Privacy Layered atop the AML/KYC and financial crime checks are the geographically siloed data privacy regulations, creating fundamental conflicts with the data-hungry nature of EDD. Conflict of Laws (KYC vs. Privacy): Data Minimization (e.g., GDPR, CCPA): Privacy laws like the GDPR (EU) and PIPL (China) mandate that organizations only collect the absolute minimum personal data required for a stated purpose. EDD's Demand: Conversely, EDD for high-risk customers requires collecting a vast amount of sensitive, intrusive data (e.g., detailed financial history, employment records) to fulfill AML requirements. Businesses must legally justify this collection and ensure it doesn't violate regional privacy mandates. Cross-Border Data Transfer Restrictions: Many regulations (especially GDPR and PIPL) restrict the transfer of a customer's personal data outside their home jurisdiction unless the destination country offers "adequate protection" (which requires complex legal mechanisms like Standard Contractual Clauses - SCCs). This forces global businesses to establish regional data centers or processing hubs and complicates compliance operations, as the identity verification documents collected in Region A may not be legally transferred to the central compliance team in Region B. Consent and Rights: The requirement for explicit, informed consent for data processing (a core tenet of GDPR) must be integrated into the digital onboarding flow, often requiring different consent forms and disclosures depending on the customer's country of residence. The customer's Right to Erasure or Right to be Forgotten creates a downstream conflict with the mandatory record-keeping requirements of AML laws, demanding that legal teams carefully balance competing regulatory obligations. The outcome of this regulatory gauntlet is the need for a highly sophisticated, dynamic compliance architecture that can switch seamlessly between regional requirements—a massive investment in both technology and dedicated regional compliance expertise. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users [v2] Register customer profile [v2] Submit customer KYC Business users • [Singapore](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/region-specific-onboarding/singapore.md): Understand the specific documentation and data requirements for onboarding individual and business users onto programs issued in Singapore. [Individual User] Onboarding Regulatory Requirements Title Description Data Type Mandatory first_name Account holder's first name String Yes middle_name Account holder's middle name String Optional last_name Account holder's last name String Yes email Account holder's verified email Email Yes mobile_country_code Account holder's verified mobile country code Enumerations (mobile_country_codes) Yes mobile Account holder's verified mobile Yes gender Account holder's gender Enumerations (genders) Yes title Account holder's title Enumerations (titles) Yes preferred_name Account holder's preferred name on card String Yes identification.primary.id_type Account holder's verification document type Enumerations (id_types) Yes identification.primary.id_number Account holder's verification document number String Yes identification.primary.id_issuance_country Account holder's verification document issuance country Enumerations (countries) Yes nationality Account holder's nationality Enumerations (nationalities) Yes birth.date Account holder's date of birth Date (YYYY-MM-DD) Yes addresses.residential.line_1 Residential address line 1 String Yes addresses.residential.line_2 Residential address line 2 String Yes addresses.residential.line_3 Residential address line 3 String Optional addresses.residential.postal_code Residential address postal code String Yes addresses.residential.city Residential address city String Yes addresses.residential.state Residential address state/province String Optional addresses.residential.country Residential address country Enumerations (countries) Yes addresses.billing.line_1 Billing address line 1 String Yes addresses.billing.line_2 Billing address line 2 String Yes addresses.billing.line_3 Billing address line 3 String Optional addresses.billing.postal_code Billing address postal code String Yes addresses.billing.city Billing address city String Yes addresses.billing.state Billing address state/province String Yes addresses.billing.country Billing address country Enumerations (countries) Yes Individual User Information Update Information updates are supported for Full KYC accounts, with restrictions on fields that can be updated: Fields that can be updated after KYC approval: email mobile_country_code and mobile addresses.residential addresses.billing [Business User] Onboarding Regulatory Requirements Title Description Data Type Mandatory company_name Account holder's first name String Yes email Account holder's verified email Yes mobile_country_code Account holder's verified mobile country code Enumerations (mobile_country_codes) Yes mobile Account holder's verified mobile Numeric (7-12 characters) Pattern: ^[0-9]*$ Yes preferred_name Account holder's preferred name on card String Yes foundation_date Date when the company is founded Date (YYYY-MM-DD) Yes lei_code Legal Entity Identifier (LEI) code for the business String Optional, when available Can be required depending on region identification.primary.id_type Business tax identification Enumerations (business_id_types) Optional, when available identification.primary.id_number Business tax identification number String Optional, when available identification.primary.id_issuance_country Business tax identification issuer country Enumerations (countries) Optional, when available identification.primary.id_date_issued Business tax identification issue date Date (YYYY-MM-DD) Optional, when available identification.primary.id_date_expiry Business tax identification expiry date Date (YYYY-MM-DD) Optional, when available addresses.foundation.line_1 Foundation address line 1 String Yes addresses.foundation.line_2 Foundation address line 2 String Yes addresses.foundation.line_3 Foundation address line 3 String Optional addresses.foundation.postal_code Foundation address postal code String Yes addresses.foundation.city Foundation address city String Yes addresses.foundation.state Foundation address state/province String Yes addresses.foundation.country Foundation address country Enumerations (countries) Yes addresses.operational.line_1 Operational address line 1 String Yes addresses.operational.line_2 Operational address line 2 String Yes addresses.operational.line_3 Operational address line 3 String Optional addresses.operational.postal_code Operational address postal code String Yes addresses.operational.city Operational address city String Yes addresses.operational.state Operational address state/province String Yes addresses.operational.country Operational address country Enumerations (countries) Yes Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users [v2] Register customer profile [v2] Submit customer KYC Region-specific onboarding Business users • [Philippines](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/region-specific-onboarding/philippines.md): Understand the specific documentation and data requirements for onboarding individual and business users onto programs issued in the Philippines. Onboarding Regulatory Requirements Title Description Data Type Mandatory first_name Account holder's first name String Yes middle_name Account holder's middle name String Optional last_name Account holder's last name String Yes suffix Account holder's name suffix e.g., Jr., Sr., III, etc. String Yes, if applicable to the user. Else, default to blank. email Account holder's verified email Email Yes mobile_country_code Account holder's verified mobile country code Enumerations (mobile_country_codes) Restricted to +63 for PH Yes mobile Account holder's verified mobile Yes gender Account holder's gender Enumerations (genders) Yes identification.primary.id_type Account holder's verification document type Enumerations (id_types) Yes identification.primary.id_number Account holder's verification document number String Yes identification.primary.id_issuance_country Account holder's verification document issuance country Enumerations (countries) Yes mothers_details.maiden_name Account holder's mother's maiden name String Yes nationality Account holder's nationality Enumerations (nationalities) Yes birth.date Account holder's date of birth Date (YYYY-MM-DD) Yes birth.line_1 Account holder's birth address line 1 String Yes birth.line_2 Account holder's birth address line 2 String Yes birth.line_3 Account holder's birth address line 3 Enumerations (line_3) for PH addresses, otherwise free text or empty Yes birth.line_4 Account holder's birth address line 4 Enumerations (line_4) for PH addresses, otherwise free text or empty Yes birth.postal Account holder's birth address postal code Enumerations (postal_code) when applicable; otherwise, free text. Yes birth.city Account holder's birth address city Enumerations (city) when applicable; otherwise, free text. Yes birth.state Account holder's birth address state/province Enumerations (state_province) when applicable; otherwise, free text. Yes birth.country Account holder's birth address country Enumerations (countries) Yes main_income_source Account holder's income source Enumerations (main_income_source) Yes employment_type Account holder's employment type Enumerations (employment_type) Yes employment_details.business_trading_name Account holder's employer/business name String (Max 50 characters) if employment type is OFW, EMPLOYED_REGULAR, EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.line_1 Employer/business address line 1 String (Max 35 characters) if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.line_2 Employer/business address line 2 String (Max 35 characters) if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.line_3 Employer/business address line 3 (Barangay) Enumerations (line_3) Optional employment_details.business_address.line_4 Employer/business address line 4 (Region) Enumerations (line_4) if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.postal_code Employer/business address postal code Enumerations (postal_code) when applicable; otherwise, free text if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.city Employer/business address city String if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.state Employer/business address state/province String if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required employment_details.business_address.country Employer/business address country Enumerations (countries) if employment type is OFW, EMPLOYED_REGULAR,EMPLOYED_CONTRACTUAL, below will be required addresses.residential.line_1 Residential address line 1 String Yes addresses.residential.line_2 Residential address line 2 String Yes addresses.residential.line_3 Residential address line 3 (Barangay) Enumerations (line_3) Optional addresses.residential.line_4 Residential address line 4 (Region) Enumerations (line_4) Yes addresses.residential.postal_code Residential address postal code Enumerations (postal_code) Yes addresses.residential.city Residential address city Enumerations (city) Yes addresses.residential.state Residential address state/province Enumerations (state_province) Yes addresses.residential.country Residential address country Enumerations (countries) Yes addresses.billing.line_1 Billing/Shipping address line 1 String Yes addresses.billing.line_2 Billing/Shipping address line 2 String Yes addresses.billing.line_3 Billing/Shipping address line 3 (Barangay) Enumerations (line_3) addresses.billing.line_4 Billing/Shipping address line 4 (Region) Enumerations (line_4) Yes addresses.billing.postal_code Billing/Shipping address postal code Enumerations (postal_code) when applicable; otherwise, free text Yes addresses.billing.city Billing/Shipping address city Enumerations (city) Yes addresses.billing.state Billing/Shipping address state/province Enumerations (state_province) Yes addresses.billing.country Billing/Shipping address country Enumerations (countries) Yes Onboarding Process Restrictions To ensure a seamless onboarding workflow, pay close attention to the items below: Do note as mandated by the license provider, the user will be marked as terminated if the below field combinations are duplicated: Cannot be duplicated: First name, Last Name, Date of Birth (combination) Email Address - user.email Mobile Number - user.mobile KYC Identification - Identification.primary.id_number 2. Employer address is mandatory for the following employment types: Employer address mandatory: EMPLOYED_REGULAR EMPLOYED_CONTRACTUAL OFW 3. Details and validation of the employer address Employer address details: Country is mandatory (see Country Enumeration), if Country is Philippines (PHL) City and state are mandatory (see City, State Enumeration) Supported Identity Documents Below are the supported ID types for customer onboarding and the required document types to be submitted for each ID type to be reliably reviewed and approved. Identification Type (requirement count) Required Supporting Images Document Type DISABLED_CERT (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie DRIVERS_ID (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie IMMIGRANT_CERT (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie NATIONAL_ID (2) PhilSys ID (physical card format) front of ID ( not required for authentication-based verification ) selfie front_of_id_document selfie ePhil ID (paper format) front of ID ( not required for authentication-based verification ) selfie front_of_id_document selfie Digital National ID (digital format) front of ID ( not required for authentication-based verification ) selfie front_of_id_document selfie OFW_ID (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie OWWA_ID (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie PASSPORT (2) photo and details page (page 2) selfie front_of_id_document selfie POSTAL_ID (2) signed front ID selfie front_of_id_document selfie PRC_ID (2) signed front ID selfie front_of_id_document selfie SENIOR_CITIZEN_CARD (3) signed front ID back of ID selfie front_of_id_document back_of_id_document selfie SSS (2) signed front ID selfie front_of_id_document selfie UMID (2) signed front ID selfie front_of_id_document selfie Customer Information Update Information updates are supported for Full KYC accounts, with restrictions on fields that can be updated: Fields that can be updated after KYC approval: email mobile_country_code and mobile addresses.residential addresses.billing KYC Results Information and documents submitted to the customer due diligence process are being forwarded and reviewed by our licensing partner. Depending on the review, a user can be approved for a Full KYC account or will be asked to resubmit documents. Below are possible scenarios that may require resubmission: Scenario Result Remarks The ID submitted has a middle name; the information submitted has the same middle name. APPROVED — The ID submitted has no middle name; the information submitted has a middle name. REJECTED Rejected as an information mismatch The ID submitted has a middle name; the information submitted has no middle name. REJECTED Rejected as incomplete information No middle name in ID, no middle name in information submitted APPROVED — Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users [v2] Register customer profile [v2] Submit customer KYC Region-specific onboarding Business users • [User Protection Guidelines](https://developer.matchmove.com/matchmove-banking-operating-system/regulations/user-protection-guidelines.md): As a regulated financial entity, MatchMove is committed to upholding the highest standards of integrity and security. We maintain strict compliance with Singapore’s regulatory frameworks as well as the local regulatory guidelines of all jurisdictions in which we operate. The safety of our financial ecosystem is a shared responsibility. Therefore, as consumers of the MatchMove platform and extension partners , you are required to comply with these user protection guidelines. These standards are designed to safeguard transactions, define clear duties of care, and ensure a secure environment for all participants. By adhering to these practices, we collectively mitigate risks and ensure the continued resilience of our digital payment services. Under the Monetary Authority of Singapore (MAS) E-Payments User Protection Guidelines (effective 16 December 2024), there are provisions for email and mobile verification indicated regarding transaction notifications and account security. The guidelines emphasize using these channels to ensure the user is alerted to any activity on their account. Here are the specific provisions: Verification for Contact Details Before Matchmove and partners can send notifications or perform authentication, they must ensure the contact information provided by the user is valid: 1. Verification at Point of Provision When a user provides a mobile number or email address during onboarding, the partner must verify these details using a "secure manner" (e.g., sending a one-time password (OTP) to that specific mobile number or a verification link to that email). 2. Updates to Contact Info Any change to the mobile number or email address on file must be subject to strong authentication. The partner is expected to send a notification to the old contact detail alerting the user that a change has been made. Mandatory Transaction Notifications The guidelines mandate that partners use the verified mobile or email channels to send real-time alerts. 1. Default Channels Partners must provide notifications via SMS or email (or via in-app push notifications). 2. Opt-out Restrictions While users can often choose their preferred channel (e.g., opting for email over SMS), partners are generally required to ensure that the notification system cannot be completely disabled for transactions above a certain threshold. 3. Content of Verification/Notification The notification must contain sufficient detail for the user to identify if the transaction is unauthorized, including the transaction amount, time, and the name of the payee (where available). Please refer to the Anti-scam Measures section for more details on the notification contents. Strong Authentication (2FA) The guidelines reinforce that mobile and email are key components of Multi-Factor Authentication (MFA): 1. Out-of-Band Verification For "high-risk" activities (like adding a new third-party payee or changing daily transfer limits), the partner must perform verification through a channel separate from the one used to initiate the request. This often involves sending a verification code to the registered mobile number or requiring a digital token approval. 2. Cooling-off Periods For changes to key mobile or email contact details, the guidelines support the implementation of a "cooling-off period" before the new details can be used to authorize high-value transactions, preventing scammers from taking over an account instantly. User Duty to Provide Accurate Info The guidelines also place a duty on the user: 1. Accurate Records Users are responsible for providing a correct and updated mobile number and/or email address to the extension partner. 2. Consequences of Failure If a user fails to provide updated contact information and consequently misses a transaction notification that would have allowed them to stop a scam, it may affect the assessment of the user's "duty of care" during a loss investigation. 3. Security of the Mobile Device Because the mobile phone often serves as the "verification device," the guidelines state that users must: Secure the mobile device with a password, PIN, or biometric (like Face ID/fingerprint). Enable lock-screen notifications privacy so that OTPs/verification codes are not visible to others when the phone is locked. • [Migration and deployments](https://developer.matchmove.com/matchmove-banking-operating-system/migration-and-deployments.md): Transitioning to a new version of a banking platform isn't just a technical update; it’s a mission-critical operation that demands precision, security, and zero-day reliability. When dealing with financial data and high-availability systems, the "move fast and break things" philosophy simply doesn't apply. This section provides the comprehensive framework required to navigate major platform updates. From initial environment staging to the final production cutover, these guides are designed to help your engineering and DevOps teams minimize downtime, maintain data integrity, and ensure a seamless experience for your end-users. • [Identity & Onboarding v2 Upgrade](https://developer.matchmove.com/matchmove-banking-operating-system/migration-and-deployments/v2-identity-and-onboarding-upgrade.md): Overview We are upgrading our Identity and Onboarding module from v1 to v2 . This migration is driven by evolving regulatory compliance requirements that necessitate enhanced identity verification capabilities, as well as the opportunity to deliver a significantly faster onboarding experience through improved automated processes. The new v2 module introduces an updated onboarding API that enhances the registration and KYC experience for both Individual and Business user types. As a partner running an active program on our platform, your integration with the onboarding and identity services will require updates. This guide outlines the scope, preparation steps, and migration process to ensure a smooth transition for your users. API Change New v2 Identity & Onboarding API Replaces all v1 onboarding endpoints for user registration and KYC submission [v2] Onboard Individual User — https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2 [v2] Onboard Business User — https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2 Note: Because of the differences in the schema versions of V1 and V2 Onboarding, existing users created under V1 Onboarding will not be accessible and searchable using the V2 Onboarding API. The existing V1 users in Production will need to be migrated to the new schema prior to the deployment. See Deployment and Migration sections below to learn more. User Types Affected Individual & Business Both user types will be migrated. Re-KYC may apply to select users. Migration Workflow 1 Preparation Your UAT stack will be provisioned with the v2 Identity API to allow you to begin integration work. UAT stack V2 Identity & Onboarding module enablement We will enable the v2 Identity API on your designated UAT environment. You will be able to access the endpoints using your existing API credentials. 2 v2 Identity & Onboarding API Integration API integration and retrofit updated features Integrate your application against the new v2 Identity endpoints. Test the full registration and KYC submission flows for both Individual and Business user types. Refer to the Implementation checklist for the integration and workflow guides. Take note of the following key changes: Change Impact v1 Identity & Onboarding API (Current) v2 Identity & Onboarding API (New) Modularized base URL (An update is required for all modules.) API endpoint URL format: /{unified_base_url}/v1/<api> The format is applicable to all APIs. API endpoint URL format: /{<category>_base_url}/v2/<api> e.g. {identity_base_url} for Identity and Onboarding API {cards_base_url} for Cards API The format is modularized per API category. All stack APIs must use this modularized base URL across all modules. To know more about these new base URLs, refer to the Begin technical integration guide for more details. Endpoint credentials No changes No changes Individual user creation normal user Create User (/v1/users) has a limited set of user profile fields that can be passed in the request. Create User (/v2/users) has an expanded set of user profile fields that can be passed in the request. To know which fields are required for you, refer to Region-specific Onboarding . Individual user creation linked an individual to a business Update the parent-child identifiers partner_id, agent_id, and customer_id to track entity linkage. Use the Create (Sub-business) Individual User (POST /businesses/{{parent_business_id}}/users) to define individual child entities. Individual eKYC generate eKYC capture link Call Process KYC Verification (POST /users/authentications/documents/process) by passing the eKYC provider ID. Call Create KYC (POST /users/authentications/documents) to upload supplementary documents. Call Process KYC Verification (POST /users/authentications/documents/process) without the need to pass an eKYC provider ID. All document uploads and EDD requirements (for high-risk users) have been added to the eKYC workflows. Individual eKYC webhook notifications Subscribe to USER.DOCUMENT_VERIFICATION.STATUS for SG programs; otherwise, see the (v1) webhook list for other regions and events. Subscribe to User and KYC status updates webhooks. Business user creation regular individual user Create User (/v1/businesses) has a limited set of user profile fields that can be passed in the request. Create User (/v2/businesses) has an expanded set of user profile fields that can be passed in the request. To know which fields are required for you, refer to Region-specific Onboarding . Business user creation linked business user to another business Update the parent-child identifiers partner_id, agent_id, and customer_id to track entity linkage. Use the Create (Sub-business) Individual User (POST /businesses/{{parent_business_id}}/businesses) to define individual child entities. Business user creation define associated parties (optional, as this functionality is available in the eKYC as well) Capability unavailable Create Business-Associated Parties (POST /associated_parties) Business eKYC generate eKYC capture link Capability unavailable Call Process KYC Verification (POST /users/authentications/documents/process) to capture all required documents and EDD requirements (for high-risk users). Business eKYC - Associated Parties generate eKYC capture link Capability unavailable Call Process Associated Party KYC Verification (POST /associated_parties/{{associated_party_id}}/authentications/documents/process) Business eKYC webhook notifications No webhooks available Subscribe to User and KYC status updates webhooks. 3 Implementation Verification Joint sign-off to confirm readiness before proceeding to production migration. End-to-end testing completion Confirm that all onboarding and KYC flows pass acceptance criteria on UAT. Document and resolve any integration issues. Readiness sign-off Both parties confirm implementation is complete and ready for production migration. 4 Deployment and Migration Moving existing users and routing new users to the v2 module. PRD stack V2 Identity module enablement We will enable the v2 Identity API on your designated PRD environment. Legacy onboarding cut-off A cut-off must be set up, preventing the creation of new users using the v1 Identity API. Migration of existing users to v2 All existing users will be migrated to the v2 Identity module by the MatchMove technical team. User data, KYC status, and approval records will be carried over. No partner action is required for this step. Routing of new users to v2 Partners are responsible for updating their app integrations to route all new user registrations through the v2 onboarding API. This is a partner action and should be completed in coordination with your deployment schedule. 5 [Post-Migration] Data Compliance and Re-KYC Requirements Select users may need to undergo re-verification under the v2 module. Business Users Users whose most recent KYC approval is older than 1 year will be required to undergo re-KYC under the v2 module. Individual Users All migrated users must complete any additional required v2 information requirements, which includes: New v2 required fields (if any) Additional compliance required fields (if any) Any additional data requirements must be supplied within an agreed-upon timeframe . Failure to do so will result in a downgrade of their KYC status . While users meeting specific criteria (to be defined and communicated separately) will be required to undergo full re-KYC under the v2 module. Support & Contact: For technical questions regarding the v2 API integration, please contact your designated Technical Account Manager or reach out to the integration support team. For migration scheduling and coordination, your Account Program Manager will be your primary point of contact throughout the process. • [Identity & onboarding overview](https://developer.matchmove.com/matchmove-banking-operating-system/identity-and-onboarding-overview.md): User The user (or customer) is the foundational entity in the system, and its creation is a mandatory prerequisite for linking and issuing any account. Users are classified as either individual or business entities, with support for both types potentially required depending on the program's nature. The MatchMove platform is designed to allow onboarding of both individual and business entities, enabling the creation of dynamic use cases for extending financial services. Individual users An Individual User entity defines a natural person who is onboarded to use the financial services in their own personal capacity. This can include individual customers in a public offering or corporate employees and contractors in a management program. All individual users must undergo Know Your Customer (KYC) verification. Business users A Business User entity defines a user who officially represents a corporation or business. Onboarding these users typically requires the business's registered name, registration IDs, and location. Businesses usually act as sub-corporate clients of the main program owner, and they must undergo Know Your Business (KYB) identity verification. Onboard individuals and businesses for your program The user is a fundamental entity that is created in the platform. User refers to an entity for which an account would be used, and then that entity can start leveraging the financial services you choose to consume from the platform. Users can be of either an individual or a business type. Depending on the jurisdiction of the product, depending on the user type onboarded, and the capabilities required, every user will have to go through the customer onboarding and due diligence process, which involves multiple stages ranging from: Adverse media checks Politically exposed personality checks Sanction list checks Document verification / Document authentication processes (in some regions) Ongoing checks and monitoring Onboarding individuals Learn how to onboard individual users on the platform Create an individual user profile Register the profile of an individual for your program Complete the individual KYC Choose one of the available modes to complete the KYC for individuals for your program Onboarding businesses Learn how to onboard your business users on the platform. Create a business user profile Register a business profile for your program Update connected party details Collect details of the connected party for the business Complete the business KYB Submit the required documents to complete the KYB for the business for your program Identity Verification and Compliance Identifying your customers is an integral part of any program, as compliance and regulatory guidelines are based entirely on the user types being served. MatchMove offers a range of state-of-the-art identification methods that comply with the KYC and KYB regulatory guidelines for every supported region. Our onboarding solutions are versatile, scalable, and suitable for various products and use cases, whether you're working with businesses or individual customers. Regulatory restrictions As a regulated platform, we ensure compliance with the licensing requirements in the respective jurisdiction. The links below highlight the applicable restrictions: Countries restricted from onboarding with SGD and USD accounts Countries requiring Enhanced Due Diligence (EDD) for SGD and USD accounts Industries prohibited for onboarding for businesses Industries require Enhanced Due Diligence (EDD) for businesses to onboard Onboarding-related API and Webhooks Individual Users Category API / Webhook Availability Description Individual User Create / Reactivate Individual Users v2 Define a profile for an individual user / Unsuspend a suspended user Individual User Get Individual Users v2 Retrieve a user profile Individual User Update Individual Users v2 Update an individual user profile Individual User Update User Status v2 Upload KYC documents for a user KYC Initiate KYC Submission v2 Generate a KYC verifification session ID KYC Upload KYC Documents v2 Upload KYC documents for a user KYC Confirm KYC Submission v2 Submit uploaded KYC documents for approval KYC List KYC Documents v2 Retrieve the KYC documents and status KYC Delete KYC Document v2 Remove an uploaded KYC document Contact Verification Send contact Verification OTP v2 Send OTP to user email or mobile being verified Contact Verification Resend Contact Verification OTP v2 Resent OTP to user email or mobile being verified Contact Verification Confirm Contact Verification OTP v2 Validate an OTP entered by the user Contact Verification Confirm Contact Verification v2 Partner confirmation on contact verification Contact Verification Self-validate Contact Verification v2 Partner confirmation on contact verification for Post-KYC user updates Sub-business Individual User Create (Sub-business) Individual Users v2 Define a profile for an sub-business individual user eKYC Initiate KYC Capture - Individual Users v2 Generate an eKYC capture link for an individual user User Enumerations List KYC Types Enumerations v1 Retrieve supported KYC modes User Enumerations List KYC Document Types Enumerations v2 Retrieve supported KYC document types User Enumerations List KYC ID Types Enumerations v2 Retrieve supported KYC identification documents User Enumerations List Mobile Country Codes Enumerations v2 Retrieve supported mobile country codes User Enumerations List Nationalities Enumerations v2 Retrieve supported nationalities User Enumerations Enumerations User Titles Enumerations v2 Retrieve supported user titles User Enumerations List Marital Status Enumerations v2 Retrieve supported marital statuses User Enumerations List Genders Enumerations v2 Retrieve supported genders User Enumerations List Employment Type Enumerations v2 Retrieve supported employment types User Enumerations List Occupations Enumerations v2 Retrieve supported occupations User Enumerations List Volume of Assets Enumerations v2 Retrieve supported volumes of assets User Enumerations List Source of Income Enumerations v2 Retrieve supported sources of income User Enumerations List States or Provinces Enumerations v2 Retrieve supported states or provinces User Enumerations List Regions (line_4) Enumerations v2 Retrieve supported regions or districts User Enumerations List Cities Enumerations v2 Retrieve supported cities User Enumerations List Postal Codes Enumerations v2 Retrieve supported postal codes Webhook Category (non-API) OFAC Service Advisory See Leverage Webhooks Webhook category to subscribe to receive notifications on Risk Evaluation status updates Webhook Category (non-API) User Details See Leverage Webhooks Webhook category to subscribe to receive notifications on Profile Update status updates Webhook Category (non-API) KYC Service Advisory See Leverage Webhooks Webhook category to subscribe to receive notifications to receive KYC Evaluation status updates Business Users Category API / Webhook Availability Description Business User Create / Reactivate Business Users v2 Define a profile for a business user / Unsuspend a suspended business user Business User Get Business Users v2 Retrieve a business user profile Business User Update Business Users v2 Update a business user profile Business Enumerations List Business Document Types Enumerations v2 Retrieve supported KYB document types Business Enumerations List Business ID Types Enumerations v2 Retrieve supported KYB identification documents Business Enumerations List Sources of Funds Enumerations v2 Retrieve supported sources of funds Business Enumerations List Purposes of Business Enumerations v2 Retrieve the supported purposes of business eKYC Initiate KYC Capture - Business Users v2 Generate an eKYC capture link for a business user eKYC Initiate KYC Capture - Associated Users v2 Generate an eKYC capture link for an business associated party user Sub-business Business Users Create (Sub-business) Business Users v2 Define a sub-business business user profile eKYC Create Business-Associated Parties v2 Define an associated party for a business eKYC List Associated Party Roles Enumerations v2 Retrieve supported business associated party roles Related Links Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users • [Individual users](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users.md): This guide highlights the high-level steps involved in onboarding an individual customer onto the product. Individual users onboarding is the initial step that you are required to do before you can start offering any of the services being offered as part of the platform. This is the first step required as part of the entire customer due diligence journey that the users undergo on an ongoing basis as they avail financial services on the platform. What is an individual user An individual user refers to a person who is seeking to establish a relationship to access financial services for a product offered by you via the MatchMove platform. The individual customer is typically an end-user or consumer for whom you would be doing account issuance, card issuance, and providing access to the payouts and collections facility. Onboarding an individual user Before any account can be issued in the system, a customer record needs to be created. In addition, the requirements the customer needs to go through will vary depending on the product construct and legal jurisdiction. Work with your Implementation manager to understand the nuances and have a robust journey tailored to your business. The lifecycle journeys can be listed below: Individual record creation with a completed user profile Customer contact details verification (only available in v2) Ongoing name screening and sanction list screening Additional demographic information collection Document review and verification process Individual record creation Before a payment account can be created or a business relationship can be established with an end customer, a minimal amount of information must be collected from the customer to create the customer record. Profile and sanction list screening To ensure regulatory compliance, the initial details captured are evaluated for potential presence in the sanction list, adverse media exposure, and politically exposed personalities, in addition to various local blacklists around the region. This is an asynchronous process that takes place post-initial record creation. In addition, after every update or addition to a customer's information, the customer's demographic information is again evaluated to ensure compliance. In addition, the demographic information on record is periodically re-scanned to ensure proper due diligence is performed for all individuals onboarded onto the platform. This activity is also performed when any profile update is performed on the user. Customer contact verification (Only available in v2 APIs) To ensure the authenticity of contact details of customers on board, as the platform, we provide the ability to authenticate the end user details and ensure the validity of that information for downstream processes like: Transactional OTP messages Tokenization authentication process Additional demographic information collection In preparation for the succeeding customer due diligence activity, as defined by product configurations, additional customer demographic information needs to be provided. This goes in conjunction with the document verification process listed below. Document review and verification process As part of the customer due diligence (CDD) process, the customer is obliged to validate the demographic information provided. These documents can be verified by doing a document verification or information retrieval via government registries like Singpass and Aadhaar, to name a few. Onboarding mechanisms available As a platform user, you have multiple options available to you for onboarding a user and fulfilling the document review and verification process. Options based on licensing and risk construct The avenues available are also dependent on the contractual relationship established as part of the product configuration. Onboarding arrangement Available options Pre-requisites Partner responsibilities MatchMove platform-managed Document Upload N/A Integrate the document upload API eKYC N/A Integrate MatchMove eKYC API SingPass N/A Integrate MatchMove eKYC API Third-party reliance Existing partner solution Partner and use cases have to be validated and approved by MatchMove compliance. Proper audit of all existing and future verifications will be done. All demographic information and documents are to be updated in the MatchMove system. Ensure all identity information in the system is accurate and up-to-date. Outsourcing agreement MatchMove-approved vendors Partner and use case have to be validated and approved by MatchMove compliance, along with an additional contractual agreement. Proper audit of all existing and future verifications will be done. All demographic information and documents are to be updated in the MatchMove system. Ensure all identity information in the system is accurate and up-to-date. All demographic information and documents are to be updated in the MatchMove system. Periodic audits as per aligned schedules Options based on API version There are two versions of the MatchMove onboarding or User API. Each addresses regional differences in requirements and regulations. Onboarding API (Version 1) - Deprecated By default, most partners will use this version to onboard their customers to the platform. This version is designed to be flexible for most of the regional financial product issuances. Onboarding API (Version 2) This version of the onboarding API is tailored for regions with more restrictive onboarding policies and regulations. You may work with your Implementation Manager to understand which approach is best suited for your program. You may work with your Implementation Manager to understand which approach is best suited for your program. Related Links Identity & onboarding overview Users overview [v1] Onboard Individual users [v1] Register customer profile [v1] Submit customer KYC [v1] Customer eKYC [v1] Performing eKYC [v2] Onboard Individual users Business users • [[v2] Onboard individual user](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2.md): Understand the complete onboarding workflow for individual users, from profile registration to successful KYC verification. This guide provides a comprehensive overview of the steps needed to activate an individual's account. Individual User onboarding involves the following processes: Individual User Registration The process involves capturing the required user information from the customer and submitting it to the platform to create a user profile or user entity that represents the customer. This process is dependent on the result of the risk evaluation and KYC verification handled by the bank partner. It is not affected by any activity in the KYC Verification process. This will only be active when the user profile has both passed risk evaluation and KYC verification. Risk Evaluation The process where the defined user profile containing the user information is checked against the various local and global financial blacklist and sanctioned personalities, to screen and prevent bad actors from gaining access to the financial capabilities of the platform. This process is added as a part of the KYC verification process handled by our bank partner. It is initiated when the KYC submission for approval is received. KYC Verification The process involves the uploading of the required customer KYC documents to the platform. The data presented in these KYC documents should correlate with and verify that the information provided in the user profile is legitimate and authentic. This process runs independently and is initiated when a KYC application is received from MatchMove by the bank partner. Figure: User, Risk, and KYC interaction and state diagram The state diagram below illustrates how the Individual User Definition, Risk Evaluation, and KYC Verification processes interact and affect one another Philippines All Other Regions Before a user is granted access to any financial facilities and capabilities within the platform, the USER and KYC must be in an approved or green status . These are the states depicted with a GREEN border: Onboarding Process Required Status Description Individual User Definition user.status = ACTIVE The individual user profile required information is completed. Risk Evaluation Risk evaluation is integrated completely into the KYC verification process. No additional risk evaluation status will need to be tracked and handled. The risk evaluation result did not garner any hits on the individual user profile when it was checked against all the available blacklists. KYC Verification user_kyc.status = APPROVED The submitted KYC documents and data authenticated the legitimacy of the information in the individual user profile. Upgrading to V2 Identity & Onboarding API from V1? Here's a complete step-by-step guide to help you — Identity & Onboarding v2 Upgrade . Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Register customer profile [v2] Submit customer KYC Region-specific onboarding Business users • [Register individual profile](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/register-individual-profile.md): Learn how to create an individual user profile, the foundational step for onboarding a new user. Understand this initial process of registering an individual on the platform before proceeding with identity verification. The Users V2 API for user onboarding is only supported in a select number of regions that have unique verification processes and more restrictive requirements. Partners using or assigned to the Users V1 API should not upgrade to the Users V2 API, unless advised otherwise. Use Cases You want to onboard an individual user who is a natural person, not a business or corporate entity. You want to onboard an individual user who will use an account for personal purposes. You want to onboard an individual user who is a single employee, contractor, or affiliate of a corporate entity. When business users are enabled, and you want to onboard an individual user and associate him with a business entity. Prerequisites Before starting to collect individual user information from your customers, refer to the User Protection Guidelines , which all platform consumers and partners must follow and adhere to with regard to securing customer data. You will need to collect the user information from the individual customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application. Individual User data The data that needs to be collected from the customer can be broken down into these groups: API mandatory (minimum) user details — are the vital identity information necessary to create a user in the system. User demographic information — includes additional statistics and location details for users. Income and other supporting details — include sources of income, employment, and other user details. API Workflow (v2) 1 Create an individual user profile in the program During your initial interaction with the customer, you may want to reduce the initial set of information you ask them. This can reduce the friction of onboarding and increase the turnover rate of your sign-ups. There are multiple onboarding options available for profile creation: Email address - a user profile can be created by providing just the email address first Mobile number - a user profile can be created by providing just the mobile number first Complete information - a user profile can be created by supplying the complete required user information Create Individual Users You can call the Create Individual Users (POST /users) to create a user by passing the required information. Individual user registration Create Individual Users - Providing minimum required information Minimum required user information Collecting minimum information from the user during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the user onboarding, we can also reduce the form fields being built on the frontend to collect user information. Instead, we can then just allow the user to provide all the required information and documents during the eKYC information collection screens. For individuals, the minimum required user information is the following: preferred_name first_name last_name email mobile_country_code mobile Create Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "preferred_name": "John Smith", "email": "jsm@matchmove.com", "mobile_country_code": "65", "mobile": "91919199", "first_name": "John", "last_name": "Smith" }' Create Individual Users response JSON { "id": "c90e71d1572e437e80c0aec126e1874a", "type": "individual", "client_ref_id": "", "provider_ref_id": "", "provider_account_number": "", "salutation": "", "suffix": "", "title": "", "first_name": "John", "middle_name": "", "last_name": "Smith", "preferred_name": "John Smith", "email": "jsm@matchmove.com", "mobile_country_code": "65", "mobile": "91919199", "gender": "", "marital_status": "", "identification": { "primary": {}, "secondary": {} }, "birth": {}, "nationality": "", "mothers_details": {}, "father_details": {}, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "", "job_title": "", "employment_details": { "business_trading_name": "", "business_purpose": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "expected_monthly_revenue": "", "vat_number": "", "business_address": {} }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "", "main_income_source": "", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "", "residency_country": "", "self_declared_as_pep": false, "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-05-05T14:09:14Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "" } Create Individual Users - Providing complete user infomation Region-specific Onboarding The example below displays the exhaustive set of user information fields that can be passed through the Create User endpoint. However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ. Partners are encouraged to refer to the Region-specific Onboarding section to see the list of information required for their program region. Only the listed region-specific user information is required to be collected from the users and submitted for user registration. Create Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "1234567891", "type": "individual", "salutation": "JLXM", "title": "Mr", "first_name": "John", "middle_name": "William", "last_name": "Smith", "preferred_name": "John Smith", "gender": "male", "mobile_country_code": "63", "mobile": "9999999999", "email": "john.smith@matchmove.com", "marital_status": "Married", "identification": { "primary": { "id_number": "000000", "id_type": "passport", "id_date_added": "2019-08-24", "id_date_issued": "2019-08-24", "id_date_expiry": "2029-08-24", "id_issuance_country": "PHL" }, "secondary": { "id_number": "000000", "id_type": "drivers_id", "id_date_added": "2019-08-24", "id_date_issued": "2019-08-24", "id_date_expiry": "2029-08-24", "id_issuance_country": "PHL" } }, "birth": { "name": "John William Smith", "date": "1990-06-15" }, "nationality": "Filipino", "mothers_details": { "first_name": "Juana", "middle_name": "Williams", "last_name": "Smith", "maiden_name": "Juana Williams" }, "fathers_details": { "first_name": "Juan", "middle_name": "Johnson", "last_name": "Smith", "maiden_name": "Juan Johnson" }, "addresses": { "residential": { "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "REGION_07", "postal_code": "6000", "city": "CEBU_CITY_CEBU", "country": "PHL", "state": "CEBU" }, "billing": { "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "REGION_07", "postal_code": "6000", "city": "CEBU_CITY_CEBU", "country": "PHL", "state": "CEBU" } }, "employment_details": { "business_trading_name": "MatchMove Pay Pte Ltd", "business_purpose": "Financials", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "", "expected_monthly_revenue": "1000000", "vat_number": "0000000", "business_address": { "line_1": "Ortigas Center", "line_2": "San Antonio", "line_3": ".", "line_4": "NCR", "postal_code": "4107", "city": "PASIG_CITY_NCR", "country": "PHL", "state": "NCR" } }, "fatca_crs_confirmed_at": "2023-09-18T14:15:22Z", "fatca_relevant": true, "main_income_source": "SALARY", "socioprofessional_category": "", "purpose_of_account_opening": "", "work_country": "Philippines", "residency_country": "PHL", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "", "data_terms_signed_at": "", "metadata": {}, "created_by": "bot@matchmove.com" }' Create Individual Users response JSON { "id": "672a00188e78487fab80ff5189c79cee", "type": "individual", "client_ref_id": "1234567891", "provider_ref_id": "", "provider_account_number": "", "salutation": "JLXM", "suffix": "", "title": "Mr", "first_name": "John", "middle_name": "William", "last_name": "Smith", "preferred_name": "John Smith", "email": "john.smith@matchmove.com", "mobile_country_code": "63", "mobile": "9999999999", "gender": "Male", "marital_status": "Married", "identification": { "primary": { "id_number": "000000", "id_type": "Passport", "id_date_issued": "2019-08-24", "id_date_expiry": "2029-08-24", "id_issuance_country": "Philippines" }, "secondary": { "id_number": "000000", "id_type": "Driver's license", "id_date_issued": "2019-08-24", "id_date_expiry": "2029-08-24", "id_issuance_country": "Philippines" } }, "birth": { "name": "John William Smith", "date": "1990-06-15" }, "nationality": "Nationality for Philippines", "mothers_details": { "first_name": "Juana", "middle_name": "Williams", "last_name": "Smith", "maiden_name": "Juana Williams" }, "father_details": { "first_name": "Juan", "middle_name": "Johnson", "last_name": "Smith", "maiden_name": "Juan Johnson" }, "addresses": { "residential": { "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "REGION_07", "city": "CEBU_CITY_CEBU", "state": "CEBU", "postal_code": "6000", "country": "Philippines" }, "billing": { "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "REGION_07", "city": "CEBU_CITY_CEBU", "state": "CEBU", "postal_code": "6000", "country": "Philippines" }, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "", "job_title": "", "employment_details": { "business_trading_name": "MatchMove Pay Pte Ltd", "business_purpose": "Financials", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "", "expected_monthly_revenue": "1000000", "vat_number": "0000000", "business_address": { "line_1": "Ortigas Center", "line_2": "San Antonio", "line_3": ".", "line_4": "NCR", "postal_code": "4107", "city": "PASIG_CITY_NCR", "country": "Philippines", "state": "NCR" } }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "", "main_income_source": "Salary", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": false, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-04-06T12:13:10Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "" } Individual user registration (PH-specific) [PH] Create Individual Users - Providing complete user information Region-specific Onboarding The example below displays the exhaustive set of user information fields that can be passed through the Create User endpoint. However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ. Partners are encouraged to refer to the Region-specific Onboarding section to see the list of information required for their program region. Only the listed region-specific user information is required to be collected from the users and submitted for user registration. Create Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "9234567891", "provider_action_id": "test123", "preferred_name": "John Smith", "salutation": "JLXM", "title": "dr", "first_name": "John", "legal_name": "John Smith", "alias_name": "John Smith", "tin": "ncmxnc", "ethnicity": "ncmxnc", "middle_name": "V", "last_name": "Smith", "maiden_name": "jkjdksajd", "gender": "MALE", "marital_status": "SINGLE", "email": "iuqie41cu489551@matchmove.com", "mobile_country_code": "63", "mobile": "1194651219", "provider_data": { "first_name": "John", "sirst_name_en": "Smith" }, "supporting_documents": [ { "id_number": "M41487196", "id_type": "ARBITRARY_DOC", "id_issuance_country": "DNK", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": false, "is_expiry_extended": false } ], "identification": { "primary": { "id_number": "M24571148", "id_type": "passport", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "DNK" }, "secondary": { "id_number": "g11516434", "id_type": "DRIVERS_ID", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "DNK" } }, "birth": { "name": "L", "date": "2000-04-02", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABORLAN_PALAWAN", "country": "PHL", "state": "Cavite", "postal_code": "4107" }, "nationality": "PHL", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "fathers_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "123", "country": "DNK", "postal_code": "2200" }, "billing": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABUCAY_BATAAN", "state": "Cavite", "country": "DNK", "postal_code": "4107" }, "shipping": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABORLAN_PALAWAN", "country": "DNK", "state": "Cavite", "postal_code": "4107" } }, "employment_type": "OFW", "job_title": "ACCOUNTANT", "employment_details": { "business_purpose": "ACCOUNTING", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABUCAY_BATAAN", "country": "DNK", "state": "Cavite", "postal_code": "4107" } }, "fatca_crs_confirmed_at": "2019-08-24T14:15:22Z", "fatca_relevant": true, "annual_income_range": "20000", "main_income_source": "OFW", "socioprofessional_category": "string", "purpose_of_account_opening": "CASH_DEPOSIT", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "data_terms_signed_at": "2022-06-15 00:00:00", "metadata": { "testing": "aaabbbb" }, "created_by": "bot@matchmove.com", "suffix": "Jr", "type": "customer" }' Create Individual Users response JSON { "addresses": { "billing": { "city": "Abucay, Bataan", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "CAVITE" }, "identity_verification": {}, "residential": { "city": "Gabaldon (Bitulok & ", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LA UNION", "state_code": "123" }, "shipping": { "city": "Aborlan, Palawan", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "CAVITE" } }, "agent_id": "", "alias_name": "John Smith", "annual_income_range": "20000", "birth": { "city": "ABORLAN_PALAWAN", "country": "PHL", "date": "2000-04-02", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "name": "John Smith", "postal_code": "4107", "state": "CAVITE" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-03-26T21:01:35Z", "date_updated": "2026-03-26T21:01:35Z", "email": "iuqie41cu489551@matchmove.com", "employment_details": { "business_address": { "city": "ABUCAY_BATAAN", "country": "DNK", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "OFW", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "William", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "Cab" }, "first_name": "John", "gender": "MALE", "id": "02952fb181024e50b0fac33d9b0e1ac6", "identification": { "primary": { "id_date_expiry": "2028-08-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Denmark", "id_number": "M24571148", "id_type": "passport" }, "secondary": { "id_date_expiry": "2028-08-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Denmark", "id_number": "g11516434", "id_type": "DRIVERS_ID" } }, "is_email_verified": "0", "is_mobile_verified": "0", "is_risk_flagged": "UNKNOWN", "job_title": "ACCOUNTANT", "kyc_processed_date": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "last_name": "Smith", "legal_name": "John Smith", "main_income_source": "OFW", "marital_status": "SINGLE", "metadata": null, "middle_name": "V", "mobile": "1194651219", "mobile_country_code": "63", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "Tori" }, "nationality": "PHL", "partner_id": "", "pending_update": [], "preferred_name": "iuiwueiwe", "provider_account_number": "", "provider_ref_id": "", "purpose_of_account_opening": "", "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [] }, "immediately_due": { "required_actions": [], "required_attributes": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "UNKNOWN", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_verification", "status_message": "", "status_reason_code": "", "sub_status": "", "suffix": "Jr", "supporting_documents": [ { "id_issuance_country": "DNK", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "M41487196", "id_sub_type": "abc", "id_type": "ARBITRARY_DOC" } ], "tin": "ncmxnc", "title": "dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl" }, "transaction_status": "", "transaction_sub_status": "", "type": "customer", "work_country": "Philippines" } Business Hierarchical Structure When onboarding business users are enabled in your program, there will be an alternative way to create individual users who need to be associated with a business user entity. Businesses often organize themselves into layers, where smaller branches or subsidiaries are distinct entities but still belong to the main parent company. Individual employees, on the other hand, are organized directly under their departments or employers. Financial flows follow this same path, where the parent company allocates capital downward for operations, and the revenue generated by these employees flows back up through their branch to the main entity. MatchMove Banking API is designed to cater to various business structure nuances. You should be able to create parent-child relationships and maintain hierarchical structures with individual and business entities. In a B2B2C model, where (refer to Figure 1): Business A (PARENT) is defined using Create Business User API. Individual AA (CHILD) can be associated with Business A (PARENT) by defining it using the Create (Sub-business) Individual User API . Similarly, in a B2B2B model, where: Business BA (PARENT) is defined using Create Business User API. Employee BAA (CHILD) can be associated with Business BA (PARENT) by defining it using the Create (Sub-business) Individual User API. As well as for, Business B (PARENT) is defined using Create Business User API. Employee BB (CHILD) can be associated with Business B (PARENT) by defining it using the Create (Sub-business) Individual User API. However, in a B2C model, where: Individual A is directly under the main partner (the default parent); therefore, it can be defined using the Create User API . Figure 1: Business Hierarchical Models Create a (Sub-business) Individual Users You can call the Create (Sub-business) Individual User s ( POST /businesses/{{parent_business_id}}/users ) passing the business ID of the parent business user to create a child individual user. Note: This API requires that business users be enabled in your program. (Sub-business) Individual definition Create (Sub-business) Individual Users - Providing minimum required information Minimum required sub-business information - Individual Collecting minimum user information from the user during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the user onboarding, we can also reduce the form fields being built on the frontend to collect user information. Instead, we can then just allow the user to provide all the required information and documents during the eKYC information collection screens. For individuals, the minimum required user information is the following: preferred_name first_name last_name email mobile_country_code mobile Create (Sub-business) Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{business_parent_id}}/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "preferred_name": "Junior Smith", "email": "jrsmith@matchmove.com", "mobile_country_code": "65", "mobile": "91929891", "first_name": "Junior", "last_name": "Smith" }' Create (Sub-business) Individual Users response JSON { "id": "98b05cf787a34efebeacb2785f4bfc3c", "type": "individual", "client_ref_id": "", "provider_ref_id": "", "provider_account_number": "", "salutation": "", "suffix": "", "title": "", "first_name": "Junior", "middle_name": "", "last_name": "Smith", "preferred_name": "Junior Smith", "email": "jrsmith@matchmove.com", "mobile_country_code": "65", "mobile": "91929891", "gender": "", "marital_status": "", "identification": { "primary": {}, "secondary": {} }, "birth": {}, "nationality": "", "mothers_details": {}, "father_details": {}, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "", "job_title": "", "employment_details": { "business_trading_name": "", "business_purpose": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "expected_monthly_revenue": "", "vat_number": "", "business_address": {} }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "", "main_income_source": "", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "", "residency_country": "", "self_declared_as_pep": false, "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-05-05T14:25:49Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "business_id": "9fcc5c86a79f4bf18ab69f435ca66b10" } Create (Sub-business) Individual Users - Providing complete user infomation Region-specific Onboarding The example below displays the exhaustive set of user information fields that can be passed through the Create Sub-Business Users endpoint. However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ. Partners are encouraged to refer to the Region-specific Onboarding section to see the list of information required for their program region. Only the listed region-specific user information is required to be collected from the users and submitted for user registration. Create (Sub-business) Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{parent_business_id}}/users' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "9234567891", "provider_action_id": "111224555", "preferred_name": "Jane", "salutation": "ms", "title": "dr", "first_name": "Jane", "legal_name": "Jane Smith", "alias_name": "", "tin": "122334aaa", "middle_name": "Williams", "last_name": "Smith", "maiden_name": "Jane Steven", "gender": "FEMALE", "marital_status": "MARRIED", "email": "jane.smith@matchmove.com", "mobile_country_code": "65", "mobile": "91118888", "provider_data": { "test_identifier": "124ed23" }, "supporting_documents": [ { "id_number": "M414L7116", "id_type": "AGREEMENT", "id_issuance_country": "DNK", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": false, "is_expiry_extended": false } ], "identification": { "primary": { "id_number": "test", "id_type": "ID_CARD", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "DNK" }, "secondary": { "id_number": "last name", "id_type": "DRIVERS_ID", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "DNK" } }, "birth": { "name": "Louie Miranda", "date": "2000-04-02", "city": "Gen Trias", "country": "PHL", "postal_code": "1000" }, "nationality": "AFGHAN", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "fathers_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "123", "line_2": "Flywheel St", "line_3": "", "line_4": "", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "123", "country": "DNK", "postal_code": "2200" }, "billing": { "line_1": "123", "line_2": "Flywheel St", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "state": "Cavite", "country": "DNK", "postal_code": "4107" }, "shipping": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABORLAN_PALAWAN", "country": "DNK", "state": "Cavite", "postal_code": "4107" } }, "employment_type": "SELF-EMPLOYED", "job_title": "ACCOUNTANT", "employment_details": { "business_purpose": "ACCOUNTING", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "123", "line_2": "Flywheel St", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "country": "DNK", "state": "Cavite", "postal_code": "4107" } }, "fatca_crs_confirmed_at": "2019-08-24T14:15:22Z", "fatca_relevant": true, "annual_income_range": "20000", "main_income_source": "SALARY", "socioprofessional_category": "string", "purpose_of_account_opening": "CASH_DEPOSIT", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "data_terms_signed_at": "2022-06-15 00:00:00", "metadata": { "test_identifier": "aaabbbb" }, "created_by": "bot@matchmove.com" }' Create (Sub-business) Individual Users response JSON { "id": "c498924262844a9a9dd46c12848a4e70", "type": "individual", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "salutation": "ms", "title": "Dr", "first_name": "Jane", "middle_name": "Williams", "last_name": "Smith", "preferred_name": "Jane", "email": "jane.smith@matchmove.com", "mobile_country_code": "65", "mobile": "91118888", "gender": "Female", "marital_status": "Married", "identification": { "primary": { "id_number": "test", "id_type": "Id Card", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Denmark" }, "secondary": { "id_number": "last name", "id_type": "Driver's license", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Denmark" } }, "birth": { "name": "Louie Miranda", "date": "2000-04-02", "city": "Gen Trias", "country": "Philippines", "postal_code": "1000" }, "nationality": "Nationality for Afghanistan", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "father_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "123", "line_2": "Flywheel St", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "123", "postal_code": "2200", "country": "Denmark" }, "billing": { "line_1": "123", "line_2": "Flywheel St", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Denmark" }, "shipping": { "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Denmark" }, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "Self Employed", "job_title": "Accountant", "employment_details": { "business_trading_name": "", "business_purpose": "ACCOUNTING", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "123", "line_2": "Flywheel St", "postal_code": "4107", "city": "ABORLAN_PALAWAN", "country": "Denmark", "state": "Cavite" } }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "20000", "main_income_source": "Salary", "purpose_of_account_opening": "Cash Deposit", "socioprofessional_category": "", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": false, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "active", "sub_status": "active", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:40:46Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "business_id": "be9db48068c4455782067426fdccd90b", "legal_name": "Jane Smith", "tin": "122334aaa", "supporting_documents": [ { "id_number": "M414L7116", "id_type": "Agreement", "id_sub_type": "abc", "id_issuance_country": "Denmark", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN" } ] } Field notes: preferred_name is usually the (First Name + Last Name), which will be used as the default cardholder name for card programs. For non-card programs, we can just pass the same, just to satisfy the API requirement. User identifier as a partner foreign key When a new individual user is created, a user identifier ( user.id ) will be generated. In the example above, the user identifier will be the " id": "cd896adb395fa384a5a8b174a007c34c ". It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This user identifier will be heavily used in most post-user creation API, and it will be convenient for you to have it accessible. 2 Complete any missing user information in preparation for KYC (requirements.immediately_due.required_attributes) To prepare for KYC submission, ensure the user's profile is fully updated with their demographic information, income, and other supporting details. Completing these requirements is necessary to successfully move forward with the KYC process. If any required information was not provided during the user profile creation, the missing information will be listed in the requirements.immediately_due.required_attributes object. Since the user object has already been created at this point, pushing any change to the profile will require us to update the user object. You can refer to the Update individual profile section to learn more. 3 [Conditional] User contact verification As per regulation and security considerations, all users that will be onboarded in the platform must have their mobile and email verified. Depending on the program region, this verification requirement may be imposed at the platform level and block the onboarding progress unless verification is completed. Based on your program's configuration, the user creation response will branch into one of two states: When Contact Verification is Not Required: The user.status will bypass the verification stage and jump directly to pending_activation . This indicates the user is ready for the next step in the onboarding flow, which is Identity Verification (KYC). You may skip this user contact verification and proceed to the KYC submission. When Contact Verification is Required: The user.status will be set to pending_verification . The onboarding progress is paused, and you must complete the contact verification process (mobile/email) before the user can proceed further. Proceed to either Partner-internal contact verification or Platform-provided contact verification. A. Partner-internal contact verification (Partner) + confirmation (via API) Programs not requiring “Platform-level mobile and email verification” may proceed with their own verification using their internal capability or through external services. Partner Contact Verification Confirmation After you have verified the user email and mobile using your own verification system, you will need to confirm it with the platform. Confirm Partner Email Verification request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "method": "email", "email_id": "john.smith@matchmove.com" }' Confirm Partner Mobile Verification request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "method": "sms", "mobile_number": "9339924187", "mobile_country_code" : "63" }' B. Platform-provided contact verification (via API) A program requiring API-level email and mobile verification will be moved to a "status": "pending_verification" in the Create User response or user object. Partners may be able to use the platform to send a one-time PIN (OTP) challenge to the customer's email or mobile number that is being verified. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation to confirm availability in your area and begin the setup process. MatchMove Contact Verification Send Contact Verification OTP Call Send Contact Verification OTP - Mobile ( POST /users/trigger/otp/sms ) or Send Contact Verification OTP - Email ( POST /users/triggers/otp/email ) to initiate or trigger the platform to send a verification request and send an OTP code to the customer. Send Contact Verification OTP - Mobile request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/trigger/otp/sms' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Send Contact Verification OTP - Mobile response JSON { "email" : "john.smith@matchmove.com" , "expires_at" : "2019-08-24T14:15:22Z" , "method" : "SMS" , "retry_after" : "1000" , "verification_code" : "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA " , "mobile_country_code" : "63", "mobile_number" : "9999999999" } Send Contact Verification OTP - Email request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/trigger/otp/email' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Send Contact Verification OTP - Email response JSON { "email" : "john.smith@matchmove.com" , "expires_at" : "2019-08-24T14:15:22Z" , "method" : "EMAIL" , "retry_after" : "1000" , "verification_code" : "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA " , "mobile_country_code" : "63", "mobile_number" : "9999999999" } Once the OTP is received, partners must ask the customer to provide the OTP code and verify it against the OTP sent by the platform. This verification must be completed before the OTP code expires. The expiry period can be configured in the program and is set to 5 minutes by default. The verification process will require you to pass the encrypted OTP code (provided by the customer) and the verification code (returned by the Initiate Mobile/Email Verification response) . OTP Code Encryption Logic: Encryption algorithm : AES CBC 256-bit, with no Initial Vector (IV) Encryption key : Use the “Basic Authentication username: password” hash IV : Use the first 16 characters of the encryption key Encoding : Use Hex encoding Sample encrption code (Go): Go package main import ( "bytes" "crypto/aes" "crypto/cipher" "encoding/base64" "fmt" "strings" ) const IV = "NDMbfRhOsN3QNGKx" const KEY = "zDYWhP5keEvuGMWxlWBQCym43jIBYKJY" func main() { EncryptTest("926946") } func EncryptTest(plaintext string) { key := []byte(KEY) encryptAES, _ := EncryptAES(plaintext, key, []byte(IV)) _, err := DecryptAES(encryptAES, key, []byte(IV)) if err != nil { fmt.Println(err.Error()) } fmt.Println("result: " + encryptAES) } // EncryptAES Encrypts the given plain text using the given key // returns a hex encoded string of the AES encrypted string func EncryptAES(content string, encryptionKey []byte, IV []byte) (string, error) { paddedPlaintext := PKCS5Padding([]byte(content), aes.BlockSize) block, err := aes.NewCipher(encryptionKey) if err != nil { return "", err } ciphertext := make([]byte, len(paddedPlaintext)) mode := cipher.NewCBCEncrypter(block, IV) mode.CryptBlocks(ciphertext, paddedPlaintext) return base64.StdEncoding.EncodeToString(ciphertext), nil } // DecryptAES decrypts a given hex encoded AES encrypted string // using the key given func DecryptAES(cipherText string, encryptionKey []byte, IV []byte) (string, error) { block, err := aes.NewCipher(encryptionKey) if err != nil { return "", err } c, err := base64.StdEncoding.DecodeString(cipherText) if err != nil { return "", err } mode := cipher.NewCBCDecrypter(block, IV) mode.CryptBlocks(c, c) return strings.TrimSpace(string(c)), err } // PKCS5Padding adds the necessary padding for the given // data func PKCS5Padding(cipherText []byte, blockSize int) []byte { padding := blockSize - len(cipherText)%blockSize padText := bytes.Repeat([]byte{byte(padding)}, padding) return append(cipherText, padText...) } Confirm Contact Verification OTP Call Confirm Contact Verification OTP ( PUT /users/verify/otp ) passing the encrypted OTP code and the verification code to initiate verification. Confirm Contact Vertification OTP request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "otp": "TW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRp", "verification_code": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA" }' Confirm Contact Vertification OTP response JSON { "status": "success", "message": "Verification completed successfully" } Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Region-specific onboarding Business users • [Update individual profile](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/update-individual-profile.md): Learn how to modify the personal information and contact details associated with an individual user account. Understand the data requirements for maintaining accurate and current user profiles within the system. The Users V2 API for user onboarding is only supported in a select number of regions that have unique verification processes, customized and more restrictive requirements. Partners using or assigned to the Users V1 API should not upgrade to the Users V2 API, unless advised otherwise. Use Cases You want to update an existing individual user profile before the user's KYC is approved. You want to update an existing individual user profile after the user's KYC has been approved. Prerequisites Before starting to collect individual user information from your customers, refer to the User Protection Guidelines , which all platform consumers and partners must follow and adhere to with regard to securing customer data. You will need to collect the user information from the individual customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application. Individual User data The data that needs to be collected from the customer can be broken down into these groups: API mandatory (minimum) user details — are the vital identity information necessary to create a user in the system. User demographic information — includes additional statistics and location details for users. Income and other supporting details — include sources of income, employment, and other user details. API Workflow (v2) 1 [Pre-KYC Profile Update] Update the customer profile in preparation for KYC In anticipation of performing the Full KYC (Pre-KYC) on your users, the demographic information, income, and other supporting details must be collected and added to the user profile. Failure to provide all the required information will block the KYC submission process. If any required information was not provided during the user profile creation, the missing information will be listed in the requirements.immediately_due.required_attributes object. Updation of any other fields are also allowed, for the list of all the updateable user fields, please refer to the Update Users (V2) API definition. Update Individual Users Call the Update Individual Users ( PUT /users ) to update the user profile's updateable fields. Update Individual Users request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic ••••••' \ --data '{ "first_name": "Johnny", "last_name": "Smith" }' Update Individual Users response JSON { "addresses": { "billing": { "city": "Cebu City, Cebu", "country": "Philippines", "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "Region VII", "postal_code": "6000", "state": "CEBU" }, "identity_verification": {}, "residential": { "city": "Cebu City, Cebu", "country": "Philippines", "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "Region VII", "postal_code": "6000", "state": "CEBU" }, "shipping": {} }, "agent_id": "", "annual_income_range": "100 to 1000", "birth": { "city": "Cebu", "country": "Philippines", "date": "1990-06-15", "name": "John Smith", "postal_code": "6000" }, "client_ref_id": "1234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2025-08-06T11:36:08Z", "date_updated": "2025-08-06T11:36:08Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": { "city": "PASIG_CITY_NCR", "country": "PHL", "line_1": "Ortigas Center", "line_2": "San Antonio", "line_3": ".", "line_4": "NCR", "postal_code": "4107", "state": "NCR" }, "business_purpose": "Financials", "business_trading_name": "MatchMove Pay Pte Ltd", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "", "vat_number": "0000000" }, "employment_type": "EMPLOYED_REGULAR", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Juan", "last_name": "Smith", "maiden_name": "Juan Johnson", "middle_name": "Johnson" }, "first_name": "Johnny", "gender": "male", "id": "34f7579b81ff462da64b6fa5e35198fe", "identification": { "primary": { "id_date_expiry": "2025-08-24", "id_date_issued": "2019-08-24", "id_issuance_country": "Philippines", "id_number": "000000", "id_type": "drivers_id" }, "secondary": { "id_date_expiry": "2025-08-24", "id_date_issued": "2019-08-24", "id_issuance_country": "Philippines", "id_number": "000000", "id_type": "passport" } }, "is_email_verified": "0", "is_mobile_verified": "0", "is_risk_flagged": "UNKNOWN", "job_title": "Software Engineer", "kyc_processed_date": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "last_name": "Smith", "main_income_source": "PAYROLL", "marital_status": "Married", "metadata": {}, "middle_name": "Williams", "mobile": "9999999999", "mobile_country_code": "63", "mothers_details": { "first_name": "Juana", "last_name": "Smith", "maiden_name": "Juana Williams", "middle_name": "Williams" }, "nationality": "PHL", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "", "purpose_of_account_opening": "", "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [] }, "immediately_due": { "required_actions": [], "required_attributes": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "UNKNOWN", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_verification", "sub_status": "", "title": "Mr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl" }, "transaction_status": "", "transaction_sub_status": "", "type": "customer", "work_country": "Philippines" } 2 [Post-KYC Profile Update] Update the allowed fields in a KYC-approved profile Depending on the program region, information updates to the user profile may have certain restrictions. During this time, the customer profile and the KYC documents have already been verified and approved. Any update to the user profile may an effect on the issued financial assets to the user. Therefore, updates to user information fields will require additional verification. While updates to the critical fields may be blocked entirely. Update User critical fields: first_name middle_name (optional) last_name preferred_name Updates to the following fields are not allowed when: The user is already KYC approved The user status is already active The user has already been issued an account/wallet. Special fields requiring additional re-verification when updated, after the customer's KYC has been approved: Mobile number Email address Residential address Billing address For the list of other updateable user fields, please refer to the Update Individual User (V2) API definition. *In PH, a 30-day cooling period is in effect — where the updates to the above special fields are disallowed, starting from the KYC approval date or the date of last change to +30 days . Update Individual Users Call the Update Individual Users ( PUT /users ) to update the user profile's updateable fields. Update Individual Users request (email updated) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "email": "johnny.smith@matchmove.com" } }' Update Individual Users response (email updated) JSON { "addresses": { "billing": { "city": "Cebu City, Cebu", "country": "Philippines", "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "Region VII", "postal_code": "6000", "state": "CEBU" }, "identity_verification": {}, "residential": { "city": "Cebu City, Cebu", "country": "Philippines", "line_1": "Resi", "line_2": "Somerset", "line_3": "Phase", "line_4": "Region VII", "postal_code": "6000", "state": "CEBU" }, "shipping": {} }, "agent_id": "", "annual_income_range": "100 to 1000", "birth": { "city": "Cebu", "country": "Philippines", "date": "1990-06-15", "name": "John Smith", "postal_code": "6000" }, "client_ref_id": "1234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2025-08-06T11:36:08Z", "date_updated": "2025-08-06T11:36:08Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": { "city": "PASIG_CITY_NCR", "country": "PHL", "line_1": "Ortigas Center", "line_2": "San Antonio", "line_3": ".", "line_4": "NCR", "postal_code": "4107", "state": "NCR" }, "business_purpose": "Financials", "business_trading_name": "MatchMove Pay Pte Ltd", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "", "vat_number": "0000000" }, "employment_type": "EMPLOYED_REGULAR", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Juan", "last_name": "Smith", "maiden_name": "Juan Johnson", "middle_name": "Johnson" }, "first_name": "Johnny", "gender": "male", "id": "34f7579b81ff462da64b6fa5e35198fe", "identification": { "primary": { "id_date_expiry": "2025-08-24", "id_date_issued": "2019-08-24", "id_issuance_country": "Philippines", "id_number": "000000", "id_type": "drivers_id" }, "secondary": { "id_date_expiry": "2025-08-24", "id_date_issued": "2019-08-24", "id_issuance_country": "Philippines", "id_number": "000000", "id_type": "passport" } }, "is_email_verified": "0", "is_mobile_verified": "0", "is_risk_flagged": "UNKNOWN", "job_title": "Software Engineer", "kyc_processed_date": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "last_name": "Smith", "main_income_source": "PAYROLL", "marital_status": "Married", "metadata": {}, "middle_name": "Williams", "mobile": "9999999999", "mobile_country_code": "63", "mothers_details": { "first_name": "Juana", "last_name": "Smith", "maiden_name": "Juana Williams", "middle_name": "Williams" }, "nationality": "PHL", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "", "purpose_of_account_opening": "", "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [] }, "immediately_due": { "required_actions": [], "required_attributes": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "UNKNOWN", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_verification", "sub_status": "", "title": "Mr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl" }, "transaction_status": "", "transaction_sub_status": "", "type": "customer", "work_country": "Philippines" "requirements" : { "eventually_due": { "required_attributes" : [], "required_actions": [] }, "immediately_due": { "required_attributes": [ ], "required_actions": [ "email_verification" ] }," pending_verification": { "email": { "created_at": "2024-06-25 15:20:39", "expired_at": "2024-07-09 15:20:39", "verification_data": { "email": "johnny.smith@matchmove.com" }, "verification_id" : "4757b9126e17491f9a0e22e39775569d" } } } } }json Once Update User is executed on the special fields, its response will have an additional payload requirements detailing whether additional actions are required for the profile update. These requirements will need to be satisfied before the updated changes get committed and reflected in the user profile. Update Individual Users response on Post-KYC update (excepts) "requirements": { "eventually_due": { "required_attributes" : [], "required_actions": [] }, "immediately_due": { "required_attributes": [ ], "required_actions": [ "email_verification" ] }," pending_verification": { "email": { "created_at": "2024-06-25 15:20:39", "expired_at": "2024-07-09 15:20:39", "verification_data": { "email": " johnny.smith@matchmove.com " }, "verification_id" : "4757b9126e17491f9a0e22e39775569d"} } } } The table below outlines the various properties possible for the requirements object and the corresponding Field Description Title Relevant API immediately_due Fields that are required to be processed/collected immediately under requirements object. values in required_attributes need to collect the information from the user immediately values in required_actions need to complete the actions immediately PUT /users/{user_id} POST /users/verify eventually_due Fields that need to be collected but are not critical for the user process under requirements object. pending_verification Fields that might become required depending on the results of verification or review. It’s an empty object unless an asynchronous verification is pending under requirements object. Initiate verification for properties in the object POST /users/verify pending_update Fields that will get updated to the system only after the respective external dependency (from the license provider or any third-party provider) or verification requirements. Monitor for account status updates Platform-provided contact verification Currently, the platform-provided mechanism for mobile/email verification is only available for the initial user profile creation. Verification of mobile/email during the Post-KYC update will need to be managed by the partner (self-verification). Self-verification entails the partner performing their own verification process on the updated fields that require re-verification. The partner will have to do a self-verification activity, where they can verify the mobile or email using their own capabilities and services. Once the self-verification is completed, the partner is required to pass some metadata of their completed verification. These metadata will be used for the purposes of audit. Every updated field requiring verification will have an associated verification ID in the requirements block in the user payload. Self-validate Contact Verification Call the Self- validate Contact Verification ( POST /users/verify ) to pass the self-verification metadata to the platform. Passing the following: Title Required Parameter Description Verification ID verification_id Verification ID associated with the updated field. This ID can be located in the requirements block in the Get User payload. Partner verification metadata id Verification ID (verification_id) associated with the field being verified. mode Defaulted to MANUAL for fields self-verified by the partner. document_type Allowed values: PROOF_OF_MOBILE_OWNERSHIP PROOF_OF_EMAIL_OWNERSHIP SUBSCRIBER_AUTHORIZATION_LETTER document_id Partner-Internal verification document identifier Self-validate Contact Verification request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify' \ --header 'content-type: application/json' \ --header 'Authorization: ••••••' \ --header 'X-Auth-User-ID: {{user_id}}' \ --data-raw '{ "id": "4757b9126e17491f9a0e22e39775569d", "mode": "MANUAL", "document_type": "PROOF_OF_EMAIL_OWNERSHIP", "document_id": "ba02d43c-3cc2-49b7-96c2-ed0861e55a83", "authentication_data": { "device_id": "id0001", "ip": "127.0.0.1", "os": "SteveOS-High", "user_agent": "" }, "date": "2024-05-24" }' Self-validate Contact Verification response JSON { "action": "email_verification", "user_id": "{{user_id}}", "id": "9085376ed64e407791334571e45fc8ce", "mode": "MANUAL", "verification_data": { "email": "johnny.smith@matchmove.com" }, "authentication_data": { "device_id": "id0001", "ip": "127.0.0.1", "os": "SteveOS-High" }, "status": "success" } 3 [Post-KYC Profile Update] Monitor if the status of the request for user profile update Once the fields requiring re-verification have been self-verified by the partner, these fields will be sent to the licensed provider or the bank partner for approval of the change. Once approved, the changes requested will be committed, and the user profile will be updated accordingly. If the partner wants to be notified when a user profile update request is completed, they must subscribe to the “ User Details ” webhook category and events. Go to the Leverage Webhooks section to learn more about setting up the webhooks. Sample webhook payload JSON "event_data\":{\"entities\":{\"user\":{\"addresses\":{\"billing\":{\"city\":\"ADAMS_ILOCOS_NORTE\",\"country\":\"PHL\",\"line_1\":\"119 Pine St\",\"line_2\":\"Maryland Subd\",\"line_3\":\"Phase\",\"line_4\":\"REGION_03\",\"postal_code\":\"400\",\"state\":\"ANTIQUE\"},\"identity_verification\":{},\"residential\":{\"city\":\"ADAMS_ILOCOS_NORTE\",\"country\":\"PHL\",\"line_1\":\"119 Pine St\",\"line_2\":\"Maryland Subd\",\"line_3\":\"Phase\",\"line_4\":\"REGION_03\",\"postal_code\":\"400\",\"state\":\"ANTIQUE\"},\"shipping\":{}},\"agent_id\":\"\",\"annual_income_range\":\"\",\"birth\":{\"date\":\"1990-03-13\"},\"client_ref_id\":\"\",\"customer_id\":\"\",\"data_terms_signed_at\":\"\",\"date_created\":\"2025-10-15T21:19:05Z\",\"date_updated\":\"2026-01-27T16:35:43Z\",\"email\":\"john.smith@matchmove.com\",\"employment_details\":{\"business_address\":{\"city\":\"ABORLAN_PALAWAN\",\"country\":\"PHL\",\"line_1\":\"Line1 street 101\",\"line_2\":\"Line2 street 101\",\"line_3\":\"Phase\",\"line_4\":\"REGION_01\",\"postal_code\":\"400\",\"state\":\"ABRA\"},\"business_purpose\":\"\",\"business_trading_name\":\"Employer Name\",\"expected_monthly_revenue\":\"\",\"industry\":\"\",\"industry_key\":\"\",\"own_economic_interest_signed_at\":\"\",\"vat_number\":\"\"},\"employment_type\":\"COMMISSION_BASED_AGENT\",\"fatca_crs_confirmed_at\":\"0001-01-01T00:00:00Z\",\"fatca_relevant\":false,\"father_details\":{},\"first_name\":\"John\",\"gender\":\"MALE\",\"id\":\"25ce05638628453ab1c0d2ea3e7562cc\",\"identification\":{\"primary\":{\"id_date_expiry\":\"2027-10-13\",\"id_date_issued\":\"2025-10-13\",\"id_issuance_country\":\"PHL\",\"id_number\":\"6009005384144\",\"id_type\":\"UMID\"},\"secondary\":{}},\"is_email_verified\":\"1\",\"is_mobile_verified\":\"1\",\"is_risk_flagged\":\"UNKNOWN\",\"job_title\":\"\",\"kyc_processed_date\":\"2025-10-27T02:23:05Z\",\"kyc_status\":\"completed\",\"kyc_sub_status\":\"approved\",\"last_name\":\"Smith\",\"main_income_source\":\"COBRANDING_PARTNER\",\"marital_status\":\"MARRIED\",\"metadata\":null,\"middle_name\":\"Williams\",\"mobile\":\"9299534289\",\"mobile_country_code\":\"63\",\"mothers_details\":{\"maiden_name\":\"Juana Steven\"},\"nationality\":\"PHL\",\"partner_id\":\"\",\"pending_update\":[],\"preferred_name\":\"John Smith\",\"provider_account_number\":\"930100139810\",\"provider_ref_id\":\"HMAP251015000043631\",\"purpose_of_account_opening\":\"\",\"requirements\":{\"eventually_due\":{\"required_actions\":[],\"required_attributes\":[]},\"immediately_due\":{\"required_actions\":[],\"required_attributes\":[]},\"pending_verification\":{}},\"residency_country\":\"\",\"risk_assesment_status\":\"UNKNOWN\",\"salutation\":\"\",\"self_declared_as_pep\":false,\"socioprofessional_category\":\"\",\"status\":\"active\",\"sub_status\":\"active\",\"title\":\"MADAM\",\"tos_acceptance\":{\"date\":\"0001-01-01T00:00:00Z\",\"device_id\":\"\",\"ip\":\"\",\"service_agreement\":\"\",\"user_agent\":\"\"},\"transaction_status\":\"\",\"transaction_sub_status\":\"\",\"type\":\"customer\",\"work_country\":\"\"}},\"entity_id\":\"25ce05638628453ab1c0d2ea3e7562cc\",\"entity_type\":\"USER\",\"event_timestamp\":\"2026-01-27T16:35:47Z\",\"message_id\":\"9d0c227a-9fef-45d2-b314-e91670967b40\",\"program_code\":\"{{product_code}}\",\"version\":\"v2\",\"webhook_event\":\"USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS\"},\"event_name\":\"USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS\",\"max_retry_age\":0,\"max_retry_attempts\":0,\"product_code\":\"{{product_code}}\",\"retry_attempt\":19,\"service_name\":\"customer\",\"trace_id\":\"25ce05638628453ab1c0d2ga3e7562cc_b6cc8c5e578a4b20a0e192e07de2c3ab\",\"webhook_id\":\"5199526d-fd73-4070-8cd7-191424d81317\"}" Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Region-specific onboarding Business users • [Submit individual KYC](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/submit-individual-kyc.md): Learn the process of submitting the required information and documentation for individual user identity verification. This guide provides an overview of the Know Your Customer (KYC) requirements needed for verification. When onboarding an individual user, partners have two distinct options to complete and verify the KYC submission: 1. Document-Based Verification This is the standard verification method where all necessary identity checks are handled directly through the MatchMove API. Process: The user uploads all required physical or digital KYC identity documents (such as passports, standard government IDs, or driver's licenses). Submission: The complete KYC application, including the document images, proof of address, and the user's demographic profile, is submitted directly through the MatchMove API. Verification: The system processes the submitted documents to check for authenticity, image quality, and demographic matching. Please note that the final decision on the approval will be made by the Financial Institution. 2. Authentication-Based Verification (PH National ID) Note: This authentication-based verification method is currently available only for users in the Philippines (PH) region. This streamlined method leverages the Philippine Statistics Authority's National ID eVerify system to authenticate the user's identity electronically, eliminating the need for manual document checks for the primary ID. Primary Authentication: The user's Philippine National ID (PhilID) is electronically verified via the eVerify platform. This step is facilitated through a separate, dedicated integration directly with the Financial Institution. Secondary Submission: Once the eVerify authentication is successful, the partner submits the user's completed profile along with any required supplementary documents through the MatchMove API. Completion: The MatchMove API consolidates the successful eVerify confirmation with the submitted profile data to finalize the KYC submission. The final decision on the approval will be made by the Financial Institution. KYC Rejection Reasons - Individuals This section provides an exhaustive list of all the individual KYC rejection reasons and their corresponding descriptions that are available on the platform. Rejection Reasons (Individuals) Description ADDRESS_MISMATCH The address does not match the proof of address. AGE_BELOW_MINIMUM The user is below the minimum age allowed. AGE_EXCEEDS_MAX_LIMIT The user is above the maximum age allowed. BLACKLISTED_PROFILE_INFO Profile details match a blacklist or sanctions entry. COUNTRY_MISMATCH The country on the document does not match the country declared. DOB_MISMATCH Date of birth does not match the document. DOCUMENT_AUTHENTICITY The document shows signs of tampering or forgery. DOCUMENT_DEMOGRAPHIC_MATCH Demographic details on the document do not match the profile. DOCUMENT_EXPIRED The document is past its validity date. DOCUMENT_EXPIRING_SOON The document expires within the minimum validity period required. DOCUMENT_ID_REJECTED The identity document submitted was not accepted. DOCUMENT_IMAGE_QUALITY_ISSUE The document image is unreadable. DOCUMENT_ISSUING_COUNTRY_NOT_SUPPORTED The issuing country of the document is not supported. DOCUMENT_LANGUAGE_NOT_SUPPORTED The document language is not supported. DOCUMENT_MISSING A required document was not submitted. DOCUMENT_NOT_RECENT_ENOUGH The document is older than the maximum age allowed. DOCUMENT_POA_REJECTED The proof of address submitted was rejected. DOCUMENT_QUALITY Document quality is too poor to process. DOCUMENT_SELFIE_REJECTED The selfie is unusable or does not match the document photo. DOCUMENT_SIGNATURE_REJECTED The signature on the document was rejected. DOCUMENT_TYPE_MISMATCH The document type submitted differs from the type required. DOCUMENT_VIDEO_REJECTED The verification video submitted was rejected. DUPLICATE_DETAILS The details submitted match an existing profile. EXPIRED_DOCUMENTS One or more of the documents submitted have expired. GENDER_MISMATCH Gender does not match the document. INFORMATION_INCOMPLETE Mandatory information is missing or incomplete. INFORMATION_MISMATCH Application information does not match the verification source. INVALID_PROFILE_INFO Profile information is invalid or in an unaccepted format. LIVELINESS_AUTHENTICATION The liveness check could not be completed successfully. LIVENESS_VERIFICATION_FAILED The user did not pass the liveness check. MISMATCH_PROFILE_DETAILS Profile details do not match the document. MISMATCH_PROFILE_NAME The profile name does not match the name on the document. NAME_MISMATCH Name on the document does not match the application. OTHERS Non-standard rejection. Contact compliance for further instruction. REGION_NOT_SUPPORTED The user's region is not serviceable under this program. REJECTED Know Your Customer (KYC) not approved. REJECTION_REQUESTED The applicant asked to withdraw the application. SUSPECT_PROFILE The profile is flagged for fraud or risk indicators. UNSUPPORTED_DOCUMENTS The document type is not accepted for this program. Document Verification Results ( USER.DOCUMENT_VERIFICATION.STATUS.verification_results ) This section details the specific verification results and status codes available for PH (Philippines) programs. For rejected sub-status codes, please refer to the exhaustive list provided in the KYC Rejection Reasons - Individuals section. status sub_status sub_status_code completed approved — completed rejected REJECTED completed rejected DOCUMENT_ID_REJECTED completed rejected DOCUMENT_SIGNATURE_REJECTED completed rejected DOCUMENT_SELFIE_REJECTED completed rejected DOCUMENT_QUALITY completed rejected INVALID_PROFILE_INFO completed rejected REJECTION_REQUESTED completed rejected DUPLICATE_DETAILS completed rejected BLACKLISTED_PROFILE_INFO completed rejected MISMATCH_PROFILE_DETAILS completed rejected MISMATCH_PROFILE_NAME • [[PH] Document-based verification](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/submit-individual-kyc/ph-document-based-verification.md): Learn the process of submitting the required information and documentation for document-based individual user identity verification. This guide provides an overview of the specific Know Your Customer (KYC) requirements needed to complete a document-based verification. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to submit the required KYC documents needed to verify the identity of an individual user. You want to submit supporting documents that will help in the individual user identity verification. You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove KYC endpoints. Prerequisites The individual user profile must be created. Refer to the Register customer profile (v2) section for more details. API Workflow (v2) 1 Check if an individual user is allowed to submit KYC Before allowing a user to submit their KYC documents, we must first verify their current KYC status. This means that if the user's KYC status is not listed below, the entry point or screen for initiating KYC submission must be hidden from the partner app interface. A user can only send a KYC submission for verification if their KYC status is not_submitted - the user has never submitted a KYC for verification rejected - the user can now resubmit because their previous KYC submission was rejected during verification List KYC documents Call List KYC Documents ( GET /users/authentications/documents ) to retrieve the KYC status of an individual user. List KYC documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List KYC documents response JSON { "status": "not_submitted", "sub_status": "not_submitted", "documents": null, "count": 0, "kyc_details": null } s *To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links. 2 (Optional) Request a verification session before document upload Note: This step is only required for programs with multiple KYC methods enabled (e.g., document-based and authentication-based). If your program has only one active method, you may skip this step. Every document-based KYC process begins by requesting a new verification session for the newly onboarded user. This step assigns a unique KYC verification session ID to manage their onboarding workflow. This session ID is strictly required before you can proceed with uploading any of the user's identity documents. Before requesting a KYC verification session, you must first check the id_type submitted by the user. This value determines the specific verification mode required for their KYC process. Get Individual Users Call Get Individual Users ( GET /users/{{user_id}} ) passing in the user ID of the user to retrieve his user profile. Get Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Authorization: ••••••' Get Individual Users response JSON { "addresses": { "billing": { "city": "MARIKINA_CITY_NCR", "country": "PHL", "line_1": "150 Sunshine Street", "line_2": "Santa Elena (Pob.)", "line_3": "SANTA_ELENA", "line_4": "NCR", "postal_code": "1800", "state": "NCR" }, "identity_verification": {}, "residential": { "city": "MAKATI_CITY_NCR", "country": "PHL", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "postal_code": "1228", "state": "NCR" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "city": "MAKATI_CITY_NCR", "country": "PHL", "date": "1991-11-11", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "state": "NCR" }, "client_ref_id": "23123213", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T11:02:29Z", "date_updated": "2026-08-18T18:11:05Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": { "city": "MAKATI_CITY_NCR", "country": "PHL", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "postal_code": "1228", "state": "NCR" }, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "EMPLOYED_REGULAR", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "MALE", "id": "{{user_id}}", "identification": { "primary": { "id_issuance_country": "PHL", "id_number": "X321312312", "id_type": "PASSPORT" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "job_title": "", "kyc_processed_date": "2026-08-12T03:02:34Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "Smith", "main_income_source": "PAYROLL", "marital_status": "", "metadata": null, "middle_name": "", "mobile": "9123812845", "mobile_country_code": "63", "mothers_details": { "maiden_name": "Juana Williams" }, "nationality": "PHL", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "17865033123122312", "provider_ref_id": "31312312310375312312", "purpose_of_account_opening": "", "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "", "risk_assesment_status": "UNKNOWN", "risk_evaluation_date": null, "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "title": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "" }, "transaction_status": "", "transaction_sub_status": "", "type": "customer", "verification_expiry": null, "work_country": "" } Follow the appropriate flow below based on the submitted id_type : Document-based verification All supported proof of identification documents, such as id_type = PASSPORT, UMID, DRIVERS_ID, etc., including NATIONAL_ID can be forwarded for document-based KYC verification. Proceed to request the Create KYC Verification step below. Authentication-based verification (Optional) Programs enabled for authentication-based verification can offer an additional workflow: users submitting id_type = NATIONAL_ID can be forwarded for authentication-based KYC. Proceed to the Authentication-based Verification section and follow the authentication-based KYC verification steps. Initiate the document_based verification by requesting a KYC verification session: Initiate KYC Submission Call Initiate KYC Submission ( POST /users/authentications/documents/verifications ) passing document_based in the verification_mode parameter to receive a new KYC verification session ID. Initiate KYC Submission request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "verification_mode":"document_based" }' Initiate KYC Submission response JSON { "created_date": "2026-08-12T10:15:13+0800", "id": "b4e3923e509b44c4ae15997516ed1594", "requirements": { "eventually_due": { "required_actions": [ "confirm_submission" ], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [ "front_of_id_document", "selfie" ] }, "pending_verification": { "confirm_submission": { "link": { "href": "/{{program_code}}/v2/users/authentications/documents", "method": "PUT" }, "verification_id": "vfc_c94434a4898f44849900da4237b0e3d6" } } }, "sub_type": "customer", "type": "users", "verification_id": "vfc_c94434a4898f44849900da4237b0e3d6", "verification_mode": "document_based" } Understanding the Initiate KYC Submission response The API returns the following information: Response field Description verification_id Unique identifier for the verification session that will track all the verification activities that the user will undergo. verification_mode The verification mode that was selected for the verification session. requirements Defines the documents, attributes, and actions required to complete the verification flow. Clients should always follow the returned requirements instead of assuming the next verification step. Requirements for KYC Verification The Initiate KYC Submission API returns a requirements object that describes the information and actions needed to complete verification. Simply follow these requirements to ensure a smooth and accurate onboarding flow. Requirements Fields Description Required Action immediately_due.required_documents Lists the document types that must be uploaded before the verification can proceed. Upload the required documents using Upload KYC documents ( POST /v2/users/authentications/documents ). eventually_due.required_actions Lists the actions that should be completed after all immediate requirements have been satisfied. Once you've fulfilled all immediate requirements, perform these listed actions in sequential order. pending_verification Includes further actions that unlock once an asynchronous verification begins. Each action supplies the verification ID, any necessary attributes, and the API endpoint needed to take the next step. Keep an eye on the verification status. If this object contains data, perform the specified action using the API details provided. Pending Verification Each action returned under pending_verification contains the following fields: Pending Verification Field Description verification_id The verification session associated with the pending action. attributes List of attributes required to complete the action. This field is returned only when additional information is required. link.method HTTP method to invoke. link.href API endpoint to invoke for completing the action. Initiate KYC Submission - Requirements payload example JSON { "requirements": { "immediately_due": { "required_documents": [ "selfie" ], "required_attributes": [ "first_name", "last_name" ], "required_actions": [ "email_verification", "mobile_verification" ] }, "eventually_due": { "required_actions": [ "confirm_submission" ] }, "pending_verification": { "confirm_submission": { "verification_id": "ver_987654321", "attributes": [ "authentication.identifier", "authentication.reference_number", "authentication.processed_date" ], "link": { "method": "PUT", "href": "{domain}/{product_code}/v2/users/authentications/documents" } } } } } 3 Collect and upload supporting documents (requirements.immediately_due.required_documents) Review the user.requirements object and check requiements.immediately_due.required_documents list to identify exactly which supporting documents are needed from the user. You can seamlessly collect these required files directly through your own mobile or web application. Once collected, securely upload each document to our system using the Create KYC API. You will not be able to proceed to upload any document unless the requirements.immediately_due.required_attributes and the requirements.immediately_due.required_actions requirements are satisfied. You will encounter an error requesting the required missing information and actions to be completed before any document upload. Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 8MB per file No. of files: maximum 4 files Upload KYC Documents Call Upload KYC Documents ( POST /users/authentications/documents ) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload. Upload KYC documents-required field enumerations: file_type allowed values are listed in the List File Types Enumerations ( GET /users/enumerations/file_types ). document_type allowed values are listed in the List Document Types Enumerations ( GET /users/enumerations/document_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Upload KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --form 'file_type="selfie"' \ --form 'document_type="selfie"' \ --form 'file=@"/Users/mm-john/Downloads/1527530326.png"' Upload KYC Documents response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "pending", "sub_status": "pending_document_submission", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "selfie" } ], "count": 1, "kyc_details": null } (Optional) Delete erroneous, incorrect, or rejected (resubmission) KYC documents Delete KYC Documents Call Delete KYC Documents ( DELETE /users/authentications/documents/{{document_id}} ) to delete existing or submitted documents of a user. Delete KYC Documents request CURL curl --location --request DELETE 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/{{document_id}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Delete KYC Documents response JSON { "success": true } 4 Confirm all uploads and submit KYC for approval Once all the required documents have been uploaded, the partner must confirm and finalize KYC for submission. Once the application is finalized, the KYC verification process will commence. Confirm KYC Submission Call Confirm KYC Submission ( PUT /users/authentications/documents/verifications ) to finalize the uploaded documents and queue the submission for KYC approval. Confirm KYC Submission request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Confirm KYC Submission response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "in_progress", "sub_status": "submitted", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "selfie" }, { "date": { "created": "2025-09-29T12:05:55+0800" }, "id": "33MEtad0IwFBakKiY7DWr9Yrxv6", "id_type": "NATIONAL_ID", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEtad0IwFBakKiY7DWr9Yrxv6.png", "provider_document_id": "", "side": "front", "status": "uploaded", "type": "id" }, { "date": { "created": "2025-09-29T12:06:08+0800" }, "id": "33MEvAu1cKjbp9IZbYDXJVYdikG", "id_type": "NATIONAL_ID", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEvAu1cKjbp9IZbYDXJVYdikG.png", "provider_document_id": "", "side": "back", "status": "uploaded", "type": "id" } ], "count": 3, "kyc_details": null } In the live environment, this KYC submission will go through a series of automated verifications and, depending on the user profile risk, may require a manual verification. In the staging environment, this KYC verification process can be simulated by sending additional simulation parameters . Refer to the Simulate individual KYC section to learn more. 5 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action USER.DOCUMENT_VERIFICATION.STATUS KYC Document Verification Update A notification is sent in the event that the KYC status of the user is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. ACCOUNT.KYC.VERIFICATION_FAILED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Initiate Verification Failed A notification is sent in the event a failure happens on any process after a verification is completed. No action required. The verification process will auto-retry. ACCOUNT.KYC.VERIFICATION_APPROVED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved. No action required. You may now proceed to provision the user with financial products such as accounts and cards. ACCOUNT.KYC.VERIFICATION_REJECTED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Verification Rejected A notification is sent in the event that the KYC status of the user is updated to rejected along with a reject code. You may ask the user to retry or redo another round of KYC submission. USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (pending activation) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "first_name": "John", "birth": { "date": "1990-01-15" }, "transaction_sub_status": "", "title": "Mr", "kyc_status": "in_progress", "type": "individual", "tos_acceptance": { "user_agent": "Web", "device_id": "", "date": "0001-01-01T00:00:00Z", "service_agreement": "", "ip": "" }, "gender": "Male", "last_name": "Smith", "date_updated": "2026-08-07T16:30:33Z", "client_ref_id": "497bb3bf-2f93-45d4-acc7-145470c4d4d2", "mothers_details": {}, "partner_id": "", "kyc_processed_date": "2026-08-07T16:30:33Z", "sub_status": "selfie_verification_inprogress", "verification_expiry": "2026-09-06 00:00:00", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "email": "john.smith@matchmove.com", "is_email_verified": "1", "employment_details": { "industry_key": "", "expected_monthly_revenue": "", "business_trading_name": "", "own_economic_interest_signed_at": "", "business_purpose": "", "industry": "", "business_address": {}, "vat_number": "" }, "father_details": {}, "marital_status": "", "salutation": "", "status": "pending_activation", "self_declared_as_pep": false, "provider_account_number": "", "main_income_source": "", "id": "28e7378a801bba5d34910ef3cd3131c3", "risk_assesment_status": "PENDING", "mobile_country_code": "63", "purpose_of_account_opening": "", "agent_id": "", "require_provider_update": [], "pending_update": [], "addresses": { "billing": { "line_2": "Unit 1504", "state": "Metro Manila", "line_1": "1847 Mabini Street", "line_3": "Alder Residences", "postal_code": "1210", "country": "Philippines", "city": "Makati City" }, "residential": { "line_1": "1847 Mabini Street", "line_2": "Unit 1504", "line_3": "Alder Residences", "city": "Makati City", "postal_code": "1210", "state": "Metro Manila", "country": "Philippines" }, "identity_verification": {}, "foundation": {}, "shipping": {}, "operational": {} }, "kyc_sub_status": "pending_document_submission", "data_terms_signed_at": "", "http_status_code": 0, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "middle_name": "", "transaction_status": "", "date_created": "2026-08-07T16:29:21Z", "is_risk_flagged": "PENDING", "status_message": "", "risk_evaluation_date": "0001-01-01T06:55:25Z", "work_country": "", "status_reason_code": "", "identification": { "secondary": {}, "primary": { "id_number": "4H7K3856O0", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "id_type": "Passport", "id_date_expiry": "2031-03-09", "id_issuance_country": "Philippines", "id_date_issued": "2021-03-10" } }, "annual_income_range": "", "nationality": "Nationality for Philippines", "preferred_name": "John Smith", "mobile": "9179627560", "employment_type": "", "socioprofessional_category": "", "requirements": { "pending_verification": {}, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "eventually_due": { "required_documents": [], "required_actions": [], "required_attributes": [] } }, "residency_country": "", "provider_ref_id": "607302535441", "suffix": "", "is_mobile_verified": "1", "verification_id": {}, "fatca_relevant": false, "job_title": "", "customer_id": "" }, "verification_results": { "details": {}, "verification_id": "vfc_a00ccceca59d363a0b4a631f29165c8e", "sub_status_code": "PENDING_DOCUMENT_SUBMISSION", "sub_status": "The documents are pending for submission", "status": "in_progress" } } } USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (rejected) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "addresses": { "billing": { "city": "Quezon City", "country": "Philippines", "line_1": "52 Kalayaan Avenue", "line_2": "Unit 803", "postal_code": "1100", "state": "Metro Manila" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "Quezon City", "country": "Philippines", "line_1": "52 Kalayaan Avenue", "line_2": "Unit 803", "postal_code": "1100", "state": "Metro Manila" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "date": "1992-04-23" }, "client_ref_id": "ee5e759f-84d2-4d26-85a8-55aeaa27285b", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-21T09:19:10Z", "date_updated": "2026-08-21T09:19:11Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": {}, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "Male", "http_status_code": 0, "id": "9ae592f1bc5a6c43be33141566c299ed", "identification": { "primary": { "id_date_expiry": "2030-11-01", "id_date_issued": "2020-11-02", "id_issuance_country": "Philippines", "id_number": "HB45697856113", "id_type": "Id Card", "metadata": { "key_1": "value_1", "key_2": "value_2" } }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "", "kyc_processed_date": "2026-09-30T09:52:11Z", "kyc_status": "completed", "kyc_sub_status": "rejected", "last_name": "Smith", "main_income_source": "", "marital_status": "", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "middle_name": "", "mobile": "9811321893", "mobile_country_code": "63", "mothers_details": {}, "nationality": "Nationality for Philippines", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "8fad3f391897a24dbc5747567", "purpose_of_account_opening": "", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "", "residency_status": "", "risk_assesment_status": "PENDING", "risk_evaluation_date": "0001-01-01T06:55:25Z", "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Philippines", "id_type": "Utility Bill" } ], "title": "Mr", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-10-30 00:00:00", "verification_id": {}, "work_country": "" }, "verification_results": { "details": {}, "status": "rejected", "sub_status": "The documents submitted did not meet the criteria", "sub_status_code": "REJECTED", "verification_id": "vfc_c3b64581c4debd213d3d69986d3f95ac" } } } USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (approved) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "addresses": { "billing": { "city": "Pasig City", "country": "Philippines", "line_1": "308 Rizal Avenue", "line_2": "Barangay Kapitolyo", "postal_code": "1603", "state": "Metro Manila" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "Pasig City", "country": "Philippines", "line_1": "14 Sampaguita Street", "line_2": "Barangay Kapitolyo", "postal_code": "1603", "state": "Metro Manila" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "date": "1988-09-11" }, "client_ref_id": "1fb1fc02-6c44-410c-b47e-143c488e4a92", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-09-30T11:49:08Z", "date_updated": "2026-09-30T11:58:21Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": {}, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "Male", "http_status_code": 0, "id": "a508bd1d7df5290ce2dd7df34d584a1f", "identification": { "primary": { "id_date_expiry": "2029-05-13", "id_date_issued": "2019-05-14", "id_issuance_country": "Philippines", "id_number": "3970584472618", "id_type": "Id Card", "metadata": { "key_1": "value_1", "key_2": "value_2" } }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "", "kyc_processed_date": "2026-09-30T11:58:21Z", "kyc_status": "pending", "kyc_sub_status": "pending_document_submission", "last_name": "Smith", "main_income_source": "", "marital_status": "", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "middle_name": "", "mobile": "9427482299", "mobile_country_code": "63", "mothers_details": {}, "nationality": "Nationality for Philippines", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "1a6b6281d9a5b4881556f8ce", "purpose_of_account_opening": "", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_409513c31f35aea91726af50433ace64" } } }, "residency_country": "", "residency_status": "", "risk_assesment_status": "PENDING", "risk_evaluation_date": "0001-01-01T06:55:25Z", "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "aml_verification_inprogress", "suffix": "", "supporting_documents": [ { "id_date_expiry": "2032-02-07", "id_date_issued": "2022-02-08", "id_issuance_country": "Philippines", "id_number": "OHJ76564441Y", "id_type": "Other" } ], "title": "Mr", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2100-01-30 00:00:00", "verification_id": {}, "work_country": "" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_409513c31f35aea91726af50433ace64" } } } ACCOUNT.KYC.VERIFICATION _<result> s a mple webhook payload JSON { "event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED", "product_code": "{{program_code}}", "timestamp": "2025-11-27 17:32:46+0800", "request_id": "89d69adb-53ff-4e67-9518-db2f8e555a79", "trace_id": "a2ba30e56005441f97d4ee4be3d53f46_ca91c8763c5b45eb9e51c714351f6388", "webhook_id": "56b767f6-c0b1-4e2d-8445-01d824d60c97", "event_data": { "message_id": "a6c8ad82-1c32-490c-93aa-9db094cfc3a5", "program_code": "{{program_code}}", "status": "pre-kyc", "timestamp": "2025-11-27 17:32:46+0800", "retry_counter": 0, "user": { "user_hash": "a2ba30e56005441f97d4ee4be3d53f46", "email": "john.smith@mathcmove.com", "mobile": "9886689021", "mobile_country_code": "63", "status": "rejected", "sub_status": "account_rejected_by_issuer", "kyc_status": "completed", "kyc_sub_status": "rejected", "transaction_status": "terminated", "transaction_sub_status": "transaction_blocked_by_issuer", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "provider_ref_id": "HMAP251127010416239", "profile": { "first_name": "JOHN", "middle_name": "WILLIAMS", "last_name": "SMITH", "preferred_name": "JOHN SMITH", "gender": "MALE", "title": "MR", "nationality": "PHL", "marital_status": "SINGLE", "birth": { "date": "1997-07-17" }, "email": "john.smith@matchmove.com", "mobile": "9886689021", "mobile_country_code": "63", "addresses": { "residential": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "billing": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "shipping": {}, "identity_verification": {} }, "employment_details": { "employment_type": "EMPLOYED_REGULAR", "business_trading_name": "MatchMove Pay", "business_address": { "line_1": "Shaw blvd", "line_2": "Pasig city", "line_3": ".", "line_4": "NCR", "city": "PASIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" } }, "mothers_details": { "maiden_name": "Steven" }, "identification": { "primary": { "id_type": "NATIONAL_ID", "id_number": "3013691154861952", "id_issuance_country": "PHL", "id_date_issued": "2025-11-27", "id_date_expiry": "2027-11-27" }, "secondary": {} }, "main_income_source": "OTHERS", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "user_agent": "", "service_agreement": "" } } }, "authentication_documents": { "count": 3, "status": "completed", "sub_status": "rejected", "failure_reason": "", "reject_reason_code": [ { "code": "DOCUMENT_ID_REJECTED", "description": "The id document submitted is rejected" } ], "documents": [ { "type": "id", "side": "front", "id": "363BCiNTxnclrEF2RCaGT19J2Hq", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/id/download/363BCiNTxnclrEF2RCaGT19J2Hq.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:08+0800" } }, { "type": "id", "side": "back", "id": "363BCzCfZOJnEOEauVrgcBqYcmx", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/id/download/363BCzCfZOJnEOEauVrgcBqYcmx.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:10+0800" } }, { "type": "selfie", "id": "363BD56x5UdHMIvmmTvHn2sERXC", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/selfie/download/363BD56x5UdHMIvmmTvHn2sERXC.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:11+0800" } } ] }, "webhook_event": "ACCOUNT.KYC.VERIFICATION_REJECTED" }, "provider_response": { "code": -1, "message": "FAIL", "httpCode": null, "data": null, "success": false }, "provider_http_status_code": 200, "retry_attempt": 0, "max_retry_attempts": 0, "max_retry_age": 0, "message": "" } • [[PH] Authentication-based verification](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/submit-individual-kyc/ph-authentication-based-verification.md): Explore the steps required to submit information for an authentication-based individual user identity verification. This document provides a clear overview of the specific Know Your Customer (KYC) requirements tied to this verification mode. Use this guide to easily navigate the requirements and complete the authentication-based verification process. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to do authentication-based verification using PH National ID eVerify through the Banking Partner integration. You want to submit supporting documents that will help in the individual user identity verification in the platform. You want to add a feature to your application that will enable individual users to upload supporting documents through the MatchMove KYC endpoints and do authentication-based verification using PH National ID eVerify with the Banking Partner integration. Prerequisites The individual user profile must be created. Refer to the Register customer profile (v2) section for more details. You have implemented the Banking Partner's PH National ID eVerify integration and have access to the eVerify Identifiers (discussed in step 4. Confirm all uploads and submit KYC for approval). API Workflow (v2) 1 Check if an individual user is allowed to submit KYC Before allowing a user to submit their KYC documents, we must first verify their current KYC status. This means that if the user's KYC status is not listed below, the entry point or screen for initiating KYC submission must be hidden from the partner app interface. A user can only send a KYC submission for verification if their KYC status is not_submitted - the user has never submitted a KYC for verification rejected - the user can now resubmit because their previous KYC submission was rejected during verification List KYC Documents Call List KYC Documents ( GET /users/authentications/documents ) to retrieve the KYC status of an individual user. List KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List KYC Documents response JSON { "status": "not_submitted", "sub_status": "not_submitted", "documents": null, "count": 0, "kyc_details": null } *To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links. 2 (Optional) Request a verification session before document upload Note: This step is only required for programs with multiple KYC methods enabled (e.g., document-based and authentication-based). If your program has only one active method, you may skip this step. Every document-based KYC process begins by requesting a new verification session for the newly onboarded user. This step assigns a unique KYC verification session ID to manage their onboarding workflow. This session ID is strictly required before you can proceed with uploading any of the user's identity documents. Before requesting a KYC verification session, you must first check the id_type submitted by the user. This value determines the specific verification mode required for their KYC process. Get Individual Users Call Get Individual Users ( GET /users/{{user_id}} ) passing in the user ID of the user to retrieve his user profile. Get Individual Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Authorization: ••••••' Get Individual Users response JSON { "addresses": { "billing": { "city": "MARIKINA_CITY_NCR", "country": "PHL", "line_1": "150 Sunshine Street", "line_2": "Santa Elena (Pob.)", "line_3": "SANTA_ELENA", "line_4": "NCR", "postal_code": "1800", "state": "NCR" }, "identity_verification": {}, "residential": { "city": "MAKATI_CITY_NCR", "country": "PHL", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "postal_code": "1228", "state": "NCR" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "city": "MAKATI_CITY_NCR", "country": "PHL", "date": "1991-11-11", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "state": "NCR" }, "client_ref_id": "23123213", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T11:02:29Z", "date_updated": "2026-08-18T18:11:05Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": { "city": "MAKATI_CITY_NCR", "country": "PHL", "line_1": "50 Makati Avenue", "line_2": "Bangkal", "line_3": "BANGKAL", "line_4": "NCR", "postal_code": "1228", "state": "NCR" }, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "EMPLOYED_REGULAR", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "MALE", "id": "{{user_id}}", "identification": { "primary": { "id_issuance_country": "PHL", "id_number": "D312312312312", "id_type": "NATIONAL_ID" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "job_title": "", "kyc_processed_date": "2026-08-12T03:02:34Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "Smith", "main_income_source": "PAYROLL", "marital_status": "", "metadata": null, "middle_name": "", "mobile": "9123812845", "mobile_country_code": "63", "mothers_details": { "maiden_name": "Juana Williams" }, "nationality": "PHL", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "17865033123122312", "provider_ref_id": "31312312310375312312", "purpose_of_account_opening": "", "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "", "risk_assesment_status": "UNKNOWN", "risk_evaluation_date": null, "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "title": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "" }, "transaction_status": "", "transaction_sub_status": "", "type": "customer", "verification_expiry": null, "work_country": "" } Follow the appropriate flow below based on the submitted id_type : Document-based verification All supported proof of identification documents, such as id_type = PASSPORT, UMID, DRIVERS_ID, etc., including NATIONAL_ID can be forwarded for document-based KYC verification. Proceed to the Document-based Verification section and follow the document-based KYC verification steps. Authentication-based verification (Optional) Programs enabled for authentication-based verification can offer an additional workflow: users submitting id_type = NATIONAL_ID can be forwarded for authentication-based KYC. Proceed to request the Initiate KYC Submission step below. Initiate the authentication_based verification by requesting a KYC verification session: Initiate KYC Submission Call Initiate KYC Submission ( POST /users/authentications/documents/verifications ) passing authentication_based in the verification_mode parameter to receive a new KYC verification session ID. Initiate KYC Submission request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "verification_mode":"authentication_based" }' Initiate KYC Submission response JSON { "created_date": "2026-08-12T10:17:44+0800", "id": "d35029a9579e4cc0b2c09ce1a44681d5", "requirements": { "eventually_due": { "required_actions": [ "confirm_submission" ], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [ "selfie" ] }, "pending_verification": { "confirm_submission": { "attributes": [ "authentication.identifier", "authentication.reference_number", "authentication.processed_date" ], "link": { "href": "/{{program_code}}/v2/users/authentications/documents", "method": "PUT" }, "verification_id": "vfc_eb4722c70eae4e5d82e430f1d5743a67" } } }, "sub_type": "customer", "type": "users", "verification_id": "vfc_eb4722c70eae4e5d82e430f1d5743a67", "verification_mode": "authentication_based" } Understanding the Initiate KYC Submission response The API returns the following information: Response field Description verification_id Unique identifier for the verification session that will track all the verification activities that the user will undergo. verification_mode The verification mode that was selected for the verification session. requirements Defines the documents, attributes, and actions required to complete the verification flow. Clients should always follow the returned requirements instead of assuming the next verification step. Requirements for KYC Verification The Initiate KYC Submission API returns a requirements object that describes the information and actions needed to complete verification. Simply follow these requirements to ensure a smooth and accurate onboarding flow. Requirements Fields Description Required Action immediately_due.required_documents Lists the document types that must be uploaded before the verification can proceed. Upload the required documents using Upload KYC Documents ( POST /v2/users/authentications/documents ). eventually_due.required_actions Lists the actions that should be completed after all immediate requirements have been satisfied. Once you've fulfilled all immediate requirements, perform these listed actions in sequential order. pending_verification Includes further actions that unlock once an asynchronous verification begins. Each action supplies the verification ID, any necessary attributes, and the API endpoint needed to take the next step. Keep an eye on the verification status. If this object contains data, perform the specified action using the API details provided. Pending Verification Each action returned under pending_verification contains the following fields: Pending Verification Field Description verification_id The verification session associated with the pending action. attributes List of attributes required to complete the action. This field is returned only when additional information is required. link.method HTTP method to invoke. link.href API endpoint to invoke for completing the action. Initiate KYC Submission - Requirements payload example JSON { "requirements": { "immediately_due": { "required_documents": [ "selfie" ], "required_attributes": [ "first_name", "last_name" ], "required_actions": [ "email_verification", "mobile_verification" ] }, "eventually_due": { "required_actions": [ "confirm_submission" ] }, "pending_verification": { "confirm_submission": { "verification_id": "ver_987654321", "attributes": [ "authentication.identifier", "authentication.reference_number", "authentication.processed_date" ], "link": { "method": "PUT", "href": "{domain}/{product_code}/v2/users/authentications/documents" } } } } } 3 Collect and upload supporting documents (requirements.immediately_due.required_documents) Review the user.requirements object and check the requirements.immediately_due.required_documents list to identify exactly which supporting documents are needed from the user. You can seamlessly collect these required files directly through your own mobile or web application. Once collected, securely upload each document to our system using the Upload KYC Documents API. You will not be able to proceed to upload any document unless the requirements.immediately_due.required_attributes and the requirements.immediately_due.required_actions requirements are satisfied. You will encounter an error requesting the required missing information and actions to be completed before any document upload. Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 8MB per file No. of files: maximum 4 files Upload KYC Documents Call Upload KYC Documents ( POST /users/authentications/documents ) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload. Upload KYC Documents-required field enumerations: file_type allowed values are listed in the List File Types Enumerations ( GET /users/enumerations/file_types ). document_type allowed values are listed in the List Document Types Enumeration s ( GET /users/enumerations/document_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Upload KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --form 'file_type="selfie"' \ --form 'document_type="selfie"' \ --form 'file=@"/Users/mm-john/Downloads/1527530326.png"' Upload KYC Documents response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "pending", "sub_status": "pending_document_submission", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "selfie" } ], "count": 1, "kyc_details": null } (Optional) Delete erroneous, incorrect, or rejected (resubmission) KYC documents Delete KYC Documents Call Delete KYC Documents ( DELETE /users/authentications/documents/{{document_id}} ) to delete existing or submitted documents of a user. Delete KYC Documents request CURL curl --location --request DELETE 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/{{document_id}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Delete KYC Documents response JSON { "success": true } 4 Confirm all uploads and submit KYC for approval Once all the required documents have been uploaded, the partner must confirm and finalize KYC for submission. Once the application is finalized, the KYC verification process will commence. Confirm KYC Submission Call Confirm KYC Submission ( PUT /users/authentications/documents/verifications ) passing the PH National ID eVerify identifiers to finalize the uploaded documents and queue the submission for KYC approval. The following three fields are populated directly from your direct integration with the Banking Partner's eVerify API. You must capture and map these specific data points as parameters and pass it to the Confirm KYC. These will allow MatchMove and the Banking Partner to be able to map and verify the eVerify results, and update the MatchMove platform accordingly. PH National ID eVerify Identifier Description authentication.identifier Document ID used for authentication authentication.reference_number eVerify reference number authentication.processed_date eVerify processed date Confirm KYC Submission request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "authentication": { "identifier": "{{document_id}}", "reference_number": "{{everify_reference_no}}", "processed_date": "{{everify_date}}" } }' Confirm KYC Submission response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "in_progress", "sub_status": "submitted", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/selfie/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "selfie" }, { "date": { "created": "2025-09-29T12:05:55+0800" }, "id": "33MEtad0IwFBakKiY7DWr9Yrxv6", "id_type": "NATIONAL_ID", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEtad0IwFBakKiY7DWr9Yrxv6.png", "provider_document_id": "", "side": "front", "status": "uploaded", "type": "id" }, { "date": { "created": "2025-09-29T12:06:08+0800" }, "id": "33MEvAu1cKjbp9IZbYDXJVYdikG", "id_type": "NATIONAL_ID", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MEvAu1cKjbp9IZbYDXJVYdikG.png", "provider_document_id": "", "side": "back", "status": "uploaded", "type": "id" } ], "count": 3, "kyc_details": null } In the live environment, this KYC submission will go through a series of automated verifications and, depending on the user profile risk, may require a manual verification. In the staging environment, this KYC verification process can be simulated by sending additional simulation parameters . Refer to the Simulate individual KYC section to learn more. 5 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action USER.DOCUMENT_VERIFICATION.STATUS KYC Document Verification Update A notification is sent in the event that the KYC status of the user is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. ACCOUNT.KYC.VERIFICATION_FAILED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Initiate Verification Failed A notification is sent in the event a failure happens on any process after a verification is completed. No action required. The verification process will auto-retry. ACCOUNT.KYC.VERIFICATION_APPROVED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved No action required. You may now proceed to provision the user with financial products such as accounts and cards. ACCOUNT.KYC.VERIFICATION_REJECTED Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.DOCUMENT_VERIFICATION.STATUS for User and KYC updates . KYC Verification Rejected A notification is sent in the event that the KYC status of the user is updated to rejected along with a reject code You may ask the user to retry or redo another round of KYC submission. USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (pending activation) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "first_name": "John", "birth": { "date": "1990-01-15" }, "transaction_sub_status": "", "title": "Mr", "kyc_status": "in_progress", "type": "individual", "tos_acceptance": { "user_agent": "Web", "device_id": "", "date": "0001-01-01T00:00:00Z", "service_agreement": "", "ip": "" }, "gender": "Male", "last_name": "Smith", "date_updated": "2026-08-07T16:30:33Z", "client_ref_id": "497bb3bf-2f93-45d4-acc7-145470c4d4d2", "mothers_details": {}, "partner_id": "", "kyc_processed_date": "2026-08-07T16:30:33Z", "sub_status": "selfie_verification_inprogress", "verification_expiry": "2026-09-06 00:00:00", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "email": "john.smith@matchmove.com", "is_email_verified": "1", "employment_details": { "industry_key": "", "expected_monthly_revenue": "", "business_trading_name": "", "own_economic_interest_signed_at": "", "business_purpose": "", "industry": "", "business_address": {}, "vat_number": "" }, "father_details": {}, "marital_status": "", "salutation": "", "status": "pending_activation", "self_declared_as_pep": false, "provider_account_number": "", "main_income_source": "", "id": "28e7378a801bba5d34910ef3cd3131c3", "risk_assesment_status": "PENDING", "mobile_country_code": "63", "purpose_of_account_opening": "", "agent_id": "", "require_provider_update": [], "pending_update": [], "addresses": { "billing": { "line_2": "Unit 1504", "state": "Metro Manila", "line_1": "1847 Mabini Street", "line_3": "Alder Residences", "postal_code": "1210", "country": "Philippines", "city": "Makati City" }, "residential": { "line_1": "1847 Mabini Street", "line_2": "Unit 1504", "line_3": "Alder Residences", "city": "Makati City", "postal_code": "1210", "state": "Metro Manila", "country": "Philippines" }, "identity_verification": {}, "foundation": {}, "shipping": {}, "operational": {} }, "kyc_sub_status": "pending_document_submission", "data_terms_signed_at": "", "http_status_code": 0, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "middle_name": "", "transaction_status": "", "date_created": "2026-08-07T16:29:21Z", "is_risk_flagged": "PENDING", "status_message": "", "risk_evaluation_date": "0001-01-01T06:55:25Z", "work_country": "", "status_reason_code": "", "identification": { "secondary": {}, "primary": { "id_number": "4H7K3856O0", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "id_type": "Passport", "id_date_expiry": "2031-03-09", "id_issuance_country": "Philippines", "id_date_issued": "2021-03-10" } }, "annual_income_range": "", "nationality": "Nationality for Philippines", "preferred_name": "John Smith", "mobile": "9179627560", "employment_type": "", "socioprofessional_category": "", "requirements": { "pending_verification": {}, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "eventually_due": { "required_documents": [], "required_actions": [], "required_attributes": [] } }, "residency_country": "", "provider_ref_id": "607302535441", "suffix": "", "is_mobile_verified": "1", "verification_id": {}, "fatca_relevant": false, "job_title": "", "customer_id": "" }, "verification_results": { "details": {}, "verification_id": "vfc_a00ccceca59d363a0b4a631f29165c8e", "sub_status_code": "PENDING_DOCUMENT_SUBMISSION", "sub_status": "The documents are pending for submission", "status": "in_progress" } } } USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (rejected) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "addresses": { "billing": { "city": "Quezon City", "country": "Philippines", "line_1": "52 Kalayaan Avenue", "line_2": "Unit 803", "postal_code": "1100", "state": "Metro Manila" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "Quezon City", "country": "Philippines", "line_1": "52 Kalayaan Avenue", "line_2": "Unit 803", "postal_code": "1100", "state": "Metro Manila" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "date": "1992-04-23" }, "client_ref_id": "ee5e759f-84d2-4d26-85a8-55aeaa27285b", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-21T09:19:10Z", "date_updated": "2026-08-21T09:19:11Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": {}, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "Male", "http_status_code": 0, "id": "9ae592f1bc5a6c43be33141566c299ed", "identification": { "primary": { "id_date_expiry": "2030-11-01", "id_date_issued": "2020-11-02", "id_issuance_country": "Philippines", "id_number": "HB45697856113", "id_type": "Id Card", "metadata": { "key_1": "value_1", "key_2": "value_2" } }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "", "kyc_processed_date": "2026-09-30T09:52:11Z", "kyc_status": "completed", "kyc_sub_status": "rejected", "last_name": "Smith", "main_income_source": "", "marital_status": "", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "middle_name": "", "mobile": "9811321893", "mobile_country_code": "63", "mothers_details": {}, "nationality": "Nationality for Philippines", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "8fad3f391897a24dbc5747567", "purpose_of_account_opening": "", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "", "residency_status": "", "risk_assesment_status": "PENDING", "risk_evaluation_date": "0001-01-01T06:55:25Z", "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Philippines", "id_type": "Utility Bill" } ], "title": "Mr", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-10-30 00:00:00", "verification_id": {}, "work_country": "" }, "verification_results": { "details": {}, "status": "rejected", "sub_status": "The documents submitted did not meet the criteria", "sub_status_code": "REJECTED", "verification_id": "vfc_c3b64581c4debd213d3d69986d3f95ac" } } } USER.DOCUMENT_VERIFICATION.STATUS sample webhook payload (approved) JSON { "program_code": "{{program_code}}", "webhook_event": "USER.DOCUMENT_VERIFICATION.STATUS", "entity_type": "USER", "version": "v2", "event_timestamp": "2026-08-07 16:30:34+0800", "message_id": "fc375210-5fa2-422d-8b77-b7eb01690b6e", "entity_id": "c8e95eb644060eec9b375c96de03a42f", "entities": { "user": { "addresses": { "billing": { "city": "Pasig City", "country": "Philippines", "line_1": "308 Rizal Avenue", "line_2": "Barangay Kapitolyo", "postal_code": "1603", "state": "Metro Manila" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "Pasig City", "country": "Philippines", "line_1": "14 Sampaguita Street", "line_2": "Barangay Kapitolyo", "postal_code": "1603", "state": "Metro Manila" }, "shipping": {} }, "agent_id": "", "annual_income_range": "", "birth": { "date": "1988-09-11" }, "client_ref_id": "1fb1fc02-6c44-410c-b47e-143c488e4a92", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-09-30T11:49:08Z", "date_updated": "2026-09-30T11:58:21Z", "email": "john.smith@matchmove.com", "employment_details": { "business_address": {}, "business_purpose": "", "business_trading_name": "", "expected_monthly_revenue": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "vat_number": "" }, "employment_type": "", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": {}, "first_name": "John", "gender": "Male", "http_status_code": 0, "id": "a508bd1d7df5290ce2dd7df34d584a1f", "identification": { "primary": { "id_date_expiry": "2029-05-13", "id_date_issued": "2019-05-14", "id_issuance_country": "Philippines", "id_number": "3970584472618", "id_type": "Id Card", "metadata": { "key_1": "value_1", "key_2": "value_2" } }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "", "kyc_processed_date": "2026-09-30T11:58:21Z", "kyc_status": "pending", "kyc_sub_status": "pending_document_submission", "last_name": "Smith", "main_income_source": "", "marital_status": "", "metadata": { "key_1": "value_1", "key_2": "value_2" }, "middle_name": "", "mobile": "9427482299", "mobile_country_code": "63", "mothers_details": {}, "nationality": "Nationality for Philippines", "partner_id": "", "pending_update": [], "preferred_name": "John Smith", "provider_account_number": "", "provider_ref_id": "1a6b6281d9a5b4881556f8ce", "purpose_of_account_opening": "", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_409513c31f35aea91726af50433ace64" } } }, "residency_country": "", "residency_status": "", "risk_assesment_status": "PENDING", "risk_evaluation_date": "0001-01-01T06:55:25Z", "salutation": "", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "aml_verification_inprogress", "suffix": "", "supporting_documents": [ { "id_date_expiry": "2032-02-07", "id_date_issued": "2022-02-08", "id_issuance_country": "Philippines", "id_number": "OHJ76564441Y", "id_type": "Other" } ], "title": "Mr", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "device_id": "", "ip": "", "service_agreement": "", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2100-01-30 00:00:00", "verification_id": {}, "work_country": "" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_409513c31f35aea91726af50433ace64" } } } ACCOUNT.KYC.VERIFICATION _<result> s a mple webhook payload JSON { "event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED", "product_code": "{{program_code}}", "timestamp": "2025-11-27 17:32:46+0800", "request_id": "89d69adb-53ff-4e67-9518-db2f8e555a79", "trace_id": "a2ba30e56005441f97d4ee4be3d53f46_ca91c8763c5b45eb9e51c714351f6388", "webhook_id": "56b767f6-c0b1-4e2d-8445-01d824d60c97", "event_data": { "message_id": "a6c8ad82-1c32-490c-93aa-9db094cfc3a5", "program_code": "{{program_code}}", "status": "pre-kyc", "timestamp": "2025-11-27 17:32:46+0800", "retry_counter": 0, "user": { "user_hash": "a2ba30e56005441f97d4ee4be3d53f46", "email": "john.smith@mathcmove.com", "mobile": "9886689021", "mobile_country_code": "63", "status": "rejected", "sub_status": "account_rejected_by_issuer", "kyc_status": "completed", "kyc_sub_status": "rejected", "transaction_status": "terminated", "transaction_sub_status": "transaction_blocked_by_issuer", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "provider_ref_id": "HMAP251127010416239", "profile": { "first_name": "JOHN", "middle_name": "WILLIAMS", "last_name": "SMITH", "preferred_name": "JOHN SMITH", "gender": "MALE", "title": "MR", "nationality": "PHL", "marital_status": "SINGLE", "birth": { "date": "1997-07-17" }, "email": "john.smith@matchmove.com", "mobile": "9886689021", "mobile_country_code": "63", "addresses": { "residential": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "billing": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "shipping": {}, "identity_verification": {} }, "employment_details": { "employment_type": "EMPLOYED_REGULAR", "business_trading_name": "MatchMove Pay", "business_address": { "line_1": "Shaw blvd", "line_2": "Pasig city", "line_3": ".", "line_4": "NCR", "city": "PASIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" } }, "mothers_details": { "maiden_name": "Steven" }, "identification": { "primary": { "id_type": "NATIONAL_ID", "id_number": "3013691154861952", "id_issuance_country": "PHL", "id_date_issued": "2025-11-27", "id_date_expiry": "2027-11-27" }, "secondary": {} }, "main_income_source": "OTHERS", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "user_agent": "", "service_agreement": "" } } }, "authentication_documents": { "count": 3, "status": "completed", "sub_status": "rejected", "failure_reason": "", "reject_reason_code": [ { "code": "DOCUMENT_ID_REJECTED", "description": "The id document submitted is rejected" } ], "documents": [ { "type": "id", "side": "front", "id": "363BCiNTxnclrEF2RCaGT19J2Hq", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/id/download/363BCiNTxnclrEF2RCaGT19J2Hq.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:08+0800" } }, { "type": "id", "side": "back", "id": "363BCzCfZOJnEOEauVrgcBqYcmx", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/id/download/363BCzCfZOJnEOEauVrgcBqYcmx.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:10+0800" } }, { "type": "selfie", "id": "363BD56x5UdHMIvmmTvHn2sERXC", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/phdemo/selfie/download/363BD56x5UdHMIvmmTvHn2sERXC.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:11+0800" } } ] }, "webhook_event": "ACCOUNT.KYC.VERIFICATION_REJECTED" }, "provider_response": { "code": -1, "message": "FAIL", "httpCode": null, "data": null, "success": false }, "provider_http_status_code": 200, "retry_attempt": 0, "max_retry_attempts": 0, "max_retry_age": 0, "message": "" } • [Simulate individual KYC](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/submit-individual-kyc/simulate-individual-kyc.md): Learn how to trigger specific KYC statuses by submitting predetermined test data during the verification process. This guide helps you understand the end-to-end user journey for individual KYC approvals and rejections in the staging environment. Use Cases: You need to simulate an individual KYC approval to test the success scenarios of your onboarding process. You need to simulate an individual KYC rejection to test the negative scenarios of your onboarding process. Prerequisites: You must already have an registered individual user that is ready to perform KYC. Refer to the Submit individual KYC section to learn about the specific required KYC criteria. Simulation Workflow [PH] Document-based verification Simulated KYC Approval Once a user profile is complete and their KYC application has been submitted, you can seamlessly test your onboarding flow using a simulated KYC approval in the staging environment. This feature allows you to bypass real document processing and safely evaluate how your system responds to a successful user verification. To simulate approval, please follow these steps: 1 [Pre-KYC Submission] Register the user Go through the normal process of creating a user and KYC document submission: Register the information details of the user — Create Individual User s Complete missing required information (if any) — Update Individual Users Verify the mobile and email of the user — User Contact Verification 2 [Pre-KYC Submission] Initiate verification with simulation flag To enable KYC simulation mode, initiate the verification process by passing the is_simulate and the verification_mode parameters to the Initiate KYC Submission API. Initiate KYC Submission request (with simulation flag) CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "is_simulate": true, "verification_mode": "document_based" }' 3 [Pre-KYC Submission] KYC document upload Refer to the following steps above to satisfy the verification requirements: [PH] Document-based verification n, section 3 . Collect and upload supporting documents (immediately_due.required_documents) User will need to upload the required documents. 4 [Pre-KYC Submission] Confirm KYC submission for approval Refer to the following steps above to submit the KYC application: [PH] Document-based verification n, section 4 . Confirm all uploads and submit KYC for approval This will invoke the KYC approval process 5 [Post-KYC Submission] Update the status of the KYC application to trigger approval simulation To start the KYC approval simulation process, we need to update the Update KYC status with the supported approval simulation status : Approval Simulation Status Simulated Result ACTIVE User Activation status: ACTIVE sub_status: ACTIVE kyc_status: COMPLETED kyc_sub_status: APPROVED ACCOUNT_FOR_APPROVAL User Pending Manual Review status: PENDING_ACTIVATION sub_status: WAITING_FOR_APPROVAL_BY_ISSUER kyc_status: IN_PROGRESS kyc_sub_status: IN_PROGRESS Update KYC Status request (with approval simulation status) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/simulate/users/authentications/documents/status' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' \ --data-raw '{ "status": "ACTIVE" }' Immediately after the KYC approval simulation process has completed on the backend, your user should be updated with the expected simulated results. Simulated KYC Rejection You can also test your application's response to an unsuccessful user verification by triggering a simulated KYC rejection in the staging environment. This approach eliminates the need for real document evaluation, allowing you to safely observe your system's error-handling workflows. To simulate rejection, please follow these steps: 1 [Pre-KYC Submission] Register user and submit KYC application (with simulation identifier) Go through the normal process of creating a user and KYC document submission: Register the information details of the user — Create Individual User s Complete missing required information (if any) — Update Individual Users To help the simulation logic identify users bound for rejection — Update Individual Users ( "middle_name": "VERIFICATION-FAILED" ) Verify the mobile and email of the user — User Contact Verification Update Individual Users request (with middle_name simulation identifier) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "middle_name": "VERIFICATION-FAILED" }' 2 [Pre-KYC Submission] Initiate verification with simulation flag To enable KYC simulation mode, initiate the verification process by passing the is_simulate and the verification_mode parameters to the Initiate KYC Submission API. Initiate KYC Submission request (with simulation flag) CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "is_simulate": true, "verification_mode": "document_based" }' 3 [Pre-KYC Submission] KYC document upload Refer to the following steps above to satisfy the verification requirements: [PH] Document-based verification , section 3 . Collect and upload supporting documents (immediately_due.required_documents) The user will need to upload the required documents. 4 [Pre-KYC Submission] Confirm KYC submission for approval Refer to the following steps above to submit the KYC application: [PH] Document-based verification , section 4 . Confirm all uploads and submit KYC for approval This will invoke the KYC approval process 5 [Post-KYC Submission] Update the status of the KYC application to trigger rejection simulation To start the KYC rejection simulation process, we need to Update KYC status to any of the available rejection simulation statuses: Rejection Simulation Status Expected Simulation Result BLOCKED DELETED User Termination status: TERMINATED sub_status: ACCOUNT_BLOCKED_BY_ISSUER / ACCOUNT_DELETED_BY_ISSUER kyc_status: IN_PROGRESS kyc_sub_status: PENDING_BANK_VERIFICATION ACCOUNT_REJECTED REJECTED_VERIFY_ID REJECTED_VERIFY_SIGNATURE REJECTED_VERIFY_VIDEO REJECTED_VERIFY_DOCUMENTS REJECTED_NATIONALITY REJECTED_USER_REQUESTED REJECTED_NO_ADDRESS REJECTED_DUPLICATE_DETAIL REJECTED_BELOW_MINAGE REJECTED_MULTIPLE_ACCOUNTS REJECTED_BLACKLISTED_MOBILE REJECTED_MISMATCHED_BIRTHDATE REJECTED_NAME_DIFFERS User Rejection status: REJECTED sub_status: ACCOUNT_REJECTED_BY_ISSUER kyc_status: COMPLETED kyc_sub_status: REJECTED DEACTIVATED User Suspension status: SUSPENDED sub_status: ACCOUNT_SUSPENDED_BY_ISSUER kyc_status: IN_PROGRESS kyc_sub_status: PENDING_BANK_VERIFICATION Update KYC Status request (with rejection simulation status) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/simulate/users/authentications/documents/status' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' \ --data-raw '{ "status": "ACCOUNT_REJECTED" }' Immediately after the KYC rejection simulation process has completed on the backend, your user should be updated with the expected simulated results. [PH] Authentication-based verification Simulated KYC Approval Once a user profile is complete and their KYC application has been submitted, you can seamlessly test your onboarding flow using a simulated KYC approval in the staging environment. This feature allows you to bypass real document processing and safely evaluate how your system responds to a successful user verification. To simulate approval, please follow these steps: 1 [Pre-KYC Submission] Register the user Go through the normal process of creating a user and KYC document submission: Register the information details of the user — Create Individual User Complete missing required information (if any) — Update Individual Users Verify the mobile and email of the user — User Contact Verification 2 [Pre-KYC Submission] Initiate verification with simulation flag To enable KYC simulation mode, initiate the verification process by passing the is_simulate and the verification_mode parameters to the Initiate KYC Submission API. Inititate KYC Submission request (with simulation flag) CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "is_simulate": true, "verification_mode": "authentication_based" }' 3 [Pre-KYC Submission] KYC document upload Refer to the following steps above to satisfy the verification requirements: [PH] Authentication-based verification n, section 3 . Collect and upload supporting documents (immediately_due.required_documents) The user will need to upload the required documents. 4 [Pre-KYC Submission] Confirm KYC submission for approval Refer to the following steps above to submit the KYC application: [PH] Authentication-based verification n, section 4 . Confirm all uploads and submit KYC for approval This will invoke the KYC approval process 5 [Post-KYC Submission] Update the status of the KYC application to trigger approval simulation To start the KYC approval simulation process, we need to Update KYC status with the supported approval simulation status : Approval Simulation Status Simulated Result ACTIVE User Activation status: ACTIVE sub_status: ACTIVE kyc_status: COMPLETED kyc_sub_status: APPROVED ACCOUNT_FOR_APPROVAL User Pending Manual Review status: PENDING_ACTIVATION sub_status: WAITING_FOR_APPROVAL_BY_ISSUER kyc_status: IN_PROGRESS kyc_sub_status: IN_PROGRESS Update KYC Status request (with approval simulation status) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/simulate/users/authentications/documents/status' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' \ --data-raw '{ "status": "ACTIVE" }' Immediately after the KYC approval simulation process has completed on the backend, your user should be updated with the expected simulated results. Simulated KYC Rejection You can also test your application's response to an unsuccessful user verification by triggering a simulated KYC rejection in the staging environment. This approach eliminates the need for real document evaluation, allowing you to safely observe your system's error-handling workflows. To simulate rejection, please follow these steps: 1 [Pre-KYC Submission] Register user and submit KYC application (with simulation identifier) Go through the normal process of creating a user and KYC document submission: Register the information details of the user — Create Individual User s Complete missing required information (if any) — Update Individual Users To help the simulation logic identify users bound for rejection — Update Individual User s ( "middle_name": "VERIFICATION-FAILED" ) Verify the mobile and email of the user — User Contact Verification Update Individual User request (with middle_name simulation identifier) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "middle_name": "VERIFICATION-FAILED" }' 2 [Pre-KYC Submission] Initiate verification with simulation flag To enable KYC simulation mode, initiate the verification process by passing the is_simulate and the verification_mode parameters to the Initiate KYC Submission API. Initiate KYC Submission request (with simulation flag) CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "is_simulate": true, "verification_mode": "authentication_based" }' 3 [Pre-KYC Submission] KYC document upload Refer to the following steps above to satisfy the verification requirements: [PH] Authentication-based verification , section 3 . Collect and upload supporting documents (immediately_due.required_documents) The user will need to upload the required documents. 4 [Pre-KYC Submission] Confirm KYC submission for approval Refer to the following steps above to submit the KYC application: [PH] Authentication-based verification , section 4 . Confirm all uploads and submit KYC for approval This will invoke the KYC approval process 5 [Post-KYC Submission] Update the status of the KYC application to trigger rejection simulation To start the KYC rejection simulation process, we need to Update KYC status to any of the available rejection simulation statuses: Rejection Simulation Status Expected Simulation Result MISMATCH_AUTHENTICATION_PROFILE_DETAILS User Rejection status: REJECTED sub_status: ACCOUNT_REJECTED_BY_ISSUER kyc_status: REJECTED kyc_sub_status: INVALID_PROFILE_INFO INVALID_REFERENCE_NO User Rejection status: REJECTED sub_status: ACCOUNT_REJECTED_BY_ISSUER kyc_status: REJECTED kyc_sub_status: INVALID_PROFILE_INFO Update KYC Status request (with rejection simulation status) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/simulate/users/authentications/documents/status' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' \ --data-raw '{ "status": "MISMATCH_AUTHENTICATION_PROFILE_DETAILS" }' Immediately after the KYC rejection simulation process has completed on the backend, your user should be updated with the expected simulated results. • [Individual eKYC](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc.md): Understand the identity verification standards and prerequisite documents required for onboarding retail users. This guide provides a comprehensive overview of the compliance framework and data structures needed for individuals. Verify your customers quickly and securely with our comprehensive individual verification suite. From document checks to biometric authentication, the MatchMove platform provides multiple layers of identity assurance—all accessible through a single integration point. Document Verification AI-powered verification of passports, national IDs, driver's licenses, and residence permits from 220+ countries. The OCR technology extracts data in 40+ languages with built-in fraud detection. Biometric Liveliness Advanced 3D face mapping confirms users are real and present. The system detects deepfakes, masks, photos, and screen presentations with 99%+ accuracy—meeting iBeta Level 2 compliance standards. Non-Doc Verification Verify identities in as little as 4.5 seconds without document uploads. The platform cross-references government databases in 10+ countries for frictionless onboarding while maintaining full compliance. Address Verification Validate proof of address documents, including utility bills, bank statements, and government correspondence. Processing completes in under 1 minute regardless of document language. KYC Verification Methods To ensure secure and compliant user onboarding, the platform offers flexible Know Your Customer (KYC) options. Depending on your integration requirements, regional availability, and user eligibility, you can utilize the following verification methods: 1. Document-Based Verification This is the standard verification method where uploaded KYC documents are used to verify that a user profile is legitimate or valid. In this method, the user profile is provided and established before the KYC process starts. Process: The user uploads their required physical or digital KYC identity documents (such as a passport, standard government ID, or driver's license). Submission: The complete KYC application, including the uploaded document images and the pre-existing user profile data, is submitted through the MatchMove API. Verification: The risk and KYC verification processes are aided by automated eKYC verifications on the submitted documents. The final verification decision and approval are made by the Financial Institution. 2. Authentication-Based Verification This method relies on a trusted third party or institution. It asks users to grant access to their already authenticated data, uses that data to update the user profile, and trusts that data as KYC-verified data. Primary Authentication: The user is asked to grant access to their verified identity data held by a trusted third-party institution or platform. Profile Update: Once access is granted, MatchMove automatically collects this external data and updates the user's profile, trusting it as KYC-verified data. Verification: The Financial Institution conducts the risk profiling based on this authenticated data and makes the final decision on approval. KYC Verification Workflows Document-based verification How Document-based verification works 1 User Initiates Verification The user begins the verification process within your platform. They consent to data processing and select their country of residence to ensure the correct document types are presented. 2 Identity Document Upload The user captures or uploads a photo of their government-issued ID (passport, national ID card, driver's license, or residence permit). The KYC service can support 14,000 document types across 220 countries. However, availability of document types for a region will follow global risks and compliance reviews. 3 AI-Powered Document Analysis The KYC service AI instantly extracts data using OCR technology, verifies document authenticity by checking security features, detects tampering or forgery attempts, and validates the document hasn't expired. 4 Biometric Liveness Check The user takes a selfie or short video. The 3D face mapping technology confirms they are a real, live person (not a photo, deepfake, or mask) and matches their face to the ID document photo. 5 Risk Profiling & Screening The verified identity is automatically screened against global sanctions lists, PEP databases, and adverse media sources, with risk scores calculated based on configurable parameters. If a user is flagged as high-risk, an Enhanced Due Diligence (EDD) workflow is activated. This prompts the user to provide additional information or supplementary documents to determine whether the risk alert is a false positive or if an exemption can be granted to allow them to proceed. 6 Verification Complete Results are returned in seconds. Approved users proceed immediately; flagged cases are routed to your compliance team for review. All data is securely stored for audit purposes. Individual Document-based Verification User Journey Designing a seamless eKYC (Electronic Know Your Customer) journey requires a delicate balance between regulatory rigor and user experience. While the interface is designed to feel intuitive and linear, the engine behind it is highly sophisticated. The following workflow outlines the standard sequence of screens a regular user will encounter. However, it is important to note that the capture process is dynamic ; the system adapts in real-time based on the user: country of residence risk associated with the profile If certain triggers are met, the journey will automatically scale to include Enhanced Due Diligence (EDD) requirements, prompting for additional documentation or clarifying questions to ensure full compliance without compromising the integrity of the data. Key Logic of the Journey Adaptive UX: The flow isn't one-size-fits-all; it adjusts based on the "residency" inputs. Risk-Based Triggering: High-risk profiles will see additional form fields that a standard-risk user will not. Dynamic Document Capture: The system intelligently requests specific IDs or supplemental proof that is legally required for verification. Disclaimer Verification Entry Document Selection *Document type availability per region is subject to MatchMove Compliance review. Document Capture Liveliness Detection (through video selfie) Individual Profile Proof of Address Upload Submission Confirmation *Result may be given instantly If there are no issues on the documents submitted or if there are no any outstanding evaluation required for the individual profile. Authentication-based verification How Authentication-based verification works 1 User Initiates Verification The user begins the verification process within your platform. Instead of being prompted to upload physical documents, they are directed to verify their identity via an integrated, trusted third-party or government-backed institution. 2 Third-Party Authentication & Consent The user is seamlessly routed to the external institution's secure portal. They log in and explicitly grant permission for their already-authenticated identity data to be shared for KYC purposes. 3 Secure Data Retrieval Once consent is granted, the system securely connects to the third-party platform. MatchMove automatically extracts the user's verified identity attributes directly from the trusted source. 4 Automated Profile Update Because this external data comes from a trusted institution, it is inherently accepted as KYC-verified data. MatchMove uses this data to automatically populate and update the user's profile, completely eliminating the need for manual data entry or physical document uploads. 5 Risk Profiling & Screening The updated, authenticated profile data is automatically screened against global sanctions lists, PEP databases, and adverse media sources. The Financial Institution then conducts its internal risk profiling based on this trusted data. 6 Verification Complete The final KYC submission is processed in seconds. Approved users proceed immediately, with the final verification decision and approval handled directly by the Financial Institution. All data is securely stored for audit purposes. Individual Authentication-Based User Journey Designing a seamless Authentication-Based KYC journey requires a delicate balance between regulatory rigor and user experience. While the interface is designed to feel entirely frictionless—often requiring just a few clicks for the user to grant access—the engine behind it securely orchestrates and validates data from trusted third-party institutions. The following workflow outlines the standard sequence of screens a user will encounter when linking their previously authenticated data. However, it is important to note that the process remains dynamic; the system adapts in real-time based on the user's: country of residence risk associated with the profile If certain risk triggers are met during the automated screening phase, the journey will automatically scale to include Enhanced Due Diligence (EDD) requirements. This will prompt the user for supplementary documentation or clarifying questions to ensure full compliance, correctly ascertaining if a risk hit is a false positive or if an exemption can be granted. Key Logic of the Journey Frictionless Data Retrieval: Instead of manual document capture, the system securely extracts verified identity attributes directly from the trusted institution to instantly update the user profile. Adaptive UX: The flow dynamically adjusts based on the user's platform eligibility and the specific data points provided by the third-party authenticator. Risk-Based Triggering: Profiles flagged as high-risk during the automated screening will trigger EDD, presenting additional form fields or supplementary document requests that a standard-risk user will entirely bypass. Third-Party KYC Entry QR Authentication; or Password Authentication Data Access Consent Add description here Data Sharing Review Add description here Data Sharing Review Add description here Data Sharing Review Add description here Data Collection Add description here Risk Evaluation and Approval Add description here AML Screening & Ongoing Monitoring Protect your business with continuous compliance monitoring that runs automatically in the background—built right into your existing workflows. Global Watchlist Screening Automated checks against OFAC, UN, EU, HMT sanctions lists, and more PEP Detection Identify Politically Exposed Persons across all jurisdictions Adverse Media Monitoring AI-powered scanning for negative news coverage Ongoing Monitoring Continuous re-screening alerts you to any status changes Risk Scoring Dynamic assessment based on multiple configurable risk factors Security & Compliance The KYC service verification infrastructure meets the highest security standards, including SOC 2 Type II certification and GDPR compliance. All verification data is encrypted end-to-end and processed in accordance with global data protection regulations. KYC and Individual User State Transition As users navigate the KYC process, their account statuses dynamically update to reflect their current stage in the onboarding journey. This guide details every user state transition, providing you with a clear roadmap of what each status means and the specific actions required to move users forward. Familiarize yourself with these transitions to ensure seamless user activation and responsive account management. Individual eKYC Workflow Profile Completion : Once the user completes their profile, their user.status updates to pending_activation and their user.kyc_status updates to pending . To activate the account, the user must now undergo eKYC. KYC Submission : Upon eKYC submission, the user.kyc_status transitions to in_progress . This automatically triggers the KYC evaluation process. Evaluation Completion : Once the evaluation concludes, the user.kyc_status updates to completed . Evaluation Results : Based on the review, the user.kyc_sub_status will be marked as either approved or rejected . If Rejected: Prompt the user to correct the specified rejection reasons and resubmit their eKYC application. If Approved: This triggers the platform-initiated User Activation process. The user is now granted access to the platform's financial assets and capabilities. Ongoing Monitoring : A periodic risk evaluation occurs throughout the lifetime of the user's account. Based on these evaluations, the user.status can be updated to suspended (a reversible action) or terminated (an irreversible action). Account Reactivation : If an account is suspended, the partner can initiate a reactivation process once the underlying suspension reason has been fully resolved. KYC and Individual User State Transition Updates Because KYC evaluation is an asynchronous process, all status updates are delivered securely via the USER.STATUS (Individual) and ASSOCIATED_PARTIES.PROFILE.STATUS (Individual - Associated Parties) webhooks. Each webhook payload provides the real-time user and KYC states to keep your system in sync. You must monitor these incoming updates and trigger the appropriate next steps or follow-up actions based on the specific states returned. Verification State Transitions Please note that the state progression of a KYC application depends on the chosen verification method: Document-Based Verification: The application may transition through states 1 to 21 , depending on your specific onboarding requirements and the user's calculated risk profile. Authentication-Based Verification: The application may skip states 1 through 8 . Because physical documents are not required for this method, data and profile verification are collected directly from a trusted third-party verification system. The third-party system then hands the data back to our system to conduct the final risk profiling. KYC Status KYC Sub-status User Status User Sub-status Individual User(I) / Partner(P) Action 1. pending pending_document_submission pending_activation information_verification_inprogress [I] Complete the profile questionnaire. 2. pending pending_document_submission pending_activation information_collection_completed No action required. 3. pending pending_document_submission pending_activation poi_verification_inprogress [I] Upload POI requirement. 4. pending pending_document_submission pending_activation poi_collection_completed No action required. 5. pending pending_document_submission pending_activation poa_verification_inprogress [I] Upload POA requirement. 6. pending pending_document_submission pending_activation poa_collection_completed No action required. 7. pending pending_document_submission pending_activation selfie_verification_inprogress [I] Undergo liveliness detection. 8. pending pending_document_submission pending_activation selfie_collection_completed No action required. 9. pending pending_document_submission pending_activation aml_verification_inprogress No action required. 10. pending pending_document_submission pending_activation edd_questionnaire_data_verification_inprogress [I] EDD activated — complete the EDD questionnaire. 11. pending pending_document_submission pending_activation edd_questionnaire_data_collection_completed No action required. 12. pending pending_document_submission pending_activation pep_questionnaire_data_verification_inprogress [I] EDD activated — complete the PEP questionnaire. 13. pending pending_document_submission pending_activation pep_questionnaire_data_collection_completed No action required. 14. pending pending_document_submission pending_activation sanction_questionnaire_data_verification_inprogress [I] EDD activated — complete the sanction questionnaire. 15. pending pending_document_submission pending_activation sanction_questionnaire_data_collection_completed No action required. 16. pending pending_document_submission pending_activation aml_questionnaire_data_verification_inprogress [I] EDD activated — complete the AML questionnaire. 17. pending pending_document_submission pending_activation aml_questionnaire_data_collection_completed No action required. 18. in_progress waiting_for_approval pending_activation internal_review_inprogress Waiting for manual MatchMove Compliance approval. No action required. 19. completed approved pending_activation active The user has been activated. [P] Proceed with financial asset provisioning for the user. 20. completed rejected pending_activation document_verification_failed The KYC submission has been rejected due to invalid documents. This webhook will immediately be followed by scenario 21 enabling the user to resubmit the rejected document again. [I] If the user is still inside the KYC capture screen, the user can resolve the rejection by uploading a valid document. [P] No action required, because the KYC capture screen is still open, and the user still has an option to resolve it. 21. pending pending_document_submission pending_activation document_verification_failed The KYC document submitted by the user has been rejected. [I] If the user decides to terminate the KYC capture session (in scenario 20), he can return back to the KYC capture screen by requesting a new link from the partner app. Once back to the KYC capture screen, he can resolve the pending document requirements by uploading valid documents. [P] Allow users to request a new KYC capture link to allow them to resume his session and resolve the pending document requirements. 22. completed rejected pending_activation terminated_for_risk The user has been terminated as a result of KYC and risk evaluation. [P] Notify the user regarding the termination. KYC Rejection Reasons - Individuals This section provides an exhaustive list of all the individual KYC rejection reasons and their corresponding descriptions that are available on the platform. Rejection Reasons (Individuals) Description ADDRESS_MISMATCH Address does not match the proof of address. AGE_BELOW_MINIMUM User is below the minimum age allowed. AGE_EXCEEDS_MAX_LIMIT User is above the maximum age allowed. BLACKLISTED_PROFILE_INFO Profile details match a blacklist or sanctions entry. COUNTRY_MISMATCH Country on the document does not match the country declared. DOB_MISMATCH Date of birth does not match the document. DOCUMENT_AUTHENTICITY The document shows signs of tampering or forgery. DOCUMENT_DEMOGRAPHIC_MATCH Demographic details on the document do not match the profile. DOCUMENT_EXPIRED The document is past its validity date. DOCUMENT_EXPIRING_SOON The document expires within the minimum validity period required. DOCUMENT_ID_REJECTED The identity document submitted was not accepted. DOCUMENT_IMAGE_QUALITY_ISSUE The document image is unreadable. DOCUMENT_ISSUING_COUNTRY_NOT_SUPPORTED The issuing country of the document is not supported. DOCUMENT_LANGUAGE_NOT_SUPPORTED The document language is not supported. DOCUMENT_MISSING A required document was not submitted. DOCUMENT_NOT_RECENT_ENOUGH The document is older than the maximum age allowed. DOCUMENT_POA_REJECTED The proof of address submitted was rejected. DOCUMENT_QUALITY Document quality is too poor to process. DOCUMENT_SELFIE_REJECTED The selfie is unusable or does not match the document photo. DOCUMENT_SIGNATURE_REJECTED The signature on the document was rejected. DOCUMENT_TYPE_MISMATCH Document type submitted differs from the type required. DOCUMENT_VIDEO_REJECTED The verification video submitted was rejected. DUPLICATE_DETAILS The details submitted match an existing profile. EXPIRED_DOCUMENTS One or more of the documents submitted have expired. GENDER_MISMATCH Gender does not match the document. INFORMATION_INCOMPLETE Mandatory information is missing or incomplete. INFORMATION_MISMATCH Application information does not match the verification source. INVALID_PROFILE_INFO Profile information is invalid or in an unaccepted format. LIVELINESS_AUTHENTICATION The liveness check could not be completed successfully. LIVENESS_VERIFICATION_FAILED The user did not pass the liveness check. MISMATCH_PROFILE_DETAILS Profile details do not match the document. MISMATCH_PROFILE_NAME Profile name does not match the name on the document. NAME_MISMATCH Name on the document does not match the application. OTHERS Non-standard rejection. Contact compliance for further instruction. REGION_NOT_SUPPORTED The user's region is not serviceable under this program. REJECTED Know Your Customer (KYC) not approved. REJECTION_REQUESTED The applicant asked to withdraw the application. SUSPECT_PROFILE The profile is flagged for fraud or risk indicators. UNSUPPORTED_DOCUMENTS The document type is not accepted for this program. Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Region-specific onboarding Business users • [[SG] Document-based verification](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-document-based-verification.md): Learn how to initiate and execute the identity verification workflow for individual account holders. This guide walks you through the steps to submit user data and facilitate the validation process within the system. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to submit the required KYC documents needed to verify the identity of an individual user. You want to submit supporting documents that will help in the individual user identity verification. You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove eKYC Provider. You want to implement a feature in your application that will allow individual users to upload supporting documents using the available MatchMove KYC endpoints. The individual user will submit KYC by going through the automated eKYC interface to collect selfies and identification documents. The individual user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism. Prerequisites The individual user profile must already be completed. Refer to the Register individual profile (v2) section for more details. The individual user profile must be in status = pending_activation . The individual user profile has a kyc_status = not_submitted , indicating that they have not attempted to perform KYC yet, or The individual user profile has a kyc_status = pending and a kyc_sub_status = pending_document_submission , indicating that they are still required to submit document, or The individual user profile has a kyc_status = completed and a kyc_sub_status = rejected , indicating that their previous submission was rejected. API Workflow 1 Check if an individual user is allowed to submit KYC Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface. A user can only send a KYC submission for verification if they have the following: User Status KYC Status Description status = pending_activation kyc_status = not_submitted The User has not yet attempted to submit his KYC status = pending_activation kyc_status = pending kyc_sub_status = pending_document_submission The User has attempted to submit his KYC but is still required to submit other documents. status = pending_activation kyc_status = completed kyc_sub_status = rejected The User has attempted to submit his KYC and has failed on his last submission. Get Individual User Call Get Individual User ( GET /users ) to retrieve the User and KYC status of an individual user. Get Individual User request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Individual User response JSON { .. "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", .. } 2 [Optional] Check if user is eligible for document-based verification By default, document-based verification is automatically enabled for all programs. You only need to call this API to check for other eligible methods if you have explicitly enabled additional verification options (such as authentication-based verification or partner-assisted verification) in your program configuration. List KYC Verification Modes Call Get KYC Verification Modes ( GET /v2/users/authentications/documents/verification_modes ) to get all available verification modes available for the program and applicable to the user. List KYC Verification Modes request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verification_modes' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List KYC Verification Modes response JSON { "verification_modes": [ { "mode": "document_based" }, { "mode": "authentication_based" } ] } The response will list all the verification modes that the user is eligible to undergo. If document_based is listed, then you can start to initiate the verification by requesting a KYC verification link. 3 Retrieve the eKYC redirect link to the document collection screen The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents. Initiate KYC Capture (Individual User) Call Initiate KYC Capture (Individual User) ( POST /users/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Individual User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Individual User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "individual", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } The Initiate KYC Capture (Individual User) API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the customer can perform the KYC document capture and submit the KYC application. The eKYC verification is asynchronous ; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take from an instant to a few minutes, provided that all document submissions are clear and legible and the partner profile aligns perfectly with the document data. 4 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action USER.STATUS User and KYC Status Update A notification is sent in the event that the User or KYC status of the business user gets updated. Handle User and KYC status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. ASSOCIATED_PARTIES.PROFILE.STATUS Associated Party KYC Status Update A notification is sent in the event that the associated parties' statuses of the business user get updated. Handle Associated Party (Individual) status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. USER.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.STATUS for User and KYC updates . KYC Document Verification Update A notification is sent in the event that the KYC status of the business user is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. ASSOCIATED_PARTY.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook ASSOCIATED_PARTIES.PROFILE.STATUS for Associated Party KYC updates KYC Document Verification Update - Associated Party A notification is sent in the event that the KYC status of the associated party is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the associated party to retry or redo another round of KYC submission. USER.STATUS (Approved) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:09:48Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2030-02-12", "id_date_issued": "2025-06-08", "id_issuance_country": "Spain", "id_number": "02345678A", "id_type": "Id Card", "metadata": "{\"mrzLine1\":\"IDESPAAA023456789026070A\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\",\"mrzLine2\":\"3456789M5678901234\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c0\",\"mrzLine3\":\"CITIZEN\\u003cSMITH\\u003c\\u003cAGUEDA\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\"}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:09:47Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "CLEARED", "risk_evaluation_date": "2026-08-12T20:09:48Z", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2027-06-28", "id_date_issued": "2021-06-19", "id_issuance_country": "Germany", "id_number": "L02M000CH8", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2030-03-14 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:09:48+0800", "message_id": "dc6ca6ce-a592-44c5-9cba-10094d5016e5", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } U SER.STATUS (Rejected) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:07:16Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2060-04-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Germany", "id_number": "Testerqnq23132", "id_type": "Id Card", "metadata": "{}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:07:16Z", "kyc_status": "not_submitted", "kyc_sub_status": "pending_document_submission", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } } }, "residency_country": "Philippines", "risk_assesment_status": "PENDING", "risk_evaluation_date": null, "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2030-02-12", "id_issuance_country": "Spain", "id_number": "ААА02345678A", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-09-11 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "pending", "sub_status": "", "sub_status_code": "", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:07:18+0800", "message_id": "11331635-226b-4485-b1a1-55b6f383a611", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } 5 [Optional] Access individual users' KYC documents All of the documents submitted by the individual user during eKYC will be accessible for the partner for audit purposes. List KYC Documents Call List KYC Documents ( GET /users/authentications/documents ) to retrieve the list of documents submitted by the user during KYC, along with the download links for each document. The response of this endpoint will contain details regarding the uploaded file, including but not limited to: file_type - describes the type or category of the document that was uploaded, e.g., ID . document_type - describes what document under a certain file type was uploaded, e.g., selfie . link - the downloadable permalink to the uploaded document date.created - the timestamp of the document upload List KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' List KYC Documents response JSON { "verification_id": "vfc_487e7b22e4ed4263x576843389373f22", "status": "completed", "sub_status": "approved", "sub_status_code": "APPROVED", "sub_status_description": "Full KYC Verified", "documents": [ { "provider_document_id": "494631728", "type": "ID", "document_id": "", "file_type": "ID", "document_type": "Primary ID Document", "kyc_type": "", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIXULCJ8u2hM62lzOehXWGEYf.jpg", "id": "3FAIXULCJ8u2hM62lzOefXWDEYf", "status": "uploaded", "date": { "created": "2026-06-15T16:18:06+08:00" } }, { "provider_document_id": "639470662", "type": "ID", "document_id": "", "file_type": "ID", "document_type": "selfie", "kyc_type": "", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIsd5577h8xgrwmqiqotHT1Ra.jpg", "id": "3FAIXd5577h8x4rwmqiqotHT1Ra", "status": "uploaded", "date": { "created": "2026-06-15T16:18:08+08:00" } } ], "count": 2, "metadata": {} } *To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users [v2] Submit customer KYC Region-specific onboarding Business users • [[SG] Authentication-based verification](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-authentication-based-verification.md): Explore the steps required to submit information for an authentication-based individual user identity verification. This document provides a clear overview of the specific Know Your Customer (KYC) requirements tied to this verification mode. Use this guide to easily navigate the requirements and complete the authentication-based verification process. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to do authentication-based verification using SG MyInfo integration. Prerequisites The individual user profile must be created. Refer to the Register customer profile (v2) section for more details. The user profile must have identification details such as identification.primary.id_type and identification.primary.id_issuance_country fields. These will be used to check whether the user is eligible for authentication-based verification. API Workflow 1 Check if an individual user is allowed to submit KYC Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface. A user can only send a KYC submission for verification if they have the following: User Status KYC Status Description status = pending_activation kyc_status = not_submitted The User has not yet attempted to submit his KYC status = pending_activation kyc_status = pending kyc_sub_status = pending_document_submission The User has attempted to submit his KYC but is still required to submit other documents. status = pending_activation kyc_status = completed kyc_sub_status = rejected The User has attempted to submit his KYC and has failed on his last submission. Get Individual User Call Get Individual User ( GET /users ) to retrieve the User and KYC status of an individual user. Get Individual User request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Individual User response JSON { .. "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", .. } 2 Check if user is eligible for authentication-based verification List KYC Verification Modes Call Get KYC Verification Modes ( GET /v2/users/authentications/documents/verification_modes ) to get all available verification modes available for the program and applicable to the user. List KYC Verification Modes request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verification_modes' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List KYC Verification Modes response JSON { "verification_modes": [ { "mode": "document_based" }, { "mode": "authentication_based" } ] } The response will list all the verification modes that the user is eligible to undergo. If authentication_based is listed, then you can start to initiate the verification by requesting a KYC verification link. 3 Retrieve the eKYC redirect link to the document collection screen The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents. Initiate KYC Capture (Individual User) Call Initiate KYC Capture (Individual User) ( POST /users/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Individual User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"authentication_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Individual User) success response - user is eligible JSON { "created_date": "2026-09-11T11:22:33+0800", "id": "{{user_id}}", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1dac9fdf956071daa9bd429c950265894269b7ab067a3f3156b4f6bace75d4565445192c48db9125940f6559957eafa0198c4d7fd3da2538e01878d1eaeb8a4ec2680ad50d9bbab826881a28a41046a8f71a0656d6fd84cf8c03cad4bdd9cf04e53bd0fc0c862940bb5f8495ccbe256ab25d74b1925f913c44c339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7721ab755e5908ccf4d60bc0eb5ab519528519ed8f2d2c48463b5aa7506391d635b8e26f739e4e5030c968a69284476608b2833f097b4106a79130fbade896811970bdaa17fd246cf345e5e1b67e0eef8f0f7268f32f025e3b150de020fedb917d02552a178cf2ae8eaa474696c7694670285433175d9dd844de4de81ff951&request_id=c2dtbWRseXQ6Mzg4YWFjZGQ3OTBjNDFjYjkyMGE4MzM1N2U0OWQxNTE6dXNlcg==&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "requirements": null, "sub_type": "individual", "type": "users", "verification_id": "vfc_038db44607174a8182bd0f85201528e5", "verification_mode": "authentication_based" } Initiate KYC Capture (Individual User) failure response - user is not eligible JSON { "id": "0c6577dc-58d5-4daa-989a-5668b08d57b7", "status": "user_eligibility_failed", "code": 422, "title": "User Eligibility Failed", "description": "Requested verification mode is not allowed for the user", "link": "https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_eligibility_failed", "timestamp": "16/Jul/2026:08:33:01 +0000 UTC" } The Initiate KYC Capture (Individual User) API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the user can authenticate via the trusted third-party platform to grant access to their verified data and complete the KYC submission The eKYC verification is asynchronous ; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take from an instant to a few minutes, provided that all document submissions are clear and legible and the partner profile aligns perfectly with the document data. 4 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action USER.STATUS User and KYC Status Update A notification is sent in the event that the User or KYC status of the business user gets updated. Handle User and KYC status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. ASSOCIATED_PARTIES.PROFILE.STATUS Associated Party KYC Status Update A notification is sent in the event that the associated parties' statuses of the business user get updated. Handle Associated Party (Individual) status changes as outlined in the Business eKYC - KYC and Business User State Transition Updates section. USER.STATUS (Approved) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:09:48Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2030-02-12", "id_date_issued": "2025-06-08", "id_issuance_country": "Spain", "id_number": "02345678A", "id_type": "Id Card", "metadata": "{\"mrzLine1\":\"IDESPAAA023456789026070A\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\",\"mrzLine2\":\"3456789M5678901234\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c0\",\"mrzLine3\":\"CITIZEN\\u003cSMITH\\u003c\\u003cAGUEDA\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\"}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:09:47Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "CLEARED", "risk_evaluation_date": "2026-08-12T20:09:48Z", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2027-06-28", "id_date_issued": "2021-06-19", "id_issuance_country": "Germany", "id_number": "L02M000CH8", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2030-03-14 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:09:48+0800", "message_id": "dc6ca6ce-a592-44c5-9cba-10094d5016e5", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } U SER.STATUS (Rejected) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:07:16Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2060-04-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Germany", "id_number": "Testerqnq23132", "id_type": "Id Card", "metadata": "{}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:07:16Z", "kyc_status": "not_submitted", "kyc_sub_status": "pending_document_submission", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } } }, "residency_country": "Philippines", "risk_assesment_status": "PENDING", "risk_evaluation_date": null, "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2030-02-12", "id_issuance_country": "Spain", "id_number": "ААА02345678A", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-09-11 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "pending", "sub_status": "", "sub_status_code": "", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:07:18+0800", "message_id": "11331635-226b-4485-b1a1-55b6f383a611", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } • [[SG] Partner-assisted verification](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/sg-partner-assisted-verification.md): Understand the identity verification standards and prerequisite configurations required for a split onboarding model. This guide provides a comprehensive overview of the compliance framework and data structures needed for collaborative KYC processes. Maintain strict compliance without slowing down your onboarding flow. From secure document uploads executed on the partner side to automated liveness detection and EDD completed by MatchMove, this tailored suite provides robust identity assurance exactly where you need it—all accessible through a single integration point. Note: Please be aware that this feature is subject to regional availability and compliance approval. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until the regional, compliance approval, and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to submit the required KYC documents needed to verify the identity of an individual user. You want to submit supporting documents that will help in the individual user identity verification. You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove eKYC Provider. You want to implement a feature in your application that will allow individual users to upload supporting documents using the available MatchMove KYC endpoints. The individual user will submit KYC by going through the automated eKYC interface to collect selfies and Enhanced Due Diligence (EDD) documents and information (when required). The individual user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism. Prerequisites The individual user profile must already be completed. Refer to the Register individual profile (v2) section for more details. The individual user profile must be in status = pending_activation . The individual user profile has a kyc_status = not_submitted , indicating that they have not attempted to perform KYC yet, or The individual user profile has a kyc_status = pending and a kyc_sub_status = pending_document_submission , indicating that they are still required to submit document, or The individual user profile has a kyc_status = completed and a kyc_sub_status = rejected , indicating that their previous submission was rejected. API Workflow 1 Check if an individual user is allowed to submit KYC Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface. A user can only send a KYC submission for verification if they have the following: User Status KYC Status Description status = pending_activation kyc_status = not_submitted The User has not yet attempted to submit his KYC status = pending_activation kyc_status = pending kyc_sub_status = pending_document_submission The User has attempted to submit his KYC but is still required to submit other documents. status = pending_activation kyc_status = completed kyc_sub_status = rejected The User has attempted to submit his KYC and has failed on his last submission. Get Individual User Call Get Individual User ( GET /users ) to retrieve the User and KYC status of an individual user. Get Individual User request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Individual User response (status excerpts) JSON { .. "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", .. } 2 [Partner-assisted] Collect and upload proof of identity (POI) document As the initial step in the shared workflow, partners use this feature to securely upload the user's primary identity documents. Once the files are successfully transmitted and attached to the user's profile, MatchMove takes over to execute the required backend compliance checks. Document required for upload: Proof of Identity (POI): Front image of the identification/travel card Back image of the identification/travel card, optional depending on the identity document Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 2MB per file No. of files: maximum 3 files In the live environment , the Proof of Identity (POI) document you upload must match the primary identification defined in the user profile. However, in the staging or UAT environments , the profile and document do not need to match, as the evaluation process is only simulated. Get Individual User response (identification excerpts) JSON .. "identification": { "primary": { "id_issuance_country": "PHL", "id_number": "X321312312", "id_type": "DRIVERS_LICENSE" }, "secondary": {} }, .. Upload KYC Documents Call Upload KYC Documents ( POST /users/authentications/documents ) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload. Upload KYC documents-required field enumerations: document_type allowed values are listed in the List Document Types Enumerations ( GET /users/enumerations/document_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Upload KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --form 'document_type="primary_front_of_id_document"' \ --form 'file=@"/Users/jsmith/Documents/1527530326.png"' Upload KYC Documents response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "pending", "sub_status": "pending_document_submission", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "primary_front_of_id_document" } ], "count": 1, "kyc_details": null } 3 [Conditional] [Partner-assisted] Collect and upload proof of address (POA) and other supporting documents Any supporting documentation provided, such as a proof of address (POA), must be accurately reflected within the user profile. This step is crucial, as the profile information is cross-referenced with the uploaded KYC documents during the verification process. Document required for upload: Proof of address (POA), when the current residential address of the user is not in the POI document . Failure to ensure that the POI document contains the user address or a POA document is uploaded will invoke the POA upload workflow on the eKYC capture screens (on step 4). Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 2MB per file No. of files: maximum 3 files Since supporting documents such as a Proof of Address (POA) are not mandatory by default, you must define this new document in the user profile's supporting_documents object prior to upload. This critical step ensures the system knows to include the supporting documents in its KYC evaluation. Please note the differing requirements based on your environment: Live Environment: The uploaded POA and other supporting document must strictly match the details defined in the user profile's supporting document object. Staging/UAT Environment: The supporting document in the profile and document do not need to match, as document evaluation is simulated in these environments. Update Individual Users Call the Update Individual Users ( PUT /users ) to update the supporting documents object with the supporting documents such as POA. Upload Individual Users field enumerations: supporting_documents.id_type allowed values are listed in the List Supporting ID Type Enumerations ( GET /users/enumerations/supporting_documents_id_types ). For POA documents, the following ID types are supported: UTILITY_BILL UTILITY_BILL2 AGREEMENT CONTRACT VEHICLE_REGISTRATION_CERTIFICATE PAYMENT_SOURCE ARBITRARY_DOC OTHER supporting_documents.id_issuance_country allowed values are listed in the List Issuance Country Enumerations ( GET /users/enumerations/id_issuance_countries ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Update Individual Users request CURL curl --location --request PUT 'https://api-sg-identity.matchmove-beta.com/sgmktgrd/v2/users/e0862ab9b3a84ea99644f00bad9192ab' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "supporting_documents": [ { "id_type": "UTILITY_BILL", "id_issuance_country": "SGP" } ] } Update Individual User response (supporting_documents excerpts) JSON .. "supporting_documents": [ { "id_type": "Utility Bill", "id_issuance_country": "Singapore" } ], .. Once the supporting document has been properly defined in the user profile, you may proceed to upload the physical file. This ensures the document is correctly linked and ready for the KYC evaluation process. Upload KYC Documents Call Upload KYC Documents ( POST /users/authentications/documents ) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload. Upload KYC documents-required field enumerations: document_type allowed values are listed in the List Document Types Enumerations ( GET /users/enumerations/document_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Upload KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --form 'document_type="utility_bill"' \ --form 'file=@"/Users/mm-john/Downloads/312312520326.png"' Upload KYC Documents response JSON { "verification_id": "vfc_4852f08291c2495f87d2f04575dd8441", "status": "pending", "sub_status": "pending_document_submission", "documents": [ { "date": { "created": "2025-09-29T12:01:38+0800" }, "id": "33MENFBXQB6BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/33MENFBXQB6BPzEeBTMGul5yk5U.png", "provider_document_id": "", "status": "uploaded", "type": "primary_front_of_id_document" }, { "date": { "created": "2025-10-29T12:01:38+0800" }, "id": "33MENFBXQ123BPzEeBTMGul5yk5U", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/id/download/88MENFBXQB6BPzEeBTMGul5yk1r.png", "provider_document_id": "", "status": "uploaded", "type": "utility_bill" } ], "count": 2, "kyc_details": null } 4 Retrieve the eKYC redirect link to the document collection screen Calling the Initiate KYC Capture API will generate the eKYC capture link and will mark the transition from the partner-assisted workflow to the automated KYC workflow. To proceed, partners must render the standalone eKYC web app using an in-app or external web browser. Within these secure capture screens, the customer will: Perform the required liveness detection. Upload a Proof of Address (POA) when their current address is not included in their Proof of Identity (POI) or when no POA is uploaded. Submit any additional information or documents if flagged for Enhanced Due Diligence (EDD). Note: Because of this handover, all subsequent document changes or uploads must be made directly via the eKYC capture interface only rather than through the Upload KYC Documents API. Initiate KYC Capture (Individual User) Call Initiate KYC Capture (Individual User) ( POST /users/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Individual User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Individual User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "individual", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } The Initiate KYC Capture API (Individual) response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the customer can perform the KYC document capture and submit the KYC application. The eKYC verification is asynchronous ; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take from an instant to a few minutes, provided that all document submissions are clear and legible and the partner profile aligns perfectly with the document data. 5 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action USER.STATUS User and KYC Status Update A notification is sent in the event that the User or KYC status of the business user gets updated. Handle User and KYC status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. ASSOCIATED_PARTIES.PROFILE.STATUS Associated Party KYC Status Update A notification is sent in the event that the associated parties' statuses of the business user get updated. Handle Associated Party (Individual) status changes as outlined in the Business eKYC - KYC and Business User State Transition Updates section. USER.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.STATUS for User and KYC updates . KYC Document Verification Update A notification is sent in the event that the KYC status of the business user is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. ASSOCIATED_PARTY.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook ASSOCIATED_PARTIES.PROFILE.STATUS for Associated Party KYC updates KYC Document Verification Update - Associated Party A notification is sent in the event that the KYC status of the associated party is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the associated party to retry or redo another round of KYC submission. USER.STATUS (Approved) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:09:48Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2030-02-12", "id_date_issued": "2025-06-08", "id_issuance_country": "Spain", "id_number": "02345678A", "id_type": "Id Card", "metadata": "{\"mrzLine1\":\"IDESPAAA023456789026070A\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\",\"mrzLine2\":\"3456789M5678901234\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c0\",\"mrzLine3\":\"CITIZEN\\u003cSMITH\\u003c\\u003cAGUEDA\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\"}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:09:47Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "CLEARED", "risk_evaluation_date": "2026-08-12T20:09:48Z", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2027-06-28", "id_date_issued": "2021-06-19", "id_issuance_country": "Germany", "id_number": "L02M000CH8", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2030-03-14 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:09:48+0800", "message_id": "dc6ca6ce-a592-44c5-9cba-10094d5016e5", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } U SER.STATUS (Rejected) sample webhook payload ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:07:16Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2060-04-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Germany", "id_number": "Testerqnq23132", "id_type": "Id Card", "metadata": "{}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:07:16Z", "kyc_status": "not_submitted", "kyc_sub_status": "pending_document_submission", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } } }, "residency_country": "Philippines", "risk_assesment_status": "PENDING", "risk_evaluation_date": null, "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2030-02-12", "id_issuance_country": "Spain", "id_number": "ААА02345678A", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-09-11 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "pending", "sub_status": "", "sub_status_code": "", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:07:18+0800", "message_id": "11331635-226b-4485-b1a1-55b6f383a611", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } 6 [Optional] Access individual users' KYC documents All of the documents submitted by the individual user during eKYC will be accessible for the partner for audit purposes. Get KYC Documents Call Get KYC Documents ( GET /users/authentications/documents ) to retrieve the list of documents submitted by the user during KYC, along with the download links for each document. The response of this endpoint will contain details regarding the uploaded file, including but not limited to: file_type - describes the type or category of the document that was uploaded, e.g., ID . document_type - describes what document under a certain file type was uploaded, e.g., selfie . link - the downloadable permalink to the uploaded document date.created - the timestamp of the document upload Get KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' Get KYC Documents response JSON { "verification_id": "vfc_487e7b22e4ed4263x576843389373f22", "status": "completed", "sub_status": "approved", "sub_status_code": "APPROVED", "sub_status_description": "Full KYC Verified", "documents": [ { "provider_document_id": "494631728", "type": "ID", "document_id": "", "file_type": "ID", "document_type": "Primary ID Document", "kyc_type": "", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIXULCJ8u2hM62lzOehXWGEYf.jpg", "id": "3FAIXULCJ8u2hM62lzOefXWDEYf", "status": "uploaded", "date": { "created": "2026-06-15T16:18:06+08:00" } }, { "provider_document_id": "639470662", "type": "ID", "document_id": "", "file_type": "ID", "document_type": "selfie", "kyc_type": "", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIsd5577h8xgrwmqiqotHT1Ra.jpg", "id": "3FAIXd5577h8x4rwmqiqotHT1Ra", "status": "uploaded", "date": { "created": "2026-06-15T16:18:08+08:00" } } ], "count": 2, "metadata": {} } *To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links. • [Simulate individual eKYC approvals](https://developer.matchmove.com/matchmove-banking-operating-system/individual-users/onboard-individual-user-v2/individual-ekyc/simulate-ekyc-approvals.md): Learn how to trigger specific eKYC statuses by submitting predetermined test data during the verification process. This guide helps you understand the end-to-end user journey for individual eKYC approvals and rejections in the staging environment. Note: This simulation guide applies exclusively to [SG] Partner-assisted KYC and [SG] Document-based Verification. Because [SG] Authentication-based verification relies on live third-party data retrieval, it does not use these document simulation steps. These procedures are unsupported in Production and should only be performed in UAT or Staging . Use Cases: You need to simulate an individual eKYC approval to test the success scenarios of your onboarding process. You need to simulate an individual eKYC rejection to test the negative scenarios of your onboarding process. Prerequisites: You must already have a registered individual user that is ready to perform eKYC. Refer to the Perform individual eKYC section to learn about the specific required KYC criteria. Approval Simulation Workflow 1 Generate a KYC capture link for the individual user Simulating a KYC approval requires you to undergo the eKYC process. Render the eKYC capture link in any web/mobile browser that you want to conduct your test on. Initiate KYC Capture (Individual User) Call Initiate KYC Capture (Individual User) ( POST /users/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Individual User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Individual User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "individual", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } 2 Perform the eKYC process and submit pre-approved documents On the eKYC capture screens, you will be first asked to upload an identification document. You will need to upload any of these pre-approved identity documents. These documents should allow you to get an approval , even if the registered user details do not align with the details in the identity documents. You can subscribe to the KYC verification webhooks to be notified of the KYC approval of the individual user. Pre-approved identity documents ID card for China (front) ID card for China (back) ADHAAR for India (front) ADHAAR for India (back) ID card for Germany (front) ID card for Germany (back Passport for Germany Proof of Address (PoA) for Germany Source: https://docs.sumsub.com/docs/verification-document-templates 3 [EDD activated] Onboarding of high-risk users If a user is flagged as "high-risk" (due to location* or profile), the system automatically triggers Enhanced Due Diligence (EDD). This adds extra screens and document requirements to their eKYC journey. Note on Testing: You can use dummy data and documents for EDD requirements during simulation. Please keep in mind that EDD flips the process from automated to manual review. Since MatchMove Compliance must personally vet these submissions in both staging and live environments, approval won't be immediate. In staging and for the purpose of simulation, we have established a 1-day SLA for these specific cases. *Refer to Standard Operating Procedure for Compliance Management document for the list of high-risk and sanctioned regions. 4 [EDD activated] Complete KYC simulation for high-risk users Since EDD requires a manual decision, a Freshdesk ticket is required to request an approval from the compliance team and complete the simulation process. Please ensure you provide the following details in your ticket request: User ID Program Code Action required: APPROVE KYC Rejection Simulation Workflow 1 Generate a KYC capture link for the user Simulating a KYC approval requires you to undergo the eKYC process. Render the eKYC capture link in any web/mobile browser that you want to conduct your test on. Initiate KYC Capture (Individual User) Call Initiate KYC Capture (Individual User) ( POST /users/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Individual User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Individual User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "individual", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } 2 Perform the eKYC process and submit pre-rejected documents On the eKYC capture screens, you will be first asked to upload an identification document. You will need to upload any of these pre-rejected identity documents. Submitting any or all these documents will guarantee rejection every time they are uploaded for a KYC submission. You can subscribe to the KYC verification webhooks to be notified of the KYC document rejections of the individual user. eKYC Rejection Workflow For document-based verification, the documents uploaded in the eKYC capture screen will be subjected to the automated verification as soon as they are uploaded. For partner-assisted verification, documents uploaded via the Create KYC documents API will be subjected to the automated verification as soon as the eKYC capture screen is loaded. Since verification is done on-the-fly, the verification results, such as rejections and approvals, will also be given immediately (even if the user is still inside the eKYC capture screen). When the verification results determine that the POI , or POA, or any other documents are invalid , the following will happen (in exact sequence): The platform will send a rejection webhook, notifying that a submitted document was rejected. This rejection webhook will have the following details: user.kyc_status = completed user.kyc_sub_status = rejected user.status = pending_activation user.sub_status = document_verification_failed To allow the user to resubmit while still inside the eKYC capture screen, the platform will update the KYC status and send a user update webhook with the following details: user.kyc_status = pending user.kyc_sub_status = pending_document_submission user.status = pending_activation user.sub_status = document_verification_failed If the user is still in the eKYC capture screen, he will be presented with the document resubmission screen again to resolve the document requirement. If the user has already terminated the eKYC session, he should be able to request a new eKYC capture link from the partner app and resume the resubmission. Refer to KYC and Individual User State Transition Updates for more details on the sequence of events and required actions in the KYC workflow. By flagging rejected documents right away, users can upload their corrections on the spot without waiting for another round of background checks. This proactive approach also minimizes the likelihood of a user submitting valid documents, only to discover a rejection later in the process. Pre-rejected identity documents Choose the rejection scenario that you want to simulate: Rejected - Standard (No EDD) --> Document rejection and resubmission allowed National ID card for ESP (front) National ID card for ESP (back) Proof of Address (PoA) for Germany Rejected - Standard (no EDD) - Prohibited Residency (US POA) --> Document rejection and with no resubmission allowed National ID card for CYP (front) National ID card for ESP (back) Proof of Address (PoA) for USA Rejected - EDD - High-Risk Users (Nigeria POI and POA) --> EDD questionnaire and a Freshdesk ticket for rejection required Driver's License ID card for NGA (front) Driver's License ID card for NGA (back) 3 [EDD activated] Complete KYC simulation for high-risk users Additional requirement to complete: Rejected - EDD activated - Compliance rejection simulation scenario Since EDD requires a manual decision, a Freshdesk ticket is required to request a KYC rejection from the compliance team and complete the simulation process. Please ensure you provide the following details in your ticket request: User ID Program Code Action required: REJECT KYC • [Business users](https://developer.matchmove.com/matchmove-banking-operating-system/business-users.md): Onboarding a business involves collecting information about the business using MatchMove APIs. This section describes the various legal entities and natural persons involved in onboarding a business, as well as the information you need to collect. What is a business user A business user refers to individuals or entities representing businesses, organizations, or corporate entities who are onboarded onto the platform to avail payment services on behalf of a business. When you onboard a business, you must collect two different streams of information: Business information: Information about the business's legal entity, including the business name, registration number, tax information, business activities, etc. Person information: Information about all natural persons who run and/or legally represent the business. A business could involve multiple natural persons assigned to different roles. These roles include legal representatives, beneficial owners, signees, and authorized persons. Onboarding a business user Before any account can be issued in the system, a customer record needs to be created. In addition, the requirements the business customer needs to go through will vary depending on the product construct and legal jurisdiction. Work with your Implementation Manager to understand the nuances and have a robust journey tailored to your business. The lifecycle journeys can be listed below: Business record creation with a completed business profile Ongoing name screening and sanction list screening Additional demographic and connected parties information collection Document review and verification process Business record creation Before a payment account can be created or a business relationship can be established with an end customer, the legal business profile and identification must be collected from the customer to create the customer record. Profile and sanction list screening To ensure regulatory compliance, the initial details captured are evaluated for potential presence in the sanction list, adverse media exposure, and politically exposed personalities, in addition to various local blacklists around the region. This is an asynchronous process that takes place post-initial record creation. In addition, after every update or addition to a customer's information, the customer's demographic information is again evaluated to ensure compliance. In addition, the demographic information on record is periodically re-scanned to ensure proper due diligence is performed for all individuals onboarded onto the platform. This activity is also performed when any profile update is performed on the user. Additional demographic and connected parties information collection In preparation for the succeeding customer due diligence activity, as defined by product configurations, additional customer demographic information needs to be provided. When available, information about the connected parties and beneficial owners of the business must be collected as well. This goes in conjunction with the document verification process listed below. Document review and verification process As part of the customer due diligence (CDD) process, the customer is obliged to validate the business profile and demographic information provided. Documents supporting the connected parties and beneficial owners with a material controlling interest in the business will also be required for submission. These documents will be verified by doing a document verification or information retrieval via available government business registries. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Onboard business users Register business profile Submit business KYB Supported KYB documents • [[v2] Onboard business users](https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2.md): Understand the complete onboarding workflow for business users, from profile registration to successful KYC verification. This guide provides a comprehensive overview of the steps needed to activate a business account. Business User onboarding involves the following processes: Business User Registration The process involves capturing the required business user information along with corporate representative data and submitting it to the platform to create a business user profile or user entity that represents the customer. This process runs independently, but its states can be affected by the Risk Evaluation process. It is not affected by any activity in the KYC Verification process. However, its active state is required before the Risk Evaluation and KYC verification processes can be initiated. Risk Evaluation The process where the defined business user profile containing the corporate information is checked against the various local and global financial blacklist and sanctioned personalities, to screen and prevent bad actors from gaining access to the financial capabilities of the platform. This process runs independently, but it requires the User state to be active for it to be initiated. It is not affected by any activity in the KYC Verification process. KYC Verification The process involves uploading the required business KYC documents to the platform. The data presented in these KYC documents should correlate with and verify that the information provided in the business user profile is legitimate and authentic. This process runs independently, but it requires the Business User state to be active for it to be initiated. It is not affected by any activity in the Risk Evaluation process. Figure: User, Risk, and KYC interaction and state diagram The state diagram below illustrates how the Business User Definition, Risk Evaluation, and KYC Verification processes interact and affect one another. Before a business user is granted access to any financial facilities and capabilities within the platform, the USER, RISK, and KYC must be in an approved or green status . These are the states depicted with a GREEN border: Onboarding Process Required Status Description Business User Definition user.status = ACTIVE The business user profile required information is completed Risk Evaluation Risk evaluation is integrated completely into the KYC verification process. No additional risk evaluation status will need to be tracked and handled. The risk evaluation result did not garner any hits on the business user profile when it was checked against all the available blacklists KYC Verification user_kyc.status = APPROVED The submitted KYC documents and data authenticated the legitimacy of the information in the business user profile. Business KYC Verification Business Entities Business user This business entity is a direct user entity under the program owner or the main partner. This business entity can be associated with another business or individual entity as a parent business. These entities can own an account and have access to financial services. e.g. Corporate ABC Note: The creation of business sub-accounts , which allows businesses to have multiple sub-accounts, has been discontinued in v2 Onboarding. On the v2 Onboarding construct, all businesses can only have one account . e.g. Corporate ABC (Main account) Corporate ABC Finance department (Sub-account) Sub-business user This sub-user entity can be a business or an individual that is directly associated as a child of a parent business. These entities can own an account and have access to financial services. e.g. Corporate ABC (Parent) Corporate ABC employee (Child) Business-associated parties An associated party is not a user entity . They cannot own an account and gain access to financial services. They can either be a business or an individual entity type. Associated parties are used to define the directors, stakeholders, and other beneficial owners of a business. These entities are defined in the system to make sure that all parties connected to the business are also verified during customer due diligence. e.g. Corp ABC (business entity) is associated with: John Smith (director) Corp CDE (majority shareholder) Steve Smith (owner) Figure: Business KYC requirement diagram The diagram below illustrates what a business entity requires before being given a KYC approval: The business must pass its own KYC verification . All the associated parties linked to a business must also pass each of their KYC verifications . The sub-business user (child) entity does not affect the KYC of its parent business . The (parent) business user entity will not be able to create a sub-business user (child) unless it gets its KYC verification first . Upgrading to V2 Identity & Onboarding API from V1? Here's a complete step-by-step guide to help you — Identity & Onboarding v2 Upgrade . Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users • [Register business profile](https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/register-business-profile.md): The Register business profile section is designed to streamline the process for businesses to get started on our platform. Users can easily create and manage their business profiles and access essential features to kickstart their operations. Use Cases You want to onboard a business user who is a business or corporate entity, not a natural person. You want to onboard a business user who will use an account for business purposes. You want to onboard a business user who is a sub-entity (sub-account) of the main program partner. You want to onboard a business user who is a corporate client (sub-account) of the main program partner. You want to onboard a business user who is a corporate client sub-entity (client sub-account) of your corporate client (sub-account). You want to onboard a business user (child) who is associated with another business (parent). Prerequisites Before starting to collect business user information from your customers, refer to the User Protection Guidelines , which all platform consumers and partners must follow and adhere to with regard to securing customer data. Collect business information from the corporate customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application. Business User data The data that needs to be collected from the business can be broken down into these groups: Business profile and legal identifiers - Vital identity information is required to create a user in the system. These will include legal business names, representative contacts, and other relevant details. Business demographics details - Additional statistics, foundation, and operational addresses of the business entity. API Workflow (v2) 1 Create a business user profile in the program You can start registering a business profile when the business profile and legal identifiers are ready. Create Business Users (Parent) Call Create Business Users ( POST /businesses ) to create a business profile for the corporate entity that you are onboarding. Business user registration Create Business Users (Parent) - Providing minimum required information Minimum required business information Collecting minimum information from the business during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the business onboarding, we can also reduce the form fields being built on the frontend to collect business information. Instead, we can then just allow the business to provide all the required information and documents during the eKYC information collection screens. For businesses, the minimum required business information is the following: preferred_name company_name email mobile_country_code mobile Create Business Users (Parent) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "preferred_name": "Corp ABC", "company_name": "Corporate ABC", "email": "abc@corporateabc.com", "mobile_country_code": "65", "mobile": "99919997" }' Create Business Users (Parent) response JSON { "id": "be9db48068c4455782067426fdccd90b", "type": "business", "client_ref_id": "9234567", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate ABC", "email": "admin@corporateabc.com", "mobile_country_code": "65", "mobile": "99999991", "business_id": "", "identification": { "primary": { "id_number": "M1417112", "id_type": "Directors Registry", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "101", "line_2": "Kitcheners Rd", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "101", "line_2": "Kitcheners Rd", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "Debt", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_verification_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:15:44Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate ABC", "foundation_date": "2021-01-02", "role": "Platform User", "alternative_names": [ "ABC" ], "lei_code": "ncmxn1c1", "website": "www.corporateabc.com", "supporting_documents": [ { "id_number": "M41wewewe1", "id_type": "Proof of Nature of Business", "id_sub_type": "abc", "id_issuance_country": "Denmark", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": true, "is_expiry_extended": true } ] } Create Business Users (Parent) - Providing complete user information Region-specific Onboarding The example below displays the exhaustive set of user information fields that can be passed through the Create Business Users endpoint. However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ. Partners are encouraged to refer to the Region-specific Onboarding section to see the list of business information required for their program region. Only the listed region-specific business information is required to be collected from the users and submitted for business registration. Create Business Users (Parent) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "9234567", "provider_action_id": "1g172h21j19", "preferred_name": "Corporate ABC", "company_name": "Corporate ABC", "role": "PLATFORM_USER", "lei_code": "ncmxn1c1", "website": "www.corporateabc.com", "alternative_names": [ "ABC" ], "email": "admin@corporateabc.com", "mobile_country_code": "65", "mobile": "99999991", "foundation_date": "2021-01-02", "supporting_documents": [ { "id_number": "M41wewewe1", "id_type": "PROOF_OF_NATURE_OF_BUSINESS", "id_issuance_country": "DNK", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": true, "is_expiry_extended": true } ], "identification": { "primary": { "id_number": "M1417112", "id_type": "DIRECTORS_REGISTRY", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "AFG" } }, "addresses": { "foundation": { "line_1": "101", "line_2": "Kitcheners Rd", "line_3": "", "line_4": "", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "country": "PHL", "postal_code": "2200" }, "operational": { "line_1": "101", "line_2": "Kitcheners Rd", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "state": "Cavite", "country": "PHL", "postal_code": "4107" } }, "socioprofessional_category": "string", "purpose_of_account_opening": "CASH_DEPOSIT", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "source_of_funds": "DEBT", "data_terms_signed_at": "2022-06-15 00:00:00", "created_by": "bot@matchmove.com" } }' Create Business Users (Parent) response JSON { "id": "be9db48068c4455782067426fdccd90b", "type": "business", "client_ref_id": "9234567", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate ABC", "email": "admin@corporateabc.com", "mobile_country_code": "65", "mobile": "99999991", "business_id": "", "identification": { "primary": { "id_number": "M1417112", "id_type": "Directors Registry", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "101", "line_2": "Kitcheners Rd", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "101", "line_2": "Kitcheners Rd", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "Debt", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_verification_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:15:44Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate ABC", "foundation_date": "2021-01-02", "role": "Platform User", "alternative_names": [ "ABC" ], "lei_code": "ncmxn1c1", "website": "www.corporateabc.com", "supporting_documents": [ { "id_number": "M41wewewe1", "id_type": "Proof of Nature of Business", "id_sub_type": "abc", "id_issuance_country": "Denmark", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": true, "is_expiry_extended": true } ] } Business Hierarchical Structure When onboarding business users are enabled in your program, there will be an alternative way to create business users who need to be associated with a business user entity. Businesses often organize themselves into layers, where smaller branches or subsidiaries are distinct entities but still belong to the main parent company. Individual employees, on the other hand, are organized directly under their departments or employers. Financial flows follow this same path, where the parent company allocates capital downward for operations, and the revenue generated by these employees flows back up through their branch to the main entity. MatchMove Banking API is designed to cater to various business structure nuances. You should be able to create parent-child relationships and maintain hierarchical structures with individual and business entities. In a B2B2C model, where (refer to Figure 1): Business A is directly under the main partner (the default parent); therefore, it can be defined using the Create Business User API . Similarly, in a B2B2B model, where: Business B (PARENT) is defined using Create Business User API. Business BA (CHILD) can be associated with Business B (PARENT) by defining it using the Create (Sub-business) Business User API. Figure 1: Business Hierarchical Models Create (Sub-business) Business Users Call Create (Sub-business) Business Users ( POST /businesses/{{parent_business_id}}/businesses ) to create a business profile and associate it with a parent business. (Sub-business) Business Users registration Create (Sub-business) Business Users - Providing minimum required information Minimum required sub-business information - Business Collecting minimum information from the business during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the business onboarding, we can also reduce the form fields being built on the frontend to collect business information. Instead, we can then just allow the business to provide all the required information and documents during the eKYC information collection screens. For businesses, the minimum required business information is the following: preferred_name company_name email mobile_country_code mobile Create (Sub-business) Business Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{business_parent_id}}/businesses' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "preferred_name": "Corp XYZ", "company_name": "Corporate XYZ", "email": "xyz@corporatxyz.com", "mobile_country_code": "65", "mobile": "89919997" }' Create (Sub-business) Business Users response JSON { "id": "a8a911536dd84504a0bd86efe99f1618", "type": "business", "client_ref_id": "", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corp XYZ", "email": "xyz@corporatxyz.com", "mobile_country_code": "65", "mobile": "89919997", "business_id": "9fcc5c86a79f4bf18ab69f435ca66b10", "identification": { "primary": {}, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "data_terms_signed_at": "", "source_of_funds": "", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "additional_info_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-05-05T11:11:45Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate XYZ", "role": "End User" } Create (Sub-business) Business Users - Providing complete user information Region-specific Onboarding The example below displays the exhaustive set of user information fields that can be passed through the Create Sub-Business Users endpoint. However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ. Partners are encouraged to refer to the Region-specific Onboarding section to see the list of business information required for their program region. Only the listed region-specific business information is required to be collected from the users and submitted for business registration. Create (Sub-business) Business Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{parent_business_id}}/businesses' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "7234567891", "provider_action_id": "99111777b", "preferred_name": "Corporate XYZ", "type": "business", "role": "SUB_PARTNER_USER", "company_name": "Corporate XYZ", "lei_code": "1ncmxnc11", "website": "www.corporatexyz.com", "foundation_date" : "2023-08-01", "alternative_names": [ "XYZ" ], "email": "admin@corporatexyz.com", "mobile_country_code": "65", "mobile": "88811111", "supporting_documents": [ { "id_number": "M414L711", "id_type": "PROOF_OF_ADDRESS", "id_issuance_country": "PHL", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": false, "is_expiry_extended": false } ], "identification": { "primary": { "id_number": "M1417112", "id_type": "GOOD_STANDING_CERT", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "AFG" } }, "addresses": { "foundation": { "line_1": "111", "line_2": "Sunshine St", "line_3": "", "line_4": "", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "country": "PHL", "postal_code": "2200" }, "operational": { "line_1": "111", "line_2": "Sunshine St", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "state": "Cavite", "country": "PHL", "postal_code": "4107" } }, "socioprofessional_category": "string", "purpose_of_account_opening": "CASH_DEPOSIT", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "source_of_funds": "DEBT", "data_terms_signed_at": "2022-06-15 00:00:00", "metadata": { "test_identifier": "aaabbbb" }, "created_by": "bot@matchmove.com" }' Create (Sub-business) Business Users response JSON { "id": "c19db9f95a5e4d56bbc27a1ddb5e9fd8", "type": "business", "client_ref_id": "7234567891", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate XYZ", "email": "admin@corporatexyz.com", "mobile_country_code": "65", "mobile": "88811111", "business_id": "be9db48068c4455782067426fdccd90b", "identification": { "primary": { "id_number": "M1417112", "id_type": "Good Standing Certificate", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "111", "line_2": "Sunshine St", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "111", "line_2": "Sunshine St", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "Debt", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending_activation", "sub_status": "document_verification_required", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:25:44Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate XYZ", "foundation_date": "2023-08-01", "role": "Sub Partner User", "alternative_names": [ "XYZ" ], "lei_code": "1ncmxnc11", "website": "www.corporatexyz.com", "supporting_documents": [ { "id_number": "M414L711", "id_type": "Proof of Address", "id_sub_type": "abc", "id_issuance_country": "Philippines", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN" } ] } Business user identifier as a partner foreign key When a new business user is created, a user identifier (user.id) will be generated. In the example above, the user identifier will be the "id": "121a84f24763990b12a6c55e2993ac4a" . It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This business user identifier will be heavily used in most post-user creation APIs, and it will be convenient for you to have it accessible. 2 [Optional] Define business-associated parties Customer due diligence on a business requires verification of the business and its associated parties, such as its shareholders, directors, and beneficial owners. During the eKYC process, all the declared associated parties in the business profile will also be sent their own eKYC verification links for completion. The business eKYC approval will be blocked unless all the connected parties have also completed and passed their own verification. Thus, it is important to declare all business-associated parties prior to initiating the business eKYC process. *This step is optional because the definition of associated parties can primarily be done through the eKYC capture screens. Create Business-Associated Parties API-required fields enumerations: role allowed values are listed in the List Associated Party Roles Enumerations ( GET /users/enumerations/associated_party_roles ). Code Associated Party Role Supported Type SHAREHOLDER Shareholder Individual, Business INVESTOR Investor Individual, Business LEGALADVISOR Legal Advisor Individual, Business TRUSTEE Trustee Individual, Business TRUSTBENEFICIARY Trust beneficiary Individual, Business TRUSTSETTLOR Trust settlor Individual, Business TRUSTPROTECTOR Trust protector Individual, Business DIRECTOR Director Individual, Business SECRETARY Secretary Individual, Business FOUNDER Founder Individual, Business UBO Ultimate Beneficial Owner Individual REPRESENTATIVE Authorized Representative Individual AUTHORIZEDSIGNATORY Authorized signatory Individual COMPANYOFFICER Company officer (CEO, CFO, etc.) Individual Create Business-Associated Parties Call Create Business-Associated Parties ( POST /associated_parties ) to define an associated party with the business profile. An associated party can be either an individual or a business. This is an OPTIONAL activity for Business User registration. Since onboarding businesses can define their associated parties from the eKYC information collection screens. Business-Associated Parties registration Create Business-Associated Parties (Individual) - Providing minimum required information Minimum required associated party information - Individual For individual associated parties, the minimum required individuals information is the following: first_name last_name role type email mobile_country_code mobile Create Business-Associated Parties (Individual) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "email": "jane.smith@matchmove.com", "mobile_country_code": "65", "mobile": "91759691", "type": "individual", "role": "DIRECTOR", "first_name": "Jane", "last_name": "Smith" }' Create Business-Associated Parties (Individual) response JSON { "id": "216ca49a839b475ca323dc9d01edfe7b", "type": "individual", "client_ref_id": "", "provider_ref_id": "", "provider_account_number": "", "salutation": "", "suffix": "", "title": "", "first_name": "Jane", "middle_name": "", "last_name": "Smith", "preferred_name": "", "email": "jane.smith@matchmove.com", "mobile_country_code": "65", "mobile": "91759691", "gender": "", "marital_status": "", "identification": { "primary": {}, "secondary": {} }, "birth": {}, "nationality": "", "mothers_details": {}, "father_details": {}, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "", "job_title": "", "employment_details": { "business_trading_name": "", "business_purpose": "", "industry": "", "industry_key": "", "own_economic_interest_signed_at": "", "expected_monthly_revenue": "", "vat_number": "", "business_address": {} }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "", "main_income_source": "", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "", "residency_country": "", "self_declared_as_pep": false, "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "pending", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-05-05T15:02:25Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "role": "Appointed to manage the company business and affairs", "business_id": "a8a911536dd84504a0bd86efe99f1618" } Create Business-Associated Parties (Individual) - Providing complete user information Create Business-Associated Parties (Individual) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "9234567891", "type": "individual", "preferred_name": "Owen Owner", "salutation": "mr", "role": "UBO", "title": "dr", "first_name": "Owen", "middle_name": "V", "last_name": "Owner", "maiden_name": "", "marital_status": "SINGLE", "email": "owen.owner@matchmove.com", "mobile_country_code": "65", "mobile": "88296601", "supporting_documents": [ { "id_number": "M41wewewe1", "id_type": "UTILITY_BILL", "id_issuance_country": "DNK", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": true, "is_expiry_extended": true } ], "identification": { "primary": { "id_number": "M4WMB6RLH1218", "id_type": "id_card", "id_date_added": "2019-08-24", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "AFG" }, "secondary": { "id_number": "seconds719218", "id_type": "drivers_id", "id_date_added": "2019-08-24", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "AFG" } }, "birth": { "name": "Owen Owner", "date": "2000-04-02", "city": "Gen Trias", "country": "PHL", "postal_code": "1000" }, "nationality": "AFGHAN", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "fathers_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "999", "line_2": "Jackfruit Dr", "line_3": "", "line_4": "", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "country": "AFG", "postal_code": "2200" }, "billing": { "line_1": "999", "line_2": "Jackfruit Dr", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "state": "Cavite", "country": "AFG", "postal_code": "4107" }, "shipping": { "line_1": "999", "line_2": "Jackfruit Dr", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "country": "AFG", "state": "Cavite", "postal_code": "4107" } }, "employment_type": "SELF-EMPLOYED", "job_title": "ACCOUNTANT", "employment_details": { "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "999", "line_2": "Jackfruit Dr", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "country": "AFG", "state": "Cavite", "postal_code": "4107" } }, "fatca_crs_confirmed_at": "2019-08-24T14:15:22Z", "fatca_relevant": true, "annual_income_range": "20000", "main_income_source": "SALARY", "socioprofessional_category": "string", "purpose_of_account_opening": "string", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "data_terms_signed_at": "2022-06-15 00:00:00", "metadata": { "internal_identifier": "123232dd" }, "created_by": "bot@matchmove.com" }' Create Business-Associated Parties (Individual) response JSON { "id": "7f93a313eb1b454e9f63483831e879da", "type": "business", "client_ref_id": "", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "", "email": "admin@corpdef.com", "mobile_country_code": "65", "mobile": "917198943", "business_id": "a8a911536dd84504a0bd86efe99f1618", "identification": { "primary": {}, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": {}, "operational": {} }, "data_terms_signed_at": "", "source_of_funds": "", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "pending", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-05-05T15:11:08Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corp DEF", "role": "Entitled to benefit from assets held in a trust" } Create Business-Associated Parties (Business) - Providing minimum required information Minimum required associated party information - Business For business-associated parties, the minimum required business information is the following: type company_name email mobile_country_code mobile role Create Business-Associated Parties (Business) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "email": "admin@corpdef.com", "mobile_country_code": "65", "mobile": "917198943", "company_name": "Corp DEF", "type": "business", "role": "TRUSTBENEFICIARY" }' Create Business-Associated Parties (Business) response JSON { "id": "4812461a30924c5c91f983970af3caea", "type": "business", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate DEF", "email": "admin@corporatedef.com", "mobile_country_code": "65", "mobile": "89898989", "business_id": "8824d28441cb4486ac9c875aa1d3bc69", "identification": { "primary": { "id_number": "M1417112", "id_type": "Good Standing Certificate", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "pending", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T13:04:43Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate DEF", "foundation_date": "2023-08-01", "role": "ultimate beneficial owner of the company", "alternative_names": [ "DEF" ], "lei_code": "da122231", "website": "www.corporatedef.com", "supporting_documents": [ { "id_number": "M414L711", "id_type": "PROOF_OF_ADDRESS", "id_sub_type": "abc", "id_issuance_country": "PHL", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN" } ] } Create Business-Associated Parties (Business) - Providing complete user information CrCreate Business-Associated Parties (Business) request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "client_ref_id": "9234567891", "provider_action_id": "1221355", "preferred_name": "Corporate DEF", "type": "business", "role": "UBO", "company_name": "Corporate DEF", "lei_code": "da122231", "website": "www.corporatedef.com", "foundation_date" : "2023-08-01", "alternative_names": [ "DEF" ], "email": "admin@corporatedef.com", "mobile_country_code": "65", "mobile": "89898989", "supporting_documents": [ { "id_number": "M414L711", "id_type": "PROOF_OF_ADDRESS", "id_issuance_country": "PHL", "id_sub_type": "abc", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN", "is_term_unlimited": false, "is_expiry_extended": false } ], "identification": { "primary": { "id_number": "M1417112", "id_type": "GOOD_STANDING_CERT", "id_date_added": "2019-08-24", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "AFG" } }, "addresses": { "foundation": { "line_1": "881", "line_2": "Wimbledon Dr", "line_3": "", "line_4": "", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "country": "PHL", "postal_code": "2200" }, "operational": { "line_1": "881", "line_2": "Wimbledon Dr", "line_3": "", "line_4": "", "city": "ABORLAN_PALAWAN", "state": "Cavite", "country": "PHL", "postal_code": "4107" } }, "socioprofessional_category": "string", "purpose_of_account_opening": "CASH_DEPOSIT", "self_declared_as_pep": true, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "provider_ref_id": "", "provider_account_number": "", "posting_status": "ok", "source_of_funds": "DEBT", "data_terms_signed_at": "2022-06-15 00:00:00", "metadata": { "internal_identifier": "aaa121bbb" }, "created_by": "bot@matchmove.com" }' Create Business-Associated Parties (Business) response JSON { "id": "4812461a30924c5c91f983970af3caea", "type": "business", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate DEF", "email": "admin@corporatedef.com", "mobile_country_code": "65", "mobile": "89898989", "business_id": "8824d28441cb4486ac9c875aa1d3bc69", "identification": { "primary": { "id_number": "M1417112", "id_type": "Good Standing Certificate", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "pending", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T13:04:43Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate DEF", "foundation_date": "2023-08-01", "role": "ultimate beneficial owner of the company", "alternative_names": [ "DEF" ], "lei_code": "da122231", "website": "www.corporatedef.com", "supporting_documents": [ { "id_number": "M414L711", "id_type": "PROOF_OF_ADDRESS", "id_sub_type": "abc", "id_issuance_country": "PHL", "id_issuer_name": "passport authority", "id_issuer_code": "PA", "id_issuer_state": "TN" } ] } Get Business-Associated Parties Call Get Business-Associated Parties ( GET /associated_parties ) to retrieve a list of all the associated parties connected to a business. Get Business-Associated Parties request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Get Business-Associated Parties response JSON { "pagination": { "total_records": 2, "records_per_page": 10, "total_pages": 1, "links": { "self": "https://svc-customer.uat.matchmove-beta.com/api/v2/associated_parties?page=1&records_per_page=10", "next": "", "previous": "" } }, "data": [ { "id": "4812461a30924c5c91f983970af3caea", "type": "business", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "preferred_name": "Corporate DEF", "email": "admin@corporatedef.com", "mobile_country_code": "65", "mobile": "89898989", "business_id": "8824d28441cb4486ac9c875aa1d3bc69", "identification": { "primary": { "id_number": "M1417112", "id_type": "Good Standing Certificate", "id_date_issued": "2025-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": {} }, "addresses": { "residential": {}, "billing": {}, "shipping": {}, "identity_verification": {}, "foundation": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "state_code": "1234", "postal_code": "2200", "country": "Philippines" }, "operational": { "line_1": "881", "line_2": "Wimbledon Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Philippines" } }, "data_terms_signed_at": "", "source_of_funds": "", "purpose_of_account_opening": "", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "service_agreement": "", "user_agent": "", "device_id": "" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T13:04:43Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "company_name": "Corporate DEF", "foundation_date": "2023-08-01", "role": "ultimate beneficial owner of the company", "alternative_names": [ "DEF" ], "lei_code": "da122231", "website": "www.corporatedef.com", "supporting_documents": [ { "id_number": "PROOF_OF_ADDRESS", "id_type": "M414L711", "id_sub_type": "abc", "id_issuance_country": "PHL", "id_issuer_code": "PA" } ] }, { "id": "eed3d63039e94e9ea92aeaa568c73b02", "type": "individual", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "salutation": "mr", "title": "DR", "first_name": "Owen", "middle_name": "V", "last_name": "Owner", "preferred_name": "Owen Owner", "email": "owen.owner@matchmove.com", "mobile_country_code": "65", "mobile": "88296601", "gender": "", "marital_status": "SINGLE", "identification": { "primary": { "id_number": "M4WMB6RLH1218", "id_type": "Id Card", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": { "id_number": "seconds719218", "id_type": "Driver's license", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" } }, "birth": { "name": "Owen Owner", "date": "2000-04-02", "city": "Gen Trias", "country": "Philippines", "postal_code": "1000" }, "nationality": "AFGHAN", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "father_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "postal_code": "2200", "country": "Afghanistan" }, "billing": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Afghanistan" }, "shipping": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Afghanistan" }, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "SELF-EMPLOYED", "job_title": "ACCOUNTANT", "employment_details": { "business_trading_name": "abcdefg", "business_purpose": "ACCOUNTING", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "999", "line_2": "Jackfruit Dr", "postal_code": "4107", "city": "ABORLAN_PALAWAN", "country": "Afghanistan", "state": "Cavite" } }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "20000", "main_income_source": "SALARY", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": false, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:54:19Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "role": "ultimate beneficial owner of the company", "business_id": "8824d28441cb4486ac9c875aa1d3bc69", "supporting_documents": [ { "id_number": "UTILITY_BILL", "id_type": "M41wewewe1", "id_sub_type": "abc", "id_issuance_country": "DNK", "id_issuer_code": "PA", "is_term_unlimited": true, "is_expiry_extended": true } ] } ] } Update Business-Associated Party Call Update Business-Associated Party ( PUT /associated_parties/{{associated_party_id}} ) update the details of an associated party. Update Business-Associated Party (Individual) request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties/{{associated_party_id}}' \ --header 'X-Auth-User-ID: {{parent_business_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' \ --data-raw '{ "type": "individual", "email": "new@corporatedef.com", "mobile_country_code": "65", "mobile": "89898981" }' Updated Business-Associated Party (Individual) response JSON { "id": "eed3d63039e94e9ea92aeaa568c73b02", "type": "individual", "client_ref_id": "9234567891", "provider_ref_id": "", "provider_account_number": "", "salutation": "mr", "title": "DR", "first_name": "Owen", "middle_name": "V", "last_name": "Owner", "preferred_name": "Owen Owner", "email": "new@corporatedef.com", "mobile_country_code": "65", "mobile": "89898981", "gender": "", "marital_status": "SINGLE", "identification": { "primary": { "id_number": "M4WMB6RLH1218", "id_type": "Id Card", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" }, "secondary": { "id_number": "seconds719218", "id_type": "Driver's license", "id_date_issued": "2020-06-08", "id_date_expiry": "2028-08-24", "id_issuance_country": "Afghanistan" } }, "birth": { "name": "Owen Owner", "date": "2000-04-02", "city": "Gen Trias", "country": "Philippines", "postal_code": "1000" }, "nationality": "AFGHAN", "mothers_details": { "first_name": "Est", "middle_name": "Tori", "last_name": "Mir", "maiden_name": "e t m" }, "father_details": { "first_name": "Vir", "middle_name": "Cab", "last_name": "Mir", "maiden_name": "v c m" }, "addresses": { "residential": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "GABALDON_BITULOK_SAB", "state": "LAUNION", "postal_code": "2200", "country": "Afghanistan" }, "billing": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Afghanistan" }, "shipping": { "line_1": "999", "line_2": "Jackfruit Dr", "city": "ABORLAN_PALAWAN", "state": "Cavite", "postal_code": "4107", "country": "Afghanistan" }, "identity_verification": {}, "foundation": {}, "operational": {} }, "employment_type": "SELF-EMPLOYED", "job_title": "ACCOUNTANT", "employment_details": { "business_trading_name": "abcdefg", "business_purpose": "ACCOUNTING", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "expected_monthly_revenue": "1000000", "vat_number": "893678372", "business_address": { "line_1": "999", "line_2": "Jackfruit Dr", "postal_code": "4107", "city": "ABORLAN_PALAWAN", "country": "Afghanistan", "state": "Cavite" } }, "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "data_terms_signed_at": "", "annual_income_range": "20000", "main_income_source": "SALARY", "purpose_of_account_opening": "", "socioprofessional_category": "", "work_country": "Philippines", "residency_country": "Philippines", "self_declared_as_pep": false, "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Curl", "device_id": "SteveOS-High" }, "metadata": null, "agent_id": "", "partner_id": "", "customer_id": "", "status": "pending", "sub_status": "", "kyc_status": "not_submitted", "kyc_sub_status": "", "transaction_status": "", "transaction_sub_status": "", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "kyc_processed_date": "", "date_created": "2026-02-11T12:54:19Z", "date_updated": "0001-01-01T00:00:00Z", "pending_update": [], "verification_id": {}, "require_provider_update": [], "http_status_code": 0, "requirements": { "immediately_due": { "required_attributes": [], "required_actions": [] }, "eventually_due": { "required_attributes": [], "required_actions": [] }, "pending_verification": {} }, "risk_assesment_status": "UNKNOWN", "status_reason_code": "", "status_message": "", "role": "ultimate beneficial owner of the company", "business_id": "8824d28441cb4486ac9c875aa1d3bc69" } Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users • [Business eKYC](https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/business-ekyc.md): Understand the due diligence requirements and documentation necessary for onboarding corporate entities. This guide explains the verified data points required for businesses and their associated stakeholders. Onboard business customers with confidence. The comprehensive KYC/B capabilities verify company legitimacy and ownership structures and ensure compliance with AML regulations—directly within the MatchMove platform. Corporate Registry Check Instant access to 600M+ commercial records worldwide. Verify company registration, legal status, and corporate details in just 15 seconds through the integrated registry network. UBO and Associated Parties Verification Identify and verify Ultimate Beneficial Owners with access to 345M+ shareholder records. The KYC service UBO verification achieves 90%+ pass rates with minimal friction. Document Review AI-powered extraction and verification of corporate documents in 140+ languages. Certificates of incorporation, articles of association, shareholder registers, and more. Ownership Structure Automatically map complete ownership hierarchies including shareholders, directors, authorized signatories, and related legal entities with visual structure diagrams. Associated Parties We Verify Ultimate Beneficial Owners Shareholders Directors Representatives Authorized Signatories Founders Secretaries Legal Advisors Trustees Beneficiaries How Business Verification Works 1 Company Information Submission The business representative enters basic company details: legal name, registration number, and country of incorporation. The KYC service system searches against 600M+ commercial records to locate and pre-fill company data. 2 Corporate Registry Verification We automatically verify the company's legal existence, registration status, and corporate details against official government registries and trusted commercial databases in real time. 3 Corporate Document Collection Required documents are uploaded: certificate of incorporation, articles of association, shareholder registers, and proof of address. The KYC service AI extracts and cross-checks data in 140+ languages. 4 Ownership Structure Mapping The complete ownership hierarchy is mapped—identifying all shareholders, directors, and Ultimate Beneficial Owners (UBOs) who hold 25% or more ownership or exercise significant control. 5 UBO & Associated Party KYC Each identified UBO and key associated party completes individual identity verification (eKYC). This ensures the real people behind the business are verified to the same standard as individual customers. 6 Corporate AML Screening The company and all associated parties are screened against global sanctions lists, PEP databases, watchlists, and adverse media. Any matches are flagged for compliance review. 7 Verification Complete Upon successful verification, the business is approved for onboarding. A complete audit trail is generated, and ongoing monitoring ensures continuous compliance throughout the relationship. AML Screening & Ongoing Monitoring Protect your business with continuous compliance monitoring that runs automatically in the background—built right into your existing workflows. Global Watchlist Screening Automated checks against OFAC, UN, EU, HMT sanctions lists and more PEP Detection Identify Politically Exposed Persons across all jurisdictions Adverse Media Monitoring AI-powered scanning for negative news coverage Ongoing Monitoring Continuous re-screening alerts you to any status changes Risk Scoring Dynamic assessment based on multiple configurable risk factors Security & Compliance The KYC service verification infrastructure meets the highest security standards including SOC 2 Type II certification and GDPR compliance. All verification data is encrypted end-to-end and processed in accordance with global data protection regulations. Business eKYC User Journey Designing a seamless eKYC (Electronic Know Your Customer) journey requires a delicate balance between regulatory rigor and user experience. While the interface is designed to feel intuitive and linear, the engine behind it is highly sophisticated. The following workflow outlines the standard sequence of screens a business user will encounter. However, it is important to note that the capture process is dynamic; the system adapts in real-time based on the business: country of business foundation industry or sector risk associated with the profile If certain triggers are met, the journey will automatically scale to include Enhanced Due Diligence (EDD) requirements, prompting for additional documentation or clarifying questions to ensure full compliance without compromising the integrity of the data. Key Logic of the Journey Adaptive UX: The flow isn't one-size-fits-all; it adjusts based on the "foundation country" and "industry" inputs. Risk-Based Triggering: High-risk industry and profiles will see additional form fields that a standard-risk business user will not. Dynamic Document Capture: The system intelligently requests specific IDs or supplemental proof that is legally required for verification. Disclaimer Verification Entry Business Profile Document Capture Declare Associated Parties Submission Confirmation *Before the business KYC verification is given approval, all of its connected parties must pass their own verifications. UBO and other associated parties must complete their individual eKYC using the verification link sent to their registered email. Note: Starting a KYC from a link sent to your email requires a relationship and trust from the sender. As such, the sending of the KYC email to associated parties must be a deliberate action from the verifying business. The KYC links for the associated parties are provided in the business KYC confirmation screen and can also be generated using the API. The platform will not send any automated emails pertaining to KYC; all platform notifications are delivered only through a webhook. KYC and Business User State Transition As users navigate the KYC process, their account statuses dynamically update to reflect their current stage in the onboarding journey. This guide details every user state transition, providing you with a clear roadmap of what each status means and the specific actions required to move users forward. Familiarize yourself with these transitions to ensure seamless user activation and responsive account management. Business eKYC Workflow Profile Completion : Once the user completes their profile, their user.status updates to pending_activation and their user.kyc_status updates to pending . To activate the account, the user must now undergo eKYC. KYC Submission : Upon eKYC submission, the user.kyc_status transitions to in_progress . This automatically triggers the KYC evaluation process. Evaluation Completion : Once the evaluation concludes, the user.kyc_status updates to completed . Associated Party Evaluation: The final approval of a business KYC application is directly dependent on the verification of its linked associated parties. A business profile cannot be fully approved until all required associated parties have successfully passed their own KYC evaluations. Evaluation Results : Based on the review, the user.kyc_sub_status will be marked as either approved or rejected . If Rejected: Prompt the user to correct the specified rejection reasons and resubmit their eKYC application. If Approved and Associated Parties KYC are Approved: This triggers the platform-initiated User Activation process. The user is now granted access to the platform's financial assets and capabilities. If Approved and Associated Parties KYC are Not Approved: The platform will wait until all the required approvals are given before it triggers the platform-initiated User Activation process. Ongoing Monitoring : A periodic risk evaluation occurs throughout the lifetime of the user's account. Based on these evaluations, the user.status can be updated to suspended (a reversible action) or terminated (an irreversible action). Account Reactivation : If an account is suspended, the partner can initiate a reactivation process once the underlying suspension reason has been fully resolved. KYC and Business User State Transition Updates Because KYC evaluation is an asynchronous process, all status updates are delivered securely via the USER.STATUS (Business) and ASSOCIATED_PARTIES.PROFILE.STATUS (Business - Associated Parties) webhooks. Each webhook payload provides the real-time user and KYC states to keep your system in sync. You must monitor these incoming updates and trigger the appropriate next steps or follow-up actions based on the specific states returned. KYC Status KYC Sub-status User Status User Sub-status Business User(B) / Partner(P) Action pending pending_document_submission pending_activation information_verification_inprogress [B] Complete the profile questionnaire. pending pending_document_submission pending_activation information_collection_completed No action required. pending pending_document_submission pending_activation company_document_verification_inprogress [B] Upload document requirements. pending pending_document_submission pending_activation company_document_collection_completed No action required. pending pending_document_submission pending_activation associated_parties_verification_inprogress [B] Add business-associated parties. pending pending_document_submission pending_activation associated_parties_collection_completed No action required. pending pending_associated_parties_verification pending_activation associated_parties_collection_inprogress Associated party completing their KYC requirements. No action required. pending pending_associated_parties_creation pending_activation associated_parties_collection_inprogress Associated party completing their KYC requirements. No action required. pending pending_document_submission pending_activation industry_questionnaire_data_verification_inprogress [B] Complete the business industry questionnaire. pending pending_document_submission pending_activation industry_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation full_kyb_verification_inprogress Manual document review activated — waiting for KYC service review results. No action required. pending pending_document_submission pending_activation full_kyb_collection_completed No action required. pending pending_document_submission pending_activation aml_verification_inprogress No action required. pending pending_document_submission pending_activation edd_questionnaire_data_verification_inprogress [B] EDD activated — complete the EDD questionnaire. pending pending_document_submission pending_activation edd_source_of_funds_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation high_risk_industry_questionnaire_data_verification_inprogress [B] EDD activated — complete the high-risk industry questionnaire. pending pending_document_submission pending_activation high_risk_industry_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation license_verification_questionnaire_data_verification_inprogress [B] EDD activated — complete the license verification questionnaire. pending pending_document_submission pending_activation license_verification_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation edd_source_of_funds_questionnaire_data_verification_inprogress [B] EDD activated — complete the source of funds questionnaire. pending pending_document_submission pending_activation edd_source_of_funds_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation pep_questionnaire_data_verification_inprogress [B] EDD activated — complete the PEP questionnaire. pending pending_document_submission pending_activation pep_questionnaire_data_collection_completed No action required. pending pending_document_submission pending_activation sanction_questionnaire_data_verification_inprogress [B] EDD activated — complete the sanction questionnaire. pending pending_document_submission pending_activation sanction_questionnaire_data_collection_completed No action required. in_progress waiting_for_approval pending_activation internal_review_inprogress EDD activated - w aiting for manual MatchMove Compliance approval. No action required. completed approved active active The user has been activated. [P] Proceed with financial asset provisioning for the business user. completed rejected pending_activation document_verification_failed The KYC submission has been rejected. [P] Allow the user to invoke eKYC again [B] Resubmit the eKYC and resolve the rejection reason. completed rejected terminated terminated_for_risk The user has been terminated as a result of KYC and risk evaluation. [P] Notify the user regarding the termination. completed approved suspended suspended_for_screening_evaluation Business user suspended as a result of periodic risk evaluation . [P] Raise a support ticket to MatchMove providing the user ID of the suspended user. KYC Rejection Reasons - Business Reject Reason Code Description KYB_REJECTED Know Your Business (KYB) not approved. INFORMATION_INCOMPLETE Mandatory business information is missing or incomplete. DOCUMENT_EXPIRING_SOON The document expires within the minimum validity period required. DOCUMENT_IMAGE_QUALITY_ISSUE The document image is unreadable. DOCUMENT_AUTHENTICITY The document shows signs of tampering or forgery. NAME_MISMATCH Registered business name does not match the application. DOCUMENT_ISSUING_COUNTRY_NOT_SUPPORTED The issuing country of the document is not supported. DOCUMENT_EXPIRED The document is past its validity date. REGION_NOT_SUPPORTED The region of registration or operation is not serviceable. COUNTRY_MISMATCH Country of incorporation does not match the country declared. DOCUMENT_MISSING A required business document was not submitted. COMPANY_REGISTRATION_EXPIRED The business registration has lapsed. NO_DIRECTORS_IDENTIFIED No director or beneficial owner could be identified. ADDRESS_MISMATCH Business address does not match the documents. COMPANY_ASSOCIATED_PARTY_VERIFICATION_PENDING An associated party has not completed verification. COMPANY_ASSOCIATED_PARTY_CREATION_PENDING An associated party record has not been created. DOCUMENT_TYPE_MISMATCH Document type submitted differs from the type required. DOCUMENT_LANGUAGE_NOT_SUPPORTED The document language is not supported. COMPANY_DATA_MISMATCH Company details do not match registry records. DOCUMENT_NOT_RECENT_ENOUGH The document is older than the maximum age allowed. Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users • [[SG] Document-based verification](https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/business-ekyc/sg-document-based-verification.md): Learn the end-to-end workflow for submitting corporate details and initiating the business verification check. This guide demonstrates how to execute the onboarding process for business accounts effectively. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to submit the required KYC documents needed to verify the identity of a business user. You want to submit supporting documents that will help in the business user identity verification. You want to implement a feature in your application that will allow business users to upload documents using the available MatchMove eKYC Provider. You want to implement a feature in your application that will allow business users to upload supporting documents using the available MatchMove KYC endpoints. The business user will submit KYC by going through the automated eKYC interface to collect selfies and identification documents. The business user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism. Prerequisites The business user profile must already be completed. Refer to the Register business profile (v2) section for more details. The individual user profile must be in status = pending_activation . The individual user profile has a kyc_status = not_submitted , indicating that they have not attempted to perform KYC yet, or The individual user profile has a kyc_status = pending and a kyc_sub_status = pending_document_submission , indicating that they are still required to submit document, or The individual user profile has a kyc_status = completed and a kyc_sub_status = rejected , indicating that their previous submission was rejected. API Workflow 1 Check if a business user is allowed to submit KYC Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface. A business user can only send a KYC submission for verification if they have the following: Business User Status Business User KYC Status Description status = pending_activation kyc_status = not_submitted The Business User has not yet attempted to submit his KYC status = pending_activation kyc_status = pending kyc_sub_status = pending_document_submission The Business User has attempted to submit his KYC but is still required to submit other documents. status = pending_activation kyc_status = completed kyc_sub_status = rejected The Business User has attempted to submit his KYC and has failed on his last submission. Get Business Users Call Get Business Users ( GET /businesses ) to retrieve the User and KYC status of an business user. Get Business Users request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Authorization: ••••••' Get Business Users response JSON { .. "status": "pending_activation", "sub_status": "document_submission_required", "kyc_status": "not_submitted", "kyc_sub_status": "", .. } 2 [Optional] Check if business is eligible for document-based verification By default, document-based verification is automatically enabled for all programs. You only need to call this API to check for other eligible methods if you have explicitly enabled additional verification options (such as authentication-based verification or partner-assisted verification) in your program configuration. List KYC Verification Modes Call Get KYC Verification Modes ( GET /v2/businesses/authentications/documents/verification_modes ) to get all available verification modes available for the program and applicable to the user. List KYC Verification Modes request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/authentications/documents/verification_modes' \ --header 'X-Auth-User-ID: {{business_id}}' \ --header 'Authorization: ••••••' List KYC Verification Modes response JSON { "verification_modes": [ { "mode": "document_based" }, { "mode": "authentication_based" } ] } The response will list all the verification modes that the user is eligible to undergo. If document_based is listed, then you can start to initiate the verification by requesting a KYC verification link. 3 [Business] Retrieve the eKYC redirect link to the document collection screen The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents. Initiate KYC Capture (Business User) Call Initiate KYC Capture (Business User) ( POST /businesses/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Business User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{business_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Business User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "business", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } The Initiate KYC Capture (Business User) API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the customer can perform the KYC document capture and submit their KYC application. The eKYC verification is asynchronous ; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take from an instant to a few minutes, provided that all document submissions are clear and legible and the partner profile aligns perfectly with the document data. 4 [Optional] [Associated Parties] Retrieve the eKYC redirect link to the document collection screen If the business-associated parties are declared and defined in the business profile prior to the invocation of the KYC document collection, all the defined associated parties will be automatically generated with their own KYC link . These links will be accessible from the business KYC confirmation screen, and you will have the option to email the link to the registered email of the associated party. However, there will be cases where the associated parties may miss KYC links in their email or consume the link after its expiry. For these scenarios, partners will be able to regenerate a fresh KYC link for these associated parties. Initiate KYC Capture (Associate Party) Call Initiate KYC Capture (Associate Party) ( POST /associated_parties/{{associated_party_id}}/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Associate Party) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/associated_parties/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{associated_party_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Associate Party) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "associated_party", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } 5 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Webhook Event Description Action U SER.STATUS User and KYC Status Update A notification is sent in the event that the User or KYC status of the business user gets updated. Handle User and KYC status changes as outlined in the Business eKYC - KYC and Business User State Transition Updates section. ASSOCIATED_PARTIES.PROFILE.STATUS Associated Party KYC Status Update A notification is sent in the event that the associated parties' statuses of the business user get updated. Handle Associated Party (Business) status changes as outlined in the Business eKYC - KYC and Business User State Transition Updates section. USER.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook USER.STATUS for User and KYC updates KYC Document Verification Update A notification is sent in the event that the KYC status of the business user is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. ASSOCIATED_PARTY.DOCUMENT_VERIFICATION.STATUS Deprecation notice: Partners are encouraged to switch to the enhanced webhook ASSOCIATED_PARTIES.PROFILE.STATUS for Associated Party KYC updates KYC Document Verification Update - Associated Party A notification is sent in the event that the KYC status of the associated party is updated to either approved or rejected. [Approved] No action required. [Rejected] You may ask the associated party to retry or redo another round of KYC submission. USER.STATUS or ASSOCIATED_PARTIES.PROFILE.STATUS (Approved) sample webhook payload JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:09:48Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2030-02-12", "id_date_issued": "2025-06-08", "id_issuance_country": "Spain", "id_number": "02345678A", "id_type": "Id Card", "metadata": "{\"mrzLine1\":\"IDESPAAA023456789026070A\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\",\"mrzLine2\":\"3456789M5678901234\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c0\",\"mrzLine3\":\"CITIZEN\\u003cSMITH\\u003c\\u003cAGUEDA\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\"}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "CLEARED", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:09:47Z", "kyc_status": "completed", "kyc_sub_status": "approved", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "pending_verification": {} }, "residency_country": "Philippines", "risk_assesment_status": "CLEARED", "risk_evaluation_date": "2026-08-12T20:09:48Z", "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "active", "status_message": "", "status_reason_code": "", "sub_status": "active", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2027-06-28", "id_date_issued": "2021-06-19", "id_issuance_country": "Germany", "id_number": "L02M000CH8", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2030-03-14 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "approved", "sub_status": "Full KYC Verified", "sub_status_code": "APPROVED", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:09:48+0800", "message_id": "dc6ca6ce-a592-44c5-9cba-10094d5016e5", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } U SER.STATUS or ASSOCIATED_PARTIES.PROFILE.STATUS (Rejected) sample webhook payload JSON { "entities": { "user": { "addresses": { "billing": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" }, "foundation": {}, "identity_verification": {}, "operational": {}, "residential": { "city": "GABALDON_BITULOK_SAB", "country": "Germany", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "2200", "state": "LAUNION", "state_code": "123" }, "shipping": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite", "state_code": "123" } }, "agent_id": "", "alias_name": "ncmxnc", "annual_income_range": "20000", "birth": { "city": "Gen Trias", "country": "Singapore", "date": "2000-04-02", "name": "John Smith", "postal_code": "1000" }, "client_ref_id": "9234567891", "customer_id": "", "data_terms_signed_at": "", "date_created": "2026-08-12T20:04:20Z", "date_updated": "2026-08-12T20:07:16Z", "email": "test@matchmove.com", "employment_details": { "business_address": { "city": "ABORLAN_PALAWAN", "country": "Denmark", "line_1": "Cusiness_@#164654,: jkjsdj lkshj", "line_2": "Cusiness_@#164654,: jkjsdj lkshj", "line_3": "Cusiness_@#164654,: jkjsdj lkshj", "line_4": "BARMM", "postal_code": "4107", "state": "Cavite" }, "business_purpose": "ACCOUNTING", "business_trading_name": "abcdefg", "expected_monthly_revenue": "1000000", "industry": "Finance & Tech", "industry_key": "fintech", "own_economic_interest_signed_at": "Manila", "vat_number": "893678372" }, "employment_type": "Self Employed", "ethnicity": "ncmxnc", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "fatca_relevant": false, "father_details": { "first_name": "Steve", "last_name": "Smith", "maiden_name": "v c m", "middle_name": "" }, "first_name": "Testerqnq", "gender": "Male", "http_status_code": 0, "id": "560b71f5e4904195a0bbd8a37020881b", "identification": { "primary": { "id_date_expiry": "2060-04-24", "id_date_issued": "2025-06-08", "id_issuance_country": "Germany", "id_number": "Testerqnq23132", "id_type": "Id Card", "metadata": "{}" }, "secondary": {} }, "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "PENDING", "job_title": "Accountant", "kyc_processed_date": "2026-08-12T20:07:16Z", "kyc_status": "not_submitted", "kyc_sub_status": "pending_document_submission", "last_name": "QAxmy", "legal_name": "ncmxnc", "main_income_source": "Salary", "marital_status": "Single", "metadata": { "testing": "aaabbbb" }, "middle_name": "V", "mobile": "360351661", "mobile_country_code": "65", "mothers_details": { "first_name": "Jane", "last_name": "Smith", "maiden_name": "e t m", "middle_name": "" }, "nationality": "Nationality for Germany", "partner_id": "", "pending_update": [], "preferred_name": "Testerqnq", "provider_account_number": "", "provider_ref_id": "6a7c61b68597306e52a7e658", "purpose_of_account_opening": "Cash Deposit", "require_provider_update": [], "requirements": { "eventually_due": { "required_actions": [], "required_attributes": [], "required_documents": [] }, "immediately_due": { "required_actions": [ "cdd_verification" ], "required_attributes": [], "required_documents": [] }, "pending_verification": { "cdd_verification": { "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } } }, "residency_country": "Philippines", "risk_assesment_status": "PENDING", "risk_evaluation_date": null, "salutation": "JLXM", "self_declared_as_pep": false, "socioprofessional_category": "", "status": "pending_activation", "status_message": "", "status_reason_code": "", "sub_status": "document_verification_failed", "suffix": "", "supporting_documents": [ { "id_issuance_country": "Germany", "id_issuer_code": "PA", "id_issuer_name": "passport authority", "id_issuer_state": "TN", "id_number": "TesterqnqM41", "id_sub_type": "abc", "id_type": "Utility Bill", "is_expiry_extended": true, "is_term_unlimited": true, "metadata": "{'mrx': 'mrzvalue'}" }, { "id_date_expiry": "2030-02-12", "id_issuance_country": "Spain", "id_number": "ААА02345678A", "id_type": "Other" } ], "tin": "ncmxnc", "title": "Dr", "tos_acceptance": { "date": "2019-08-24T14:15:22Z", "device_id": "SteveOS-High", "ip": "192.168.0.1", "service_agreement": "terms_condition", "user_agent": "Web" }, "transaction_status": "", "transaction_sub_status": "", "type": "individual", "verification_expiry": "2026-09-11 00:00:00", "verification_id": {}, "work_country": "Philippines" }, "verification_results": { "details": {}, "status": "pending", "sub_status": "", "sub_status_code": "", "verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18" } }, "entity_id": "560b71f5e4904195a0bbd8a37020881b", "entity_type": "USER", "event_timestamp": "2026-08-12 20:07:18+0800", "message_id": "11331635-226b-4485-b1a1-55b6f383a611", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "USER.STATUS" } 6 [Optional] Access business users' KYC documents All of the documents submitted by the business user during eKYC will be accessible for the partner for audit purposes. List KYC Documents Call List KYC Documents ( GET /users/authentications/documents ) to retrieve the list of documents submitted by the user during KYC, along with the download links for each document. The response of this endpoint will contain details regarding the uploaded file, including but not limited to: file_type - describes the type or category of the document that was uploaded, e.g., ID . document_type - describes what document under a certain file type was uploaded, e.g., selfie . link - the downloadable permalink to the uploaded document date.created - the timestamp of the document upload List KYC Documents request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' List KYC Documents response JSON { "verification_id": "vfc_487e7b22e4ed4263x576843389373f22", "status": "completed", "sub_status": "approved", "sub_status_code": "APPROVED", "sub_status_description": "Full KYC Verified", "documents": [ { "provider_document_id": "494631728", "type": "ID", "document_id": "", "file_type": "ID", "document_type": "Primary ID Document", "kyc_type": "", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIXULCJ8u2hM62lzOehXWGEYf.jpg", "id": "3FAIXULCJ8u2hM62lzOefXWDEYf", "status": "uploaded", "date": { "created": "2026-06-15T16:18:06+08:00" } } ], "count": 1, "metadata": {} } Related Links Identity & onboarding overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users • [Simulate business eKYC approvals](https://developer.matchmove.com/matchmove-banking-operating-system/business-users/onboard-business-users-v2/business-ekyc/simulate-business-ekyc-approvals.md): Learn how to trigger specific eKYC statuses by submitting predetermined test data during the verification process. This guide helps you understand the end-to-end user journey for business eKYC approvals and rejections in the staging environment. Note that these procedures are unsupported in Production and should only be performed in UAT or Staging . Use Cases: You need to simulate an business eKYC approval to test the success scenarios of your onboarding process. You need to simulate an business eKYC rejection to test the negative scenarios of your onboarding process. Prerequisites: You must already have an active registered business user that is ready to perform eKYC. Refer to the Perform business eKYC section to learn about the specific required KYC criteria. Approval Workflow 1 Generate a KYC capture link for the business user Simulating a KYC approval requires you to undergo the eKYC process. Render the eKYC capture link in any web/mobile browser that you want to conduct your test on. Initiate KYC Capture (Business User) Call Initiate KYC Capture (Business User) ( POST /businesses/authentications/documents/verifications ) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request. Callback Parameters (eKYC capture screen back to your app) redirect_url : The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow. redirect_mode : The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect). redirect_text : The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button. Initiate KYC Capture (Business User) request CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/authentications/documents/verifications' \ --header 'X-Auth-User-ID: {{business_id}}' \ --header 'Authorization: ••••••' --header 'Content-Type: application/json' \ --data '{ "verification_mode":"document_based", "redirect_url":"www.partner-callback.com", "redirect_mode": "button", "redirect_text": "Exit" }' Initiate KYC Capture (Business User) response JSON { "id": "caa61227979e43fea38d2730c11e8667", "links": [ { "href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=", "method": "GET", "rel": "capture.sdk" } ], "sub_type": "business", "type": "users", "verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e", "verification_mode": "document_based" } 2 Perform the eKYC process and submit pre-approved values The following procedure below is the only way to simulate an approval in the staging environment. Submitting any other values aside from the pre-approved values will result in rejection. You can subscribe to the KYC verification webhooks to be notified of the KYC approval of the business user. KYC Capture Screen Description In the Company Information screen, enter and change the following fields: Pre-approved values: Company name : Demo Company With Beneficiaries Ltd Registration number: 99999999 Country / Location of registration: GBR Associated party definition: In the Edit associated party screen, you will need to define an associated party. For the sake of efficiency, we recommend that you define an associated party that is an Individual User. Since associated parties are required to have their own KYC approved, defining an individual will be easier since it has fewer requirements than defining a business user. Role selection: In the live environment, it is required to define an associated party for all the roles available in the associated party form. For staging or UAT, if you just want to simulate the KYC approval process, you won't need to define an associated party for every role. Instead, you can define at least one associated party (Assoc Party A) and assign all the roles to this party (Assoc Party A). Associated party submission: Complete the user details of the associated party and proceed to submit. After submission, the business verification will be put on hold, awaiting the successful verification of all of its defined associated parties. Associated party KYC submission and approval (individual): On the Verification not yet complete (eKYC Submitted) screen, click the Verify Now button or render the KYC capture link in a web browser to proceed with the associated party's verification. Follow the Simulate individual eKYC approvals section to learn about how to simulate the verification of an individual user. Source: https://docs.sumsub.com/docs/test-business-verification#conduct-test-checks-for-business-verification 3 [Additional] For onboarding business from high-risk regions and industries If a business user is flagged as "high-risk" (due to business foundation location* or profile), the system automatically triggers Enhanced Due Diligence (EDD). This adds extra screens and document requirements to their eKYC journey. Note on Testing: You can use dummy data and documents for EDD requirements during simulation. Please keep in mind that EDD flips the process from automated to manual review. Since MatchMove Compliance must personally vet these submissions in both staging and live environments, approval won't be immediate. In staging and for the purpose of simulation, we have established a 1-day SLA for these specific cases. *Refer to Standard Operating Procedure for Compliance Management document for the list of high-risk and sanctions regions. 4 Request to trigger the simulation of the business KYC approval process from the backend: After the individual associated party KYC has been completed and passed its own verification, you will then need to submit a Freshdesk ticket requesting the KYC approval of the business user. On this ticket, please include details of the business, such as the business user ID, business name, and email. This additional step is needed to sync all the KYC states between MatchMove and the KYC provider in the simulation environment. When the states are all synced, that is when the update webhooks will be triggered. • [Deprecated](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated.md): Legacy Onboarding APIs (Deprecated) Please be advised that the guides and API specifications within this section are considered legacy. They are no longer being actively maintained or updated with new platform features. While existing integrations using these endpoints will continue to function for now, we highly recommend that all partners transition to our modern onboarding flows. The upgraded v2 APIs offer a more streamlined, secure, and robust experience. Where to go next: For individual users, please follow the updated guide at [v2] Onboard individual user . For corporate entities, please follow the updated guide at [v2] Onboard business users . • [[v1] Onboard individual user](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-individual-user-v1.md): Understand the complete onboarding workflow for individual users, from profile registration to successful KYC verification. This guide provides a comprehensive overview of the steps needed to activate an individual's account. Individual User onboarding involves the following processes: Individual User Registration The process involves capturing the required user information from the customer and submitting it to the platform to create a user profile or user entity that represents the customer. This process runs independently, but its states can be affected by the Risk Evaluation process. It is not affected by any activity in the KYC Verification process. However, its active state is required before the Risk Evaluation and KYC verification processes can be initiated. Risk Evaluation The process where the defined user profile containing the user information is checked against the various local and global financial blacklist and sanctioned personalities, to screen and prevent bad actors from gaining access to the financial capabilities of the platform. This process runs independently, but it requires the User state to be active for it to be initiated. It is not affected by any activity in the KYC Verification process. KYC Verification The process involves the uploading of the required customer KYC documents to the platform. The data presented in these KYC documents should correlate with and verify that the information provided in the user profile is legitimate and authentic. This process runs independently, but it requires the User state to be active for it to be initiated. It is not affected by any activity in the Risk Evaluation process. Figure: User, Risk, and KYC interaction and state diagram The state diagram below illustrates how the Individual User Definition, Risk Evaluation, and KYC Verification processes interact and affect one another. Before a user is granted access to any financial facilities and capabilities within the platform, the USER, RISK, and KYC must be in an approved or green status . These are the states depicted with a GREEN border: Onboarding Process Required Status Description Individual User Definition user.status.text = ACTIVE The user profile required information is completed Risk Evaluation user.risk_assessment_status = CLEARED The risk evaluation result did not garner any hits on the user profile when it was checked against all the available blacklists. KYC Verification kyc.kyc_status = APPROVED The submitted KYC documents and data authenticated the legitimacy of the information in the user profile. Related Links Identity & onboarding overview Users overview Individual users [v1] Register customer profile [v1] Submit customer KYC [v1] Customer eKYC [v1] Performing eKYC [v2] Onboard Individual users Business users • [Register individual profile](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-individual-user-v1/register-customer-profile.md): Learn how to create an individual user profile, the foundational step for onboarding a new user. Understand this initial process of registering an individual on the platform before proceeding with identity verification. Use Cases You want to onboard an individual user who is a natural person, not a business or corporate entity. You want to onboard an individual user who will use an account for personal purposes. You want to onboard an individual user who is a single employee, contractor, or affiliate of a corporate entity. Prerequisites Before starting to collect individual user information from your customers, refer to the User Protection Guidelines , which all platform consumers and partners must follow and adhere to with regard to securing customer data. You will need to collect the user information from the individual customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application. Individual User data The data that needs to be collected from the customer can be broken down into these groups: API mandatory (minimum) user details — are the vital identity information necessary to create a user in the system. User demographic information — includes additional statistics and location details for users. API Workflow (v1) 1 Create an individual user profile in the program (segmented) You have the option to gradually collect user information through a segmented profile form to lower onboarding friction and improve sign-up conversion. You can call the Create User ( POST /users ) to create a user by passing the API mandatory (minimal) information first: Create User request passing only the API mandatory (minimal) information CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v1/users' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'first_name="John"' \ --data-urlencode 'last_name="Smith"' \ --data-urlencode 'mobile_country_code="65"'\ -—data-urlencode 'mobile="999999999"' \ --data-urlencode 'preferred_name="John Smith"'\ --data-urlencode 'email="john.smith@matchmove.com"'\ --data-urlencode 'password="p@ssw0rd"'\ --data-urlencode 'nationality="Singaporean"' Create User response (minimal information provided) JSON { "id": "cd896adb395fa384a5a8b174a007c34c", "email": "john.smith@matchmove.com", "name": { "first": "John", "middle": null, "last": "Smith", "preferred": "John Smith" }, "nature_of_business": "", "purpose_of_account": "", "mobile": { "country_code": "65", "number": "99999999" }, "nationality": "Singaporean", "countryofissue": null, "country_of_issue": null, "country_code_of_issue": null, "identification": { "type": "", "number": "", "issue": null, "expiry": null }, "alt_id_countryofissue": null, "alt_id_country_code_of_issue": null, "alt_identification": { "type": "", "number": null, "issue": null, "expiry": null }, "birthday": null, "place_of_birth": null, "gender": null, "title": "", "marital_status": null, "mothers_maiden_name": null, "mothers_first_name": null, "mothers_last_name": null, "customer_id": null, "links": [ { "rel": "users.wallets", "href": "https://beta-api.mmvpay.com/{{program_code}}/v1/users/wallets", "method": "GET" } ], "status": { "is_active": false, "text": "inactive", "state": "pending" }, "date": { "registration": "2025-07-22T16:05:52+08:00" }, "partner_id": null, "agent_id": null, "client_reference_id": null, "customer_bank_reference": null, "employer_name": null, "employment_type": null, "source_of_funds": null, "occupation": null, "volume_of_assets": null, "account_type": "individual", "risk_assessment_status": "UNKNOWN" } Create User API-required fields enumerations: mobile_country_code allowed values are listed in the Get Mobile Country Code Enumeration ( GET /users/enumerations/mobile_country_code ). nationality allowed values are listed in the Get Nationality Enumeration ( GET /users/enumerations/nationalities ). marital_status allowed values are listed in the Get Marital Status Enumeration ( GET /users/enumerations/marital_status ). gender allowed values are listed in the Get Genders Enumeration ( GET /users/enumerations/genders ). country_code_of_issue allowed values are listed in the Get Countries Enumeration ( GET /users/enumerations/countries ). Use the country code. country_of_issue allowed values are listed in the Get Countries Enumeration ( GET /users/enumerations/countries ). Use the country description. title allowed values are listed in the Get Titles Enumeration ( GET /users/enumerations/titles ). id_type allowed values are listed in the Get ID Types Enumeration ( GET /users/enumerations/id_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . See Utilize Enumerations section to learn more. Other field notes: preferred_name is usually the (First Name + Last Name), which will be used as the default cardholder name for card programs. For non-card programs, we can just pass the same, just to satisfy the API requirement. password is the password used for the direct B2C products of MatchMove. Due to backwards compatibility, this field has been maintained as an API requirement. As such, any dummy password that satisfies the field requirement may be passed. User identifier as a partner foreign key When a new individual user is created, a user identifier ( user.id ) will be generated. In the example above, the user identifier will be the "id": "cd896adb395fa384a5a8b174a007c34c ". It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This user identifier will be heavily used in most post-user creation API, and it will be convenient for you to have it accessible. 2 Add additional required user information (segmented) When the user has already signed up and can log in to your application, you can ask them to complete their user profile to gain access to your services. Call the Update User ( PUT /users ) to update the user profile with their demographic information. Update User-restricted fields: first_name middle_name (optional) last_name preferred_name Updates to the following fields are not allowed when: The user is already KYC approved The user status is already active The user has already been issued an account/wallet. Update User request passing the user's demographic information CURL curl --location --request PUT 'https: //{{identity_base_url}}/{{program_code}}/v1/users' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'gender=male' \ --data-urlencode 'title=Mr' \ --data-urlencode 'birthday=1990-09-16' \ --data-urlencode 'id_type=passport' \ --data-urlencode 'id_number=S1234546D' \ --data-urlencode 'country_of_issue=Singapore' \ --data-urlencode 'nationality=Singaporean' \ --data-urlencode 'id_expiry_date=2029-09-16' \ --data-urlencode 'id_date_issue=2024-01-01' Update User response (demographic information) JSON { "id": "cd896adb395fa384a5a8b174a007c34c", "email": "johnsmith@matchmove.com", "name": { "first": "John", "middle": null, "last": "Smith", "preferred": "John Smith" }, "nature_of_business": "", "purpose_of_account": "", "mobile": { "country_code": "65", "number": "99999999" }, "nationality": "Singaporean", "countryofissue": "Singapore", "country_of_issue": "Singapore", "country_code_of_issue": "SGP", "identification": { "type": "passport", "number": "S1234546D", "issue": "2024-01-01T00:00:00+08:00", "expiry": "2029-09-16T00:00:00+08:00" }, "alt_id_countryofissue": null, "alt_id_country_code_of_issue": null, "alt_identification": { "type": "", "number": null, "issue": null, "expiry": null }, "birthday": "1990-09-16", "place_of_birth": null, "gender": "male", "title": "Mr", "marital_status": null, "mothers_maiden_name": null, "mothers_first_name": null, "mothers_last_name": null, "customer_id": null, "links": [ { "rel": "users.wallets", "href": "https://{{server}}/{{program_code}}/v1/users/wallets", "method": "GET" } ], "status": { "is_active": false, "text": "inactive", "state": "pending" }, "date": { "registration": "2025-06-04T16:13:37+08:00" }, "partner_id": null, "agent_id": null, "client_reference_id": null, "customer_bank_reference": null, "employer_name": null, "employment_type": null, "source_of_funds": null, "occupation": null, "volume_of_assets": null, "account_type": "individual", "risk_assessment_status": "CLEARED" } 3 [Alternative] Create an individual user profile in the program (complete) If onboarding friction is not an issue, partners can also onboard and create a user in one go, passing both the mandatory (minimal) and demographic information. Create User request passing all required information CURL curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v1/users' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'first_name="John"' \ --data-urlencode 'last_name="Smith"' \ --data-urlencode 'mobile_country_code="65"'\ --data-urlencode 'mobile="999999999"' \ --data-urlencode 'preferred_name="John Smith"'\ --data-urlencode 'email="john.smith@matchmove.com"'\ --data-urlencode 'password="p@ssw0rd"'\ --data-urlencode 'nationality="Singaporean"' \ --data-urlencode 'gender=male' \ --data-urlencode 'title=Mr' \ --data-urlencode 'birthday=1990-09-16' \ --data-urlencode 'id_type=passport' \ --data-urlencode 'id_number=S1234546D' \ --data-urlencode 'country_of_issue=Singapore' \ --data-urlencode 'nationality=Singaporean' \ --data-urlencode 'id_expiry_date=2029-09-16' --data-urlencode 'id_date_issue=2024-01-01' Create User response (all required information) JSON { "id": "cd896adb395fa384a5a8b174a007c34c", "email": "johnsmith@matchmove.com", "name": { "first": "John", "middle": null, "last": "Smith", "preferred": "John Smith" }, "nature_of_business": "", "purpose_of_account": "", "mobile": { "country_code": "65", "number": "99999999" }, "nationality": "Singaporean", "countryofissue": "Singapore", "country_of_issue": "Singapore", "country_code_of_issue": "SGP", "identification": { "type": "passport", "number": "S1234546D", "issue": "2024-01-01T00:00:00+08:00", "expiry": "2029-09-16T00:00:00+08:00" }, "alt_id_countryofissue": null, "alt_id_country_code_of_issue": null, "alt_identification": { "type": "", "number": null, "issue": null, "expiry": null }, "birthday": "1990-09-16", "place_of_birth": null, "gender": "male", "title": "Mr", "marital_status": null, "mothers_maiden_name": null, "mothers_first_name": null, "mothers_last_name": null, "customer_id": null, "links": [ { "rel": "users.wallets", "href": "https://{{server}}/{{program_code}}/v1/users/wallets", "method": "GET" } ], "status": { "is_active": true, "text": "active", "state": "active" }, "date": { "registration": "2025-06-04T16:13:37+08:00" }, "partner_id": null, "agent_id": null, "client_reference_id": null, "customer_bank_reference": null, "employer_name": null, "employment_type": null, "source_of_funds": null, "occupation": null, "volume_of_assets": null, "account_type": "individual", "risk_assessment_status": "CLEARED" 4 Submit the residential and billing addresses of the user The residential and billing addresses of an individual user are vital information that will be considered during the full KYC verification of the user. The residential address determines the regulatory requirements that will be applied to the user, while the billing address will be the reference for card ordering and delivery processes. Call the Update User Addresses ( PUT /users/addresses/residential ) to update the user profile with their residential addresses. Update User Addresses request (residential) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/addresses/residential' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'address_1=50' \ --data-urlencode 'address_2=Sunrise St' \ --data-urlencode 'city=01-01' \ --data-urlencode 'state=Singapore' \ --data-urlencode 'country=Singapore' \ --data-urlencode 'country_code=SGP' \ --data-urlencode 'zipcode=399999' Update User Addresses response (residential) JSON { "residential": { "address_1": "50", "address_2": "Sunrise St", "city": "01-01", "country": "Singapore", "country_code": "SGP", "state": "Singapore", "zipcode": "399999" } } Call the Update User Addresses ( PUT /users/addresses/billing ) to update the user profile with their billing addresses. The billing address can be the same as the residential address. Update User Addresses request (billing) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/addresses/billing' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'address_1=50' \ --data-urlencode 'address_2=Sunrise St' \ --data-urlencode 'city=01-01' \ --data-urlencode 'state=Singapore' \ --data-urlencode 'country=Singapore' \ --data-urlencode 'country_code=SGP' \ --data-urlencode 'zipcode=399999' Update User Addresses response (billing) JSON { "billing": { "address_1": "50", "address_2": "Sunrise St", "city": "01-01", "country": "Singapore", "country_code": "SGP", "state": "Singapore", "zipcode": "399999" } } 5 Display the customer profile details for the user Call the Get User ( GET /user ) to retrieve the active user profile and details. Get User request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: Basic ••••••' \ --data-urlencode 'id={{user_id}}' Get User response JSON { "id": "cd896adb395fa384a5a8b174a007c34c", "email": "john.smith@matchmove.com", "name": { "first": "John", "middle": null, "last": "Smith", "preferred": "John Smith" }, "nature_of_business": "", "purpose_of_account": "", "mobile": { "country_code": "65", "number": "99999999" }, "nationality": "Singaporean", "countryofissue": "Singapore", "country_of_issue": "Singapore", "country_code_of_issue": "SGP", "identification": { "type": "passport", "number": "S1234546D", "issue": "2024-01-01T00:00:00+08:00", "expiry": "2029-09-16T00:00:00+08:00" }, "alt_id_countryofissue": null, "alt_id_country_code_of_issue": null, "alt_identification": { "type": "", "number": null, "issue": null, "expiry": null }, "birthday": "1990-09-16", "place_of_birth": null, "gender": "male", "title": "Mr", "marital_status": null, "mothers_maiden_name": null, "mothers_first_name": null, "mothers_last_name": null, "customer_id": null, "links": [ { "rel": "users.wallets", "href": "https://beta-api.mmvpay.com/<product-code>/v1/users/wallets", "method": "GET" } ], "status": { "is_active": true, "text": "active", "state": "active" }, "date": { "registration": "2025-06-04T16:13:37+08:00" }, "partner_id": null, "agent_id": null, "client_reference_id": null, "customer_bank_reference": null, "employer_name": null, "employment_type": null, "source_of_funds": null, "occupation": null, "volume_of_assets": null, "account_type": "individual", Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v1] Submit customer KYC [v1] Customer eKYC [v1] Performing eKYC [v2] Onboard Individual users Business users • [Submit individual KYC](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-individual-user-v1/submit-customer-kyc.md): Learn the process of submitting the required information and documentation for individual user identity verification. This guide provides an overview of the Know Your Customer (KYC) requirements needed for verification. Use Cases You want to submit the required KYC documents needed to verify the identity of an individual user. You want to submit supporting documents that will help in the individual user identity verification. You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove KYC endpoints. Prerequisites The individual user profile must already be completed. Refer to the Register customer profile (v1) section for more details. The individual user profile risk assessment status must not be risk_flagged . The individual user profile must be in an active status. API Workflow (v1) 1 Check if an individual user is allowed to submit KYC Before allowing a user to submit their KYC documents, we must first verify their current KYC status. This means that if the user's KYC status is not listed below, the entry point or screen for initiating KYC submission must be hidden from the partner app interface. A user can only send a KYC submission for verification if their KYC status is: not_submitted - the user has never submitted a KYC for verification rejected - the user can now resubmit because their previous KYC submission was rejected during verification Call Get KYC ( GET /users/authentications/documents ) to retrieve the KYC status of an individual user. Get KYC request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ Get KYC response JSON { "count": "n/a", "status": "not_submitted" } 2 Collect and upload supporting documents User documents can be collected via the partner's mobile or web app and uploaded via the KYC API. Document required for upload: Front image of the identification/travel card Back image of the identification/travel card Selfie/full-face image Proof of residence*/residency document, e.g., utility bill, bank statements, etc. Translation documents (if submitted documents are not in English) *Only required if the user's address is not obtainable from the ID/travel cards. Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 8MB per file No. of files: maximum 50 files Call Create KYC ( POST /users/authentications/documents ) to upload KYC documents. This method only allows for the upload of a single document. For multiple documents, this API should be called for each document upload. Create KYC-required field enumerations: document_type allowed values are listed in the Document Types Enumeration ( GET /users/enumerations/document_types ). kyc_type allowed values are listed in the KYC Types Enumeration ( GET /users/enumerations/kyc_types ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Create KYC request (upload required KYC documents) CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'data=<base64_encoded_image> ' \ --data-urlencode 'document_type={{document_type}}' \ --data-urlencode 'kyc_type=MM_DOCUMENT_UPLOAD' Create KYC response (upload required KYC documents) JSON { "count": 1, "documents": [ { "document_id": "", "document_type": "selfie", "kyc_type": "MM_DOCUMENT_UPLOAD", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/30FyROnArptb6UHvTGMc8HVdnh8.jpg" } ], "status": "pending" } 3 Confirm all uploads and submit KYC for approval Once all the required documents have been uploaded, the partner must confirm and finalize KYC for submission. This invokes the KYC verification process with the MatchMove Compliance team. Call Confirm KYC ( PUT /users/authentications/documents ) to finalize the uploaded documents and queue the submission for KYC approval. Confirm KYC request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Confirm KYC response JSON { "count": 1, "status": "submitted" } 4 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Title Description Action ACCOUNT.KYC.VERIFICATION_START KYC Initiate Verification Started A notification is sent in the event that the user completes the eKYC form . No action required. ACCOUNT.KYC.VERIFICATION_COMPLETED KYC Initiate Verification Success A notification is sent in the event the external eKYC service provider verification process is completed. No action required. ACCOUNT.KYC.VERIFICATION_FAILED KYC Initiate Verification Failed A notification is sent in the event a failure happens on any process after a verification is completed. No action required. The verification process will auto-retry. ACCOUNT.KYC.VERIFICATION_APPROVED KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved No action required. You may now proceed to provision the user with financial products such as accounts and cards. ACCOUNT.KYC.VERIFICATION_REJECTED KYC Verification Rejected A notification is sent in the event that the KYC status of the user is updated to rejected along with a reject code You may ask the user to retry or redo another round of KYC submission. Sample webhook payload JSON { "event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED", "program_code": "sgdemo", "timestamp": "2025-11-27 17:32:46+0800", "request_id": "89d69adb-53ff-4e67-9518-db2f8e555a79", "trace_id": "a2ba30e56005441f97d4ee4be3d53f46_ca91c8763c5b45eb9e51c714351f6388", "webhook_id": "56b767f6-c0b1-4e2d-8445-01d824d60c97", "event_data": { "message_id": "a6c8ad82-1c32-490c-93aa-9db094cfc3a5", "program_code": "sgdemo", "status": "pre-kyc", "timestamp": "2025-11-27 17:32:46+0800", "retry_counter": 0, "user": { "user_hash": "a2ba30e56005441f97d4ee4be3d53f46", "email": "john.smith@mathcmove.com", "mobile": "9886689021", "mobile_country_code": "63", "status": "rejected", "sub_status": "account_rejected_by_issuer", "kyc_status": "completed", "kyc_sub_status": "rejected", "transaction_status": "terminated", "transaction_sub_status": "transaction_blocked_by_issuer", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "provider_ref_id": "HMAP251127010416239", "profile": { "first_name": "JOHN", "middle_name": "WILLIAMS", "last_name": "SMITH", "preferred_name": "JOHN SMITH", "gender": "MALE", "title": "MR", "nationality": "PHL", "marital_status": "SINGLE", "birth": { "date": "1997-07-17" }, "email": "john.smith@matchmove.com", "mobile": "9886689021", "mobile_country_code": "63", "addresses": { "residential": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "billing": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "shipping": {}, "identity_verification": {} }, "employment_details": { "employment_type": "EMPLOYED_REGULAR", "business_trading_name": "MatchMove Pay", "business_address": { "line_1": "Shaw blvd", "line_2": "Pasig city", "line_3": ".", "line_4": "NCR", "city": "PASIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" } }, "mothers_details": { "maiden_name": "Steven" }, "identification": { "primary": { "id_type": "NATIONAL_ID", "id_number": "3013691154861952", "id_issuance_country": "PHL", "id_date_issued": "2025-11-27", "id_date_expiry": "2027-11-27" }, "secondary": {} }, "main_income_source": "OTHERS", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "user_agent": "", "service_agreement": "" } } }, "authentication_documents": { "count": 3, "status": "completed", "sub_status": "rejected", "failure_reason": "", "reject_reason_code": [ { "code": "DOCUMENT_ID_REJECTED", "description": "The id document submitted is rejected" } ], "documents": [ { "type": "id", "side": "front", "id": "363BCiNTxnclrEF2RCaGT19J2Hq", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCiNTxnclrEF2RCaGT19J2Hq.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:08+0800" } }, { "type": "id", "side": "back", "id": "363BCzCfZOJnEOEauVrgcBqYcmx", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCzCfZOJnEOEauVrgcBqYcmx.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:10+0800" } }, { "type": "selfie", "id": "363BD56x5UdHMIvmmTvHn2sERXC", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/selfie/download/363BD56x5UdHMIvmmTvHn2sERXC.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:11+0800" } } ] }, "webhook_event": "ACCOUNT.KYC.VERIFICATION_REJECTED" }, "provider_response": { "code": -1, "message": "FAIL", "httpCode": null, "data": null, "success": false }, "provider_http_status_code": 200, "retry_attempt": 0, "max_retry_attempts": 0, "max_retry_age": 0, "message": "" } 5 Add supplementary documents to the KYC submission At any stage of the KYC approval and review process, the following can happen: Pre-KYC Approval During the KYC review, MatchMove Compliance may request some additional documents on the customer profile that they are reviewing. Specially for high-risk customers who will be required to undergo an Enhanced Due Diligence (EDD) process. Additional documents on top of the standard requirements will be asked to be uploaded for the EDD. Post-KYC Approval MatchMove Compliance conducts routine audits on approved KYC profiles to check for document expiry, change of address, etc. These scenarios may require customers to upload up-to-date documents and other supplementary documents to help validate the scenario changes. To upload the required supplementary documents, the partner will need to use the same document upload API that was used for the KYC submission. Call Create KYC ( POST /users/authentications/documents ) to upload supplementary documents. Create KYC request (upload supplementary documents) CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'data=<base64_encoded_image> ' \ --data-urlencode 'document_type={{document_type}}' \ --data-urlencode 'kyc_type=MM_DOCUMENT_UPLOAD' Create KYC response (upload supplementary documents) JSON { "count": 2, "documents": [ { "document_id": "", "document_type": "selfie", "kyc_type": "MM_DOCUMENT_UPLOAD", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/30FyROnArptb6UHvTGMc8HVdnh8.jpg" }, { "document_id": "", "document_type": "proof_of_address", "kyc_type": "MM_DOCUMENT_UPLOAD", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/40CxYOnArptb6UHvTGMc8HVdf0.jpg" } ], "status": "pending" } Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v1] Register customer profile [v1] Customer eKYC [v1] Performing eKYC [v2] Onboard Individual users Business users • [Individual eKYC](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-individual-user-v1/customer-ekyc.md): Understand the concept of electronic Know Your Customer (eKYC) within our platform. This guide explains how to leverage digital methods for individual user identity verification. Document Verification via eKYC Service When the Process eKYC API is invoked, a unique document capture/collection link will be generated for the user. It is recommended for partners to render or display the eKYC web page in an in-app web browser to maintain app stickiness. The eKYC capture link will only be valid for 90 minutes after it is generated. A fresh eKYC link can be generated again using the Process eKYC API when the previous one has not been submitted. Go to the Performing eKYC section to know more about the workflow for generating an eKYC capture link. eKYC Document Capture Web Pages The verifying user will go through a series of pages that require the capture of the identity document and a live selfie. eKYC start page Document type selection page The list of supported documents available for upload will depend on the regional document availability and MatchMove Compliance's assessment of document risks. Selected document page Document capture page Depending on the selected document, a back image of the document may be required. Live selfie capture page Confirmation page eKYC Web Page Customization To maintain the partner's brand coherence with the standalone eKYC pages, a few look-and-feel customizations are supported. These include customization to text, buttons, links, pop-ups, icons, and background colors. The customized changes must be defined using the listed parameters below and must be passed to the Process KYC API customization argument. Supported UI parameters for customization: Parameter Description font_family_title Change the font family of the screen titles font_family_subtitle Change the font family of the screen subtitles font_family_body Change the font family of the screen body font_size_title Change font size of the screen titles font_size_subtitle Change font size of the screen subtitles font_size_body Change font size of the screen body font_weight_title Change font weight on SDK screen titles (number format only, e.g., 400, 600) font_weight_subtitle Change font weight on SDK screen subtitles (number format only, e.g,. 400, 600) font_weight_body Change font weight on SDK screen content (number format only, e.g,. 400, 600) color_content_title Change the text color of the screen titles color_content_subtitle Change the text color of the screen subtitles color_content_body Change the text color of the screen body color_background_surface_modal Change the background color of the screen color_border_surface_modal Change the color of the SDK screen border border_width_surface_modal Change the border width of the screen border_style_surface_modal Change the border style on the screen border_radius_surface_modal Change the border radius of the screen color_content_button_primary_text Change the color of the Primary Button text color_background_button_primary Change the background color of the Primary Button color_background_button_primary_hover Change the background color of the Primary Button on hover color_background_button_primary_active Change the background color of the Primary Button on click/tap color_border_button_primary Change the color of the Primary Button border color_content_button_secondary_text Change the color of the Secondary Button text color_background_button_secondary Change the background color of the Secondary Button color_background_button_secondary_hover Change the background color of the Secondary Button on hover color_background_button_secondary_active Change the background color of the Secondary Button on click/tap color_border_button_secondary Change the color of the Secondary Button border color_content_doc_type_button Change Document Type Button text color color_background_doc_type_button Change the background color of the Document Type Button color_border_doc_type_button Change the color of the Document Type Button border color_border_doc_type_button_hover Change the color of the Document Type Button border on hover color_border_doc_type_button_active Change the color of the Document Type Button border on click/tap color_background_icon Change the color of the background circle of pictogram icons in the SDK border_radius_button Change the border radius value of the Primary, Secondary, and Document Type Option buttons color_content_link_text_hover Change Link text color color_border_link_underline Change Link underline color color_background_link_hover Change the Link background color on hover color_background_link_active Change the link background color on click/tap color_content_alert_info Change the warning pop-up text color color_background_alert_info Change the warning pop-up background color color_content_alert_info_link_hover Change warning popup fallback Link background on hover color_content_alert_info_link_active Change warning popup fallback Link background on click/tap color_content_alert_error Change the error pop-up text color color_background_alert_error Change the error pop-up background color color_content_alert_error_link_hover Change error popup fallback, Link background on hover color_content_alert_error_link_active Change error popup fallback Link background on click/tap color_background_info_pill Change the background color of the Cross Device, Camera/Mic Permissions screens' information header pill color_content_info_pill Change the text color of the Cross Device, Camera/Mic Permissions screens' information header pill color_background_button_icon_hover Change the background color of the Back and Close icon buttons on hover color_background_button_icon_active Change the background color of the Back and Close icon buttons on click/tap color_background_button_camera_hover Change the background color of the Live Selfie/Document Capture screens' Camera button on hover color_background_button_camera_active Change the background color of the Live Selfie/Document Capture screens' Camera button on click/tap Document Verification via National eKYC Service In certain regions, like Singapore and India, a system to access the national registry of residents' profiles is available. For these regions, MatchMove also provides support to integrate with the National KYC Service to allow data collection with the national registry as the source, instead of capturing documents via the eKYC Service. The user profile, demographics, and identifications that will be collected will follow the same due diligence requirements as stated by the regional regulators. KYC Lifecycle Management After the initial KYC Verification has been approved and completed, there could be some scenarios that may trigger a re-verification. This includes and may not be limited to: The customer record is getting risk-flagged A customer document on file is reaching expiry The Issuing or Banking Partner rejected the KYC because the compliance team flagged some verified documents, requiring re-verification. Partners are expected to handle the above scenarios and ensure that the KYC process is re-initiated for the affected customers. KYC Webhooks Since the KYC process is an asynchronous activity that crosses multiple systems, immediate feedback may not always be possible. Even for the eKYC services, where the verification process is automated, an immediate response will only happen to users who submitted clean and no-issue documents. One way to get timely KYC status updates is to subscribe to webhooks and be notified when the KYC status changes. Alternatively, partners can also do a status pull when needed using the Get KYC Details API. KYC-related webhook events that can be subscribed to: Code Name Remarks ACCOUNT.KYC.VERIFICATION_START KYC Initiate Verification Started This notifies the program if the user completes the SDK form ACCOUNT.KYC.VERIFICATION_COMPLETED KYC Initiate Verification Success This notifies the program if the external KYC service provider verification process is completed ACCOUNT.KYC.VERIFICATION_FAILED KYC Initiate Verification Failed This notifies the program if a failure happens on any process after a verification is completed ACCOUNT.KYC.VERIFICATION_APPROVED KYC Verification Approved This notifies the program if the KYC status of the user is updated to approved ACCOUNT.KYC.VERIFICATION_REJECTED KYC Verification Rejected This notifies the program if the KYC status of the user is updated to rejected, along with a reject code KYC Failures The review process is continuous and periodic. A user's KYC status may be downgraded based on periodic audits, suspicious activity, or outdated documentation. During events where a KYC is rejected, an appropriate reason for the rejection will be sent in the webhook payload. The rejection reason can be an array of reason codes highlighted below: Reason Code Description DOCUMENT_QUALITY The documents uploaded are of bad quality / cropped out of frame DOCUMENT_AUTHENTICITY The documents submitted are suspected to be not being genuine DOCUMENT_DEMOGRAPHIC_MATCH The demographic information of the user doesn't match the information extracted from documents LIVELINESS_AUTHENTICATION The liveliness check of the user has failed EXPIRED_DOCUMENTS The document information present in the system has expired UNSPECIFIED The reason for rejection is reserved for the time being Simulating KYC Status During the development stage, the automated KYC and Risk evaluation engines may not be in full effect compared to the live environment. Thus, we cannot guarantee that certain user profiles will get a rejection or approval. For this, we have added support to mock and simulate KYC approval. Approval We will need to add or update the word “Approved” to the LAST NAME of the user to force an approval. e.g. Last name: Approved John Approved Rejection We will need to add or update the word “Rejected” to the LAST NAME of the user to force a rejection. This will return the rejection reason: DOCUMENT_DEMOGRAPHIC_MATCH e.g. Last name: Rejected John Rejected Pending Review or Flagged for Review We will need to add or update the word “Pending” to the LAST NAME of the user to force a review. This will return the rejection reason: DOCUMENT_QUALITY e.g. Last name: Pending John Pending FAQs List of commonly asked questions on the KYC integration: Does the user have the option to upload documents from the Phone Gallery or files? For the document upload flow from the native SDK, right now, we require a real-time capture of documents, and uploading from the gallery is not supported. How are device permissions managed? When the camera is invoked, the user will be prompted for the permission request. Once the user has granted the permission, the SDK can utilize the camera functionality. What are the limitations and restrictions on the images to be uploaded? The maximum image size should not exceed 8 MB, and the maximum documents that can be uploaded is 30. What screen will appear when the final selfie is taken? By default, the screen will display the Thank you or confirmation screen. Partners should be able to override this by specifying the new redirect URI in the redirect_uri parameter in the Process KYC Verification API. When a user drops off in the middle of the eKYC workflow, can they restart and restart from where? The eKYC process can be re-initiated if the KYC status is either REJECTED or NOT SUBMITTED. In this case, since the user has not completed the KYC process, the status will be NOT SUBMITTED. For this scenario, the eKYC can be reinitiated, and he will need to start from the first screen again. How do we communicate to the users that their KYC has already been approved? First, we should subscribe to the available KYC webhooks to be notified of KYC status update events. Once the webhook is received, it will come with a payload that contains information on the update. Partners can then pass this information to the customers using an email, an SMS, or a mobile push notification. Lastly, using the app UI, we can display the KYC status by pulling it from the Get KYC Details API. When a user's KYC gets rejected, how many times can they retry? Will he be blocked from retrying too many times? The user can retry and will not be blocked. The blocking constraint may be added in the future if we monitor abuse of the process. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v1] Register customer profile [v1] Submit customer KYC [v1] Performing eKYC [v2] Onboard Individual users Business users • [Perform individual eKYC](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-individual-user-v1/customer-ekyc/perform-an-ekyc.md): Learn how to initiate and complete an electronic Know Your Customer (eKYC) check for a user. This guide covers the end-to-end process of using our eKYC solution to verify a customer's identity. Use Cases You want to submit the required KYC documents needed to verify the identity of an individual user. You want to submit supporting documents that will help in the individual user identity verification. You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove eKYC Provider. You want to implement a feature in your application that will allow individual users to upload supporting documents using the available MatchMove KYC endpoints. The individual user will submit KYC by going through the automated eKYC interface to collect selfies and identification documents. The individual user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism. Prerequisites The individual user profile must already be completed. Refer to the Register customer profile (v1) section for more details. The individual user profile risk assessment status must not be risk_flagged . The individual user profile must be in an active status. API Workflow 1 Check if an individual user is allowed to submit KYC Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface. A user can only send a KYC submission for verification if their KYC status is: not_submitted - the user has never submitted a KYC for verification rejected - the user can now resubmit because their previous KYC submission was rejected during verification Call Get KYC ( GET /users/authentications/documents ) to retrieve the KYC status of an individual user. Get KYC request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get KYC response JSON { "count": "n/a", "status": "not_submitted" } 2 Retrieve the eKYC Provider ID from the available services enabled in the program The availability of eKYC providers will differ from region to region. It will be important to check which one is enabled and configured in your program. Call Get KYC Providers ( GET /oauth/consumer/kyc/providers ) to get the eKYC service provider ID (identifier) that is enabled for your program. Get KYC Provider request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/oauth/consumer/kyc/providers' \ --header 'Authorization: ••••••' Get KYC Provider response JSON { "providers": [ { "id": "pvd_6e4adecc8cc74220a67b8766d879715a", "name": "Onfido", "description": "Verifying real identity in a remote world", "code": "MUAISPONMEJTB12810", "user_type": "customer", "callback_url": "https://beta-api.mmvpay.com", "details": null }, { "id": "pvd_927d1da99a8b4b6fae78baebfea73811", "name": "Matchmove", "description": "Internal Provider", "code": "MUAISPCCWEZIS03738", "user_type": "customer", "callback_url": "https://beta-api.mmvpay.com", "details": null } ] }jso 3 Retrieve the eKYC redirect link to the document collection screen The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents. Call Process KYC Verification ( POST /users/authentications/documents/process ) by passing the eKYC provider ID to get the href or the redirect link to the eKYC web app. Process KYC Verification request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents/process' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'provider_id={{ekyc_provider_id}}' \ --data-urlencode 'user_type=customer' \ --data-urlencode 'user_id={{user_id}} \ --data-urlencode 'program_code={{program_code}}' \ --data-urlencode 'mode=web_sdk'curl Process KYC Verification response JSON { "verification_id": "vfc_add3d8e603664df2ac6161ed78d68a8f", "profile_id": "pfi_2cf00f2a42a04571b73b4bddc06e9ca6", "success": true, "links": [ { "rel": "capture.sdk", "href": "https://identity.uat.matchmove-beta.com/api/v1/web/sdk?id=7bb523ecc983de217a9deaea2f91c400358f1061e5b4361d0d4b64d6dbbd9a718c531b45492818d29a0a4642e545bb35f2s5adae3791348433175d9dd844de4de81ff951", "method": "GET" } ] } The Process KYC Verification API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the customer can perform the KYC document capture and submit their KYC application. The eKYC verification is asynchronous ; some background processing needs to be completed before the approval/rejection can be given. Usually, an automated eKYC verification turnaround time will take instant to a few minutes, provided that all document submissions are clear, legible, and the partner profile aligns perfectly with the document data. 4 Monitor for the approval of the submitted KYC The KYC verification turnaround time follows an SLA from submission to approval. If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “ KYC Service Advisory ” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. KYC Service Advisory webhooks Partners have the option to subscribe to the webhook events related to KYC approval. Title Description Action ACCOUNT.KYC.VERIFICATION_START KYC Initiate Verification Started A notification is sent in the event that the user completes the eKYC form . No action required. ACCOUNT.KYC.VERIFICATION_COMPLETED KYC Initiate Verification Success A notification is sent in the event the external eKYC service provider verification process is completed. No action required. ACCOUNT.KYC.VERIFICATION_FAILED KYC Initiate Verification Failed A notification is sent in the event a failure happens on any process after a verification is completed. No action required. The verification process will auto-retry. ACCOUNT.KYC.VERIFICATION_APPROVED KYC Verification Approved A notification is sent in the event that the KYC status of the user is updated to approved No action required. You may now proceed to provision the user with financial products such as accounts and cards. ACCOUNT.KYC.VERIFICATION_REJECTED KYC Verification Rejected A notification is sent in the event that the KYC status of the user is updated to rejected along with a reject code You may ask the user to retry or redo another round of KYC submission. Sample webhook payload JSON { "event_name": "ACCOUNT.KYC.VERIFICATION_REJECTED", "product_code": "sgdemo", "timestamp": "2025-11-27 17:32:46+0800", "request_id": "89d69adb-53ff-4e67-9518-db2f8e555a79", "trace_id": "a2ba30e56005441f97d4ee4be3d53f46_ca91c8763c5b45eb9e51c714351f6388", "webhook_id": "56b767f6-c0b1-4e2d-8445-01d824d60c97", "event_data": { "message_id": "a6c8ad82-1c32-490c-93aa-9db094cfc3a5", "program_code": "sgdemo", "status": "pre-kyc", "timestamp": "2025-11-27 17:32:46+0800", "retry_counter": 0, "user": { "user_hash": "a2ba30e56005441f97d4ee4be3d53f46", "email": "john.smith@mathcmove.com", "mobile": "9886689021", "mobile_country_code": "63", "status": "rejected", "sub_status": "account_rejected_by_issuer", "kyc_status": "completed", "kyc_sub_status": "rejected", "transaction_status": "terminated", "transaction_sub_status": "transaction_blocked_by_issuer", "is_email_verified": "1", "is_mobile_verified": "1", "is_risk_flagged": "UNKNOWN", "provider_ref_id": "HMAP251127010416239", "profile": { "first_name": "JOHN", "middle_name": "WILLIAMS", "last_name": "SMITH", "preferred_name": "JOHN SMITH", "gender": "MALE", "title": "MR", "nationality": "PHL", "marital_status": "SINGLE", "birth": { "date": "1997-07-17" }, "email": "john.smith@matchmove.com", "mobile": "9886689021", "mobile_country_code": "63", "addresses": { "residential": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "billing": { "line_1": "5", "line_2": "Sunny St", "line_3": ".", "line_4": "NCR", "city": "TAGUIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" }, "shipping": {}, "identity_verification": {} }, "employment_details": { "employment_type": "EMPLOYED_REGULAR", "business_trading_name": "MatchMove Pay", "business_address": { "line_1": "Shaw blvd", "line_2": "Pasig city", "line_3": ".", "line_4": "NCR", "city": "PASIG_CITY_NCR", "state": "NCR", "country": "PHL", "postal_code": "1632" } }, "mothers_details": { "maiden_name": "Steven" }, "identification": { "primary": { "id_type": "NATIONAL_ID", "id_number": "3013691154861952", "id_issuance_country": "PHL", "id_date_issued": "2025-11-27", "id_date_expiry": "2027-11-27" }, "secondary": {} }, "main_income_source": "OTHERS", "fatca_crs_confirmed_at": "0001-01-01T00:00:00Z", "tos_acceptance": { "date": "0001-01-01T00:00:00Z", "ip": "", "user_agent": "", "service_agreement": "" } } }, "authentication_documents": { "count": 3, "status": "completed", "sub_status": "rejected", "failure_reason": "", "reject_reason_code": [ { "code": "DOCUMENT_ID_REJECTED", "description": "The id document submitted is rejected" } ], "documents": [ { "type": "id", "side": "front", "id": "363BCiNTxnclrEF2RCaGT19J2Hq", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCiNTxnclrEF2RCaGT19J2Hq.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:08+0800" } }, { "type": "id", "side": "back", "id": "363BCzCfZOJnEOEauVrgcBqYcmx", "id_type": "NATIONAL_ID", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/id/download/363BCzCfZOJnEOEauVrgcBqYcmx.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:10+0800" } }, { "type": "selfie", "id": "363BD56x5UdHMIvmmTvHn2sERXC", "status": "uploaded", "link": "https://storage-service.mmvpay.com/api/v1/files/sgdemo/selfie/download/363BD56x5UdHMIvmmTvHn2sERXC.jpg", "provider_document_id": "", "date": { "created": "2025-11-27T14:34:11+0800" } } ] }, "webhook_event": "ACCOUNT.KYC.VERIFICATION_REJECTED" }, "provider_response": { "code": -1, "message": "FAIL", "httpCode": null, "data": null, "success": false }, "provider_http_status_code": 200, "retry_attempt": 0, "max_retry_attempts": 0, "max_retry_age": 0, "message": "" } } 5 Add supplementary documents to the KYC submission At any stage of the KYC approval and review process, the following can happen: Pre-KYC Approval During the KYC review, MatchMove Compliance may request some additional documents on the customer profile that they are reviewing. Specially for high-risk customers who will be required to undergo an Enhanced Due Diligence (EDD) process. Additional documents on top of the standard requirements will be asked to be uploaded for the EDD. Post-KYC Approval MatchMove Compliance conducts routine audits on approved KYC profiles to check for document expiry, change of address, etc. These scenarios may require customers to upload up-to-date documents and other supplementary documents to help validate the scenario changes. To upload the required supplementary documents, the partner will need to use the same document upload API that was used for the KYC submission. Call Create KYC ( POST /users/authentications/documents ) to upload supplementary documents. Create KYC request (upload supplementary documents) CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/users/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'data=<base64_encoded_image> ' \ --data-urlencode 'document_type={{document_type}}' \ --data-urlencode 'kyc_type=MM_DOCUMENT_UPLOAD' Create KYC response (upload supplementary documents) JSON { "count": 2, "documents": [ { "document_id": "", "document_type": "selfie", "kyc_type": "MM_DOCUMENT_UPLOAD", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/30FyROnArptb6UHvTGMc8HVdnh8.jpg" }, { "document_id": "", "document_type": "proof_of_address", "kyc_type": "MM_DOCUMENT_UPLOAD", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/40CxYOnArptb6UHvTGMc8HVdf0.jpg" } ], "status": "pending" } Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v1] Register customer profile [v1] Submit customer KYC [v1] Customer eKYC [v2] Onboard Individual users Business users • [[v1] Onboard business users](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-business-users-v1.md): Understand the complete onboarding workflow for business users, from profile registration to successful KYB verification. This guide provides a comprehensive overview of the steps needed to activate a business account. Business User onboarding involves the following processes: Business User Registration The process involves capturing the required business user information along with corporate representative data and submitting it to the platform to create a business user profile or user entity that represents the customer. This process runs independently, but its states can be affected by the Risk Evaluation process. It is not affected by any activity in the KYC Verification process. However, its active state is required before the Risk Evaluation and KYC verification processes can be initiated. Risk Evaluation The process where the defined business user profile containing the corporate information is checked against the various local and global financial blacklist and sanctioned personalities, to screen and prevent bad actors from gaining access to the financial capabilities of the platform. This process runs independently, but it requires the User state to be active for it to be initiated. It is not affected by any activity in the KYC Verification process. KYB Verification The process involves uploading the required business KYB documents to the platform. The data presented in these KYB documents should correlate with and verify that the information provided in the business user profile is legitimate and authentic. This process runs independently, but it requires the Business User state to be active for it to be initiated. It is not affected by any activity in the Risk Evaluation process. Figure: User, Risk, and KYB interaction and state diagram The state diagram below illustrates how the Business User Definition, Risk Evaluation, and KYB Verification processes interact and affect one another. Before a business user is granted access to any financial facilities and capabilities within the platform, the USER, RISK, and KYC must be in an approved or green status . These are the states depicted with a GREEN border: Onboarding Process Required Status Description Business User Definition user.status_text = ACTIVE The business user profile required information is completed Risk Evaluation user.risk_assessment_status = CLEARED The risk evaluation result did not garner any hits on the business user profile when it was checked against all the available blacklists KYB Verification kyb.kyb_status = APPROVED The submitted KYB documents and data authenticated the legitimacy of the information in the business user profile. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v2] Onboard business users • [Register business profile](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-business-users-v1/register-business-profile.md): The Register business profile section is designed to streamline the process for businesses to get started on our platform. Users can easily create and manage their business profiles and access essential features to kickstart their operations. Use Cases You want to onboard a business user who is a business or corporate entity, not a natural person. You want to onboard a business user who will use an account for business purposes. You want to onboard a business user who is a sub-entity (sub-account) of the main program partner. You want to onboard a business user who is a corporate client (sub-account) of the main program partner. You want to onboard a business user who is a corporate client sub-entity (client sub-account) of your corporate client (sub-account). Prerequisites Before starting to collect business user information from your customers, refer to the User Protection Guidelines , which all platform consumers and partners must follow and adhere to with regard to securing customer data. Collect business information from the corporate customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application. Business User data The data that needs to be collected from the business can be broken down into these groups: Business profile and legal identifiers - Vital identity information is required to create a user in the system. These will include legal business names, representative contacts, and other relevant details. Business demographics details - Additional statistics, foundation, and operational addresses of the business entity. API Workflow (v1) 1 Create a business user profile in the program You can start registering a business profile when the business profile and legal identifiers are ready. Call Create Business User ( POST /businesses ) to create a business profile for the corporate entity that you are onboarding. Create Business User API-required fields enumerations: mobile_country_code allowed values are listed in the Get Mobile Country Code Enumeration ( GET /users/enumerations/mobile_country_code ). tax_id_type allowed values are listed in the Get Business ID Types Enumeration ( GET /users/enumerations/business_id_types ). source_of_funds values are listed in the Get Source of Funds Enumeration ( GET /users/enumerations/business_source_of_funds ). tax_identification.issuance_country allowed values are listed in the Get Countries Enumeration ( GET /users/enumerations/countries ). Use the country code. purpose_of_account_opening allowed values are listed in the Get Purpose of Account Enumeration ( GET /users/enumerations/business_purpose_of_account ). *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . See Utilize Enumerations section to learn more. Create Business User request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/businesses' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'name="XYZ Corp"' \ --data-urlencode 'preferred_name="XYZ Corp"' \ --data-urlencode 'mobile_country_code="65"' \ --data-urlencode 'mobile="88888888"' \ --data-urlencode ‘email=corporate@xyz.com' \ --data-urlencode ‘role=SUB_PARTNER_USER' \ --data-urlencode 'tax_id_number=AA12345' \ --data-urlencode 'tax_id_type=tin' \ --data-urlencode 'foundation_date=2019-08-24' \ --data-urlencode 'tax_id_date_issued=2019-08-24' \ --data-urlencode 'tax_id_date_expiry=2025-08-24' \ --data-urlencode 'tax_id_issuance_country=SGP' Create Business User response JSON { "id": "121a84f24763990b12a6c55e2993ac4a", "account_type": "business", "email": "corporate@xyz.com", "name": { "business": "XYZ Corp", "preferred": "XYZ Corp" }, "mobile": { "country_code": "65", "number": "88888888" }, "status": { "is_active": false, "text": "inactive", "state": "pending" }, "foundation_date": "", "date": { "registration": "2025-07-24T11:56:59+08:00" }, "client_ref_id": "", "role"="SUB_PARTNER_USER", "source_of_funds": "BUSINESS", "purpose_of_account_opening": "", "additional_details": "", "tax_identification": { "type": "tin", "number": "AA12345", "issuance_country": "", "date_issued": "2019-08-24", "date_expiry": "2025-08-24" }, "role": "End User", "risk_assessment_status": "CLEARED" } Business user identifier as a partner foreign key When a new business user is created, a user identifier (user.id) will be generated. In the example above, the user identifier will be the "id": "121a84f24763990b12a6c55e2993ac4a" . It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This business user identifier will be heavily used in most post-user creation API, and it will be convenient for you to have it accessible. 2 Update the foundation and operational address of the business The foundation address type (mandatory) refers to the address where the business was incorporated or established. The operational address type (optional) refers to the address currently used as the center of business. Call Update Business Addresses ( PUT /businesses/addresses/foundation ) to update the foundation address of the business. Update Business request (foundation address) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/addresses/foundation' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'address_1=50' \ --data-urlencode 'address_2=Sunrise St.78' \ --data-urlencode 'city=01-01' \ --data-urlencode 'state=Singapore' \ --data-urlencode 'country=Singapore' \ --data-urlencode 'country_code=SGP' \ --data-urlencode 'zipcode=399999'curl Update Business response (foundation address) JSON { "foundation": { "address_1": "50", "address_2": "Sunrise St.78", "city": "01-01", "country": "Singapore", "country_code": "SGP", "state": "Singapore", "zipcode": "399999" } } Call Update Business Addresses ( PUT /businesses/addresses/operational ) to update the operational address of the business. The operational address can be the same as the foundation address. Update Business request (operational address) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/addresses/operational' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'address_1=50' \ --data-urlencode 'address_2=Sunrise St.78' \ --data-urlencode 'city=01-01' \ --data-urlencode 'state=Singapore' \ --data-urlencode 'country=Singapore' \ --data-urlencode 'country_code=SGP' \ --data-urlencode 'zipcode=399999' Update Business response (operational address) JSON { "operational": { "address_1": "50", "address_2": "Sunrise St.78", "city": "01-01", "country": "Singapore", "country_code": "SGP", "state": "Singapore", "zipcode": "399999" } } 3 Prepare for the KYB submission process The data for connected parties and beneficial owners will usually be enclosed inside the uploaded KYB documents and not directly accessible unless the documents are reviewed. So to aid faster identification of these individuals and connected entities for KYB approval and audits, we will need to prepare at least their basic details and add them to the business profile. Since all data passed to the business profile will directly be viewable in the administrator dashboard by the MatchMove Compliance team for review. When available, the details of the connected parties and beneficial owners can be passed through the additional_details field of the business profile. You can use the Create Business User (during initial profile creation) or the Update Business User (as a profile update) endpoint to pass these details. Business user profile additional_details template: JSON { "beneficial_owners": [ { "entity_type": "individual | business", "ownership_percentage": "0 to 100", "business_name": "mandatory if entity_type = business, else NA", "foundation_date": "mandatory if entity_type = business, format = YYYY-MM-DD, else NA", "shareholder": { "type": "owner | authorized_signatory", "first_name": "mandatory", "middle_name": "optional, else blank", "last_name": "mandatory", "dob": "YYYY-MM-DD" } }, .. ]} Call Update Business User ( PUT /businesses ) to update the business profile with the additional details that will be required for full KYB verification. Update Business User request (additional_details) CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/{{business_user_id}}' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'additional_details={ "beneficial_owners": [ { "entity_type": "individual", "ownership_percentage": "10", "business_name": "NA", "foundation_date": "NA", "shareholder": { "type": "owner", "first_name": "John", "middle_name": "", "last_name": "Smith", "dob": "1980-01-01" } } ] }' Update Business User response (additional_details) JSON { "id": "121a84f24763990b12a6c55e2993ac4a", "account_type": "business", "email": "corporate@xyz.com", "name": { "business": "XYZ Corp", "preferred": "XYZ Corp" }, "mobile": { "country_code": "65", "number": "88888888" }, "status": { "is_active": false, "text": "inactive", "state": "pending" }, "foundation_date": "", "date": { "registration": "2025-07-24T11:56:59+08:00" }, "client_ref_id": "", "source_of_funds": "BUSINESS", "purpose_of_account_opening": "", "additional_details": { "beneficial_owners": [ { "entity_type": "individual", "ownership_percentage": "10", "business_name": "NA", "foundation_date": "NA", "shareholder": { "type": "owner", "first_name": "John", "middle_name": "", "last_name": "Smith", "dob": "1980-01-01" } } ] }, "tax_identification": { "type": "tin", "number": "AA12345", "issuance_country": "", "date_issued": "2019-08-24", "date_expiry": "2025-08-24" }, "role": "End User", "risk_assessment_status": "CLEARED" "risk_assessment_status": "CLEARED" Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users [v1] Submit business KYB [v1] Supported KYB documents • [Submit business KYB](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-business-users-v1/submit-business-kyb.md): The Submit business KYB section allows users to verify the business and connected parties to comply with Know Your Business (KYB) regulations. By utilizing this functionality, users can ensure the authenticity and accuracy of their business information, enhancing trust and compliance within their operations. Use Cases You want to submit the required KYB documents needed to verify the identity of a business user. You want to submit supporting documents that will help in the business user verification. You want to implement a feature in your application that will allow business users (representatives) to upload documents using the available MatchMove KYB endpoints. Prerequisites The business user profile must already be completed. Refer to the Register business profile section for more details. The business user profile risk assessment status must not be risk_flagged . The business user profile must be in an active status. The required business and supplemental documents listed in the Standard Operating Procedure for Compliance Management guide are prepared and ready for upload. Standard Operating Procedure (SOP) for Compliance Management This document is the MatchMove Compliance guide detailing the rules and regulations surrounding the onboarding of individual and business users. You may reach out to your Implementation Manager to access this document. API Workflow 1 Check if a business user is allowed to submit KYB We must check the business user's KYB submission status to see when the KYB entry points in the mobile or web app are shown. Otherwise, it should be hidden from display. A user can only send a KYB submission for verification if their KYB status is: not_submitted - the user has never submitted a KYB for verification Call Get Business User KYB ( GET /businesses/authentications/documents ) to get the KYB status of the business. Get the Business User KYB request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/authentications/documents' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Authorization: ••••••' Get the Business User KYB response JSON { "count": "n/a", "status": "not_submitted" } 2 Collect and upload the required KYB business and supplemental documents Business documents that can certify the validity and authenticity of your business profile are required. These can include certificates of incumbency, constitution documents, etc. Connected parties and beneficial owners are individuals or entities with a material controlling interest in the business. These include, but are not limited to, any director, partner, or person with executive authority. Call Create KYB ( POST /businesses/authentications/documents ) to submit/upload the required documents to verify a business. This method only allows for the upload of a single document. For multiple documents, this API should be called for the upload of each document. Documents required for KYB upload: Refer to the Standard Operating Procedure (SOP) for Compliance Management document Document upload restrictions: File format : PNG, JPEG, PDF File size : maximum 8MB per file Number of files : maximum 50 files Create KYB-required field enumerations: document_type allowed values are listed in the Business Document Types Enumeration ( GET /users/enumerations/business_document_types ). kyb_type allowed values are listed in the KYC Types Enumeration ( GET /users/enumerations/kyc_types ). For more details on each supported business document, you can check the Supported KYB documents section. *These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}} . Create KYB request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/authentications/documents' \ --header 'X-Auth-User-ID: {{business_user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'data=<base64_encoded_image> ' \ --data-urlencode 'document_type=<document_type>' \ --data-urlencode 'kyb_type=MM_DOCUMENT_UPLOAD' Create KYB response JSON { "documents": [ { "document_id": "", "document_type": "board_resolution", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}>/kyc/download/2uQsu5nr1eRfabOqYxNMZgJpoOc.jpg", "kyb_type": "MM_DOCUMENT_UPLOAD" } ], "count": 1, "status": "pending", "sub_status": "pending registration submission" } 3 Confirm all uploads and submit KYB for approval Once all the required documents have been uploaded, the partner must confirm and finalize KYB for submission. This invokes the KYB verification process with the MatchMove Compliance team. Call Confirm KYB ( PUT /business/authentications/documents ) to finalize the uploaded documents and queue the submission for KYB approval. Confirm KYB request CURL curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/business/authentications/documents' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Confirm KYB response JSON { "count": 1, "status": "submitted" } Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users [v1] Register business profile [v1] Supported KYB documents • [Supported KYB documents](https://developer.matchmove.com/matchmove-banking-operating-system/deprecated/onboard-business-users-v1/supported-kyb-documents.md): Learn about the types of documents required for Know Your Business (KYB) verification. This guide serves as a reference for the accepted documentation needed to successfully verify a business entity. The table below lists the documents that may be required for business onboarding. Document Type Code Description board_resolution A signed document by company directors authorizing specific actions (e.g., opening an account). Example: Board Resolution for Account Opening. certificate_of_incorporation Legal document issued upon company formation. Confirms company name, number, and incorporation date. Example: Gov-issued Cert. of Incorporation. certificate_of_registration Proof that the company is registered with local regulatory authorities. Used in place of incorporation certs in some jurisdictions. certificate_of_good_standing A document proving the company complies with statutory requirements and is legally active. Usually issued by a regulatory authority. memorandum_and_articles_of_association Foundational company documents detailing structure, roles, responsibilities, and governance. Required for KYB verification. certificate_of_incumbency Confirms names of current directors and key officers. Typically issued by a company secretary or registered agent. connected_party_photo_id Government-issued photo ID (passport or national ID) of UBOs, directors, or signatories. Required for identity verification. connected_party_proof_of_address Utility bill, bank statement, or government-issued letter showing residential address of connected parties (dated within 3 months). due_diligence_questionnaire A filled form capturing detailed business information for AML and compliance assessment. business_address_proof Utility bill, lease agreement, or government letter confirming company’s physical office address. accounting_corporate_regulatory_authority_report Business registration details retrieved from a government portal (e.g., ACRA BizFile for Singapore companies) if available for the country. organizational_structure Visual/chart or document showing ownership layers, UBOs, and control persons. Required for complex structures. transaction_originator_form Form identifying the party initiating transactions on behalf of the entity. Mandatory for Singapore MPI-licensed entities. compliance_personal_details CV, ID, and background information of the Compliance Officer. Shows qualifications and role responsibility. financial_statements Audited or management accounts showing the company's financial health. Required for financial and risk review. Related Links Identity & onboarding overview Users overview Individual users [v1] Onboard Individual users [v2] Onboard Individual users Business users [v1] Onboard business users [v2] Onboard business users [v1] Register business profile [v1] Submit business KYB • [Accounts overview](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview.md): Flexible multipurpose accounts for your business use case The Account is a digital ledger object that functions as the root payment instrument and primary source of funds. It is analogous to a wallet. The system enforces a one-to-one relationship between a user profile and an account, where each account is designated by a unique identifier called a Wallet ID . Account-related API and Webhooks Account Category API / Webhook Availability Description Wallet / Account Issuance Create Account v1 Provision a KYC-approved user with an account Wallet / Account Issuance Get Account v1 Retrieve the account provisioned to a user Webhooks No webhooks are available — Webhooks are only available for asynchronous transactions. Wallet creation transactions are synchronous transactions that will provide a success and failure response after execution. Related Links Account overview Account types Standard accounts mJIT™ accounts Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Account types](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/account-types.md): To begin product configuration, the partner must select one of two account types. This choice determines the available capabilities that can be enabled for the program. Standard accounts A normal balance (shared balance) program refers to a product configuration where the balance is only maintained at the master account level. All cards linked to the account will use the available balance at the account level to process card payments. mJIT™ accounts The mJIT™ program is a specialized type of product configuration, fit for specific use cases. For mJIT™ programs, there is no balance available at the user account level. At the point of processing payments, the prefund balance available at a program level is pulled in a just-in-time manner to the account and debited again to process the transaction. Standard account vs mJIT™ account Configuration Standard Account mJIT™ account Wallet Limits The wallet limits approved for the program restrict this account type. The wallet limits approved for the program restrict this account type. Wallet Balance The account type holds its value or balance This account type does not hold its value or balance. Rather, this account is always kept zeroized (set to zero). The partner will need to maintain their own “partner ledger” where they can keep the records of debits and credits against their "customer assigned balance". The mJIT™ account is discussed in detail in this section . Wallet Transactions (Closed-Loop) Since this account holds a balance, transfers between wallets and the program prefund will be available through the API. Since this account does not hold a balance, transfers between wallets and program prefund are not available through the API. Card Transactions (Open-Loop) On this account type, MatchMove will fully manage the card transaction authorization process. ( Optional ) But partners can still be involved in the authorization if they decide to implement the Shared Authorization model. On this account type, the card transaction authorization is to be shared between the partner and MatchMove. ( Mandatory ) Partners must take part in the authorization process by implementing the Shared Authorization model. Record Keeping The record of credits and debits against the account and balance will be maintained in the MatchMove ledger. This will include transactions made directly on the wallets or made indirectly in conjunction with card transactions. The records of credits and debits against the partner's assigned balance will only be maintained on the partner's ledger. Related Links Account overview Standard accounts mJIT™ accounts Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Standard accounts](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/account-types/standar-accounts.md): Understanding the Standard Account Type The Standard Account is structured around a centralized balance model, wherein all capital is held in a single master account. This architecture streamlines fund management by creating a unified pool of funds accessible by multiple linked payment cards. The following sections detail its principal components and functionalities. Wallet Limits The account is governed by limits configured at the program level. These limits apply to the master account as a whole, not to individual cards linked to it. Wallet Balance The core of the Standard Account is its centralized/shared balance . All funds, whether from top-ups or incoming transfers, are credited to this single master account, also known as a wallet. This balance represents the total available funds for all financial activities associated with the account. Wallet Transactions All non-card transactions directly impact the central wallet balance. This includes: Top-ups: Adding funds to the account increases the account balance. Transfers: Sending or receiving money from other accounts will debit or credit the account balance. Partner fees: Any service fees are deducted directly from this account balance. Every transaction is recorded and immediately reflected in the total available funds. Card Transactions In a standard account, all funds are held in a single master account. Every card linked to this account draws from this central balance to process payments. For example, if an account has a $1,000 balance with three linked cards, all three cards share that same $1,000. If one card is used for a $400 purchase , the available balance for all cards immediately becomes $600 . Therefore, the balance in the master account determines the collective spending power for every linked card. The cards act as access points to the single pool of funds, rather than holding individual balances themselves. Shared Authorization model is also available as an optional feature for Standard Account types. This will enable the partner to participate in the authorization process by having the ability to run their own business logic before a transaction is authorized. However, on the standard account, a “partner ledger” and a debit to the “customer assigned balance” are not required on the partner side. The approval or rejection given by the partner will be based only on the business logic that they ran. Record Keeping A significant advantage of the Standard Account model is simplified record-keeping . Since all transactions—whether they are top-ups, transfers, or purchases from any linked card—are tied to a single master account, they are consolidated into one unified statement. This provides a complete and chronological history of all financial activity, making it easy to track spending and manage finances without needing to reconcile multiple statements. Related Links Account overview Account types mJIT™ accounts Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [mJIT™ accounts](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/account-types/mjit-tm-accounts.md): Understanding the mJIT™ Account Type The mJIT ™ (MatchMove Just-In-Time) Account is an advanced account type designed for partners who want to manage customer balances on their own systems. Instead of storing funds directly in the wallet, this model maintains the wallet balance at zero and employs a mechanism that pulls funds from the main prefund just-in-time to approve a transaction. This provides greater control and flexibility over fund management. Wallet Limits Even though an mJIT account maintains a zero balance, it is still governed by the overall wallet limits approved for the program. These restrictions, which may include daily transaction counts, spending caps, and other velocity checks, apply to the account to ensure all activity remains within the program's defined operational and compliance boundaries. Wallet Balance The defining feature of an mJIT account is that it does not hold a balance . The account is always "zeroized," meaning its balance on the platform is maintained at zero. Since the balance is not kept in the MatchMove ledger, the partner is responsible for maintaining their own "partner ledger." This external ledger is where the partner records all customer debits and credits, effectively tracking transactions made against their “ customer assigned balance “ on their own systems. This assigned balance is dependent on the partner's relationship with the customer. MatchMove will have no visibility on this ”assigned balance,” and the platform will refer to the prefund balance for card transactions. Wallet Transactions Since the mJIT account does not hold a balance on the platform, certain transactions are unavailable. Specifically, direct API-based transfers between wallets or from a program pre-fund account are not supported for this account type. Card Transactions Card transactions on an mJIT account require a Shared Authorization model. This is a mandatory process where both the partner and MatchMove participate in approving a transaction. Here’s how it works: A cardholder initiates a purchase. The transaction request is sent to the MatchMove platform by the card network. The platform will send a pre-authorization webhook (containing details of the payment request) to the partner. The partner will receive the pre-authorization webhook and run their own business logic. The partner checks their external ledger to confirm if the customer has sufficient funds and proceeds to debit their ledger. The partner responds with an approval or denial to the platform. If approved, funds are pulled "just-in-time" from the partner prefund to settle the transaction. This collaborative process ensures that transactions are only approved when the partner confirms the availability of funds in their own system. This also assumes that the partner has subscribed to the pre-authorization webhook, which enables the Shared Authorization model. Record Keeping With the mJIT model, the official record of credits and debits is maintained exclusively on the partner's ledger . Since the platform wallet remains at zero, it will not provide a transactional history of balance changes. The partner assumes full responsibility for accurately tracking all customer funds and transaction histories on their end. Related Links Account overview Account types Standard accounts Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Provision user accounts](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/provision-account-for-user.md): Learn the process for creating a new user account on the platform. Understand how to provision the necessary foundation for your users to access financial features. The user in this document pertains to both the individual and business user types. Use Case You want to provision an account (wallet) to a user, which enables access to the financial capabilities offered on the platform. Prerequisite The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user must not own any account or wallet yet. API workflow 1 Create an account for the user The account or wallet is the placeholder of customer funds and the ledger that records all debits and credits made by the customer and performed against the account. That is why account creation is necessary before any payment instrument or asset can be created and any financial transaction can be initiated. Call the Create Account ( POST /users/wallets ) to open an account and associate it with a user profile. Create Account request CURL curl --location --request POST 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Create Account response JSON { "id": "<user_id>", "number": "6377021205375825", "holder": { "name": "John Smith" }, "funds": { "available": { "currency": "USD", "amount": "0.00" }, "withholding": { "currency": "USD", "amount": "0.00" } }, "token": { "type": "CVV", "generation": "dynamic" }, "date": { "expiry": "2030-09", "issued": "2025-09-02", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/<program_code>/card-small.png", "medium": "https://assets.mmvpay.com/global/products/<program_code>/card-medium.png", "large": "https://assets.mmvpay.com/global/products/<program_code>/card-large.png" }, "status": { "is_active": true, "text": "active" }, "reason": null, "details": { "max_load_limit": null, "network_type": "MatchMove", "fee": "0.00", "fee_currency": "USD", "purse": { "pre_kyc": { "purse_max_limit": 0 }, "post_kyc": { "purse_max_limit": 500000 } }, "topup_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "deduct_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "transfer_in_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "transfer_out_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "load_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "unload_limits": { "pre_kyc": { "unit_transactional_limit": 750, "daily_transactional_limit": 2250, "daily_count_limit": null, "weekly_transactional_limit": 2250, "weekly_count_limit": null, "monthly_transactional_limit": 2250, "monthly_count_limit": null, "annual_transactional_limit": 15000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "remittance_limits": { "pre_kyc": { "unit_transactional_limit": 0, "daily_transactional_limit": 0, "daily_count_limit": null, "weekly_transactional_limit": 0, "weekly_count_limit": null, "monthly_transactional_limit": 0, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": 0, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 500000, "daily_transactional_limit": 500000, "daily_count_limit": null, "weekly_transactional_limit": 500000, "weekly_count_limit": null, "monthly_transactional_limit": 1000000, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "reversal_limits": { "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "refund_limits": { "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } } }, "kit": "000005518998" } Related Links Account overview Account types Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Access account information](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/access-account-information.md): Learn how to access information for a specific user account. Understand the process for retrieving key details such as the account status and available balances. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the account details of a specific user. You want to retrieve the outstanding balance of an account belonging to a specific user. You want to retrieve the outstanding transaction limits available for a specific user account. You want to retrieve the list of cards associated with a specific user account. Prerequisites The user profile risk assessment status must not be risk_flagged . The user profile must be in an active status. The user must have an approved KYC or KYB status. The user account or wallet must be in an active status. API Workflow 1 Retrieve customer account details The customer account or wallet is the main financial asset that enables all financial capabilities in the platform. Thus, the wallet will be linked to all other financial instruments that are owned by the same user. Call Get Account ( GET /users/wallets ) to get the full account or wallet details of the customer. Get Account request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Account response JSON { "funds": { "available": { "currency": "SGD", "amount": "0.00" }, "withholding": { "currency": "SGD", "amount": "0.00" }, "categories": { "DEFAULT": { "available": { "currency": "SGD", "amount": "0.00" }, "withholding": { "currency": "SGD", "amount": "0.00" } } } }, "id": "e4fe41fbdd28ce09fe2f7aa27b2299e5", "number": "6377021438215970", "holder": { "name": "John Smith" }, "token": { "type": "CVV", "generation": "dynamic" }, "date": { "expiry": "2028-12", "issued": "2023-12-19", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/<program_code>/card-small.png", "medium": "https://assets.mmvpay.com/global/products/<program_code>/card-medium.png", "large": "https://assets.mmvpay.com/global/products/<program_code>/card-large.png" }, "status": { "is_active": true, "text": "active" }, "reason": null, "details": { "max_load_limit": null, "network_type": "MatchMove", "fee": "0.00", "fee_currency": "SGD", "purse": { "pre_kyc": { "purse_max_limit": 1000 }, "post_kyc": { "purse_max_limit": 100000 } }, "topup_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "deduct_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "remittance_limits": { "pre_kyc": { "unit_transactional_limit": 0, "daily_transactional_limit": 0, "daily_count_limit": null, "weekly_transactional_limit": 0, "weekly_count_limit": null, "monthly_transactional_limit": 0, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": 0, "lifetime_count_limit": null, "allowed": 0 }, "post_kyc": { "unit_transactional_limit": 0, "daily_transactional_limit": 0, "daily_count_limit": null, "weekly_transactional_limit": 0, "weekly_count_limit": null, "monthly_transactional_limit": 0, "monthly_count_limit": null, "annual_transactional_limit": null, "annual_count_limit": null, "lifetime_transactional_limit": 0, "lifetime_count_limit": null, "allowed": 0 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "transfer_in_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "transfer_out_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 1 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "load_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 0 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 0 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "unload_limits": { "pre_kyc": { "unit_transactional_limit": 1000, "daily_transactional_limit": 3000, "daily_count_limit": null, "weekly_transactional_limit": 3000, "weekly_count_limit": null, "monthly_transactional_limit": 3000, "monthly_count_limit": null, "annual_transactional_limit": 20000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 0 }, "post_kyc": { "unit_transactional_limit": 1000000, "daily_transactional_limit": 1000000, "daily_count_limit": null, "weekly_transactional_limit": 7000000, "weekly_count_limit": null, "monthly_transactional_limit": 30000000, "monthly_count_limit": null, "annual_transactional_limit": 50000000, "annual_count_limit": null, "lifetime_transactional_limit": null, "lifetime_count_limit": null, "allowed": 0 }, "current": { "lifetime_transactional": 0, "lifetime_count": 0, "daily_transactional": 0, "daily_count": 0, "weekly_transactional": 0, "weekly_count": 0, "monthly_transactional": 0, "monthly_count": 0, "annual_transactional": 0, "annual_count": 0 } }, "reversal_limits": { "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "refund_limits": { "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "issuance_limits": { "<card_type_code>": { "pre_kyc": { "allowed": 1, "daily_count_limit": null, "weekly_count_limit": null, "monthly_count_limit": null, "yearly_count_limit": null, "lifetime_count_limit": null }, "rules": [], "post_kyc": { "allowed": 1, "daily_count_limit": null, "weekly_count_limit": null, "monthly_count_limit": null, "yearly_count_limit": null, "lifetime_count_limit": null }, "current": { "daily_count": 0, "weekly_count": 0, "monthly_count": 0, "yearly_count": 0, "lifetime_count": 1 } } }, "active_limits": { "<card_type_code>": { "allowed": 1, "pre_kyc": 5, "post_kyc": 5, "current": 1 } } }, "kit": "000004014410", "cards": [ { "id": "b846591162a0fc71b2c179bd5d9ad424", "status": { "is_active": true, "text": "active" }, "type": [ { "rel": "self", "href": "https://beta-api.mmvpay.com/<program_code>/v1/users/wallets/cards/types/homeezmccard", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://beta-api.mmvpay.com/<program_code>/v1/users/wallets/cards/b846591162a0fc71b2c179bd5d9ad424", "method": "GET" } ] } ] } Related Links Account overview Account types Provision user accounts Understand account limits Virtual accounts overview Issue a virtual account • [Understand account limits](https://developer.matchmove.com/matchmove-banking-operating-system/accounts-overview/understand-account-limits.md): Understand the various limits that apply to a user account. Learn about the different tiers of limits for transactions and balances that govern account activity. Manage and display limits to your customers As regulated products, every account issued is governed by a set of limits. These limits are set depending on product use case, type of entities onboarded, and the jurisdiction of issuance. The limits are decided by the MatchMove Compliance team as per the risk classification and dictated by the regulatory partners and governing bodies. Purse Limits Purse limits denote the maximum funds that can be stored in the account at any given point in time. The system guarantees that funds added to the account will never breach the limit configured depending on the user's state. Get the Account purse limits The purse limit of any account can be retrieved by calling the Get Wallets API. Call Get Wallets ( GET /users/wallets ) to retrieve the account details, which include, but are not limited to, purse and transaction limits. Get Account / Wallet request CURL curl -X GET 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' Get Account / Wallet response (purse limit excerpt) JSON { "details”:{ "purse": { "pre_kyc": { "purse_max_limit": 1000 }, "post_kyc": { "purse_max_limit": 5000 } } } Transaction limits Similarly, every account issued also has transaction limits imposed, depending on the product configured for the program owner. These limits are broken down into applicable transaction types and velocity and count limits for the transaction type. The possible values of limits configured are illustrated in the table below Limit type Description daily_count_limit The number of transactions for the transaction category that can be performed in a given day. The day is defined as per the program issuance region. daily_transactional_limit The cumulative value of the transactions in the issuance currency for the transaction category that can be performed on a given day. The day is defined as per the product issuance region. lifetime_count_limit Total Number of transactions for the transaction category that can be performed for the lifetime of the account lifetime_transactional_limit The cumulative value of the transactions for the transaction category that can be performed for the lifetime of the account monthly_count_limit The total number of transactions for the calendar month that can be performed for the account. The duration is defined as per the product issuance region monthly_transactional_limit The cumulative value of transactions for the calendar month that can be performed for the account. The duration is defined as per the product issuance region weekly_count_limit The total number of transactions for the calendar week starting on that date can be performed for the account. The duration is defined as per the product issuance region weekly_transactional_limit The cumulative value of transactions for the calendar week can be calculated for the account. The duration is defined as per the product issuance region annual_count_limit The total number of transactions for the calendar year that can be performed for the account. The duration is defined as per the product issuance region annual_transactional_limit The cumulative value of transactions for the calendar year that can be performed for the account. The duration is defined as per the product issuance region unit_transactional_limit The maximum value of a transaction for the transaction category that can be performed at any given point in time. Get Account / Wallet response (transaction limit excerpt) JSON { "details": { "topup": { "pre_kyc": { "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 }, "current": { "lifetime_count": 29, "lifetime_transactional": 12037.25, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 6, "monthly_transactional": 3595.79 } } } } Related Links Account overview Account types Provision user accounts Access account information Virtual accounts overview Issue a virtual account • [Virtual accounts overview](https://developer.matchmove.com/matchmove-banking-operating-system/virtual-accounts-overview.md): Enable your accounts to be funded by traditional banking channels A Virtual Account is a proxy account that can be created against an account issued by MatchMove Platform. This virtual account allows the MatchMove-issued virtual account to be plugged into the banking infrastructure to enable the collection of funds via banking channels. You can share your virtual account number with a counterparty, and the counterparty can initiate payments using their virtual accounts from their bank accounts. Types of virtual accounts Depending on the type of user onboarded on the system. There are two different types of virtual accounts that the system supports. Do note that for businesses belonging to the Money service industry, due to regulatory restrictions by the partner, we are unable to issue a USD virtual account. Individual virtual account Virtual accounts are assigned to individuals onboarded in the system. Once issued, individual users can use this virtual account like a normal bank account to transfer funds from their own accounts or request funds by sharing virtual account details and asking them to transfer funds via their bank accounts. Business virtual account Virtual accounts are assigned to businesses onboarded onto the platform. Once issued business can use this account to receive payments from counterparties by sharing the account details. These accounts function like traditional bank accounts, and the counterparty can initiate a payment like they would for any traditional bank account. Virtual account creation modes Depending on the currency of the linked account. The virtual account creation flow can have variations in terms of its lifecycle. The platform supports two processes for virtual account creation Synchronous creation For synchronous virtual account creation, the response to virtual account creation is communicated instantly. Once created, the virtual account is immediately available to be utilised for collecting funds Applicable account currency SGD Asynchronous creation For asynchronous virtual account creation, the virtual account creation takes time to get activated. Only after post-activation can the virtual account be utilized for collecting funds. Applicable account currency USD Virtual account statuses Depending on your program configuration, the virtual account setup will be either a synchronous mode or an asynchronous mode. High-level statuses involved in virtual account creation are listed below: Virtual Account Status Description initialised The virtual account creation request is initialized. pending The virtual account creation request is in progress rejected The virtual account creation request is rejected pending_activation The virtual account creation request is pending activation failed The virtual account creation request has failed. The virtual account creation can be retried. active The virtual account creation request is successful. Virtual Account States A webhook will be sent whenever the virtual account status is changed to pending , rejected , pending_activation , failed , or active . If, for some reason, a virtual account creation request transitions to failed status, it is recommended to restart the virtual account creation process. A virtual account will only be usable and available for transactions once the status is set to active . Figure: Virtual account creation state diagram Virtual Account-related API and Webhooks Virtual Account Category API / Webhook Availability Description Virtual Account Issuance Create Virtual Account v1 Provide a KYC-approved user who owns an account with a virtual account. Virtual Account Issuance Get Linked Virtual Account v1 Retrieve the linked virtual account details of a user. Webhooks Category (non-API) Virtual Accounts Advisory, particularly the webhook events: v1 Webhook category to subscribe to receive notifications on virtual account status updates Webhook Event (non-API) INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS See Leveraging Webhooks Webhook notification on status updates of virtual accounts issued to individual users Webhook Event (non-API) BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS See Leveraging Webhooks Webhook notification on status updates of virtual accounts issued to business users Related Links Account overview Account types Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Provision virtual accounts](https://developer.matchmove.com/matchmove-banking-operating-system/virtual-accounts-overview/issue-a-virtual-card.md): Learn how to issue a dedicated virtual account for a user. Understand how these accounts provide unique details to streamline the process of receiving and sending bank transfers. The user in this document pertains to both the individual and business user types. Use Cases You want to provision a virtual account to a user, which can be used for various collections and payout capabilities offered on the platform. You want to provision and attach a virtual account to a user account to facilitate top-ups and payouts (when available). Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The virtual account capability must be enabled in the program configuration. API Workflow 1 Initiate virtual account creation request Call the Create Virtual Account ( POST /users/wallets/virtual_accounts ) to initiate the creation of a virtual account for a user. Create Virtual Account request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'X-Auth-user-id: {{user_id}}' \ --header 'Authorization: ••••••' Create Virtual Account response (synchronous creation) JSON { "id": "faea7b1d-47bc-4474-a91d-f2c9b6b462b4", "account_holder_name":"John Doe", "account_number":"4441234560000123456", "bank_code": "MAYPSGSGXXX", "status": "active", "created_at": "2024-04-29T14:05:49+08:00", "account_bank_name": "MatchMove Pay Pte Ltd", } Create Virtual Account response (asynchronous creation) JSON { "id": "faea7b1d-47bc-4474-a91d-f2c9b6b462b4", "account_holder_name":"John Doe", "account_number":"4441234560000123456", "bank_code": "DBSSSGSG", "status": "initialised", "created_at": "2024-04-29T14:05:49+08:00", "account_bank_name": "DBS", "account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982", "account_bank_country": "Singapore" } You can use this response to display virtual account details in your application. Make sure to display the status clearly to your user: The virtual account can only accept fund transfers after it has a status active . Transactions initiated before the status becomes active will be rejected. Individual Users: - The virtual account account_holder_name will be based on the registered first_name + middle_name (when available) + last_name of the user. Business Users: - The virtual account account_holder_name will be based on the registered business name . 2 Get virtual account details Call the List Virtual Account ( GET /users/wallets/virtual_accounts ) to get the virtual account details of a user. List Virtual Accounts request CURL curl --location --request GET 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Virtual Account response JSON { "total_records": 1, "records_per_page": 10, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://beta-api.mmvpay.com/sgmmdemo/v1/users/wallets/virtual_accounts?page=1&records_per_page=10", "method": "GET" } ], "data": [ { "id": "b98c1bc7-c872-4704-939d-9a37afc0d21a", "account_holder_name":"John Doe", "account_number":"4441234560000123456", "bank_code": "DBSSSGSG", "status": "pending_activation", "created_at": "2024-04-29T14:15:38+08:00", "account_bank_name": "DBS", "account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982", "account_bank_country": "Singapore" } ] } 3 [Asynchronous creation] Consume webhooks to be notified of virtual account status updates Since virtual account creation is asynchronous, you should subscribe to webhooks to be notified of the virtual account status changes. Virtual Account Advisory webhooks Partners have the option to subscribe to the webhook events related to virtual account status updates. Webhook Description Title INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS A notification is sent in the event that a virtual account of an individual user changes its status. No action required. BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS A notification is sent in the event that a virtual account of a business user changes its status. No action required. Sample virtual account status webhook payload (Individual user) JSON { "consumer": { "consumer_name":"MatchMove Demo", "product_code":"sgmmdemo" }, "account_type": "individual", "payment_instrument":{ "id":"90eb8e97-cd4f-4c27-a5fe-c136xxxxxxxx", "payment_instrument_type":"virtual_account", "status":"active", "remarks":"created successfully", "account_number":"4441234560000123456", "account_holder_name":"John Doe", "bank_code":"MAYPSGSGXXX" }, "individual_details":{ "email":"john.doe@acme.com", "kyc_status":"active", "mobile":"88888888", "mobile_country_code":"65", "id":"547666394dfb916132d0xxxxxxxxxxxx" }, "webhook_event":"INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS" } Sample virtual account status webhook payload (Business user) JSON { "consumer": { "consumer_name":"MatchMove Demo", "product_code":"sgmmdemo" }, "account_type": "business", "payment_instrument":{ "id":"90eb8e97-cd4f-4c27-a5fe-c136xxxxxxxx", "payment_instrument_type":"virtual_account", "status":"active", "remarks":"created successfully", "account_number":"4441234560000123457", "account_holder_name":"ACME PTE LTD", "bank_code":"DBSSGSGXXX", }, "business_details":{ "email":"it@acme.com", "kyc_status":"active", "mobile":"88888888", "mobile_country_code":"65", "id":"547666394dfb916132d0xxxxxxxxxxxx" }, "webhook_event":"BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS" } Related Links Account overview Account types Provision user accounts Access account information Understand account limits Virtual accounts overview Issue a virtual account • [Funds overview](https://developer.matchmove.com/matchmove-banking-operating-system/funds-overview.md): Funds denote a way to move money in and out of a user account within the platform. The movement of funds is governed by the limits configured during product setup. A sufficient pre-fund balance will be required before any movement of funds to the user balance can proceed. Use cases Learn how to use the funds API to manage funds for user accounts on the platform. Credit funds Increase a user's available balance by moving funds from the program prefund (source) to their account (receiver). Debit funds Decrease a user's available balance by moving funds from their account (source) back to the program prefund (receiver). Perform P2P Execute an account-to-account transfer to move funds seamlessly between two platform users. Reverse funds Cancel and reverse a specific, previously settled debit transaction to refund the user's account. Funds-related API and Webhooks Closed-loop transaction Category API / Webhook Availability Description Funds Create Debit Transaction (Wallet to Prefund) v1 Perform a debit to a user account (source) to prefund (receiver). Funds Create Credit Transaction (Prefund to Wallet) v1 Perform a prefund (source) to a user account (receiver) credit Funds Create Credit Transaction (Wallet to Wallet) v1 Perform an account (source) to account (receiver) credit. Funds Create Debit Reversal Transaction v1 Perform a reversal of a previous account debit. Webhooks No webhooks are available — Webhooks are only available for asynchronous transactions. Closed-loop transactions are synchronous transactions that will provide a success and failure response after execution. Related Links Reverse debited funds from a user account Credit funds to a user account Debit funds from a user account Perform an account-to-account (P2P) transfer Transactions overview • [Credit funds to a user account](https://developer.matchmove.com/matchmove-banking-operating-system/funds-overview/credit-funds-to-a-user-account.md): Learn how to directly credit funds to a user's account balance from the prefund. This guide explains the process for making direct balance adjustments, such as issuing refunds, rewards, or making corrections. The user in this document pertains to both the individual and business user types. Use Cases You want to add funds to a specific user account, where the source of funds is the partner prefund. You want to add funds to a specific user account, where the source of funds is a top-up channel that you have integrated. You want to credit funds to a user account for the disbursement of rewards, credit notes, cashbacks, etc. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user account's current topup_limits and purse_max_limit must have enough buffer to accommodate the incoming credit amount. API Workflow 1 Finish your internal validations Ensure that your internal validations are completed. Confirm the receipt of funds to the wallet if the transfer relies on external dependencies. 2 Prepare the payload To facilitate compliance and tracking, prepare the required payload to tag all transactions and identify the source of funds. Additional transaction metadata details.pp - Payment processor, which identifies which type of payment was processed or executed details.transaction_comments - Any message or internal comments on the transaction details.payment_ref - The payment reference identifier generated by the payment service provider details.source_account - The fund source account or card number for the debit or credit details.source_bank_name - The fund source bank name or the bank issuer of the card (when available) details.source_network_name - The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available) 3 Credit funds to the user account from the prefund Call the Create Credit or Transfer Transaction ( POST /users/wallets/funds ) to add funds to the user account. This action will utilize the funds from the program prefund account balance and add it to the program account balance. You can use any of these user identifiers ( user_id, mobile, email ) to identify the destination of the transfer. In this example, we will use the user_id of the owner of the destination account. Create Credit or Transfer Transaction request (recipient: user account) CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'user_id={{user_id}}' \ --data-urlencode 'amount=50' \ --data-urlencode 'details={ \"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_account\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_bank_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_network_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\" }' Reference: Anti-scam Measures Create Credit or Transfer Transaction response (recipient: user account) JSON { "id": "edde2e3c44428660970d11e0b53888b9c3de744c82a3568c70c6f5c8c0023e98", "ref_id": "000002C1000000000003000000000278", "user_id": "cb532825ef5397a0571b3b66f20780d7", "wallet_id": "4cc5efa24dc483f578dcccc17ac6b459", "confirm": "skip", "sor_transaction": null, "category_details": [ { "name": "DEFAULT", "amount": "50.00", "currency": "USD" } ] } 4 Handle errors gracefully As a financial payment platform, we subject every transaction to a series of checks and validations to ensure adherence to the limits configured for the account. Any resulting failures or errors are communicated via the response payload structure shown below. A comprehensive list of error codes for this API is available on the API reference page. Sample error response JSON { "id":"683e98350c1e8", "code":400, "status":"user_parameter_validation_failed", "title":"User Parameter Validation Failed", "description":"Field required not met; amount must be greater than 0", "link":"https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_parameter_validation_failed", "timestamp":"2025-06-03 14:06:41 +08" } 5 Display / notify transaction status to end user Closed-loop transactions, like account crediting, do not have any webhook events associated with them. Since these types of transactions are synchronous, the response and status will be received immediately after API execution. For partners who intend to send a push notification via in-app, email, or SMS — the API response payload containing transaction details and other metadata can be used in message content. To learn more about closed-loop transaction notifications, head to the Anti-Scam Measures section. Related Links Funds overview Reverse debited funds from a user account Debit funds from a user account Perform an account-to-account (P2P) transfer Transactions overview • [Debit funds from a user account](https://developer.matchmove.com/matchmove-banking-operating-system/funds-overview/debit-funds-from-a-user-account.md): Understand the process for debiting funds from a user's account balance. This guide covers how to make direct adjustments for scenarios like applying service fees or making corrections. The user in this document pertains to both the individual and business user types. Use Cases You want to collect funds from a user account, such as subscription fees, platform fees, transaction fees, etc. You want to collect funds from a user account for payment for services or goods rendered by the main partner. You want to “zero out a user account” by transferring all its remaining balance to the partner prefund before the account is closed on the platform. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user account's current deduct_limits must have enough buffer to accommodate the outgoing debit amount. API Workflow 1 Finish your internal validations Ensure that your internal validations are completed. Confirm the receipt of funds to the wallet if the transfer relies on external dependencies. 2 Prepare the payload To facilitate compliance and tracking, prepare the required payload to tag all transactions and identify the source of funds. Additional transaction metadata details.pp - Payment processor, which identifies which type of payment was processed or executed details.transaction_comments - Any message or internal comments on the transaction details.payment_ref - The payment reference identifier generated by the payment service provider details.source_account - The fund source account or card number for the debit or credit details.source_bank_name - The fund source bank name or the bank issuer of the card (when available) details.source_network_name - The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available) 3 Debit funds from a user wallet to the prefund Call Create Debit Transaction ( DELETE /users/wallets/funds ) to debit funds from a user wallet and credit to the prefund. You can use any of these user identifiers ( user_id, mobile, email ) to identify the source of the transfer. In this example, we will use the user_id of the owner of the source account. Create Debit Transaction request CURL curl --location --request DELETE 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'user_id={{user_id}}' \ --data-urlencode 'amount=10' \ --data-urlencode 'details={ \"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"merchant_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\" }' Reference: Anti-scam Measures Create Debit Transaction response JSON { "id": "1ef851022a58f9971334aea933f286db936bba7833ccf476d2f55ece9c0dd308", "ref_id": "000002C1000000000002000000000279", "user_id": "01e09f4194c7640d672574fee7723a1f", "wallet_id": "f6beb0bf2fe263ac1ffb4d30c6d789f0", "confirm": "skip", "sor_transaction": null, "category_details": [ { "name": "DEFAULT", "amount": "10.00", "currency": "USD" } ] } 4 Handle errors gracefully As a financial payment platform, we subject every transaction to a series of checks and validations to ensure adherence to the limits configured for the account. Any resulting failures or errors are communicated via the response payload structure shown below. A comprehensive list of error codes for this API is available on the API reference page. Sample error response JSON { "id":"683e98350c1e8", "code":400, "status":"user_parameter_validation_failed", "title":"User Parameter Validation Failed", "description":"Field required not met; amount must be greater than 0", "link":"https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_parameter_validation_failed", "timestamp":"2025-06-03 14:06:41 +08" } 5 Display/notify transaction status to end user Closed-loop transactions, like account crediting, do not have any webhook events associated with them. Since these types of transactions are synchronous, the response and status will be received immediately after API execution. For partners who intend to send a push notification via in-app, email, or SMS — the API response payload containing transaction details and other metadata can be used in message content. To learn more about closed-loop transaction notifications, head to the Anti-Scam Measures section. Related Links Funds overview Reverse debited funds from a user account Credit funds to a user account Perform an account-to-account (P2P) transfer Transactions overview • [Reverse debited funds from a user account](https://developer.matchmove.com/matchmove-banking-operating-system/funds-overview/reverse-user-account-debit.md): Learn how to reverse a specific debit transaction made from a user's account. This guide explains the process for refunding a particular charge after it has been debited from a user account. The user in this document pertains to both the individual and business user types. Use Cases You want to reverse a previously successful debit on a user account. You want to return a debit that was made to a user account due to an error or mistake. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user account's current topup_limits and purse_max_limit must have enough buffer to accommodate the incoming credit amount. API Workflow 1 Finish your internal validations Ensure that your internal validations are completed. Confirm the receipt of funds to the wallet if the transfer relies on external dependencies. 2 Prepare the payload To facilitate compliance and tracking, prepare the required payload to tag all transactions and identify the source of funds. Additional transaction metadata details.pp - Payment processor, which identifies which type of payment was processed or executed details.transaction_comments - Any message or internal comments on the transaction details.payment_ref - The payment reference identifier generated by the payment service provider details.source_account - The fund source account or card number for the debit or credit details.source_bank_name - The fund source bank name or the bank issuer of the card (when available) details.source_network_name - The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available) 3 Reverse an account debit to return funds to a user's account To reverse a previously debited transaction and return the funds to the source user wallet, you will need to pass the transaction.ID or the transaction ID of the previously successful debit transaction that you want to reverse. Call Create Debit Reversal Transaction ( POST /users/wallets/funds/reversals/{ref_id} ) to reverse a previous debit made to a user account. Create Debit Reversal Transaction request CURL url --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds/reversals/{{transaction_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ -—data-urlencode 'amount=5' \ --data-urlencode 'details={ \"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_account\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_bank_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_network_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\" }' Reference: Anti-scam Measures Create Debit Reversal Transaction response A sample response payload of a successful debit reversal transaction. Please note that a new transaction ID will be generated for the reversal transaction. The only way to correlate the debit and the reversal transaction is through the ref_id or the reference ID of the transaction. JSON { "user_id": "cd896adb395fa384a5a8b174a007c34c", "wallet_id": "033d5a04a5430d67655b7d09aa767d9a", "transaction": { "reversal": { "id": "0bb494e6c5ce11b278bc92aa109e5e30c149e004fa7b8364ed51343b75a7e02a", "ref_id": "000002C100000000020300000000027F", "category_details": [ { "name": "DEFAULT", "amount": "5.00", "currency": "USD" } ] } } } 4 Handle errors gracefully As a financial payment platform, we subject every transaction to a series of checks and validations to ensure adherence to the limits configured for the account. Any resulting failures or errors are communicated via the response payload structure shown below. A comprehensive list of error codes for this API is available on the API reference page. Sample error response JSON { "id":"683e98350c1e8", "code":400, "status":"user_parameter_validation_failed", "title":"User Parameter Validation Failed", "description":"Field required not met; amount must be greater than 0", "link":"https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_parameter_validation_failed", "timestamp":"2025-06-03 14:06:41 +08" } 5 Display/notify transaction status to end user Closed-loop transactions, like account crediting, do not have any webhook events associated with them. Since these types of transactions are synchronous, the response and status will be received immediately after API execution. For partners who intend to send a push notification via in-app, email, or SMS — the API response payload containing transaction details and other metadata can be used in message content. To learn more about closed-loop transaction notifications, head to the Anti-Scam Measures section. Related Links Funds overview Credit funds to a user account Debit funds from a user account Perform an account-to-account (P2P) transfer Transactions overview • [Perform an account-to-account (P2P) transfer](https://developer.matchmove.com/matchmove-banking-operating-system/funds-overview/perform-a-p2p-transfer.md): Learn how to facilitate an account-to-account transfer between two users on your platform. This guide covers the process for moving funds internally from one user's balance to another. The user in this document pertains to both the individual and business user types. Use Cases You want to transfer funds from one user account (source) to another user account (recipient) for payments of goods or services rendered by the recipient. You want to implement a feature in your application that will allow users (source) to pay another user (recipient) for payments of goods or services rendered by the recipient. You want to implement a feature in your application that will allow business users (source) to transfer rebates and rewards to another user (recipient) in the platform. You want to implement a feature in your application that will allow business users (source) to credit salaries and benefits to another user (recipient) in the platform. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user account's current topup_limits and purse_max_limit must have enough buffer to accommodate the incoming credit amount. API Workflow 1 Finish your internal validations Ensure that your internal validations are completed. Confirm the receipt of funds to the wallet if the transfer relies on external dependencies. 2 Prepare the payload To facilitate compliance and tracking, prepare the required payload to tag all transactions and identify the source of funds. Additional transaction metadata details.pp - Payment processor, which identifies which type of payment was processed or executed details.transaction_comments - Any message or internal comments on the transaction details.payment_ref - The payment reference identifier generated by the payment service provider details.source_account - The fund source account or card number for the debit or credit details.source_bank_name - The fund source bank name or the bank issuer of the card (when available) details.source_network_name - The name of the network where the transaction is processed, e.g., Mastercard, VISA, etc. (when available) 3 Credit funds to the user account from the prefund Call the Create Credit or Transfer Transaction ( POST /users/wallets/funds ) to add funds to the user account. This action will utilise the funds from the program prefund account balance and add it to the program account balance. Create Credit or Transfer Transaction request (source: prefund, recipient: user account) CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'email=john.doe@matchmove.com' \ --data-urlencode 'amount=50' \ --data-urlencode 'details={ \"pp\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"transaction_comments\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"payment_ref\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_account\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_bank_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\", \"source_network_name\":\"<SEE_ANTI_SCAM_MEASURES_DOC>\" }' Reference: Anti-scam Measures Create Credit or Transfer Transaction response (source: prefund, recipient: user account) JSON { "id": "edde2e3c44428660970d11e0b53888b9c3de744c82a3568c70c6f5c8c0023e98", "ref_id": "000002C1000000000003000000000278", "user_id": "cb532825ef5397a0571b3b66f20780d7", "wallet_id": "4cc5efa24dc483f578dcccc17ac6b459", "confirm": "skip", "sor_transaction": null, "category_details": [ { "name": "DEFAULT", "amount": "50.00", "currency": "USD" } ] } 4 Handle errors gracefully As a financial payment platform, we subject every transaction to a series of checks and validations to ensure adherence to the limits configured for the account. Any resulting failures or errors are communicated via the response payload structure shown below. A comprehensive list of error codes for this API is available on the API reference page. Sample error response JSON { "id":"683e98350c1e8", "code":400, "status":"user_parameter_validation_failed", "title":"User Parameter Validation Failed", "description":"Field required not met; amount must be greater than 0", "link":"https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_parameter_validation_failed", "timestamp":"2025-06-03 14:06:41 +08" } 5 Display/notify transaction status to end user Closed-loop transactions, like account crediting, do not have any webhook events associated with them. Since these types of transactions are synchronous, the response and status will be received immediately after API execution. For partners who intend to send a push notification via in-app, email, or SMS — the API response payload containing transaction details and other metadata can be used in message content. To learn more about closed-loop transaction notifications, head to the Anti-Scam Measures section. Related Links Funds overview Reverse debited funds from a user account Credit funds to a user account Debit funds from a user account Transactions overview • [Transactions overview](https://developer.matchmove.com/matchmove-banking-operating-system/transactions-overview.md): A transaction is the transfer of funds between two or more financial entities, such as accounts and cards. It is a fundamental concept in finance and accounting that provides a chronological record of all financial activity. Immutable Ledger The transaction registry is an immutable ledger that is the core of the transaction system. It is a record that, once written, cannot be altered or deleted. Every successful debit and credit is recorded permanently, creating a complete and unchangeable history of financial movements. The ledger's immutability ensures that there is a single, trustworthy source of truth for all transactions. This is crucial for auditing , fraud detection , and maintaining the integrity of the financial system. Transaction Data Each transaction recorded in the ledger contains detailed information that identifies exactly what happened. This data acts as a narrative for the fund's movement. Key pieces of information include: Source: The account or card from which the funds were debited. This identifies the sender. Destination: The account or card to which the funds were credited. This identifies the recipient. Amount: The exact value of the funds transferred. Timestamp: The precise date and time the transaction occurred. Unique Transaction ID: A unique identifier assigned to each transaction for tracking and reference. and many more.. A Comprehensive Trail The collection of all transactions acts as a complete audit trail for an account. By examining the ledger, one can trace every single event that has affected an account's balance from its creation to the present day. This transparent and verifiable trail is essential for: Accountability: It shows who initiated a transaction and where the money went, making it easy to identify any unauthorized or fraudulent activity. Dispute Resolution: In case of a billing error or dispute, the transaction trail provides all the necessary evidence to investigate and resolve the issue. Financial Reporting: It allows account holders and auditors to review spending habits, reconcile statements, and generate accurate financial reports. Transaction-related API and Webhooks History Category API / Webhook Availability Description Card Transactions Get Card Transactions v1 Retrieve a list of historical transactions made against a specific card Wallet Transactions Get Wallet Card Transactions v1 Retrieve a list of historical transactions made against an account or wallet Webhooks (non-API) No webhooks available — Webhooks are only available for asynchronous transactions. Getting history is a synchronous call that will provide a success and failure response after execution. Related Links Funds overview Transaction history • [Retrieve transaction history](https://developer.matchmove.com/matchmove-banking-operating-system/transactions-overview/history.md): Understand how to retrieve the transaction history for a user's account. This guide explains how to fetch a list of all ledger activities, including credits, debits, and transfers, for reconciliation and display. The history of transactions can be retrieved at the account level or on the card level . These transactions are records of each debit and credit made against the payment instrument — wallet or card . Note: The transaction history of the User's Account or Card can be retrieved with records not older than 90 days. Wallet Transaction History Wallet transaction history will include all closed-loop fund movements against the account/wallet. It will also keep track of all transactions involving open-loop card debits and credits. Call List Wallet Transactions ( GET /users/wallets/transactions ) to retrieve the list of transactions that happened against the user's wallet. List Wallet Transactions request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/transactions/{{page}}?limit={{records_per_page}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Wallet Transactions response JSON { "transactions": [ { "id": "4b3aca3d5e491eba944583450820d7fc", "type": "Money Transfer Debit", "amount": "1.00", "balance": "93.01", "currency": "USD", "status": "Success", "description": "ACTIVE", "indicator": "debit", "date": "2026-01-23T13:32:06+08:00", "details": { "is_custom_ref_id": "0", "name": "money transfers", "notification": false, "parameters": { "amount": "1.00", "details": { "reason": "p2p_transfer", "reference": "AAAAAAAAAAAAA" }, "email": "joe.smith@matchmove.com", "transfer_type": "send money", "source_currency": "USD", "destination_currency": "USD", "fund_category_id": "1", "fund_category_name": "DEFAULT", "amount_points": "1.00" }, "reason": "p2p_transfer", "receiver": "joe.smith@matchmove.com", "reference": "AAAAAAAAAAAA", "transaction_currency": "USD", "transfer_type": "send money" }, "source": { "id": "7d02bfc0be47de72de5a61438ee31fb7", "number": "6377021205421785", "payment_instrument_type": "wallet" }, "destination": { "id": "77bbb79267c4e6fe498ee4ccc4d3a577", "number": "6377021205047671", "payment_instrument_type": "wallet" } }, { "id": "293a62a8767839a5788f802b637e47d2", "type": "Money Transfer Debit", "amount": "10.00", "balance": "94.01", "currency": "USD", "status": "Success", "description": "ACTIVE", "indicator": "debit", "date": "2026-01-22T19:07:04+08:00", "details": { "is_custom_ref_id": "0", "name": "money transfers", "notification": false, "parameters": { "amount": "10.00", "details": { "reason": "p2p_transfer", "reference": "test" }, "email": "test@matchmove.com", "transfer_type": "send money", "source_currency": "USD", "destination_currency": "USD", "fund_category_id": "1", "fund_category_name": "DEFAULT", "amount_points": "10.00" }, "reason": "p2p_transfer", "receiver": "test@matchmove.com", "reference": "test", "transaction_currency": "USD", "transfer_type": "send money" }, "source": { "id": "7d02bfc0be47de72de5a61438ee31fb7", "number": "6377021205421785", "payment_instrument_type": "wallet" }, "destination": { "id": "c7e5e3cdbd4ab6ce9e284d3355180f23", "number": "6377021205083031", "payment_instrument_type": "wallet" } }, { "id": "a697e643bd46ecc5919694cb2d3b7235", "type": "Cross Border Payout Fee", "amount": "5.05", "balance": "104.01", "currency": "USD", "status": "Success", "description": "ACTIVE", "indicator": "debit", "date": "2026-01-21T20:33:39+08:00", "details": { "id": "T5EREdDOxgDO5kDO2cTMtklTDV0TSd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "recipient": { "id": "0a08ee09721446fdb2a5ad071067fc36", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "ABACUS FEDERAL SAVINGS BANK", "receiving_institution_code": "226072870", "account_name": "Joe Smith", "account_number": "82889128", "account_type": "Savings Account" }, "quote": { "id": "5IETKVVM5cDO5kDO2cTMtklTDV0TSd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": true, "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.05" }, "total": { "currency": "USD", "amount": "5.05" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.05" }, "total": { "currency": "USD", "amount": "5.05" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" }, "total": { "currency": "USD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "100.00" }, "converted_amount": { "currency": "USD", "amount": "94.95" }, "recipient_amount": { "currency": "USD", "amount": "94.95" }, "additional_data": { "purpose_of_payment": "Household Maintenance", "user_occupation": "", "user_recipient_relationship": "", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "0001-01-01 00:00:00", "tos_acceptance_device_id": "", "tos_acceptance_ip": "1.97.48.204", "tos_acceptance_user_agent": "Mozilla/5.0 (iPad; CPU OS 18_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/143.0.7499.92 Mobile/15E148 Safari/604.1", "tos_acceptance_service_agreement": "" }, "remarks": "LOCAL-218-20260121-760402", "created_by": "fdab36e9e1ed4a4a9a191ffa7c2cfbc4", "created_at": "2026-01-21T20:33:38 +08:00", "updated_at": "2026-01-21T20:33:48 +08:00" } }, { "id": "adf66b0429c88653572f84a69eb90b9f", "type": "Cross Border Payout", "amount": "94.95", "balance": "109.06", "currency": "USD", "status": "Success", "description": "ACTIVE", "indicator": "debit", "date": "2026-01-21T20:33:39+08:00", "details": { "id": "T5EREdDOxgDO5kDO2cTMtklTDV0TSd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "recipient": { "id": "0a08ee09721446fdb2a5ad071067fc36", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "ABACUS FEDERAL SAVINGS BANK", "receiving_institution_code": "226072870", "account_name": "jie luo", "account_number": "82889128", "account_type": "Savings Account" }, "quote": { "id": "5IETKVVM5cDO5kDO2cTMtklTDV0TSd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": true, "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.05" }, "total": { "currency": "USD", "amount": "5.05" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.05" }, "total": { "currency": "USD", "amount": "5.05" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" }, "total": { "currency": "USD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "100.00" }, "converted_amount": { "currency": "USD", "amount": "94.95" }, "recipient_amount": { "currency": "USD", "amount": "94.95" }, "additional_data": { "purpose_of_payment": "Household Maintenance", "user_occupation": "", "user_recipient_relationship": "", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "0001-01-01 00:00:00", "tos_acceptance_device_id": "", "tos_acceptance_ip": "1.97.48.204", "tos_acceptance_user_agent": "Mozilla/5.0 (iPad; CPU OS 18_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/143.0.7499.92 Mobile/15E148 Safari/604.1", "tos_acceptance_service_agreement": "" }, "remarks": "LOCAL-218-20260121-760402", "created_by": "fdab36e9e1ed4a4a9a191ffa7c2cfbc4", "created_at": "2026-01-21T20:33:38 +08:00", "updated_at": "2026-01-21T20:33:48 +08:00" } }, { "id": "337f3701713f68646879efc3b0e31e3d", "type": "Money Transfer Debit", "amount": "10.00", "balance": "204.01", "currency": "USD", "status": "Success", "description": "ACTIVE", "indicator": "debit", "date": "2026-01-21T20:31:20+08:00", "details": { "is_custom_ref_id": "0", "name": "money transfers", "notification": false, "parameters": { "amount": "10.00", "details": { "reason": "p2p_transfer" }, "email": "joe.smith@matchmove.com", "transfer_type": "send money", "source_currency": "USD", "destination_currency": "USD", "fund_category_id": "1", "fund_category_name": "DEFAULT", "amount_points": "10.00" }, "reason": "p2p_transfer", "receiver": "joe.smith@matchmove.com", "transaction_currency": "USD", "transfer_type": "send money" }, "source": { "id": "7d02bfc0be47de72de5a61438ee31fb7", "number": "6377021205421785", "payment_instrument_type": "wallet" }, "destination": { "id": "77bbb79267c4e6fe498ee4ccc4d3a577", "number": "6377021205047671", "payment_instrument_type": "wallet" } } ], "records_per_page": 5, "page": 1, "total_records": 5 } Card Transaction History Card transaction history only records the transactions made against cards, and every authorized transaction requires consumption of the wallet balance. Therefore, every authorized card transaction will be accompanied by its respective wallet transaction for the consumption of the wallet balance. Call List Card Transactions ( GET /users/wallets/cards/transactions ) passing the card ID to retrieve the list of transactions that happened against a specific user's card. List Card Transactions request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/{{page}}?limit={{records_per_page}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Card Transactions response JSON { "transactions": [ { "id": "CV_4b9407d51cd8403b988c1398bf21915a", "type": "Credit Voucher", "amount": "0.12", "balance": "488.57", "currency": "SGD", "status": "Success", "description": "SETTLED", "indicator": "credit", "date": "2025-09-02T19:30:08+08:00", "details": { "name": "transaction authorizations", "transaction_currency": "SGD", "merchant_name": "Test Account SGP", "merchant_category_code": "5962", "merchant_location": "", "terminal_id": "TEST1234", "original_transaction_currency": "SGD", "original_transaction_amount": "0.12", "total_fees_charged": "0.00", "total_fees_currency": "SGD", "total_transaction_amount": "0.12", "total_transaction_currency": "SGD", "transaction_mode": "ECOM", "transaction_network": "Master", "additional_details": { "AAV": "", "CSC": "" } } }, { "id": "NAS_96f839a5148548a098a91025691c4d74", "type": "No Auth Settlement", "amount": "1.40", "balance": "488.45", "currency": "SGD", "status": "Success", "description": "SETTLED", "indicator": "debit", "date": "2025-09-02T19:30:04+08:00", "details": { "name": "transaction authorizations", "transaction_currency": "SGD", "merchant_name": "FACEBK ADS fb.me ads SGP", "merchant_category_code": "6012", "merchant_location": "", "terminal_id": "TEST1234", "original_transaction_currency": "SGD", "original_transaction_amount": "1.40", "total_fees_charged": "0.00", "total_fees_currency": "SGD", "total_transaction_amount": "1.40", "total_transaction_currency": "SGD", "transaction_mode": "ECOM", "transaction_network": "Master", "additional_details": { "AAV": "", "CSC": "" } } }, { "id": "P_446a284c393a49c5aa6676d9c2cbf98b", "type": "Purchase", "amount": "0.10", "balance": "489.85", "currency": "SGD", "status": "Success", "description": "SETTLED", "indicator": "debit", "date": "2025-09-02T19:29:53+08:00", "details": { "name": "transaction authorizations", "transaction_currency": "SGD", "merchant_name": "TEST ACCOUNT SGP", "merchant_category_code": "6012", "merchant_location": "PHL", "terminal_id": "TEST1234", "original_transaction_currency": "SGD", "original_transaction_amount": "0.10", "total_fees_charged": "0.00", "total_fees_currency": "SGD", "total_transaction_amount": "0.10", "total_transaction_currency": "SGD", "transaction_mode": "ECOM", "transaction_network": "Master", "additional_details": { "AAV": "", "CSC": "" } } }, { "id": "P_06836f92666b43be9805a441fda858e0", "type": "Authorization Released", "amount": "0.10", "balance": "489.95", "currency": "SGD", "status": "Success", "description": "REVERSED", "indicator": "credit", "date": "2025-09-02T19:29:41+08:00", "details": { "name": "transaction authorizations", "transaction_currency": "SGD", "merchant_name": "TEST ACCOUNT SGP", "merchant_category_code": "6012", "merchant_location": "PHL", "terminal_id": "TEST1234", "original_transaction_currency": "SGD", "original_transaction_amount": "0.10", "total_fees_charged": "0.00", "total_fees_currency": "SGD", "total_transaction_amount": "0.10", "total_transaction_currency": "SGD", "transaction_mode": "ECOM", "transaction_network": "Master", "additional_details": { "AAV": "", "CSC": "" }, "date_reversed": "2025-09-02T19:29:41+08:00" } }, { "id": "P_06836f92666b43be9805a441fda858e0", "type": "Purchase", "amount": "0.10", "balance": "489.85", "currency": "SGD", "status": "Success", "description": "SETTLED", "indicator": "debit", "date": "2025-09-02T19:29:38+08:00", "details": { "name": "transaction authorizations", "transaction_currency": "SGD", "merchant_name": "TEST ACCOUNT SGP", "merchant_category_code": "6012", "merchant_location": "PHL", "terminal_id": "TEST1234", "original_transaction_currency": "SGD", "original_transaction_amount": "0.10", "total_fees_charged": "0.00", "total_fees_currency": "SGD", "total_transaction_amount": "0.10", "total_transaction_currency": "SGD", "transaction_mode": "ECOM", "transaction_network": "Master", "additional_details": { "AAV": "", "CSC": "" } } } ], "records_per_page": 5, "page": 1, "total_records": 5 }} Card Transaction Types - transaction.type Purchase Cash Withdrawal Purchase Reversal ATM Balance Inquiry Fee ATM Cash Withdrawal Fee Balance Inquiry Fee Cross Border Cross Currency Fee Cross Border Fee Cross Currency Fee ATM Balance Inquiry Fee Reversal ATM Cash Withdrawal Fee Reversal Cross Border Fee Reversal Cross Currency Fee Reversal ATM Balance Inquiry Balance Inquiry ATM Balance Inquiry Reversal Credit Voucher Authorization Released Issuer Forex Fee Reversal Cash Withdrawal Reversal Mismatch Reversal Mismatch Debit No Auth Settlement Issuer Surcharge Issuer Surcharge Reversal Account Verification Account Verification Reversal Related Links Funds overview Transactions overview • [Retrieve prefund balances](https://developer.matchmove.com/matchmove-banking-operating-system/retrieve-prefund-balances.md): What is a Prefund? In the context of a financial platform, a prefund refers to the capital deposited in advance by a partner into a centralized reserve—specifically, the partner pool account . This pre-allocated funding acts as working capital to ensure smooth, real-time operations across the platform. Instead of processing bank transfers or settling funds for every individual user transaction one by one, the platform draws directly from this prefunded pool. This allows for instant authorization and seamless processing of everyday activities, such as onboarding users, provisioning accounts, and facilitating transactions. In short, it is the upfront balance required to ensure all subsequent financial movements within the program are fully backed and can execute immediately. Prefund Balances Program (Credit) Prefund Balance The Program Prefund Balance represents the partner's central pool account or their primary institutional account within the platform. It serves as the overarching funding source for the partner's program operations. Debit Prefund Balance The Debit Prefund Balance represents the cumulative total of all individual user account balances within the platform. As new users are onboarded, they are provisioned with their own individual accounts; the debit prefund balance acts as the aggregate sum of the funds held across all of these specific user accounts. In simpler terms, the debit prefund balance is the balance of all your users in the platform. Use Cases You want to know the current program prefund balance of the partner pool account. You want to know the current debit prefund balance, which is the cumulative balance of all the user accounts in the platform. Prerequisites The program has been configured, and the staging stack has been provisioned. The program staging stack has already been handed over to the partner. The partner is already in possession of the API credentials to access the endpoints. API Workflow 1 Retrieve the program prefund balance Call the Get Program Credit (Partner) Prefund ( GET /oauth/consumer/{{consumer_key}}/prefund/credit ) to retrieve the current outstanding balance of the program prefund in the platform. Get Program Credit (Partner) Prefund request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/prefund/credit' \ --header 'Authorization: ••••••'' consumer_key is one of the keys from your API credentials. More details can be found here . Get Program Credit (Partner) Prefund response JSON { "balance": "91224459.010000" } 2 Retrieve the debit prefund balance Call the Get Program Debit (Users) Prefund ( GET /oauth/consumer/{{consumer_key}}/prefund/debit ) to retrieve the current outstanding balance of all the user accounts in the platform. Get Program Debit (Users) Prefund request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/prefund/debit' \ --header 'Authorization: ••••••'' consumer_key is one of the keys from your API credentials. More details can be found here . Get Program Debit (Users) Prefund response JSON { "balance": "7222159.010000" } 3 Keeping track of your prefund balances Keeping a close eye on your prefund balances is crucial to maintaining seamless program operations. Because your platform activities draw directly from this central pool, maintaining an adequate balance ensures that your incoming transactions—such as card and wallet transactions, domestic and cross-border payouts, and other payments within the platform—are always fully funded and can be processed without interruption. To help you manage your funds effectively, we provide two layers of monitoring: 1. Automated Alerts via AdminNet You can easily monitor your funds by setting up custom email notification events directly within AdminNet , your administrator dashboard. By configuring specific balance thresholds, you will receive immediate automated email alerts whenever your prefund is running low, allowing you to top up your account proactively. 2. Proactive Monitoring by Our Finance Department As an added layer of assurance, our Finance Department actively monitors your prefund levels. Using a monthly velocity forecast based on your specific program volume, our team will keep track of your balance trajectory and personally notify your assigned contact if your funds are at risk of running too low. • [Cards overview](https://developer.matchmove.com/matchmove-banking-operating-system/cards-overview.md): Issue cards to your users to spend globally A card is a payment device that enables a user to conduct transactions at merchants. Cards can be physical or virtual. Moreover, users can also tokenize cards for use in digital wallets. The platform enables MatchMove consumers to customize a card’s attributes, behaviors, and lifecycle. Customization also includes limits on spending, the number of card uses, and the number of active cards. Get Started Choose a card product Understand the card product you are offering to the end user. Understand the impact, limitations, and benefits. Choose a funding model Choose the fund management model best suited for your use case. Issue cards Build the experience custom to your application via a simple API integration. Manage Cards Learn how to manage your cards for your end users. Card issuance Understand the lifecycle of a card based on form factor to create your issuance journey Card display Understand how to display card information to your end user while ensuring security. Card PIN management Setting PINs for your users' physical cards for card-present transactions and ATM transactions when required. Card spending controls Setting customized spending limits for transaction categories Card statuses A card entity transitions through various states throughout its lifecycle, determined by the actions applied to it after creation. Figure: Card states diagram Card-related API and Webhooks Cards Issuance Category API / Webhook Availability Description Card Issuance Get Configured Card Types v1 Get defined card types in the program Card Issuance Create Card v1 Create a virtual or physical card for a user Card Issuance Activate Card v1 Activate a physical card of a user Card Issuance Suspend / Block Card v1 Suspend or delete an active user card Card Issuance Reactivate Card v1 Reactivate a suspended card Card Issuance Set Card PIN v1 Define a card PIN for a physical card Card Issuance Retrieve (Non-sensitive) Card Details v1 Retrieve transaction non-critical card information Card Issuance Retrieve (Sensitive) Card Details v2 Retrieve transaction-critical card information xc Authorization Webhooks (non-API) Pre Auth See Get (Platform) Webhook List Webhook category to subscribe to if the partner has a decision logic that occurs before authorizing a transaction. Subscribing to this webhook will enable the Shared Authorization model for financial transactions Authorization Webhooks (non-API) Successful Transaction Notifications See Leverage Webhooks Webhook category to subscribe to receive notifications on completed card transactions Authorization Webhooks (non-API) Decline Transaction Notifications See Leverage Webhooks Webhook category to subscribe to receive notifications on declined card transactions Authorization Webhooks (non-API) Open Loop Reversals See Leverage Webhooks Webhook category to subscribe to receive notifications on reversed card transactions Card Settlement Settlement Advice See Leverage Webhooks Webhook category to subscribe to receive notifications on the real-time availability of downloadable settlement reports for reconciliation Card Spend Controls Category API / Webhook Availability Description Cards Transactional Limits Configure transactional limits for a particular card and category v1 Create a transactional category limit for a specific card Cards Transactional Limits Retrieve transactional limits for a card v1 Retrieve defined transactional category limits on a specific card Cards Transactional Limits Disable transactional limits for a particular card and category v1 Disable an active transactional category limit for a specific card Cards Transactional Limits Retrieve transactional limits for categories v1 Retrieve transactional category limits defined for a category Cards Transactional Limits Update transactional limits for a particular card v1 Update defined transactional category limits Related Links Card overview Create your card product Issue a card Issue a virtual card Link & activate a non-personalized physical card Request for a personalized physical card Activate a personalized physical card Manage card Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Configure card transactional limits Card payment authentication Assisted 3DS authentication Simulate assisted 3DS authentication Card payments Transaction overview Card payment fees Simulate card transactions Transaction authorizations Transaction settlements Manage card security • [Card program operations](https://developer.matchmove.com/matchmove-banking-operating-system/card-program-operations.md): Prepare your business for launch by mastering the operational side of card issuance. Running a successful card program requires more than just a seamless API integration. While your engineering team focuses on the technical build, this section guides you through the critical non-technical milestones required by the MatchMove Banking Operating System, your Banking Partner, and the Payment Networks. Completing these operational steps in parallel with your technical integration ensures you hit your go-live target without compliance, design, or production delays. Explore the guides below to manage your program's end-to-end operational lifecycle: Launch Requirements & Network Approvals Secure your foundational program approvals and regulatory prerequisites before you go live. BIN Assignment: Determine your Bank Identification Number (BIN) strategy, whether you are launching on a fast-to-market shared BIN or requesting a dedicated BIN for sole brand ownership. Program Compliance: Navigate mandatory network registrations, including the Prepaid Program Management (PPM) submission, volume forecasting, and Know Your Business (KYB) due diligence. Launch Timelines: Track expected end-to-end timelines based on your specific program configuration and BIN model. Card Design & Digital Experience Define your card products and get your artwork cleared for production. Every card face—whether a physical piece of plastic or a virtual render in an app—must be approved by the Payment Network. Artwork Approval: Learn the design rules, mandatory network elements, and the submission process to get your physical and virtual card designs approved quickly. Digital-First Certification: If you are launching a numberless card (where sensitive details like the PAN and CVV are hidden on the physical card and only accessed in-app), follow the steps to submit your Digital First Card Program (DFCP) form. Production & Last-Mile Delivery Manage the logistics of getting cards from the production bureau into your cardholders' hands. Distribution Models: Choose how your cards are delivered. Learn the operational differences between personalized direct-to-cardholder courier delivery and distributing non-personalized card stock in bulk at retail or branch locations. Card Personalization: Understand the bureau process for embossing, printing, and encoding physical cards. Linking and Activation: Discover how unassigned card stock is securely linked to a verified user account and the activation steps cardholders must take before their first transaction. • [Launching a card program](https://developer.matchmove.com/matchmove-banking-operating-system/card-program-operations/launching-a-card-program.md): Learn the end-to-end operational process for launching your card program, including mandatory network approvals, compliance submissions, and physical or virtual card design. This guide covers all the non-technical prerequisites you need to complete before your program goes live. Audience: MatchMove Partners launching a card program on the MatchMove Banking Operating System. Scope: The non-technical and operational program activities required to start a card program — BIN (Bank Identification Number) certification and assignment, PPM (Prepaid Program Management) submission and approval, the DFCP (Digital First Card Program) form, and card design and approval. These activities are outside the technical integration with the MatchMove Banking API (Application Programming Interface) and the banking platform. Technical implementation (API integration, UAT (User Acceptance Testing), and go-live) is not covered here — it is a separate track that runs in parallel with the timeline in this document and is documented in Start your implementation on the developer portal. Regional availability: Product capabilities, BIN types, funding models, and process details described in this document vary by region, Financial Institution, and Payment Network. Not all features are available in all markets. Your MatchMove Program Manager will confirm what applies to your program and region during project kick-off. Document validity: Published August 14, 2026 The processes, requirements, and timelines described in this document are true as of this writing and are subject to change by the Payment Networks and Financial Institutions without prior notice. Regional nuances apply throughout the workflow — the exact sequence, forms, review durations, and approval requirements can differ by market. Always confirm the current process with your MatchMove Account and Implementation Manager before relying on this document for planning. 1. Overview Launching a card program involves four parties working in sequence and in parallel: Stakeholder Role in the Launch Partner The Extension Partner — the program owner. Defines the proposition, provides brand assets and program details, completes forms, and builds the customer-facing experience. MatchMove Program manager and platform provider. Coordinates all submissions, performs first-line review, manages the Financial Institution and Payment Network relationships, and configures the platform. Financial Institution (FI) The regulated issuer / BIN sponsor. Reviews and endorses all program submissions, owns the relationship with the Payment Network, and holds final accountability to the regulator. Payment Network The card scheme (e.g. Mastercard, Visa). Approves the card design, the program proposal (PPM — prepaid programs), the digital-first experience (DFCP — numberless card designs), and assigns/certifies the BIN. Indicative end-to-end timeline: typically 8–15 weeks for the default configuration (shared prepaid BIN), ranging from ~4–8 weeks for the fastest configuration (shared debit BIN, full-detail card) to ~15–24 weeks for a dedicated prepaid BIN. Physical card availability adds a further 10–14 weeks of card production after design approval — see the end-to-end tally by program configuration in Section 9. Several tracks run in parallel, and the technical implementation track runs in parallel with all of the activities in this document. Process at a Glance The launch runs through the Prerequisites plus six steps. Steps 1, 2, and 3 — and the Step 4 artwork drafting — run in parallel from kick-off; the Step 4 submission is the convergence point where the BIN and the applicable PPM/DFCP approvals must be in place. Steps 5 and 6 then follow sequentially. Prerequisites — Agreement and Due Diligence (2–3 weeks): Commercial agreement signed; KYB completed; program definition and eligibility confirmed. Step 1 — Dedicated BIN Setup (7–9 weeks; dedicated BINs only): BIN assigned, certified, and enabled with the Payment Network. Skipped entirely on the default shared-BIN model. Step 2 — PPM Submission and Approval (4–7 weeks; prepaid BINs only): The program is registered with the Payment Network through the Financial Institution. Step 3 — DFCP Form (2–4 weeks; numberless card designs only): The digital-first cardholder experience is documented and approved by the network. Step 4 — Card Design Submission (usually 1–3 weeks): Partner artwork is reviewed, endorsed, costed, and submitted to the network. Step 5 — Card Design Approval (1–2 weeks): The Payment Network reviews and approves the design; proofing follows for physical cards. Step 6 — Mass Blank Card Production (10–14 weeks; physical cards only): Printing, then kitting, of the physical cards — starts only after the design approval. 2. Prerequisites (Before Any Submission) ⏱️ Estimated time: 2–3 weeks — driven largely by how quickly complete Know Your Business (KYB) documentation is provided. These must be in place before the formal launch process begins. Requirements Signed commercial agreement between the Partner and MatchMove. MatchMove will request the Partner to have an entity in the jurisdiction designated for the partnership — however, this does not need to hold up signing: the agreement can be signed on the Partner's existing entity and novated (transferred) to the designated entity after it is established (see FAQ 6). Completed Partner due diligence (KYB), including corporate documents, ownership structure with Ultimate Beneficial Owners (UBOs), and licensing information where applicable. Agreed program definition: card type (prepaid / debit), form factor (virtual, physical, or both), target market and geography, funding sources, and use cases. Named Partner contacts: program owner, compliance contact, technical lead, and design/brand contact. Program eligibility confirmed against platform restrictions — see the developer portal's Prohibited industries , High-risk industries , Prohibited countries , and High-risk countries pages before committing to a launch plan. Actions by Stakeholder Stakeholder Action Partner Provide KYB documents, confirm program definition, and nominate contacts. MatchMove Complete Customer Due Diligence (CDD) review; confirm program feasibility with the Financial Institution; issue the launch checklist and kick-off plan. Financial Institution Preliminary review of the Partner and proposed program. Payment Network Not yet involved. Approvers: MatchMove Compliance and the Financial Institution (Partner onboarding approval). Environment: Not environment-bound — a documentation and due-diligence activity. 3. Step 1 — BIN Selection and Setup (for dedicated BINs) ⏱️ Estimated time: 7–9 weeks end to end — assignment ~1 week, network project setup ~1 week, certification 4–5 weeks (the long pole), and test/go-live 1–2 weeks. Skipped entirely on the default shared-BIN model. The BIN (Bank Identification Number) identifies the issuer and product on the network. Programs run on one of two BIN models: BIN Model What It Is Process Impact Shared BIN (the default) A standard BIN already certified and live on the MatchMove platform, shared across multiple programs. The network recognizes only the parent BIN — allocating a range or sub-range within it to an individual program is an internal activity of the Financial Institution / MatchMove, not a network approval. MatchMove allocates a range on the shared BIN and configures the program against it (products, limits, currencies) as part of standard platform setup; for prepaid programs, the PPM references the existing shared BIN. This entire step does not apply — no Payment Network certification or network-level BIN assignment is needed. Dedicated BIN (on Partner request) A new BIN assigned exclusively to the Partner's program, requested through the Financial Institution (BIN sponsor) and assigned by the Payment Network. Typically chosen for brand ownership of the BIN, portfolio portability, or a product type or country of issuance not supported on the shared BINs. The full process in this step applies — assignment, network implementation project, certification, and test/go-live, adding approximately 7–9 weeks to the launch plan. BIN Types — and When This Step Applies Every BIN (and each account range within it) carries a fixed set of registered attributes. These concepts apply across payment networks, with only the terminology differing: Attribute Description Funding type Prepaid or debit Use designation Consumer or commercial. Brand program code The specific network product the range issues under. Within the commercial designation, program codes further distinguish tiers such as Business (small-business cards), Corporate , Purchasing , and Fleet — so a "business BIN" is a commercial BIN carrying a business-tier program code, in whichever funding type the market supports (most commonly commercial prepaid on this platform). Licensed country of issuance The country the BIN is licensed to issue in. Settlement currency The currency the range settles in. The combination of funding type and use designation gives the four primary BIN types supported in MatchMove: BIN Type Definition Consumer prepaid Issued to individuals, spending a preloaded balance held on the platform. The standard type for consumer wallet and card programs. Commercial prepaid Issued to businesses and their employees or payees, funded from a preloaded corporate float. Covers expense management, payroll, and disbursement programs; cards registered under the Business product tier carry "Business" printed on the card face. Consumer debit Issued to individuals, drawing directly on a deposit account the cardholder holds with the Financial Institution. Commercial debit Issued to businesses, drawing on a business deposit account; Business-tier cards in this designation likewise carry "Business" on the card face. In every case, the card face must reflect the product the range is registered for — which is why "Business" (or any commercial marking) cannot appear on a card issued from a consumer range. A range can only ever issue the product it is registered for. This is why a program cannot simply "reuse" any available BIN: a debit product cannot be issued on a prepaid range, a commercial product cannot ride a consumer range, and a range licensed for one country cannot issue in another. Who can request a BIN. The Payment Network assigns BINs only to its licensed customers — principal members/issuers (each network identifies its licensed members by a membership identifier) or affiliates acting through their sponsoring principal. Program managers and partners can never request a BIN from the network directly. The request chain is always: Partner → MatchMove → Financial Institution (the licensed customer / BIN sponsor) → Payment Network. The Financial Institution's license must also cover the requested product and country — a license to issue consumer prepaid in one market does not automatically extend to debit, commercial products, or other countries. When the full dedicated-BIN process is required, reduced, or skipped: Scenario What is needed This step? Program matches an existing certified shared BIN — same funding type, use designation, product, and country Internal range allocation on the shared BIN by MatchMove / Financial Institution; platform configuration only Skipped entirely (the default path) New product variation within a family already certified on an existing BIN — e.g. a new design that requires a new program code or market segment where the network's regional rules allow segmentation by account range New 11-digit account range (or 8-digit sub-BIN) added under the existing BIN via a network implementation project; certification burden is reduced because the parent BIN's processing is already certified Reduced — project and configuration, lighter testing New funding type (e.g., first debit program when existing BINs are prepaid), new use designation (first commercial program), or new country of issuance New BIN assignment and full certification — the processing chain has never been certified for this product configuration Full 7–9 week process Partner elects a dedicated BIN for a product type already supported New BIN assignment and full certification, by choice rather than necessity Full 7–9 week process Why partners choose a dedicated BIN when they don't strictly need one: Driver Description Scale A single 8-digit BIN accommodates roughly a million card numbers, so very large programs need their own range. Isolation On a shared BIN, elevated fraud from another program on the same BIN can cause merchants to treat the whole BIN with suspicion. Sole Ownership Dedicated 8-digit BINs streamline marketing communications and make it easier to plan events and activities with merchants, as the entire BIN is exclusive to your program rather than shared with others. Portability A dedicated BIN is perceived as easier to move when changing sponsor banks, though in practice moving banks involves friction regardless, particularly for physical cards printed with the issuer's name. A note on debit specifically: debit cards draw on a deposit account held by the cardholder, so debit issuance carries prerequisites that prepaid does not — the Financial Institution must be able to hold cardholder deposit accounts in the market, and in most jurisdictions only deposit-taking institutions can issue debit. A partner asking to "move from prepaid to debit" is therefore not just requesting a different BIN type: it changes the account structure, the regulatory basis, and potentially which Financial Institution can support the program. The network-side process is the same 7–9 weeks described below, but Financial Institution readiness should be scoped before the BIN request is made. Dedicated BIN Setup: Assignment, Certification, and Go-Live For dedicated-BIN programs, the process runs in four stages, in this order: Stage Activity Estimated Time 1 BIN request and network assignment — MatchMove formally requests the new BIN from the Financial Institution (BIN sponsor); the Financial Institution requests the BIN assignment from the Payment Network. The network assigns the BIN and registers the product parameters. ~1 week 2 Network implementation project setup — MatchMove requests the network's implementation project, and a network project manager is assigned to run the certification. ~1 week 3 BIN certification — certification test scripts are executed with the network, proving the BIN and the processing chain behind it correctly handle authorization, clearing, settlement, and exception flows. Runs on the network certification environment, connected to MatchMove staging . 4–5 weeks 4 BIN test and go-live + PPM submission — final production testing and enablement of the certified BIN on the live environment; the PPM (Step 2, prepaid BINs) is submitted in the same window. 1–2 weeks (2 if clarifications arise) Network Implementation Overview A newly assigned BIN cannot process transactions until MatchMove opens a formal implementation project to configure it within the payment network's systems. It takes approximately one week for the network to process this request and assign a dedicated Project Manager to oversee the technical setup. Partners do not need to interact with this Project Manager directly, as the MatchMove Card Operations team will manage all testing and communication on your behalf. Please note that the network may charge a project-creation fee depending on the region and program type. Finally, because the PPM (required for prepaid programs) must reference an active BIN, dedicated prepaid BINs must complete this network assignment and certification before the PPM is submitted. In contrast, prepaid programs using the default shared BINs have already satisfied this certification and can submit their PPM immediately. Dedicated debit BINs follow the same four stages, with no PPM at the end. 3.1 Requirements and Parameters Parameter Requirement BIN assignment A new BIN is assigned by the Payment Network to the Financial Institution (BIN sponsor) at the start of the process, on MatchMove's formal request. Product configuration Program code, funding type (prepaid/debit), consumer/commercial designation, and country of issuance registered against the BIN. Network implementation project Implementation project opened with the Payment Network and a network project manager assigned before certification can begin — the formal work order for all network-side configuration and testing. Network certification Mandatory certification test scripts executed with the network covering authorization, clearing, and settlement message flows for the BIN. Performed on the network certification environment, connected to MatchMove staging. EMV/contactless certification (physical) EMV (the Europay–Mastercard–Visa chip standard) profile and contactless kernel certification via the personalization bureau for physical card programs. Tokenization enrollment (if in scope) BIN enrollment for network tokenization services to support wallet provisioning (e.g. Apple Pay / Google Pay), where included in the program. Processor setup BIN range configured on the issuer processor and MatchMove platform: authorization rules, currency, limits, and routing — staging configuration for certification and live configuration at the test-and-go-live stage. 3.2 Process MatchMove formally requests the new BIN from the Financial Institution (BIN sponsor). The Financial Institution requests the BIN assignment from the Payment Network; the network assigns the BIN and registers the product parameters. (~1 week) MatchMove requests the network implementation project; the network assigns a project manager who owns the enablement end to end — network-side configuration, test scripts, testing schedule, defect tracking, and completion sign-off. (~1 week) MatchMove configures the BIN on the staging platform and issuer processor test setup. Certification test scripts are executed against the network's certification environment — authorization, clearing, settlement, and exception flows — with defects resolved and retested. For physical programs, EMV and contactless profiles are certified with the personalization bureau. (4–5 weeks) The Payment Network signs off on certification; final BIN testing and production enablement follow in the live environment, and the PPM (prepaid BINs) is submitted in the same window. (1–2 weeks) 3.3 Stakeholder Actions and Approvers Stakeholder Action Partner No direct action; kept informed of milestones. Confirms product parameters (limits, currencies) where choices exist. MatchMove Formally request the BIN and the network implementation project; staging and live configuration of the BIN; execute certification test cycles; and manage defect resolution. Financial Institution Request the BIN assignment from the network; own the BIN relationship; approve production enablement. Payment Network Assign the BIN and register product parameters; assign the implementation project manager; run and sign off certification. Approvers: Payment Network (BIN assignment and certification sign-off); Financial Institution (production enablement). Environment: Stages 1–2 — administrative (no environment). Stage 3 (certification) — network certification environment with MatchMove staging. Stage 4 (test and go-live) — live (production). 4. Step 2 — PPM Submission and Approval ⏱️ Estimated time: 4–7 weeks — Financial Institution review typically 2–3 weeks, network review 2–4 weeks. Incomplete volume forecasts and Know Your Customer (KYC) model ambiguity are the most common causes of delay. The Prepaid Program Management (PPM) is the formal program proposal registered with the Payment Network through the Financial Institution. It describes what the program is, who it serves, and how it is controlled. The network's approval of the Prepaid Program Management is what authorizes the program to operate under the scheme. When is a PPM required? The requirement follows the funding type of the BIN the program runs on: BIN Funding Type PPM Requirement Prepaid (consumer or commercial) PPM required — the program must be registered and approved through the PPM before it can operate under the scheme. Debit (consumer or commercial) PPM not required — debit programs are not registered through a PPM; program approval is handled by the Financial Institution under its debit product approvals. Do all prepaid programs require a new PPM? Every prepaid card program must be registered with the Payment Network before launch (debit programs are exempt — see the table above). But not every prepaid program requires a new, full PPM submission . What is required depends on how the program is structured: Full PPM submission — required for prepaid programs introducing a new product construct: a new product type, a new market or country of issuance, a new funding model, a dedicated prepaid BIN, or any proposition materially different from what the network has previously approved for the Financial Institution. Amendment to an existing PPM — required when an existing approved program changes materially (e.g. new funding sources, revised limits, expanded target market). Your MatchMove Program Manager will confirm at kick-off which path applies to your program. Programs covered under an existing PPM avoid the 4–7 week review cycle described below. 4.1 Requirements and Parameters Below is the information needed to be prepared before the PPM submission: Parameter Requirement Program description Product type (e.g. reloadable prepaid, debit), positioning, and intended use cases. Target market Customer segments (consumer / corporate), geography, and distribution channels. Funding and load Permitted funding sources (bank transfer, card top-up, payroll, and corporate float), load limits, and balance limits. Program limits Transaction limits, velocity limits, ATM (Automated Teller Machine) access (if any), and cross-border usage parameters. KYC model Tiered KYC structure, verification methods, and limits per tier, aligned to the Financial Institution's regulatory obligations. AML/CFT controls Anti-Money Laundering / Countering the Financing of Terrorism (AML/CFT) — transaction monitoring approach, sanctions screening, and suspicious-activity escalation model. Projected volumes Forecast card issuance, active cards, load volume, and spend volume (typically a 3-year projection). Program roles Identification of the Program Manager (MatchMove), the Partner, and any other service providers, as required by network rules. Information gathered in the PPM form. The form itself consolidates the above into a structured submission. Typical fields include: Field Group Details Program identification Program name, launch date, program category (e.g. consumer prepaid, corporate prepaid, debit), and the Financial Institution's network membership identifiers. Parties and roles Issuer (Financial Institution), Program Manager (MatchMove), the Partner, and any other registered service providers (processor, personalization bureau, and distribution agents). BIN and product details The BIN/range the program will operate on, the network program code/platform, the card brand and tier, and the form factor (virtual, physical, or both). Target market Country of issuance, customer segments (consumer/corporate), eligibility criteria, and distribution channels (app, web, agent, employer). Funding and limits Permitted load/funding sources, maximum balance, load limits (per transaction/day/month), spend and withdrawal limits, ATM access, and domestic vs. cross-border usage. KYC and compliance KYC tiers with verification methods and limits per tier, AML/CFT monitoring approach, and sanctions screening. Cardholder fees The fee schedule is presented to cardholders (issuance, reload, ATM, foreign exchange (FX), dormancy), where required by the network or regulator. Volume forecasts Projected cards issued, active cards, load volume, and spend volume, typically over 3 years. Marketing and distribution description How the program will be promoted and how cards reach cardholders. Dependency note — dedicated BINs come first: The PPM must reference the issuing BIN and its registered product configuration. Programs on the default shared BINs are unaffected — the shared BIN is already certified, and the PPM references it directly. For a dedicated prepaid BIN , the BIN assignment and certification (Step 1) must complete first; the PPM is then submitted at the BIN test-and-go-live stage. See Section 3 for the full sequence. 4.2 Process The MatchMove Implementation team provides the PPM form and information pack to the Partner when needed, pre-filled with platform-level parameters. The Partner fills out the PPM form — completing the business sections: program description, target market, volumes, and distribution. MatchMove reviews for completeness and consistency and aligns the compliance sections with the Financial Institution. The Financial Institution performs a risk and compliance review, then submits the PPM to the Payment Network. The Payment Network reviews and may raise clarification queries, which MatchMove coordinates responses to. Network approval is issued; the program is registered under the Financial Institution's license. 4.3 Stakeholder Actions and Approvers Stakeholder Action Stakeholder Action Partner Fill out the PPM form (business sections); provide volume forecasts; respond promptly to clarification queries. MatchMove Assemble and quality-check the submission; coordinate all query responses; track approval status. Financial Institution Risk/compliance review; formal submission to the network; regulatory sign-off. Payment Network Program review and approval; program registration. Approvers: Financial Institution (risk/compliance) and Payment Network (final program approval). Environment: Not environment-bound — a documentation and registration activity (no staging or live configuration involved). 5. Step 3 — DFCP Form (Digital First Card Program) ⏱️ Estimated time: 2–4 weeks , assuming the cardholder app journey is build-complete at submission. Can run in parallel with Steps 1–2. Where the design omits or masks card details, DFCP approval is required before the card design submission (Step 4). Where the Partner opts for a numberless card — a design that omits or masks the card details — PAN (Primary Account Number), expiry, and CVV (Card Verification Value) — on the card face, with credentials delivered and accessed digitally instead — the Payment Network requires a Digital First Card Program (DFCP) submission. This certifies that the digital cardholder experience meets the network's standards for security, disclosure, and servicing. When is a DFCP required? The requirement follows the Partner's card design decision: Card Design Decision DFCP Requirement Numberless card — the design omits or masks the PAN, expiry, or CVV on the card face; the cardholder accesses full details digitally DFCP required — must be submitted and approved before the card design can be submitted (see the Step 4 prerequisites). Full-detail card — the design carries the complete card details on the card face DFCP not needed. What does "digital-first" mean? A digital-first card program is one where the card is born digital: the cardholder applies, is approved, and receives a usable card entirely through digital channels — with a physical card as an optional companion rather than the primary product. The Payment Network's digital-first framework sets functional requirements across four areas of the cardholder journey: No. Area Requirement 1 Digital acquisition The cardholder applies online or in-app and receives their card details almost immediately upon approval, with no paper application or branch visit. 2 Instant digital issuance and usage Card credentials are available for use right away: online, in-app, and at the point of sale through wallet provisioning (e.g. Apple Pay / Google Pay). A physical card is optional and, where offered, may omit printed credentials. 3 Secure access to card details The full PAN, expiry, CVC (Card Verification Code, also written CVV), and customer-service information are accessed through the digital environment (with masking and step-up authentication), removing the need for them to appear on a physical card. 4 Digital card management and servicing The cardholder can check balances, view transactions, receive alerts, manage card controls, and reach support entirely within the digital channel. The DFCP form is how the network verifies that a program meets these requirements before launch. Because many programs on the MatchMove platform opt for numberless designs with credentials delivered through the partner app, the DFCP applies to many partner launches — and since the evidence is specific to each partner's app and journey, it cannot be inherited from another program the way an existing PPM or shared BIN can. 5.1 Requirements and Parameters Parameter Requirement Digital card display Screens showing how the approved card art, PAN, expiry, and CVV are displayed in-app, including masking behavior and step-up authentication before revealing full credentials. Physical Card Art Final physical card artwork for review, with the PAN and other sensitive card details partially or fully omitted from the physical design. DFCP Form Partners are required to prepare a comprehensive workflow detailing: how digital cards are instantly generated for online spending prior to physical card delivery and any additional processes specified in the required form. Note: The Financial Institution will review the workflow prior to Payment Network approval. The MatchMove Implementation team will supply the form and a sample for guidance when needed. Credential delivery How the cardholder receives and accesses card credentials digitally (no physical carrier) and controls preventing unauthorized exposure. Cardholder servicing Digital access to transaction history, card controls (freeze/unfreeze), PIN (Personal Identification Number) management (if applicable), and lost/stolen reporting. Terms and disclosures In-app access to cardholder terms and conditions, fees, and customer support channels. Security controls Authentication model for app access and sensitive actions, aligned to network requirements. Supporting evidence Annotated screenshots or a demo build of the cardholder journey, mapped to each DFCP requirement. Information gathered in the DFCP form. The form documents the digital-first experience against the network's checklist. Typical fields include the following: Field Group Details Program identification Program name, issuer (Financial Institution), BIN/product reference, and target launch date, linking the DFCP to the PPM and card design. Digital-first features in scope Which capabilities the program uses: virtual card issuance, digital display of PAN/expiry/CVV, digital PIN set/reset, tokenization, and wallet provisioning (e.g. Apple Pay / Google Pay), and optional physical card issuance on request. Application details The cardholder-facing app or web channel, supported platforms (iOS/Android/web), and where the digital card experience sits within it. Credential display and security How full card credentials are revealed (masking defaults, step-up authentication method, session/timeout behavior) and the authentication model for app access and sensitive actions. Cardholder servicing evidence Screens demonstrating transaction history, card controls (freeze/unfreeze), lost/stolen reporting, and customer support access. Disclosures Where cardholders access terms and conditions and the fee schedule within the digital journey. Evidence pack Annotated screenshots or a demo build, mapped requirement-by-requirement to the network's DFCP checklist. 5.2 Process The MatchMove Implementation team provides the Partner with the DFCP form and requirements checklist when needed, mapped to platform capabilities (many requirements are satisfied by the MatchMove platform by default). The Partner fills out the DFCP form and supplies the app screens / journey evidence for the Partner-built experience layers. MatchMove reviews the completed form and evidence pack against the checklist and quality checks the submission. The Financial Institution endorses and submits the DFCP to the Payment Network. The Payment Network reviews, raises comments if any, and issues DFCP approval. 5.3 Stakeholder Actions and Approvers Stakeholder Action Partner Fill out the DFCP form; provide app journey evidence; implement any required UX (user experience) changes from network feedback. MatchMove Map requirements to platform capabilities; assemble and quality-check the submission; coordinate remediation. Financial Institution Endorse and submit the DFCP. Payment Network Review and approve the digital-first experience. Approvers: Payment Network (final); Financial Institution (endorsement). Environment: Evidence is captured from the staging build of the cardholder app/journey (a build-complete staging or UAT environment is sufficient — production is not required for submission). Digital wallet enablement (e.g. Apple Pay / Google Pay): enabling the program's cards in digital wallets is handled as part of the technical implementation track , not the approvals in this document. Scope it at kick-off — wallet-provider approval timelines vary by market and can trail the card go-live without gating it. See Start your implementation on the developer portal. 6. Step 4 — Card Design Submission ⏱️ Estimated time: usually 1–3 weeks — artwork drafting and MatchMove review cycles through Financial Institution endorsement, commercials, and submission to the Payment Network. Note that this timeline ultimately depends on how quickly the Partner can finalize and approve the design on their side, as the card design will need to align with and follow the Partner's own internal branding guidelines. Designs that follow the template closely on first submission move fastest. Refer to the Card Design Submission section to learn more. Card design is required for every program. There is no default or pre-approved white-label card art on the platform — every program launches with its own card design, and every card face — physical and virtual — must be approved by the Payment Network before it can be issued or displayed to cardholders. This step covers everything up to and including the submission of the design to the network; the network's review, approval, and production follow in Step 5. 6.1 Requirements and Parameters Parameter Requirement Artwork files Print-ready vector files (Adobe Illustrator AI or Encapsulated PostScript EPS format) plus PDF proofs, front and back, at the network-specified dimensions and bleed. Virtual card art supplied as high-resolution digital renders. Network brand mark The scheme logo is placed per the network's brand standards — position, size, clear space, and approved color variants. Issuer identification The Financial Institution (issuer) name displayed as mandated by the network and regulator. Mandatory elements (physical) Chip position, contactless indicator, hologram/brand hologram element, signature panel or "no signature required" treatment, magnetic stripe (if applicable), and card number/expiry/CVV placement per the personalization spec. Mandatory elements (virtual) Card art rendering with scheme mark, masked/unmasked PAN display rules, and expiry/CVV presentation consistent with the approved design. Prohibited content No third-party trademarks without authorization, no content conflicting with network brand standards, no misleading product descriptors. Co-brand rules If the Partner brand appears on the card, co-brand placement rules apply (relative sizing and positioning against the scheme mark). 6.2 Prerequisites Prerequisites Description BIN Assignment A BIN must already be assigned. This establishes the card type and ensures all necessary network elements are incorporated into the design upfront. Design Freeze The final design must be locked in. Any subsequent changes will reset the project timeline from the beginning. PPM Approval Prepaid BINs require the program to be registered and approved through the PPM before the design can be submitted for review; this does not apply to debit BINs. See Step 2 for more information. DFCP Approval If the Partner opts for a numberless card — a design that only displays a partial or masked PAN or incomplete card details — a DFCP approval from the network must be submitted and approved before the actual card art design can be submitted for approval. See Step 3 for more information. Sampling Decision The Partner must decide whether to request a physical card sample/prototype (a dummy for aesthetic proofing) or proceed directly to mass production. 6.3 Submission Process Draft Submission: The Partner submits the draft artwork to MatchMove using the design template and specifications provided during kick-off. MatchMove Review: MatchMove reviews the artwork against network brand standards and the personalization bureau's technical specifications, returning consolidated feedback if adjustments are needed. Design Freeze & Costing: Once the artwork is finalized and frozen, the final card cost is calculated based on the selected design features. Financial Institution Endorsement: MatchMove submits the clean, finalized design to the Financial Institution for endorsement. Commercials: A quotation is provided to the Partner for approval. An invoice is then issued and must be paid upfront before work commences on the next step. Network Submission: For Virtual Cards: The Financial Institution submits the design to the Payment Network's card design approval system. For Physical Cards: The printer submits the final pre-press form to the Payment Network. 6.4 Stakeholder Actions and Approvers Stakeholder Action Partner Produce final artwork in AI (Adobe Illustrator) file; respond to feedback; approve the quotation and settle the invoice. MatchMove First-line design review; consolidate feedback; coordinate design freeze, costing, and commercials. Financial Institution Endorse and approve the proposed design before submission to the network. Payment Network Receives the submission (review and approval follow in Step 5). Approvers: MatchMove (first-line review) and Financial Institution (endorsement) — the gates before the design reaches the network. Environment: Not environment-bound — an artwork and documentation activity. 7. Step 5 — Card Design Approval ⏱️ Estimated time: 1–2 weeks for network approval (SLA (Service Level Agreement): 5 business days per review round — each comment cycle is treated as a new request, resets the SLA, and typically adds 1–2 weeks of elapsed time). Physical programs add digital proofing, and an optional sampling run adds 4-5 weeks if requested. Once the design is submitted (Step 4), the Payment Network reviews it against its brand standards and issues the approval that allows the card face to be issued or displayed to cardholders. For physical cards, approval flows straight into proofing and production. 7.1 Approval and Production Process 1. Proofing & Production (Physical Cards Only): The final freeze design is routed to the personalization bureau, and a digital proof of the final print layout is produced for Partner sign-off. If sampling is requested: This is a chargeable service that takes 4–5 weeks (excluding metal and LED cards) to produce a physical prototype for inspection. If sampling is not required: The design proceeds directly to mass production immediately after the Partner signs off and the Network approval on the digital prepress proof is obtained. 2. Network Approval: The Payment Network reviews the submission (SLA: 5 business days). If they return comments, the submission flow in Step 4 (steps 1–4) is repeated. Note: Each round of revisions is treated as a new request and resets the 5-day SLA clock. 7.2 Stakeholder Actions and Approvers Stakeholder Action Partner Respond to network comments (via Step 4 rework); sign off on the digital proof and physical samples (if requested). MatchMove Coordinate comment cycles and resubmissions; liaise with the personalization bureau on proofing, sampling, and production. Financial Institution Re-endorse revised designs where required. Payment Network Final design approval. Approvers: Payment Network (final). Environment: Not environment-bound — an artwork and documentation activity. The approved design is later configured for display in staging (for DFCP evidence and UAT) and live (at go-live). 8. Step 6 — Mass Blank Card Production (Physical Cards Only) ⏱️ Estimated time: 10–14 weeks — card printing 8–10 weeks, stationery printing 6-7 weeks (runs in parallel with card printing), then kitting 2–4 weeks, will all be a factor in the fulfillment process. Can only start after the card design approval (Step 5) is given. Once the card design is approved, the physical cards move into actual production. This runs in two sequential stages: Title Description Title Stage Activity Estimated Time 1 Card printing — mass production of the physical cards at the personalization bureau against the approved design. 8–10 weeks 2 Stationery printing — production of the accompanying stationery (carriers, envelopes, and inserts). This depends on the quantity, type of personalization process, and stationery design. 6–7 weeks. Runs in parallel with the card printing. 3 Kitting — assembling the printed cards and stationery into their final packs ready for distribution. 2–4 weeks Card production is strictly sequential: It cannot begin until the Payment Network's design approval is issued, and kitting follows once both printing runs are complete. For digital-first programs, this does not gate the program launch — virtual card issuance can go live while production runs, with physical cards following. Programs whose primary product is the physical card should plan the launch date around this step. 8.1 Stakeholder Actions and Approvers Stakeholder Action Partner Confirm card quantities and distribution details; no other direct action. MatchMove Liaise with the personalization bureau on production scheduling, quality, and delivery. Financial Institution No direct action. Payment Network No direct action, provided the design approval is in place. Approvers: None — a production activity following the Step 5 approval. Environment: Not environment-bound — a physical manufacturing and fulfillment activity. 9. Consolidated Timeline ⏱️ End-to-end: configuration-dependent — typically 8–15 weeks to program approval readiness on the default shared prepaid BIN, from ~4–8 weeks (shared debit BIN, full-detail card) up to ~15–24 weeks (dedicated prepaid BIN). Physical card availability adds 10–14 weeks of card production (Step 6) after the design approval. Elapsed calendar time from signed agreement, with parallel tracks managed by MatchMove and the technical implementation track running alongside. See the tally by configuration below. Indicative, assuming prompt turnarounds and no major rework: Phase Duration Stage Dependencies / Parallelism Prerequisites (KYB, program definition) 2–3 weeks Pre-signing Runs first — no parallelism. Gates everything else Step 1 — Dedicated BIN setup (dedicated BINs only) 7–9 weeks Post-signing Can run in parallel with Steps 3–4 (artwork drafting) starting at kick-off. Does not apply to the default shared-BIN model. Four stages: BIN request & network assignment (~1 wk) → network project setup (~1 wk) → certification (4–5 wks) → BIN test & go-live (1–2 wks), with the PPM (prepaid BINs) submitted at the final stage Step 2 — PPM submission and approval 4–7 weeks Implementation Can run in parallel with Steps 3–4 starting at kick-off on the shared-BIN model; for dedicated BINs, starts at the BIN test-and-go-live stage (see Step 1). Required for prepaid BINs only (see Section 4). Not required as a new submission for programs covered under an existing approved PPM (see Section 4) Step 3 — DFCP form 2–4 weeks Implementation Can run in parallel with Steps 1–2 starting at kick-off (requires a build-complete app journey). Required only for numberless card designs (see Section 5); must be approved before Step 4 Step 4 — Card design submission Usually 1–3 weeks — depends on how quickly the Partner finalizes and approves the design against their internal branding guidelines. Implementation Artwork drafting can run in parallel with Steps 1–3 starting at kick-off ; the submission itself requires the BIN assigned and the applicable PPM/DFCP approvals (see Section 6.2) Step 5 — Card design approval 1–2 weeks (+4–5 weeks if physical sampling is requested) Implementation Sequential — starts only after the Step 4 submission. 5-business-day network SLA per review round; each comment cycle resets the SLA; must complete before card production Step 6 — Mass blank card production (physical cards only) 10–14 weeks (card printing 8–10 wks → stationery printing parallel 6-7 wks → kitting 2–4 wks) Post-approval Sequential — can only start after the Step 5 design approval. Digital-first programs can launch virtual issuance while production runs. End-to-end Configuration-dependent — see the tally below Typically 8–15 weeks on the default shared prepaid BIN model End-to-End Tally by Program Configuration The end-to-end timeline depends on which steps the program's configuration triggers. All eight combinations: BIN Model Funding Type Card Design Steps Required To Approval readiness With Physical Cards (+ Step 6) Shared Debit Full-detail Prerequisites + Design only (Steps 4–5) ~4–8 weeks (the fastest configuration) ~14–22 weeks Shared Debit Numberless Prerequisites + DFCP + Design (Steps 3–5) ~6–12 weeks ~16–26 weeks Shared Prepaid Full-detail Prerequisites + PPM + Design (Steps 2, 4–5) ~8–15 weeks ~18–29 weeks Shared Prepaid Numberless Prerequisites + PPM + DFCP + Design (Steps 2–5; DFCP runs inside the PPM window) ~8–15 weeks (the default configuration) ~18–29 weeks Dedicated Debit Full-detail Prerequisites + BIN + Design (Steps 1, 4–5) ~11–17 weeks ~21–31 weeks Dedicated Debit Numberless Prerequisites + BIN + DFCP + Design (Steps 1, 3–5) ~11–17 weeks ~21–31 weeks Dedicated Prepaid Full-detail Prerequisites + BIN + PPM + Design (Steps 1–2, 4–5) ~15–24 weeks ~25–38 weeks Dedicated Prepaid Numberless Prerequisites + BIN + PPM + DFCP + Design (all steps; DFCP runs inside the BIN window) ~15–24 weeks (the longest configuration) ~25–38 weeks (the longest configuration) Card Program Launch Timeline — Shared BIN (Default Model) Card Program Launch Timeline — Dedicated BIN How these tallies work: The weeks shown are calendar time from start to finish , not all the step durations added together. Steps that run at the same time are only counted once — for example, while the PPM is under review (4–7 weeks), the DFCP and the card artwork are being worked on in the background, so they add no extra weeks. What sets the pace is the longest chain of steps that must happen one after another. On the default shared-BIN model that chain is: Prerequisites → PPM review → design submission → design approval. On a dedicated BIN it is: Prerequisites → BIN setup → PPM review → design submission → design approval. Delays anywhere on that chain extend the end-to-end timeline directly — including the time the Partner takes to finalize the design against their own internal branding guidelines. The tallies show the standard path . They do not include an optional physical card sample ( add 4–5 weeks if requested), extra rounds of network comments ( add 1–2 weeks per round ), or time the Partner takes to finalize the design on their side. A shortcut for some prepaid programs: if the program can run under an existing approved PPM (see Section 4), the PPM review is skipped — and the timeline drops to roughly the debit figure in the same BIN model group. Physical cards: the "To Approval Readiness" column ends at program approval readiness; the "With Physical Cards" column adds card production (Step 6 — printing then kitting, 10–14 weeks ), which begins only after the design approval. Digital-first programs can go live with virtual cards at approval readiness while production runs; physical-first programs should plan their launch on the "With Physical Cards" column. The technical implementation track (API integration, UAT) runs in parallel with everything in this document from project kick-off, so the approval activities and the technical build normally complete within the same overall window. 10. Partner Preparation Checklist Everything the Partner will be asked to provide, grouped by step. Preparing these early is the single biggest accelerator of the timeline. Step What the Partner prepares Prerequisites Corporate/KYB documents, ownership structure with UBOs, licensing information, named contacts (program owner, compliance, technical lead, design/brand), and confirmed program definition (card type, form factor, market, funding sources, use cases). Step 1 — Dedicated BIN (if applicable) Confirmation of product parameters (limits, currencies) where choices exist; no other direct inputs. Step 2 — PPM (prepaid BINs) Completed PPM form business sections: program description, target market and distribution channels, cardholder fee schedule, and 3-year volume forecasts (cards issued, active cards, load and spend volume). Step 3 — DFCP (numberless card designs) Completed DFCP form; annotated app screens / journey evidence from the build-complete staging app, covering credential display, servicing, and disclosures. Steps 4–5 — Card design Print-ready artwork (Adobe Illustrator AI / EPS format, front and back) per the template supplied at kick-off; brand assets; approval of the quotation; sign-off on digital proofs (and physical samples, if requested). Digital wallet enablement (if in scope) Handled in the technical implementation track — confirm wallets and markets in scope at kick-off. Throughout An empowered single point of contact per workstream, responding to feedback and clarification queries within days. 11. Costs and Pricing Several activities in the launch process are chargeable. This document does not publish pricing — please reach out to the MatchMove Sales and Business Development team for pricing , as pricing depends on several factors such as the volume, scale, markets, and configuration of the program. Activities that typically carry charges include: Chargeable Activity Description Platform setup and program configuration Per the commercial agreement. Dedicated BIN setup Network BIN fees, implementation project fees, and certification effort (dedicated-BIN programs only). Card art review and approval The network charges a fee to review and approve your intended card art design for virtual use or physical production. Prototype Production of sample cards in small batches (typically 15 pcs) to ensure the design comes out as intended. Physical card production Personalization, card stock, and delivery; physical sample cards printed on request. Digital wallet enablement Delivered within the technical implementation track, where in scope. Program-level network fees E.g. registration and scheme fees, passed through per the commercial agreement. The commercial agreement signed before kick-off is the authoritative source for what applies to your program and who bears each cost. 12. After Launch: Ongoing Obligations and Changes Approval to launch is not the end of the Financial Institution's and network's involvement. Partners should plan for: Obligation Description Marketing material review Public-facing materials that reference the card program (websites, app store listings, campaigns) typically require review and approval through MatchMove and the Financial Institution before publication. Ongoing reporting and program reviews The Financial Institution conducts periodic reviews of the program's volumes, complaints, and compliance posture as part of its regulatory oversight; MatchMove coordinates the inputs. Changes to the live program Changes re-enter the relevant approval track: a new or revised card design goes back through card design submission and approval (Steps 4–5); changes to limits, funding sources, fees, or target market require a PPM amendment for prepaid programs (see Section 4) or the Financial Institution's equivalent approval for debit programs; a new funding type, product designation, or country of issuance is treated as a new program registration and may trigger the BIN assessment in Step 1. Coordination of the above after go-live is shared between your MatchMove Program Manager (Implementation Team) and your Account Manager (Customer Growth team), with the Account Manager progressively taking over as the program stabilizes. Frequently Asked Questions What happens if a submission is rejected? Most "rejections" in practice are comment cycles: the network or Financial Institution returns the submission with required changes, MatchMove consolidates the feedback, the Partner reworks the affected items, and the submission goes back in — each cycle typically adds 1–2 weeks. Outright declines are rare and usually indicate a program-construct issue (e.g. an unsupported product type or market); in that case, MatchMove will work with the Partner to restructure the proposal before resubmitting. Can we launch in more than one country? Yes, but not with a single set of approvals. BINs are licensed per country of issuance, and the Financial Institution and regulatory basis can differ by market — so each country is effectively its own run of this process (registration, BIN scoping, and design/DFCP where the network requires it), which MatchMove coordinates and can run in parallel. Multi-market ambitions should be raised at kick-off so the sequence can be planned. Can we issue in more than one payment network? Yes — but each network requires its own BIN, its own program registration, and its own card design approval, so a dual-network program is two parallel approval tracks. Most programs launch on one network first. Do we need to redo everything to add a new card design to a live program? No — only Steps 4–5 (card design submission and approval) re-run for the new design. The program registration, BIN, and DFCP generally carry over, though a materially different digital experience may require a DFCP update. Does the technical integration wait for these approvals? No — integration can begin as early as project kick-off and runs in parallel (see the Scope note and Section 9). Only the go-live itself waits on all approvals being in place. Does our company need a business entity in the program's region to sign the contract and start a program? MatchMove will request the Partner to have an entity in the jurisdiction designated for the partnership. However, this does not need to hold up signing: MatchMove can sign based on the Partner's existing entity and novate the agreement — transfer it to the designated entity — after it is established. Raise your corporate structure with MatchMove early so the contracting path can be planned alongside the Prerequisites. Tips for a Faster Launch Tip Why It Matters Submit complete artwork the first time Most design delays come from missing mandatory elements — use the template supplied at kick-off. Prepare volume forecasts early The PPM cannot progress without realistic 3-year projections. Build the app journey in parallel DFCP needs a build-complete cardholder experience; don't leave the credential-display screens to the end. Respond to network queries within days, not weeks Each open query cycle typically costs 1–2 weeks of elapsed time. Nominate empowered contacts A single decision-maker per workstream on the Partner side is the biggest single accelerator. All timelines in this document are indicative and depend on the responsiveness of all parties, the Payment Network's review queues, and the complexity of the program. Your MatchMove Program Manager will provide a program-specific plan at kick-off. • [Create your card product](https://developer.matchmove.com/matchmove-banking-operating-system/card-program-operations/create-your-card-product.md): Build the perfect white-label card for your customers. The MatchMove platform allows the flexibility to have multiple card products for a given program. You can choose and design multiple card products and manage the assignment of these cards to your users as needed. The guide below lists the building blocks of the card program. The account type cannot be controlled at a card product level. All card products for the given program have the same associated account types and hence follow the same funding model. 1 Choose your form factor It is important to decide what card form factor you issue, as this impacts your integration workflow and the sequence of API calls you need to orchestrate. Physical cards also impact how you design your customer journeys. 2 Choose your distribution strategy If you choose to issue physical cards, determining the journey from the delivery of cards to the end user to the point of activation is critical to establish. 3 Choose your card product The current network products available in stock are listed below. Choose the product based on your program currency. BIN Type Definition Consumer prepaid Issued to individuals, spending a preloaded balance held on the platform. The standard type for consumer wallet and card programs. Commercial prepaid Issued to businesses and their employees or payees, funded from a preloaded corporate float. Covers expense management, payroll, and disbursement programs; cards registered under the Business product tier carry "Business" printed on the card face. Consumer debit Issued to individuals, drawing directly on a deposit account the cardholder holds with the issuing bank. Commercial debit Issued to businesses, drawing on a business deposit account; business-tier cards in this designation likewise carry "Business" on the card face. 4 Design your dream card All designs that are created need to follow the brand guidelines of the network as applicable for the specific card product you are subscribing to. You have significant freedom in terms of designing the card to be branded uniquely for your customers, but you do need to adhere to imposed Card network guidelines. The following sections are basic guidelines that must be followed in designing your card. Virtual card art guidelines For virtual card design, all artwork must adhere to a horizontal orientation. In cases where the physical card is designed in a vertical format, the elements must be appropriately rearranged to fit a horizontal layout. The non-tokenized card art is the image used in the application or website to represent the actual card. The following mandatory elements must appear on the front-facing design of the non-tokenized card. Reach out to your Implementation Manager to get the applicable template approved by the network. Required Elements Partner's Brand/Co-brand Logo - Positioned at the upper left-hand corner. MasterCard Logo - Positioned at the lower right-hand section. Cardholder Name - Displayed prominently on the card art design. Full 16-Digit Card Number (PAN) - A placeholder 16-digit number must be displayed. CVC - The card verification code. Expiry Date/Valid Thru - The card's expiration date. Card Type Identifier - For example, the term "business" (in lowercase) may be used for specific Card BINs (as advised by MM). Prohibited Elements PayWave icon Chip image/icon Additional Considerations If the Name, PAN, Expiry Date, and CVC are not displayed on the front of the virtual card art, they must be located near the card art within the app interface. In instances where the card art is designed to simulate a flip animation (representing both the front and back of the physical card), the Name, PAN, Expiry Date, and CVC may be placed on the back side, leaving the front side clean with only the Partner and MasterCard logos visible. Approval Process All card art designs are subject to the network's approval before they can be used or displayed digitally on the app or website. Physical card art guidelines Required Elements Partner's Brand/Co-brand Logo - Positioned at the upper left-hand corner. MasterCard Logo - Positioned at the lower right-hand section. Cardholder Name - Displayed prominently on the card art design. Full 16-Digit Card Number (PAN) - A placeholder 16-digit number must be displayed. CVC - The card verification code. Expiry Date/Valid Thru - The card's expiration date. Card Type Identifier - For example, the term "business" (in lowercase) may be used for specific Card BINs (as advised by MM). Prohibited Elements PayWave icon Chip image/icon Additional Considerations If the Name, PAN, Expiry Date, and CVC are not displayed on the front of the virtual card art, they must be located near the card art within the app interface. In instances where the card art is designed to simulate a flip animation (representing both the front and back of the physical card), the Name, PAN, Expiry Date, and CVC may be placed on the back side, leaving the front side clean with only the Partner and MasterCard logos visible. Approval Process All card art designs are subject to the network's approval before they can be used or displayed digitally on the app or website. Tokenized card art guidelines For partners who prefer vertical card design, be aware that a vertically oriented design in a wallet will appear in a horizontal orientation even though the artwork is vertical. Tokenized card art refers to the image used in third-party wallets approved by MasterCard. such as Google Pay and Apple Pay. Required Elements Partner's Brand/Co-brand Logo - Displayed on the virtual card face. MasterCard Logo - Displayed on the virtual card face. Card Type Identifier - For example, the term "business" (in lowercase) may be used for specific Card BINs (as advised by MM). Prohibited Elements PayWave logo Chip image Card Art Specifications Specific card art specifications and requirements will be provided separately for each third-party tokenized wallet project initiated. Please refer to MDES Guides. Card image - 1536 x 969 pixels PNG format (not more than 3MB) for approval by the MasterCard Design team. The card must have all the required elements in a proper format as per MasterCard's guidelines, with sharp edges. Additional assets required for tokenization Customer Service Phone Number Customer Service Email Company legal entity name as appeared in the contract with MM Program Name 5 Print your card Work with the Implementation Team to decide the cadence at which the card orders are printed and shared with you, to be distributed to your cardholder. Do discuss with your implementation manager the options available for you. You can choose multiple options, ranging from the kind of printing to the welcome kit that is sent to you as part of the printed card kit. 6 Configure your card product As part of the platform product setup, you have the flexibility of defining granular controls on various attributes of your card product. You are recommended to align the number of products you need, as well as the segmentation and feature controls you want to implement for your end users. Configure your card issuance limits How many cards do you want to be issued to a user for a given card product? How many cards do you want to be issued to the user in total? The system is limited to issuing 50 cards per user created in the system Configure your card fee schedule Decide on your fee schedule for each card program. As a partner, you have the option of configuring markup for any of the following fee line items Configure restrictions on your card program Note that the platform will decline these transactions, but you are still obligated to pay the decline fees for these transactions. Work with your implementation manager to decide the best approach In addition to the default restrictions configured on the platform as part of the regulatory requirements, you have the flexibility to configure additional restrictions based on : MID (Merchant ID) TID (Terminal ID) MCC (Merchant Category Code) You can use this opportunity to restrict the same, depending on your use case. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payments Manage card security • [Card design submission](https://developer.matchmove.com/matchmove-banking-operating-system/card-program-operations/card-design-submission.md): Learn how to design and submit card artwork for approval by Mastercard. This guide covers what the card must carry, what it must not, which colors and finishes are permitted, and the process that takes a design from first draft to network approval. Audience: MatchMove Partners launching a card program on the MatchMove Banking Operating System, and specifically the Partner's design team and program owner. Scope: The design and submission of card artwork for consumer and commercial prepaid and debit card programs, covering both the physical card printed on plastic and the virtual card art shown on screen. Both require Payment Network approval. Not covered here: the rest of the launch sequence, including the approvals that precede design and the production and fulfillment that follow it, documented in Launching a card program ; tokenization , a technical track covered by the Implementation checklist ; and on-screen digital card display behavior , documented in On-screen digital card display . Regional availability: Card program features, permitted design treatments, and approval requirements described in this document vary by region, Financial Institution, and Payment Network. Not all treatments are available in all markets. Your MatchMove Program Manager will confirm what applies to your program and region during project kick-off. Document validity: Published September 15, 2026 . The requirements, standards, and timelines described in this document are true as of this writing and are subject to change by the Payment Networks and Financial Institutions without prior notice. Regional nuances apply throughout — the exact required elements, review durations, and approval requirements can differ by market. Always design against the current standards at the time of card production, and confirm the current requirements with your MatchMove Account and Implementation Manager before relying on this document for planning. 1. Overview ⏱️ Card artwork design kicks off the approval process — nothing downstream starts until the Partner delivers the first draft, so the date the artwork is ready is the date the clock starts. Drafting and internal branding approvals are Partner-controlled and sit outside the estimates below. From the first draft submission: 2–5 weeks to network approval — 1–3 weeks through the reviews and the pre-press form, then 1–2 weeks for the network's decision, assuming approval on the first pass. A virtual card is ready at that point . A physical card is in hand around 19 weeks , since production and fulfillment add a further 10–14 weeks. Each round trip between submission and approval adds a further pass, which compounds. See Timelines, Review, and Approval . Card design is not a cosmetic step. The Payment Network reviews every card face against its brand standards before a single card is printed, and a rejected design restarts the review clock. Most rejections are avoidable: a logo placed too close to a network mark, a background that swallows the brand mark, a security feature omitted, or artwork supplied in the wrong color space. This guide covers Card Design Submission and Card Design Approval — Steps 4 and 5 of the launch sequence. It is authoritative for card design: what the card face must carry, how it is laid out, and the reviews it passes through. Two numbering systems appear in this guide. Steps 4 and 5 refer to the launch guide's seven-step sequence. The eleven steps in Timelines, Review, and Approval are the card design process itself, from first draft to a card ready for distribution. Who does what Role In this step Partner Produces the artwork, supplies brand assets, customer service details, and the card order count, clears internal branding approvals, approves the pre-press form, and settles the invoice MatchMove Supplies the design template and Payment Network artwork; reviews against network standards, Financial Institution requirements, and prior approval experience; prepares the quotation with the bureau; generates the embossing file Financial Institution The regulated issuer and BIN (Bank Identification Number) sponsor. Reviews the design for its own branding, hotline, and market disclosures, and accepts issuance under its license Personalization bureau A certified card vendor. Checks the artwork against its printing process, produces the pre-press form, submits it to the Payment Network, prints and kits the cards Payment Network Mastercard. Approves the design at step 9 Partner artwork deliverables The Partner produces and submits the artwork; MatchMove supplies the template and Payment Network artwork to build it on (Sections 5 and 6), and the Financial Institution supplies the legal text wording. Deliverable What it is Applies when Physical card artwork The design is printed on the plastic, front and back. The only deliverable that goes to a printer, and the subject of Sections 5 to 6 The program issues plastic. Virtual card artwork The design for a card issued without plastic. It exists only on screen, so this file is the image displayed in the app. The program issues virtual cards. Cards are also represented on screen in two forms: non-tokenized art in the Partner application or website and tokenized art in a third-party wallet after provisioning. All virtual card art is horizontal and requires Mastercard approval — see Virtual Card Art and Integration . Note. On-screen digital card display behavior is not in scope, nor is tokenization itself. The first is documented in On-screen digital card display . Process at a glance Eleven steps sit between a first draft and a card ready for distribution. Six are approvals, three are reviews or checks, and two are production. What Mastercard approves is not the Partner's artwork but the digital pre-press form produced from it. No. Step Owner Card type 1 Partner branding sign-off and draft submission in CMYK (Cyan, Magenta, Yellow, Key) for physical or RGB (Red, Green, Blue) for virtual Partner Virtual and physical 2 MatchMove internal review MatchMove Virtual and physical 3 Financial Institution review Financial Institution Virtual and physical 4 Joint artwork review and production printing quotation MatchMove / bureau Physical only 5 Invoice settlement Partner Physical only 6 Pre-press form Personalization bureau Physical only 7 Pre-press form approval Partner Physical only 8 Card design pre-press form submission Bureau, or BIN sponsor on virtual Virtual and physical 9 Card pre-press form approval Payment Network Virtual and physical 10 Mass card printing Bureau / MatchMove Physical only 11 Card kitting, personalization and last-mile delivery Bureau / courier Physical only Virtual programs run five of the eleven — the three reviews, then submission and approval. Timelines, Review, and Approval sets out what happens at each step, who owns it, and what changes by card type. 2. When to Start, and What Gates Submission Design starts at kick-off. Submission is gated. Treating them as one block is the most common way partners put card design on the critical path unnecessarily. Artwork drafting runs in parallel with BIN setup, PPM (Prepaid Program Management), and DFCP (Digital First Card Program). None of those needs to complete first. Because the design must also clear the Partner's internal branding approvals — frequently the slowest link — starting early matters. To begin, the Partner needs the design template .ai files provided by MatchMove at kick-off (see The Card Design Template ), its own brand guidelines, and a decision on numberless versus full-detail design . Four conditions for gate submission. Each supplies something the design depends on, so working past them costs time rather than saving it. Gate Applies to Why it gates the design BIN assignment All programs The BIN encodes the network, funding type, product tier, and country of issuance — each of which changes what must appear on the card face. Each BIN also carries a Mastercard program code with an associated design requirement: a BIN on the Business Debit program code must show the Business Debit identifier. On a numbered card the printed PAN (Primary Account Number) must begin with the assigned BIN PPM approval Prepaid BINs only Registers the program and its name with the network. The card face carries that name. DFCP approval Numberless designs only The network's certification of the digital credential experience — what makes omitting the PAN, expiry, and security code compliant rather than a missing element Sampling decision All programs decide; only physical can sample. Changes both the quotation and the schedule. Sampling adds 3–5 weeks and a charge and is mandatory on metal and LED cards. Design freeze happens at step 9, on Payment Network approval — not before. Everything up to that point is revisable, which is the purpose of the sequence: objections surface while changes are still cheap. After freeze, a change is a resubmission — see Timelines, Review, and Approval . 3. Timelines, Review, and Approval ⏱️ 1–3 weeks through steps 1 to 8 , then 1–2 weeks for the network's decision at step 9 , at an SLA (Service Level Agreement) of 5 business days per round. Optional sampling adds 3–5 weeks. Excludes the Partner's drafting time, and compounds with each round trip. Card artwork design sits at the top of the timeline and starts the approval process. Week 0 is the Partner's draft submission, not project kick-off: step 1 is Partner-dependent, has no fixed duration, and sets the date everything downstream begins. Production dominates : steps 1 to 9 take about five weeks, printing and kitting the remaining fourteen. A change caught before step 9 costs a revision cycle; caught after, it costs a reprint. Readiness milestones are marked on the chart: virtual at week 5, non-personalized physical at week 15, personalized physical at week 19. What happens at each step No. Step Artifacts What happens 1 Partner branding sign-off and draft submission in CMYK for physical, RGB for virtual Draft [.ai] artwork, card order count The Partner clears internal brand, marketing, and legal approvals, then emails the package to the MatchMove Implementation team — there is no upload portal. One complete set per design. The package is: print-ready front and back as [.ai] files at 100% scale on the MatchMove template with the die-line on its own layer, plus [.pdf] proofs; the virtual card art [.ai] file where the program issues virtual cards, with a mock-up if the credentials are not on the front; the activation QR artwork where used; a specification sheet naming stock, finish, personalization method, any specialty process, and the color inventory; the card order count and sampling decision; and evidence that the BIN, PPM, and DFCP prerequisites are met 2 MatchMove internal review Draft [.ai] artwork, review feedback Checked against network brand standards, Financial Institution requirements, the bureau's technical specifications, and what has actually passed and failed across hundreds of previous approvals. Expect feedback on points the published standards do not cover — submit a rough draft early rather than a polished design late. 3 Financial Institution review Reviewed [.ai] artwork, sign-off Checks its own branding, hotline, and market disclosures, and accepts issuance under its license 4 Joint artwork review and production printing quotation Reviewed [.ai] artwork, quotation, invoice The bureau checks fonts, colors, and production settings against the press and recommends changes. The quotation then prices per-card cost, production at volume, the pre-press form, network approval, and — where they apply — kitting, personalization, and delivery. 5 Invoice settlement Settled invoice The Partner settles the invoice. The bureau does not begin the pre-press form until payment is received 6 Pre-press form Digital pre-press [.pdf] form The bureau produces the form from the corrected artwork. Rework carries a charge depending on the severity of the changes 7 Pre-press form approval Digital pre-press [.pdf] form The Partner confirms the pre-press form matches the design intended. A rejected form returns the design to step 1 , and a further redesign form is chargeable. 8 Card design pre-press form submission Physical — approved [.pdf] form Virtual — artwork as a [.png], plus the card activation flow Submitted to the Payment Network portal. On virtual programs the BIN sponsor submits directly. 9 Card pre-press form approval Network approval Brand compliance checked and approval granted. USD 750 per design , valid two years. On rejection: a content placement issue returns to step 6, an artwork issue to step 1 10 Mass card printing Purchase Order, embossing file, printed cards The bureau receives the PO and notifies MatchMove, which generates the embossing file against the approved BIN. The bureau prints 11 Card kitting, personalization and last-mile delivery Kitted cards, carriers, inserts, delivery Personalized — individual personalization , carrying the cardholder name. Kitting and last-mile delivery are mandatory Non-personalized — bulk personalization , the same process without a cardholder name. Kitting is optional, with stationery fulfillment, and cards ship in bulk to one destination Three of the eleven steps are the Partner's — branding sign-off, invoice settlement, and form approval. Each is a hard stop until the Partner acts. Two carry a charge : the pre-press form at step 6 and each network round at step 9. Steps 1 to 3 are free, so a problem caught there costs a revision while the same problem later means a new form, a further network round, or both. The Financial Institution review should confirm, not discover — its requirements are supplied at kick-off and checked at step 2, so a surprise at step 3 means a gap in the package. The bureau's check is about printing, not design : expect comments on type that will not hold at card scale and colors that will not separate cleanly, but the design decision remains the Partner's. Round trips compound A network comment is not a quick edit: the form is revised, earlier reviewers see it again, and the SLA resets because each resubmission is a new request. Approved first pass, submission and approval take 2–5 weeks ; two comment rounds plus sampling can pass 10 weeks . There is no cap on rounds — the argument for using the free reviews properly. Pre-press form and physical sample The digital pre-press form is a PDF (Portable Document Format) showing the artwork, typography, and exact placement of the chip, stripe, network marks, legal statement, issuer logo, and customer support number as they will print. The bureau produces it at step 6 from artwork already corrected at step 4. It is what the Partner signs off at step 7 and what Mastercard approves at step 9, reviewed for symbol sizing and clearances, PANTONE and CMYK color use, contrast, and placement of mandatory elements. Until that approval the bureau cannot legally print cards carrying the Mastercard mark. Not to be confused with the pre-press proof — the technical blueprint used to set up the press, carrying CMYK and PANTONE separations, bleed lines, crop marks, overprint settings, and sheet layout. The bureau prepares both; only the form is submitted. Pre-press form Physical sample Required? Mandatory on physical programs Optional , mandatory on metal and LED Approved by Partner and Payment Network Partner Adds Nothing — inside the step 9 window 3–5 weeks Shows Layout, placement, and content as printed Color, finish, and feel in the hand A sample earns its weeks where the design depends on something a screen cannot show — foil, metal, matte or textured laminate, spot varnish, or a PANTONE match that must be right the first time. Decide before submission, since it changes both the quotation and the schedule. When submission can start Submission is gated on upstream approvals, so the earliest date is set by the slowest applicable gate rather than by how fast the artwork is finished. Upstream gate Time Applies to Prerequisites — Agreement and Due Diligence 2–3 weeks All programs Step 1 (BIN Selection and Setup) 7–9 weeks Dedicated BINs only Step 2 (PPM) 4–7 weeks Prepaid BINs only Step 3 (DFCP Form) 2–4 weeks Numberless designs only On the default configuration — shared BIN, prepaid, numberless — the design waits on the PPM, so submission opens roughly 6–10 weeks after kick-off even where artwork was ready in week two. Frequent rejection causes Most are covered by Never place on the card face under Factors That Affect Card Design . The ones specific to submission rather than design: A required product, tier, or source-of-funds identifier omitted for the issuing market The contactless indicator missing on a contactless-enabled card Fonts not outlined, or artwork supplied in RGB Elements intruding into the chip, stripe, or signature panel zones Placeholder text, visible template layer names, or crop marks left in the file Changing a design after approval An approved design is locked. Changing it is a resubmission, not an edit, and the cost depends on how far it has traveled. Any change after network approval is treated as a new design , with its own approval timeline and USD 750 fee. Change requested What happens After approval, before production The design unfreezes and re-enters the sequence: MatchMove, Financial Institution, and a fresh Payment Network review. Expect the full sequence again, plus a further chargeable network round. After production has begun Production runs 10–14 weeks and cannot be partially recalled — card printing 8–10 weeks, stationery 6–7 in parallel, then kitting 2–4, and kitting cannot start before the stationery is produced. Cards already printed carry the old design. The Partner may abandon that stock, in which case the full cost is sunk. After cards are in circulation Cards in the field are not recalled. The new design applies to newly issued and reissued cards only, so both circulate until the old stock cycles out. The Partner may terminate cards early and replace them — the replacement is a new card type , reconstructed on the MatchMove back end with its own card type code — see Virtual Card Art and Integration What counts as a change. Any alteration to the approved artwork — color, imagery, logo, layout, or finish. Correcting a typo in the legal text is a change. Swapping a finish is a change and a re-cost. Both designs remain live. A revision does not replace its predecessor in the field. Plan for a period — potentially years, given a three-to-five-year card lifecycle — in which cardholders hold either version. The screen image updates immediately. Once the revised design is uploaded, the API serves the new image to every application reading from the card object. A cardholder holding an old physical card may see the new design in the app. If that matters, discuss sequencing with MatchMove before submitting the change. A new variant is usually cheaper than a revision. Where the goal is a different look rather than a correction, adding a second design with its own card type code leaves the approved one undisturbed and lets both run in parallel. 4. Costs and Charges A card program carries up to nine chargeable items, quoted together in a single invoice at step 4. Which applies depends on the card type. Charge Basis Virtual Physical, personalized Physical, non-personalized Card approval USD 750 per design , valid for two years, then renewable. Charged per Payment Network review round Not chargeable Mandatory Mandatory Digital pre-press form Charged per event. A rejected form means a further form and a further charge. Not applicable Mandatory Mandatory Production printing Cost per card, and the overall cost at the card order count Not applicable Mandatory Mandatory Kitting Assembly with carriers and inserts Not applicable Mandatory Optional Card data generation and file transmission Per record, preparing card details for both personalized and bulk processes (emboss and reversed emboss record) Not applicable Mandatory Mandatory Design profile template setting One time per design, on first production of a new design Not applicable Mandatory Mandatory Personalization (individual and bulk) Writing cardholder data and card details to the chip and magnetic stripe, and printing the details on the card surface. Applies to numberless designs too — the cardholder name is still required on the face Not applicable Mandatory Mandatory Last-mile delivery Courier delivery to the cardholder, on personalized programs Not applicable Mandatory Not applicable — see one-time delivery One-time delivery Bulk delivery of non-personalized stock to a single address. Quoted and charged separately, outside the step 4 quotation Not applicable Not applicable Optional, depending on the country Virtual programs carry no charges here. Card approval is free for virtual cards, and there is nothing to proof, print, kit, personalize, or deliver. Submission to the Payment Network is made directly by the BIN sponsor , not the bureau. Non-personalized cards are bulk personalized. Personalization still happens — the same process, without a cardholder name. The card data is generated in bulk, one batch for the quantity ordered, and the personalization process writes and prints the card information itself: PAN, expiry, and CVV. Only the name is absent. Because there is no cardholder name on the card, there is no address to deliver to. Kitting remains available as an option, together with stationery fulfillment. The cards then ship in bulk to a single destination , quoted and charged separately as a one-time delivery outside the step 4 quotation. The program owner then manages the card inventory and distributes cards to individual cardholders directly. Fee waivers can be applied for case by case where a design goes through multiple network rounds — raise it with MatchMove rather than assuming the charge is fixed. Multiple designs in one program A program can run tiers, variants, co-brands, and limited editions on the same BIN, but each design is submitted and approved separately — no bulk approval. Two designs means two of everything, including its own chargeable network rounds, its own printing quotation, and its own print run clearing the minimum order quantity independently. Specialty finishes on one variant do not price the others. An approval does not travel between regions. The Financial Institution arrangement differs in every region, and with it the licensing statement, the source-of-funds identifier, and the local regulatory disclosures the card face must carry. Expect a separate design and approval in a second market even where the artwork is visually identical. Minimum order quantity Card printing is volume-priced, and there is a minimum order quantity — currently 1,500 cards . This figure is subject to change; confirm the current minimum with MatchMove before committing. Two consequences: The minimum applies per design. A program running three designs runs three print jobs, each of which must clear the minimum on its own. Three designs is not three variations on one order. It sets a floor on the program. A design decision that looks free at the artwork stage — adding a premium tier variant, for example — carries a minimum print commitment behind it. 5. The Card Design Template Work in the template, not from this section. MatchMove provides the Mastercard card design template as an Adobe Illustrator (.ai) file containing precisely mapped vector layers, technical dimensions, and mandatory branding placements required to meet Mastercard's global Rules and Standards. It is the blueprint for laying out card artwork, and it is authoritative where this guide and the template differ. Horizontal and vertical templates are both provided. Mastercard only at present. What the template contains 1. Mandatory branding assets The Mastercard Brand Mark — official vector versions of the interlocking red and orange circles, using exact PANTONE color matching. These must not be converted to CMYK. Brand mark placements — separate layer variations showing valid placements, typically the top right or bottom right corner of the card front. 2. Physical layout and dimensions Card boundaries — a base shape at standard ID-1 / CR80 dimensions, 85.60 mm × 53.98 mm. Bleed and safe zones — pre-configured gridlines indicating where critical text or graphics must end to avoid being cut off during high-volume manufacturing. Element placement — the permitted position of every element on both faces, marked to scale: where the brand mark, chip, contactless indicator, magnetic stripe, signature panel, account details, issuer logo, customer service contact, and legal text sit relative to one another and to the card edge. This is what the template settles and this guide does not — take every placement from the .ai file. 3. Structural hardware overlays — keep-out zones EMV (Europay, Mastercard, and Visa) chip placement — a precise bounding box where the metallic microchip will sit. Design elements are blocked from this area to preserve hardware functionality. Contactless indicator — the universal radio wave symbol, showing where the contactless antenna graphic belongs. 4. Personalization and variable data outlines Cardholder data — dummy text placeholders for the 16-digit PAN (Primary Account Number), expiration date, and cardholder name. Font guidelines — sizing and layout requirements detailing how embossed, indent-printed, or laser-etched text aligns with the overall design. The bureau's default is Arial. Partner’s will need to supply the font, and the perso bureau will check if that is compatible and can be imported into their system to be incorporated into the perso process. 5. Card back elements Magnetic stripe zone — a standardized horizontal block mapping the high-coercivity stripe. Signature panel — a designated block outline for the physical signature strip. Security details — placement outlines for the three-digit CVC 2 (Card Validation Code 2) security code, compliance text, and issuer contact details. The canvas at a glance For orientation, the diagrams below show how the elements relate on both faces. They are not a substitute for the template — every measurement and placement comes from the .ai file. The same anatomy in vertical orientation: The diagrams use two colors. Blue marks Partner elements — the card artwork, your logo, and the printed fields you position. Red marks supplied or fixed elements from Mastercard, MatchMove, or the Financial Institution, which must not be altered. Elements are tagged [M] mandatory or [O] optional under Payment Network rules — not what the program needs commercially and not what MatchMove or the Financial Institution may require. The template is authoritative. Note. Whether the cardholder name appears at all depends on the personalization type: individual personalization carries a name, bulk personalization does not. Where it appears, it normally sits on one face only — front or back. If both sides are required, additional charges will apply. Valid layout variations There is no single correct layout. The three variations below differ in how the account details are applied to the card — the personalization method — not in the artwork itself. The same design can usually be produced either way; what changes is the manufacturing process, the cost, and where the printed details can sit. Three horizontal designs, each front and back: Embossed, full detail — the conventional layout. The account number, expiry, and cardholder name are physically raised out of the plastic by a stamping die, then usually tipped with foil. The network logo sits over the raised numerals. Because the characters displace the card body, they push through and appear in mirror on the back, so the reverse must leave that area clear. Unembossed, full detail — the same details flat-printed onto the surface rather than raised. Nothing displaces the plastic, so the back is unaffected and the front reads cleaner. Printed details may be positioned differently from embossed ones, so do not carry an embossed layout across unchanged. This is the more common choice on new programs and is a prerequisite for an activation QR code on the back. Numberless — no account number, expiry, or security code on either face. Credentials are delivered in the app, and the design is stripe-free with no signature panel. Requires an approved DFCP before submission. The cardholder name is still required and is usually the only personalized element on the face, though a shortened form may be substituted. Freeing the PAN zone opens the largest usable area on the card — the strongest numberless designs use it as negative space rather than filling it, and the back carries the service and legal text that would otherwise compete with account data. Three vertical designs: The chip and magnetic stripe do not move. They are built into the plastic during manufacturing. On a vertical design the card is held with its long edge upright, so the stripe runs as a band down the left side of the back and the chip sits near the top of the front, with artwork and text upright beside them. Two consequences. A vertical back has less usable width , because the stripe takes a full-height band instead of a strip across the top. And a vertical card still needs horizontal virtual card art — plan that second layout from the outset. What the template does not settle Five things sit outside it, and each needs a conversation with MatchMove: Secure Symbol or hologram. Every card carries a security element, and there are two routes. Availability is gated by region — not both are offered in every market, so confirm which applies to yours with MatchMove before designing. Secure Symbol Hologram What it is A special/premium network symbol, made up of holographic material hot-stamped onto the front , used in place of the standard printed brand mark The conventional holographic patch, usually on the back Effect on the back The back opens up. With no hologram there and no signature panel required by Mastercard, the whole face becomes available for design. Claims its own area on a face already carrying the stripe, signature panel, and legal text Magnetic stripe withdrawal. Mastercard has published a phased withdrawal: from 2024 the stripe is no longer required on newly issued cards in most markets; from 2027 the transition begins in the United States; from 2029 no new Mastercard debit cards will be issued with a stripe; and by 2033 stripes are expected to be out of circulation, with prepaid cards in the United States and Canada currently exempt. If your program has a multi-year reissue cycle, discuss stripe-free design now rather than at the next redesign. Required legal text and the Licensee Acknowledgement Statement. The legal text names the technology provider and the Financial Institution, plus the licensing statement, cardholder agreement reference, and any local regulatory disclosure. It is supplied as exact wording and must not be edited or abbreviated — if it does not fit, the layout changes, not the text. The Licensee Acknowledgement Statement is required on the back where the issuer name or logo is not included on the card ; it is optional where the issuer logo is provided. In Asia-Pacific the wording names Mastercard Asia/Pacific Pte. Ltd. as licensor. Financial Institution requirements. These vary by institution and market — there is no universal list. MatchMove provides the applicable set at kick-off and checks it at step 2. Categories that commonly appear: issuer logo, customer service contact, lost or stolen card reporting, cardholder agreement reference, a regulatory or deposit insurance mark, and property-of-issuer wording. A requirement surfacing at step 3 is a gap in the kick-off package, not a design fault. Production elements are added by the bureau and must be accommodated rather than designed: the 2D barcode, manufacturer ID, and print sequence number. "ELECTRONIC USE ONLY" is required on flat-printed cards. 6. Factors That Affect Card Design The template settles geometry. These choices shape how the design is reproduced, and each carries a cost or timeline. Confirm the specifics with your MatchMove implementation contact. Factor What to decide Why it matters Brand mark placement Nothing of yours enters the mark's exclusion zone. Use the reverse, alternate, or binocular treatment where the background is dark or busy. Clear space is drawn in the template, but the template cannot stop you from filling it — the most frequently violated rule in card design. A dark mark on a dark background is a rejection regardless of composition. Card material Standard PVC (polyvinyl chloride), recycled PVC, or metal Metal has the longest lead time and highest cost, mandatory sampling , and needs milling for chip insertion. PVC can carry a tint or fleck that shifts light backgrounds. Color and finish Gloss, matte, frosted, or spot UV; silver, gold, or rainbow foil; textured laminate. Mastercard Symbol in full-color match PANTONE only — never built in CMYK. Gloss saturates and shows scuffs; matte mutes deep tones but improves legibility; spot UV needs a matte base for the contrast to read. Foil does not reproduce as a printed color — specify as foil. Deep saturated backgrounds print differently on PVC than on screen, and aggregator sites carry conflicting brand values — the supplied artwork is the only correct source. Special effects Any feature embedded in the card body rather than printed on it — LED illumination is the common case. The affected area is co-designed with the manufacturer. LED lights are powered by the terminal's contactless field and glow through a chosen area of the artwork. Non-standard construction, so sampling is mandatory and runs longer than the standard window. Personalization Embossed or flat-printed. Size the cardholder name field against a full-length 25-character string, and supply any font file to the bureau. The name comes from preferred_name on the MatchMove user object, the default cardholder name for physical cards, which is capped at 25 characters Embossing displaces the card surface and distorts adjacent print on both faces. Method changes where printed details may sit and whether a QR code is viable. A name field sized to a short sample oversets in production. The default recommendation is to use the flat-printed method, as it is easier to plan and arrange with the other card details settings. Imagery Contrast around every mark and printed field; legible at card scale Nothing that reads as endorsing another payment brand or institution. Fine detail disappears on plastic. Three things follow from the table: Specify material and finish before submission. They are cost inputs and part of what the network approves. Request a physical sample for anything specialty. Foil, matte, metal, and spot varnish all shift between screen, proof, and production — and a dark matte or textured surface can pull the network mark below the contrast threshold. Confirm availability. Not every finish is offered by every bureau or in every market. Never place on the card face These are the most common causes of design rejection — each something a designer added in good faith that Mastercard does not permit. Altered network artwork. Do not redraw, recolor, stretch, skew, rotate, crop, or apply effects to the Mastercard Symbol. The Mastercard wordmark alongside the Symbol. Since November 2018 the full-color Symbol without the wordmark is the card treatment. Grayscale or solid Mastercard Brand Mark on the chip side , or on the visible side of a card in any digital payment environment. Anything intruding into brand mark clear space , or background imagery that drops the mark below readable contrast. Competing payment network or acceptance marks , unless the program is formally co-badged and the arrangement approved. The word "card" inside the program name. "World Elite Mastercard" is correct; "World Elite Mastercard Card" is not. Translated network names. English only, except authorized versions in Chinese, Arabic, Georgian, and Korean. MatchMove provides the design template and all artwork assets — the template .ai files described in The Card Design Template , the Payment Network artwork built into them, and the required legal text. Mastercard card artwork lives on Mastercard Connect, restricted to financial institutions and certified card manufacturers, so a Partner has no direct route to it. Never source a brand mark from a web search, a brand aggregator, a competitor's card image, or a marketing-use download — a mark rebuilt or resampled from an image will fail review. The Partner supplies its logo in production-ready vector, background artwork and palette, licensed fonts converted to outlines, customer service details in the form the Financial Institution requires, the activation QR code artwork where used, and the finished files assembled on the template. 7. Virtual Card Art and Integration Two things sit on the integration side of card design: the virtual card art shown on screen and how any approved design reaches the application once MatchMove uploads it. Virtual card art Virtual card art is the image representing the card on screen — in the Partner application or website and in third-party wallets. It is a separate deliverable from the physical artwork, built from the card art template Mastercard provides, and all of it must be horizontal — a vertical physical design has to be relaid out. Two kinds, with different requirements. Non-tokenized Tokenized Where it appears Partner application or website Third-party wallet — Google Pay, Apple Pay — provisioned through MDES Required Partner logo (upper left), Mastercard logo (lower right), cardholder name, placeholder 16-digit PAN, CVC, expiry, and the card type identifier where the BIN requires one Partner logo, Mastercard logo, and the card type identifier where the BIN requires one Prohibited PayWave icon, chip image PayWave logo, chip image Specification As above Issued per wallet project. Do not design against a general specification. Where the credentials are not on the front , the name, PAN, expiry, and CVC must appear near the card art in the app. Where the art simulates a flip animation, those four may sit on the back, leaving the front clean with only the two logos. Submission. The AI file from the Mastercard template, plus a mock-up where the credentials are not on the front. All virtual card art requires Mastercard approval — including the digital art that represents the physical card, which is treated as a virtual card approval — before use. It is not covered by the physical card design approval for printing; those are two separate approvals. Consuming approved designs MatchMove uploads the design, and the API serves it on the card object for both physical and virtual cards. Read it from the API rather than hardcoding a copy — the API always serves the currently approved artwork, revisions propagate without a release, and a program running several designs cannot serve one embedded image correctly. See Issue a card . Each approved design has its own card type code , passed as a parameter whenever a card is created to select which design that card carries. A program issuing three designs has three codes, and the application must know which to send — a build decision that needs to reach the development team before integration starts, since an incorrect code issues physically different plastic and the error only shows once the card is produced. Three identifiers are easily confused: Identifier Issued by Identifies Mastercard program code Mastercard, against the BIN The card product type — Business Debit, for example. Determines which design requirements apply MatchMove program code MatchMove Which program is running Card type code MatchMove Which approved card design A program has one MatchMove program code and one or many card type codes. The Mastercard program code belongs to the BIN, not the program. Not covered here. The full wallet artwork package — app icon, card label, color parameters — is specified per project when a wallet integration is initiated; raise it at kick-off, since it carries its own approval cycle. Display behavior is documented in On-screen digital card display . 8. References Authoritative — gated These are the governing documents. Neither is accessible to Partners directly; MatchMove holds the access and supplies what a Partner needs from them. Mastercard Card Design Standards — the authoritative source for all Mastercard physical card design requirements, including placement coordinates, minimum sizes, and back-of-card specification. Published on Mastercard Connect ( mastercardconnect.com ), restricted to financial institutions and certified card manufacturers. Where a Partner needs a specific requirement confirmed against either document, route the question through the MatchMove implementation contact rather than seeking access. Public — background reading only The links below are useful for understanding the standards. They are not an artwork source: all brand assets for a MatchMove card program come from MatchMove. Mastercard Branding Requirements — https://www.mastercard.com/brandcenter/us/en/brand-requirements/mastercard.html Mastercard Rules — https://www.mastercard.com/content/dam/mccom/shared/business/support/rules-pdfs/mastercard-rules.pdf Note. The requirements in this guide are a consolidated, simplified summary drawn from the public brand standards above and from MatchMove's implementation experience. Where a specific measurement, coordinate, or minimum size is required for a Mastercard design, the Card Design Standards is authoritative and this guide is not a substitute for it. Partners are expected to comply with the version of each standard current at the time of card production. • [Card personalization and distribution](https://developer.matchmove.com/matchmove-banking-operating-system/card-program-operations/card-personalization-and-distribution.md): This section explains how cards move from your program configuration to your cardholders' hands — covering both virtual and physical cards, the distribution models available, and the integration touchpoints your platform needs to support along the way. Overview Card distribution is the end-to-end journey of a card from issuance request to an active, transaction-ready card. On the MatchMove Banking Operating System, this journey differs by card type: Virtual cards are issued and delivered instantly through the API. There is no physical card to prepare or deliver — the card is available to the cardholder the moment issuance succeeds. Physical cards must reach the cardholder before they can be used — whether personalized cards are delivered to them or distributed as non-personalized stock to the partner for the last mile delivery. These cards will remain inactive until the cardholder activates them. Understanding which model your program uses determines which parts of this guide apply to your integration. Scope This document covers the distribution journey: from the point a card is issued under your program through delivery or hand-over to linking and activation. It applies to both virtual and physical cards across all distribution models. The following assumptions apply throughout: Card design has been approved. Once the network approves your card artwork against their branding guidelines Virtual card designs can be displayed digitally within the partner’s app or website For physical cards, this approval clears the design for mass production Cards are already manufactured (blank card). Card manufacturing, data preparation and file transmission, data injection (required for the personalization process), surface printing, and packaging occur separately during the card kitting and fulfillment phase and fall outside the scope of this document. Before You Issue A Card: Program Prerequisites Launching a card program involves several critical milestones that must be reached before your platform can execute its first issuance API request. During this onboarding phase, you will collaborate with your MatchMove account team to finalize the following configurations: BIN and card design approval — physical and virtual card artwork must be approved against network branding requirements before cards can be produced. Program configuration — a specific card_type is assigned to each unique card product, defined by its form and design. Each combination is its own card product with its own card_type — even two personalized physical cards that differ only in color, say a blue edition and a red edition, are two distinct card products. These must be added to the system under your program before they can be issued. This is configured by your MatchMove account team once the card design is approved. Card stock (physical programs, production only) — for physical card issuance, manufactured card stock must be available first (for both personalized and non-personalized card models). Lead times apply to initial stock and replenishment. This prerequisite applies only to the production environment — there is no physical card production in staging, so integration and UAT can proceed without stock in place. Once these are in place, your platform can begin issuing cards programmatically. Virtual Card Issuance Virtual cards follow the simplest issuance path because no delivery of the card is needed. When your platform calls the card issuance endpoint for a verified customer, the platform generates the card, links it to the customer's wallet, and returns a card reference. From that point the card is live. Your application then surfaces the card details to the cardholder through the secure card display mechanism — full PAN, expiry, and CVV are never returned in plain API responses and must be rendered through the secure retrieval flow. Because there is no physical journey, the operational focus for virtual programs is on the moments around issuance: ensuring the customer has completed KYC before the issuance call and handling issuance failures gracefully. Physical Card Issuance and Distribution Physical cards introduce a journey between issuance and use. How the journey works depends first on the card class your program uses: Personalised Cards (Model 1) These cards are produced for a specific customer and carry their personal identity. Card Features The cardholder's name is embossed or printed on the card, and the expiry date matches the date it was ordered on the platform. Production Process Blank cards are kept in inventory. Personalization (embossing names and encoding credentials) occurs in batches as issuance requests are received. Distribution & Last Mile Delivery Because the customer is known, these follow direct-to-cardholder distribution. The last-mile delivery leg is usually handled by an appointed courier connected to the MatchMove platform. Non-Personalised Cards (Model 2) These cards are produced as generic stock with no cardholder identity and a generic expiry date. Assigned After Last Mile Delivery The card is sent to the user without any assignment happening before last-milemile delivery request is raised. The user can activate any generic card they receive. To activate, the user must provide card details that match the bulk card records maintained in the partner's database. Non-Personalised Cards (Model 3) These cards are produced as generic stock with no cardholder identity and a generic expiry date. Assigned Before Last Mile Delivery The card is bound/assigned to a specific user before the last-mile delivery A request is raised. Only the specific user can activate the assigned card. If an unassigned user attempts activation or the card received is incorrect, the partner's database will reject the request. Model Card Class Linked to Customer Cardholder Actions after Card Receipt 1 — Direct to cardholder Personalized At issuance Activation 2 — Assigned After Last Mile Delivery Non-personalized After last-mile delivery Linking, then activation 3 — Assigned Before Last Mile Delivery Non-personalized Before last-mile delivery Activation Model 1 — Direct-to-Cardholder Distribution (Personalised) Each card is personalized for a specific customer and shipped directly to them. Issuance request. Your platform calls the issuance endpoint with the cardholder's details, including the delivery address. Personalization. Issuance requests are processed in batches: a pre-manufactured blank card is embossed or printed with the cardholder's name and encoded with the card credentials. Delivery. The personalized card is packaged with its carrier and delivered through a MatchMove platform-chosen arrangement: dispatched directly to the cardholder's address via platform-enabled couriers. Specific delivery methods and timelines vary by market and arrangement. Delivery and activation. The card arrives inactive. The cardholder activates it through your application, which calls the card activation endpoint. Until activated, the card cannot transact. This model suits programs where cardholders sign up remotely — the trade-off is delivery lead time between issuance and first use. Many programs pair a physical card with an instantly issued virtual card so the cardholder can transact immediately while the physical card is in transit. To learn more about how you can issue a personalized physical card, you may go to the Request for a personalized physical card section. Model 2 — Assigned After Last Mile Delivery (Non-Personalised) Non-personalized card stock is distributed to your customers directly — handed over in person at retail locations, branch offices, or event sites, or delivered without prior assignment. The card reaches the customer before it is tied to any account, so the customer completes the linking themselves. Stock distribution. Unassigned cards are produced in one go and delivered to your one centralized appointed distribution point. The Partner will then arrange for its own next distribution services to their retail partners or ship onward directly to customers. Each card carries a unique reference but no cardholder identity. Handover and Last Mile Delivery. After undergoing the personalization process, the printed bulk of personalized cards will be handed over from MachMove and then handed over to the Partner at the bureau center. After that, the partner will handle the last-mile delivery to the cardholder either via its own arrangement or by connecting to a MatchMove-appointed courier company. The card is given to a customer — either an existing user of your program or a brand-new one. New customers must complete registration and KYC before the card can be linked. Card linking / assignment. The customer goes through the card linking process, which links that specific card to their verified account. Card activation. Once linked, the customer completes activation. Only after both steps is the card ready to transact. This model eliminates shipping waits for in-person distribution and is the only model that supports acquiring brand-new customers at the point of hand-over. The operational responsibility shifts to your side: physical stock custody, inventory reconciliation, and secure handling of unassigned cards at each location. To learn more about how you can link an existing user to a non-personalized card, you may go to Link & activate a non-personalised physical card (Non-personalized) section. Model 3 — Assigned Before Last Mile Delivery (Non-Personalised) Non-personalized stock is linked to a customer before it leaves your custody. Each card is assigned to an existing, verified user in the system and only then dispatched to them. Card linking / assignment. Your platform assigns a specific card from stock to an existing user's account. The link is established system-side — the customer takes no action at this stage. Handover and Last-Mile Delivery. Similar to Model 2, there will be a handover of the bulk personalized printed cards from the personalization bureau to the Partner. Then the Partner will be responsible for managing the last-mile delivery to the cardholder either via its own logistics/courier company or through MatchMove-appointed courier partner Card activation. On receipt, the customer completes activation only — no linking step is needed, because the card is already linked to their account. This model combines the production economics of non-personalized stock with the simpler cardholder experience of Model 1: the customer receives a card that is already theirs and has just one step between receipt and first use. It requires that the customer already exist in the system, so it suits programs distributing to an established user base rather than acquiring new customers at handover. Card Order and Delivery Service For card programs that require last-mile delivery or courier assistance, MatchMove offers the Card Order and Delivery Service — an added, subscription-based service that takes over the delivery leg of the distribution journey. When enabled, the cards are dispatched to your cardholders through the platform's integrated courier network (see Card Delivery Options), supported by two capabilities that make deliveries reliable and visible. The service is activated per program and currently available in select regions; check with your MatchMove account team whether it can be enabled for your market. The two supporting capabilities address the questions every delivery-based program eventually faces: can we actually deliver to this address? And where is the card right now? Address serviceability checks validate a cardholder's delivery address before a card order is placed. Confirming up front that an address can be delivered to prevent delivery failures before production even begins — catching the problem at order time, when it costs a correction, rather than at delivery time, when it costs a returned card, a reissue, and a frustrated cardholder. Card order tracking provides end-to-end visibility of each order across the full journey — from initial order and personalization through to final delivery at the cardholder's doorstep. Your teams can retrieve the current status of any card order, and you can surface that same visibility to cardholders in your own application. Together, these capabilities reduce failed deliveries, cut reissue costs, and lower support volume during the delivery window — the period when cardholders are most likely to reach out asking where their card is. Card Linking / Assignment Card linking applies to non-personalized cards distributed under Model 2. It is the step that turns a generic card into the customer's card: the physical card they are holding is bound to their verified account in the system, and from that point the card belongs to them alone. Linking is necessary in Model 2 because of when the card changes hands. The customer receives the card before any relationship between card and account exists — unlike Model 1, where the card is produced for a known customer, or Model 3, where your platform assigns the card before dispatch. Until linking happens, the card in the customer's hands is inert plastic: it carries a unique reference, but it is connected to no account, holds no funds, and cannot transact. This is also what makes non-personalized distribution safe to operate at scale — a card lost or stolen before linking cannot be used by anyone. The linking journey looks like this from the customer's perspective: Be a verified customer. Linking requires a registered, KYC-verified account. Existing customers already meet this; new customers who received a card at hand-over complete registration and verification first. Identify the card. Two numbers on the card are needed to link it: the card proxy number (a non-sensitive reference that identifies the physical card) and the PAN (only the last 4-digit card number is needed for verification). How the customer captures these depends on the card design. On standard designs, the numbers are printed on the card and can be entered directly. Any design can also carry a QR code that the customer scans to be taken into the linking journey with the card already identified — and on numberless designs, where the numbers are hidden from the card face, the QR code is usually the primary way in. The customer provides these details through your application, telling the system exactly which physical card they hold. Link confirmed. The system binds that specific card to the customer's account. The card now appears under their profile, and the customer proceeds to activation. Linking is a one-time, permanent association — once a card is linked to an account, it cannot be re-linked to a different customer. To learn more about card linking or assignment, you may go to Link & activate a non-personalised physical card (Non-personalized) section. The QR Code on the Card For card designs that carry a QR code (usually printed on the back of the card), the code encodes a URL that takes the customer straight into the card journey — scanning it identifies the card without the customer typing anything. Sample QR URL format < Partner static URL > + / + < 8-digit Card Proxy numbe r> + < 4-digit PAN number > e.g. https://<matchmove-partner>.com/123456789999 The URL is composed of: Partner static URL — your fixed base address. This can be a universal link, so a scan can land the customer on your app landing page or directly invoke your mobile app itself, dropping them straight into the card linking experience. Card proxy number — the 8-digit non-sensitive reference that identifies the specific physical card. Last 4 digits of the PAN — can be used as a partial confirmation of the card number. For security purposes, only the last 4 digits of the PAN are loaded into the URL — never the full card number. URLs are inherently exposable: they can appear in browser histories, server logs, and shared links, so the full PAN is deliberately kept out of the QR code to ensure the card number is never exposed digitally. Activation and First Use Regardless of distribution model, a physical card's lifecycle gate is activation. Activation can only begin once the card is linked to the customer — whichever model established that link: at issuance for personalized cards (Model 1), through the customer's card-linking process (Model 2), or through system-side assignment (Model 3). Only then can card activation be started. Your integration should treat activation as a deliberate cardholder action — typically triggered from your app after the cardholder confirms receipt — rather than an automatic step. For programs on mJIT funding, remember that activation makes the card usable , but every transaction is still authorized in real time against your funding decision. For standard funding programs, ensure the associated wallet is funded before the cardholder's first transaction attempt. To learn more about the card activation process, you may go to the Link & activate a non-personalised physical card , and Activate a personalised physical card sections. • [Issue a card](https://developer.matchmove.com/matchmove-banking-operating-system/issue-a-card.md): Partners can enable different card types and forms that suit their business requirements. The card issuance process has some prerequisites before a card can be issued to a customer: User profile defined The user profile has been created. This should apply to both individual and business users. Depending on regional availability, some regions may allow card issuance even for minimum KYC-level users. User profile active After the user profile is created, it will undergo a risk evaluation. The user profile must pass this risk check; otherwise, the user will be flagged and deactivated. User account provisioned An active account/wallet associated with the user profile must be provisioned. The account will be the placeholder for cards. To it, all the cards will be associated or linked. Virtual Card Virtual cards are payment cards similar to physical cards, but in a digital form. They can function like a physical card and are enabled for online and offline payments. For offline and in-store payments, these virtual cards must be tokenized into a digital wallet before they can be used. A virtual card is issued to a user account in an active state. They don't need to be activated and are ready to be used immediately for payments, provided the user account has a balance. Physical Card Physical cards are the physical and tangible form of payment cards. They can be used standalone for online and offline payments, provided that the user account has a balance. A physical card is issued to a user account in a “pending activation” state. They cannot be used unless the card has completed the activation process. The activation can only commence once the physical card has been delivered to the cardholder. Details about the card will need to be verified by the partner before the physical card can be activated. Physical cards have two (2) types: 1. Personalised Physical Cards Personalized physical cards are printed with the cardholder's information embedded in them. This embedding of cardholder details on the cards is called personalisation . Usually, these cards are printed in batches depending on the order arrangements of the partner with MatchMove and the card printer. Card delivery can be directly from the card printer or picked up by the partner. 2. Non-personalised Physical Cards Non-personalized physical cards are printed with a card design without personalization or cardholder information embedded in it. This type of card is usually ordered in bulk units. Since no cardholder information is embedded in the card, an identifier is printed instead. This identifier is printed on the back of the card and is called the “CARD KIT NUMBER” or the “ASSOCIATION CODE ( assoc_code )”. This identifier will be used to associate a specific card with a user during card issuance. During card delivery, the partner must determine which specific card has been associated with the user and send the correct one to the user. Issue a Card Issue a virtual card Issue a virtual card for your end user. Link and activate non-personalised physical cards Allow your end user to link and activate non-personalized cards. Request for a physical personalised card Allow your user to request personalized cards. Activate a personalised physical card Allow your user to activate a personalized card after it's printed. Related Links Card overview Create your card product Issue a virtual card Link & activate a non-personalized physical card Request for a personalized physical card Activate a personalized physical card Manage cards Card spending control Card payment authentication Card payments Manage card security • [Issue a virtual card](https://developer.matchmove.com/matchmove-banking-operating-system/issue-a-card/issue-a-virtual-card.md): Understand the process for instantly issuing a digital-only virtual card for your users. This guide covers the steps required to create a card ready for immediate online use. The user in this document pertains to both the individual and business user types. Use Cases You want to issue a virtual card and associate it with a user account. You want to issue a card (virtual) to a user that can be immediately usable after card creation. You want to issue a virtual card that can be used for e-commerce or online purchases. You want to issue disposable or one-time transaction virtual cards that can be discarded after their card transactions are settled. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. API Workflow 1 Retrieve available card types Call the List Card Types ( GET /users/wallets/cards/types ) to get a list of available card products enabled in the program. Note that this API uses public scope. Ensure X-Auth-User-ID is not passed when calling this API. List Card Types API request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' List Card Types API response JSON { "types": [ { "code": "sgmmdemomcpcard", "name": "MatchMove Physical Card", "description": "MatchMove Physical Card", "form_factor": "physical", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-large.png" }, "details": { "max_load_limit": 500000, "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomcppcard", "name": "MatchMove Personalized Physical Card", "description": "MatchMove Personalized Physical Card", "form_factor": "physical", "personalised_order": true, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } } ] } If you want to offer the choice to the user and also show the card design, you can filter the objects with form_factor value equal to virtual . Additionally, you can use the image object under a given card type to display the card design to the user when he is choosing the card product. You are also recommended to check details.issuance_limit to validate if the user can be issued more cards against that card type. Every card product has an issuance limit, which dictates how many cards for a given card type can be issued to a given user in the system. If you try to create cards that breach this limit, the system will throw an issuance limit error. 2 Initiate virtual card creation Depending on whether it's a user-initiated choice or a choice you are making for your program on behalf of the user, once the card_type_code has been selected. Call the Create Card ( POST /users/wallets/cards/types/{{card_type_code}} ) to trigger the virtual card creation. You may refer to the API reference page to view the list of error codes associated with this endpoint. Create Card (Virtual) request CURL curl --location --request POST 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/{{card_type_code}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Create Card (Virtual) response JSON { "id": "7bea197412c6df14ce4e80b5e6d13353", "number": "5412320000120012", "holder": { "name": "John Smith" }, "type": { "type": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-07", "issued": "2025-07-18", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "status": { "is_active": true, "text": "active" }, "reason": null, "kit": "000012342122", } 3 Display virtual card details to the end-user (frontend) Call the Get Card Details ( GET /users/wallets/cards/{{card_id}} ) API by passing the card_id to retrieve the non-sensitive card details. This will include the cardholder's name, card image, etc., which you can use to construct the card form in your frontend and display it to the user. Go to the Retrieve non-sensitive card information to learn more about non-sensitive card information. Get Card Details request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/7bea197412c6df14ce4e80b5e6d13353' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Card Details response JSON { "id": "7bea197412c6df14ce4e80b5e6d13353", "number": "5412320000120012", "holder": { "name": "John Smith" }, "type": { "type": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-07", "issued": "2025-07-18", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "status": { "is_active": true, "text": "active" }, "reason": null, "kit": "000012342122", } Call the Get Card Sensitive Details ( GET /users/wallets/cards/{{card_id}}/sensitive-data ) to reveal the transaction-sensitive card information. Go to the Retrieve sensitive card information to learn more about these protected card data. When needed, the list of card IDs associated with a user and account can be retrieved using the Get Wallet s ( GET /users/wallets ). Related Links Card overview Create your card product Issue a card Link & activate a non-personalized physical card Request for a personalized physical card Activate a personalized physical card Manage card Card spending control Card payment authentication Card payment fees Manage card security • [Link & activate a non-personalised physical card](https://developer.matchmove.com/matchmove-banking-operating-system/issue-a-card/link-and-activate-non-personalized-physical-card.md): Learn how to assign and activate a non-personalised physical card for a specific user. This guide explains the process of linking a non-personalised physical card to a user's account, making it ready for use. The user in this document pertains to both the individual and business user types. Use Cases You want to link or associate a specific non-personalised physical card (non-activated) from the bulk of printed physical cards. You want to activate a linked card that was delivered to a user and enable it for online and offline transaction usage. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. For card activation, the physical card must have already been delivered to the end user via applicable channels or modes of distribution. The embossing file containing the details of the non-personalized cards (in bulk) that can be linked to the users has already been handed over to the partner. Request this file from your MatchMove Implementation team before you proceed with the non-personalised card provisioning. API Workflow 1 Retrieve available card types Call the List Card Types ( GET /users/wallets/cards/types ) to get a list of available card products enabled in the program. Note that this API uses public scope. Ensure X-Auth-User-ID is not passed when calling this API. List Card Types API request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' List Card Types API response JSON { "types": [ { "code": "sgmmdemomcpcard", "name": "MatchMove Physical Card", "description": "MatchMove Physical Card", "form_factor": "physical", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-large.png" }, "details": { "max_load_limit": 500000, "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomcppcard", "name": "MatchMove Personalized Physical Card", "description": "MatchMove Personalized Physical Card", "form_factor": "physical", "personalised_order": true, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } } ] } If you want to offer the choice to the user and also show the card design, you can filter the objects with form_factor value equal to physical . Additionally, you can use the image object under a given card type to display the card design to the user when he is choosing the card product. You are also recommended to check details.issuance_limit to validate if the user can be issued more cards against that card type. Every card product has an issuance limit, which dictates how many cards for a given card type can be issued to a given user in the system. If you try to create cards that breach this limit, the system will throw an issuance limit error. 2 Link a non-personalized card to the user account Call the Create Cards POST /users/wallets/cards/types/{{card_type_code}} passing the correct physical card card_type_code to trigger the linkage process of a non-personalized card to the account. Depending on your card-issuing journey, you have two modes of providing the card identifier that will be linked to the user account. This card identifier must be passed to the assoc_number parameter for linkage. Card Identifier Description assoc_number Proxy number or card kit number This is the identifier that is used to generate the kit number of the personalized card. This number will be printed on the back of the physical card. In the staging environment, the proxy number can be located in the embossing file received from the MatchMove Implementation team. assoc_number = PY + <kit_number> E.g., if the proxy number is 00012342122, the value passed for assoc_number will be PY000012342122 Card number or PAN This is the actual card number of the physical card assigned and delivered to the end user In the staging environment, the PAN will be masked until the card is activated, so this linking method will not be available. In the live environment, the PAN can be located by the end-user printed on the non-personalised physical card. In this scenario, the card delivery has happened before the card creation or linking. You will need to ask the end-user to input this PAN in your frontend to be able to link it to his account. assoc_number = <16-digit card number> E.g., if the card number is 5412 3200 0012 0012, the value passed for assoc_number will be 5412320000120012 The Create Card s has a parameter that allows you to do card linking and activation of a non-personalised card in one go. To do this, you will need to pass it auto_activate = true as a request parameter. Create Cards (Non-personalized physical) request using proxy number CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcpcard' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'assoc_number=PY000012342122' Create Cards (Non-personalized physical) request using card number CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcpcard' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'assoc_number=5412320000120012' Create Cards (Non-personalized physical) response JSON { "id": "d41d8cd98f00b204e9800998ecf8427e", "number": "5412XXXXXXXX0012", "holder": { "name": "John Doe" }, "type": { "type": "sgmmdemomcpcard", "name": "MatchMove Physical Card", "description": "MatchMove Physical Card", "form_factor": "physical", "personalised_order": false }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-01", "issued": "2030-01-01", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-large.png" }, "status": { "is_active": false, "text": "pending_activation", }, "activation_code": "123456", "kit": "000012342122" } Create cards response The Create Cards request will return the card status as pending_activation on the initial. The new linked card will be assigned a unique card_id identifier, which is a unique identifier for the card in the MatchMove platform. You also have the option to save this card_id in your data store to have a direct identifier to access a specific card. The response will also return a activation_code value that will be required to activate the card later, if you did not pass auto_activate = true 3 Activate a non-personalized physical card Using the activation_code returned from the card linking stage and the card_id generated by the system, you can proceed to activate the physical card. Call Activate Cards PUT /users/wallets/cards/{{card_id}} to start activating the non-personalized physical card. Activate Cards (non-personalized physical) request Bash curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'activation_code={{activation_code}}' Activate Cards (non-personalized physical) response JSON { "status": "success" } [Optional] Additional security and authentication measures that you can add before card activation: Verify the activation code — the activation_code can be sent to the customer in the form of an email/SMS/push as an OTP. When the customer has returned the code, you can verify if it's similar to the one in the records. Verify the last 4 digits of the card number — Until the card is in an active state, the card number on file will be masked and only reveal the last 4 digits. You can ask for the last 4 digits of the PAN from the user and verify it against the one in the records. Verify the proxy number or the card kit number — Additionally, you can also ask to validate the card kit number printed on the back of the non-personalized physical card of the customer. 4 Display non-personalised physical card details to the end-user (front end) Even though the card is of a physical product, you can still display its card details in a digital format. Call the Get Card Non-sensitive Details ( GET /users/wallets/cards/{{card_id}} ) by passing the card_id to retrieve the non-sensitive card details. This will include the cardholder's name, card image, etc., which you can use to construct the card form in your frontend and display it to the user. Go to the Retrieve non-sensitive card information to learn more about non-sensitive card information. Get Card Non-sensitive Details request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/7bea197412c6df14ce4e80b5e6d13353' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Card Non-sensitive Details response JSON { "id": "7bea197412c6df14ce4e80b5e6d13353", "number": "5412320000120012", "holder": { "name": "John Smith" }, "type": { "type": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-07", "issued": "2025-07-18", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "status": { "is_active": true, "text": "active" }, "reason": null, "kit": "000012342122", } Call the Retrieve Card Sensitive Details ( GET /users/wallets/cards/{{card_id}}/sensitive-data ) to reveal the transaction-sensitive card information. Go to the Retrieve sensitive card information to learn more about these protected card data. When needed, the list of card IDs associated with a user and account can be retrieved using the Get Wallet ( GET /users/wallets ). Related Links Card overview Create your card product Issue a card Issue a virtual card Request for a personalized physical card Activate a personalized physical card Manage card Card spending control Card payment authentication Card payments Card payment fees Manage card security • [Request for a personalised physical card](https://developer.matchmove.com/matchmove-banking-operating-system/issue-a-card/request-for-a-personalized-physical-card.md): Understand the steps to request a new physical card that is personalized with the cardholder's name. This guide covers the process of initiating a card order for production and delivery to the user. The user in this document pertains to both the individual and business user types. Use Cases You want to implement a feature in your application that will allow users to request a personalized physical card. You want to send a card order for a personalized physical card (non-activated) for a specific user. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. API Workflow 1 Retrieve available card types Call the List Card Types ( GET /users/wallets/cards/types ) to get a list of available card products enabled in the program. Note that this API uses public scope. Ensure X-Auth-User-ID is not passed when calling this API. List Card Types API request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' List Card Types API response JSON { "types": [ { "code": "sgmmdemomcpcard", "name": "MatchMove Physical Card", "description": "MatchMove Physical Card", "form_factor": "physical", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcpcard/card-large.png" }, "details": { "max_load_limit": 500000, "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomccard", "name": "MatchMove Virtual Card", "description": "MatchMove Virtual Card", "form_factor": "virtual", "personalised_order": false, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomccard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } }, { "code": "sgmmdemomcppcard", "name": "MatchMove Personalized Physical Card", "description": "MatchMove Personalized Physical Card", "form_factor": "physical", "personalised_order": true, "token": { "type": "CVV", "generation": "static" }, "currency": [ "USD" ], "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png" }, "details": { "network_type": "mastercard", "fee": "0.00", "fee_currency": "USD", "max_count": 10, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 } } } } ] } If you want to offer the choice to the user and also show the card design, you can filter the objects with form_factor value equal to physical . Additionally, you can use the image object under a given card type to display the card design to the user when he is choosing the card product. You are also recommended to check details.issuance_limit to validate if the user can be issued more cards against that card type. Every card product has an issuance limit, which dictates how many cards for a given card type can be issued to a given user in the system. If you try to create cards that breach this limit, the system will throw an issuance limit error. 2 Initiate a request for a personalized card order Call the Create Cards ( POST /users/wallets/cards/types/{{card_type_code}} ) passing the card type code of the personalized physical card. For personalized cards, you can specify a name on the card that will be embossed and printed on the physical card. You can do this by passing an optional parameter name_on_card . If the value is not passed, the card will be embossed based on the preferred_name value defined in the user profile. For personalized physical cards, the auto_activate parameter is not applicable. An activation process must be completed for this card type. Create Cards (Personalized physical) request Bash curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomcppcard' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ Create Cards (Personalized physical) response JSON { "id": "d41d8cd98f00b204e9800998ecf8427e", "number": "5412XXXXXXXX0012", "holder": { "name": "John Smith" }, "type": { "type": "sgmmdemomcppcard", "name": "MatchMove Personalized Physical Card", "description": "MatchMove Personalized Physical Card", "form_factor": "physical", "personalised_order": true }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-01", "issued": "2030-01-01", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png" }, "status": { "is_active": false, "text": "pending_activation", }, "links": [ { "rel": "cards.activation", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e", "method": "PUT" } ], "activation_code": "145193", "kit": "000004600855" } Create cards response The Create Cards request will return the card status as pending_activation on the initial. The new linked card will be assigned a unique card_id identifier, which is a unique identifier for the card in the MatchMove platform. You also have the option to save this card_id in your data store to have a direct identifier to access a specific card. The response will also return an activation_code value that will be required to activate the card later. 3 Card delivery to the customer In the live environment , after a successful personalized physical card provisioning, a card order will be generated and shared with the card printer. Then once the personalized physical card has been delivered to the end-user, the card activation process can commence. The delivery process to the end user is generally recommended to be managed by partners. Do reach out to your Implementation Manager to better understand the options available for you. In the staging environment , the actual printing of personalized physical cards will only be simulated. As such, you will need to pool (listed in batches) all newly provisioned personalized physical cards card id and submit them to the MatchMove Implementation team. This card list will be used to simulate card printing, which will result in a reverse embossing file . When the simulation is completed (signalling that the card has been delivered), the card activation process can commence. Related Links Card overview Create your card product Issue a card Issue a virtual card Link & activate a non-personalized physical card Activate a personalized physical card Manage card Card spending control Card payment authentication Card payments Manage card security • [Activate a personalised physical card](https://developer.matchmove.com/matchmove-banking-operating-system/issue-a-card/activate-a-personalized-physical-card.md): Learn the process for activating a personalised physical card once the user has received it. This guide explains the final step required to make the newly delivered card ready for transactions. The user in this document pertains to both the individual and business user types. Use Cases You want to activate a personalised physical card that was delivered to a user and enable it for online and offline transaction usage. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The physical card must be in a pending_activation status. The physical card must have already been delivered to the end user via applicable channels or modes of distribution. API Workflow 1 Activate a personalized physical card Collect the activation_code and card_id values returned as part of the request for the personalised physical card process. If you need to retrieve the activation_code again, this value can be accessed using the Get Card Non-sensitive Details ( GET /users/wallets/cards/{{card_id}} ). Get Card Non-sensitive Details request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Card Non-sensitive Details response JSON { "id": "d41d8cd98f00b204e9800998ecf8427e", "number": "5412XXXXXXXX0012", "holder": { "name": "John Smith" }, "funds": { "available": { "currency": "USD", "amount": "0.00" }, "withholding": { "currency": "USD", "amount": "0.00" } }, "type": { "type": "{{card_type_code}}", "name": "MatchMove Pay Persoanalised Physical Card", "description": "MatchMove Pay Persoanalised Physical Card", "form_factor": "physical", "personalised_order": true }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2029-06", "issued": "2024-06-25", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/{{card_type_code}}/card-small.png", "medium": "https://assets.mmvpay.com/global/products/{{card_type_code}}/card-medium.png", "large": "https://assets.mmvpay.com/global/products/{{card_type_code}}/card-large.png" }, "status": { "is_active": false, "text": "pending_activation" }, "reason": null, "links": [ { "rel": "cards.pins.set", "href": "https://beta-api.mmvpay.com/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e/pins", "method": "POST" }, { "rel": "cards.pins.verify", "href": "https://beta-api.mmvpay.com/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e/pins", "method": "PUT" }, { "rel": "cards.activation", "href": "https://beta-api.mmvpay.com/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e", "method": "PUT" } ], "activation_code": "145193", "kit": "000004600855" } [Optional] Additional security and authentication measures that you can add before card activation: Verify the activation code — the activation_code can be sent to the customer in the form of an email/SMS/push as an OTP. When the customer has returned the code, you can verify if it's similar to the one in the records. Verify the last 4 digits of the card number — Until the card is in an active state, the card number on file will be masked and only reveal the last 4 digits. You can ask for the last 4 digits of the PAN from the user and verify it against the one in the records. When all requirements are ready and verified, call the Activate Cards ( PUT /users/wallets/cards/{{card_id}} ) passing the activation code and card ID of the card being activated. Activate Cards (Personalized physical) request CURL curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'activation_code=145193' Activate Cards (Personalized physical) response JSON { "status": "success" } 2 Display personalised physical card details to the end-user (frontend) Even though the card is a physical product, you can still display its card details in a digital format. Call the Get Card Non-sensitive Details ( GET /users/wallets/cards/{{card_id}} ) to retrieve the non-sensitive card details. Go to the Retrieve non-sensitive card information to learn more about non-sensitive card information. Call the Get Card Sensitive Details ( GET /users/wallets/cards/{{card_id}}/sensitive-data ) to reveal the transaction-sensitive card information. Go to the Retrieve sensitive card information to learn more about these protected card data. When needed, the list of card IDs associated with a user and account can be retrieved using the Get Wallet ( GET /users/wallets ). Related Links Card overview Create your card product Issue a card Issue a virtual card Link & activate a non-personalized physical card Request for a personalized physical card Manage card Card spending control Card payment authentication Card payments Manage card security • [Manage cards](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards.md): Understand the various lifecycle operations available for managing user cards. This guide provides an overview of post-issuance actions, from setting controls to changing a card's state. Enable your users to fully control their cards from your mobile or web app The Managing Cards section allows users to perform essential actions on payment cards associated with their account. These functionalities allow users to suspend, unsuspend, block/delete, or reactivate cards as needed. This section provides the necessary tools for efficiently managing card-related operations within the application. Card Info Every card has information associated with it that is confidential. In addition to ensuring the security of end users for issuing cards, the MatchMove platform provides an additional level of security by providing two endpoints for showing the card information. The Get Card Details (GET v1/users/wallets/cards/{card_id}) API can be used to just display basic information in your application for your end user. When the user intends to use the card information to make payments, the required information is exposed via Get Sensitive Card Data (GET /v2/users/wallets/cards/{card_id}/sensitive-data) API. The API returns information in an encrypted manner, which you can then decrypt and show to your end users. This ensures proper end-to-end security for your users and ensures their details are safe Card statuses As part of the issuance and general lifecycle of the card, the card transitions to various statuses. These statuses control what that card can be used for. Status Functionality allowed pending_activation The card can only be activated at this point. No functionality other than activating a card is allowed at this point in time. active All functionality for the card is allowed. locked No new transaction can be authorized by the card. Any pending settlements will still be processed. blocked No new transaction can be authorized. No settlements can be posted against the card. Card PIN A card PIN is a 4 to 6-digit secret code that verifies the cardholder during transactions. A card PIN is the personal code you enter at an ATM or point‑of‑sale terminal to prove the card is yours. It’s checked by the MatchMove platform to authorize certain transactions, especially chip‑and‑PIN with an EMV chip. Transactions eligible for PIN are dependent on multiple factors, ranging from where the card is issued, the country where it is swiped, and the law of the land, as well as the profile associated with the card printing process. The MatchMove Platform is currently configured to support 4-digit pins. If your end user encounters a machine that mandates a six-digit PIN, you are recommended to ask the user to prefix 00 the PIN when entering the information in the terminal. Ensure that at the point of setting the PIN, you communicate to the user to use 4 digits for setting the PIN. Related Links Card overview Create your card product Issue a card Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Retrieve user cards](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/retrieve-users-cards.md): Learn how to retrieve a list of all cards associated with a specific user account. This guide explains how to fetch card data for display or management within your application. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the list of cards associated with a user account. You want to retrieve the card IDs from the list of associated cards. You want to know the individual status of each card from the list of associated cards. You want to display a list of cards that a user owns in your application. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user must have already been provisioned with at least one card. API Workflow 1 Retrieve the list of all cards associated with a user account Call the Get Wallet ( GET /users/wallets ) to get the wallet object, which contains a list of all the cards associated with the Get Wallet request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --header 'X-Auth-User-Id: {{user_id}}' Get Wallet response JSON { "funds": { "available": { "currency": "SGD", "amount": "0.00" }, "withholding": { "currency": "SGD", "amount": "0.00" }, "categories": { "DEFAULT": { "available": { "currency": "SGD", "amount": "0.00" }, "withholding": { "currency": "SGD", "amount": "0.00" } } } }, "id": "2daec22dec9cde3020e3843e13fcd3d3", "number": "6377020000000012", "holder": { "name": "John Doe" }, "date": { "expiry": "2030-03", "issued": "2025-03-05", "closed": null }, "status": { "is_active": true, "text": "active" }, "reason": null, "details": { "max_load_limit": 500000, "fee": "0.00", "fee_currency": "SGD", "purse": { "pre_kyc": { "purse_max_limit": 750 }, "post_kyc": { "purse_max_limit": 500000 } }, "topup_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 }, "current": { "lifetime_count": 29, "lifetime_transactional": 12037.259999999998, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "deduct_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 }, "current": { "lifetime_count": 20, "lifetime_transactional": 9093.54, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "transfer_in_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 }, "current": { "lifetime_count": 27, "lifetime_transactional": 23647.45, "daily_count": 2, "daily_transactional": 5000, "weekly_count": 2, "weekly_transactional": 5000, "monthly_count": 8, "monthly_transactional": 5040.7 } }, "transfer_out_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 750 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 500000 }, "current": { "lifetime_count": 41, "lifetime_transactional": 6118.829999999998, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 22, "monthly_transactional": 62.489999999999995 } }, "load_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": 15000, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 0 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 0 }, "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } }, "unload_limits": { "pre_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 2250, "lifetime_count_limit": null, "lifetime_transactional_limit": 15000, "monthly_count_limit": null, "monthly_transactional_limit": 2250, "weekly_count_limit": null, "weekly_transactional_limit": 2250, "annual_count_limit": null, "annual_transactional_limit": 15000, "unit_transactional_limit": 0 }, "post_kyc": { "allowed": 0, "daily_count_limit": null, "daily_transactional_limit": 500000, "lifetime_count_limit": null, "lifetime_transactional_limit": null, "monthly_count_limit": null, "monthly_transactional_limit": 500000, "weekly_count_limit": null, "weekly_transactional_limit": 500000, "annual_count_limit": null, "annual_transactional_limit": null, "unit_transactional_limit": 0 }, "current": { "lifetime_count": 0, "lifetime_transactional": 0, "daily_count": 0, "daily_transactional": 0, "weekly_count": 0, "weekly_transactional": 0, "monthly_count": 0, "monthly_transactional": 0 } } }, "cards": [ { "id": "89defae676abd3e3a42b41df17c40096", "status": { "is_active": false, "text": "locked" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomccard", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/5d6e52ee8586e0a7241b01c897b64666", "method": "GET" } ] }, { "id": "180ac588b91dc6bff6a5d42a671d1d6a", "status": { "is_active": true, "text": "active" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomccard", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/3e0d7f14bdd2ea3adecefa8361dd236e", "method": "GET" } ] }, { "id": "48e96eb31980d217d6d539eb583acbbc", "status": { "is_active": false, "text": "blocked" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/sgmmdemomccard", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/a25ab5a977f604b1398a89f25d9c7168", "method": "GET" } ] } ] } Parse the cards object to get the count of cards the user has, and create the length of the carousel or list view accordingly. Sample card object The card object is an array of all cards associated with the user account, including the basic information about each card. JSON [ { "id": "5d9bb6d5cbf2a07f514fd90fe401df2b", "status": { "is_active": false, "text": "locked" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/{{card_type}}", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/5d9bb6d5cbf2a07f514fd90fe401df2b", "method": "GET" } ] }, { "id": "22f139ca4f5bbf9e2174e9d0a526ed88", "status": { "is_active": false, "text": "active" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/{{card_type}}", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/22f139ca4f5bbf9e2174e9d0a526ed88", "method": "GET" } ] }, { "id": "b9943321da1382ffb25271b1856f4efb", "status": { "is_active": false, "text": "pending_activation" }, "type": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/types/{{card_type}}", "method": "GET" } ], "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/cards/b9943321da1382ffb25271b1856f4efb", "method": "GET" } ] } ] }, You can use the card type to dynamically fetch the card image associated with that card by generating url dynamically and concatenating it with the card type as below : https://assets.mmvpay.com/global/products/{{card_type}}/card-{{size.png}} The supported value for size is small medium large If needed, you can also use the response of List Card Types GET /users/wallets/cards/types to display additional details like product name, form factor, and description as well as other auxiliary attributes. The card types object can also be safely cached, rather than you having to call it every time. 2 Display action for each card depending on status Depending on the card status, you can have your UI show actions available for a particular card. The table below illustrates the actions possible depending on the card status. Card Status Possible Actions blocked No additional action is possible. This state is irreversible. You can choose to filter the array by status and exclude blocked card statuses to display only the remaining cards to your users locked Unlock (Unsuspend) pending_activation Activate active View basic details. View sensitive details. Lock (Suspend) Block (Delete) Set PIN (only for physical cards). Related Links Card overview Create your card product Issue a card Manage cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Retrieve non-sensitive card information](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/get-basic-info-of-a-specific-card.md): Understand how to securely retrieve non-sensitive information for a specific card for display in your application. This guide covers accessing details like the last four digits and cardholder name without exposing transaction-critical data. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the non-sensitive and transaction-non-critical details of a specific card. You want to retrieve the card status and form details of a specific card. You want to display a visual image of the card, along with the non-sensitive data, in your application. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an active status. API Workflow 1 Retrieve the non-sensitive card details Call the Get Card Non-sensitive Details ( GET /users/wallets/cards/{{card_id}} ) by passing the card_id to retrieve the non-sensitive card details. Non-sensitive card details Card Detail Description id The card_id or the card identifier generated for the card number The masked card number or PAN of the card holder.name The cardholder's name type The card type and form factor details date The issuance and expiry date of the card image The card form image status The current card status The list of card IDs associated with a user and account can be retrieved using the Get Wallet ( GET /users/wallets ) Get Card Non-sensitive Details API request Bash curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/d41d8cd98f00b204e9800998ecf8427e' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Card Non-sensitive Details API response JSON { "id": "d41d8cd98f00b204e9800998ecf8427e", "number": "5412XXXXXXXX0012", "holder": { "name": "John Doe" }, "type": { "code": "sgmmdemomcppcard", "name": "MatchMove Personalized Physical Card", "description": "MatchMove Personalized Physical Card", "form_factor": "physical", "personalised_order": true }, "token": { "type": "CVV", "generation": "static" }, "date": { "expiry": "2030-01", "issued": "2030-01-01", "closed": null }, "image": { "small": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-small.png", "medium": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-medium.png", "large": "https://assets.mmvpay.com/global/products/sgmmdemomcppcard/card-large.png" }, "status": { "is_active": true, "text": "active", }, "activation_code": "123456", "kit": "000012342122" } You can use this non-sensitive card information to render the card form displaying the basic information to the user. Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Retrieve sensitive card information](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/retrieve-sensitive-card-information.md): Learn the secure method for retrieving sensitive card information, such as the full card number and CVV. This guide explains the security requirements for accessing these critical card transaction fields. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the sensitive and transaction-critical details of a specific card, such as the security code and unmasked PAN. You want to display a visual image of the card, along with the sensitive data needed to initiate a card transaction, in your application. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an active status. API Workflow 1 Retrieve sensitive information via API Call the Get Card Sensitive Details GET /users/wallets/cards/{{card_id}}/sensitive-data passing the X-Data-Key-ID to retrieve the sensitive card information. The X-Data-Key-ID key will be provided to you alongside the program resources. Sensitive card information Card Detail Description pan_info.number The encrypted card number or the PAN pan_info.date The card expiry number security_code_info.value The encrypted security code (CVV/CVC) Depending on your need, the API has an optional query parameter info_type to only retrieve either pan_info or security_code_info . Get Card Sensitive Details request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a/sensitive-data' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'X-Auth-User-Id: {{data_key_id}}' \ --header 'Authorization: ••••••' Get Card Sensitive Details response JSON { "pan_info": { "number": "d6Lf1qAYOvgBgxKKuD0FO/L1czVkEZWJwMlLSe0GY1g=", "date": { "expiry": "2030-01" } }, "security_code_info": { "value": "RVRdEqm6NV+7+Kar0ismVg==" } } 2 Decrypt the encrypted card details An encryption key will also be provided with the program resources. This encryption key is mapped to the X-Data-Key-ID used in the Get Card Sensitive Details. Encryption Specifications Algorithm: AES-256-CBC Key Size: 256 bits (32 bytes) Padding: PKCS#7 Initialization Vector (IV): Derived from the first 16 bytes of the card_id Decryption Steps Derive the IV: Extract the first 16 bytes from the card_id. Configure the AES Cipher: Use AES-256-CBC mode with PKCS#7 padding. Decrypt the Encrypted Data: Decode the Base64-encoded encrypted string and decrypt using the derived IV and AES key. Sample decryption code Go Golang code snippet to help decrypt the encrypted data Go package main import ( "crypto/aes" "crypto/cipher" "encoding/base64" "errors" "fmt" ) // pkcs7Unpadding removes the padding from the decrypted data func pkcs7Unpadding(data []byte) ([]byte, error) { paddingLength := int(data[len(data)-1]) if paddingLength > len(data) { return nil, errors.New("invalid padding size") } return data[:len(data)-paddingLength], nil } // decryptAES decrypts AES-256-CBC encrypted data func decryptAES(encryptedData, key, iv []byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { return nil, err } if len(encryptedData) < aes.BlockSize { return nil, errors.New("ciphertext too short") } mode := cipher.NewCBCDecrypter(block, iv) // Decrypt into a new buffer decrypted := make([]byte, len(encryptedData)) mode.CryptBlocks(decrypted, encryptedData) // Remove PKCS#7 padding decrypted, err = pkcs7Unpadding(decrypted) if err != nil { return nil, err } return decrypted, nil } // DecryptBase64AES256CBC decrypts base64-encoded AES-256-CBC ciphertext using the given key and cardHashId as IV func DecryptBase64AES256CBC(base64Ciphertext, cardHashId, base64Key string) (string, error) { // Base64 decode the ciphertext encryptedData, err := base64.StdEncoding.DecodeString(base64Ciphertext) if err != nil { return "", err } // Base64 decode the key key, err := base64.StdEncoding.DecodeString(base64Key) if err != nil { return "", err } if len(key) != 32 { return "", errors.New("invalid key size: must be 32 bytes for AES-256") } // Use the first 16 bytes of the cardHashId as the IV iv := []byte(cardHashId)[:aes.BlockSize] if len(iv) != aes.BlockSize { return "", errors.New("invalid IV size") } // Decrypt the data decryptedData, err := decryptAES(encryptedData, key, iv) if err != nil { return " ", err } return string(decryptedData), nil } func main() { // Example usage cardHashId := "your_card_hash_id_here" // Example card identifier (must be at least 16 bytes) // Original 32-byte key (as a hex string) originalKey := "your_original_key" // Convert the hex string to bytes keyBytes, err := hex.DecodeString(originalKey) if err != nil { fmt.Println("Error decoding hex:", err) } // Base64 encode the key base64Key := base64.StdEncoding.EncodeToString(keyBytes) base64Ciphertext := "your_base64_encrypted_data_here" // Decrypt the data decrypted, err := DecryptBase64AES256CBC(base64Ciphertext, cardHashId, base64Key) if err != nil { fmt.Println("Error decrypting:", err) } else { fmt.Println("Decrypted data:", decrypted) } } PHP PHP code snippet to help decrypt the encrypted data PHP <?php // Decrypt AES-256-CBC encrypted data function decryptAES($encryptedData, $key, $iv) { $decrypted = openssl_decrypt($encryptedData, 'aes-256-cbc', $key, OPENSSL_RAW_DATA, $iv); if ($decrypted === false) { throw new Exception('Decryption failed'); } return $decrypted; } // Decrypt Base64-encoded AES-256-CBC ciphertext using the given key and cardHashId as IV function decryptBase64AES256CBC($base64Ciphertext, $cardHashId, $base64Key) { // Base64 decode the ciphertext $encryptedData = base64_decode($base64Ciphertext); if ($encryptedData === false) { throw new Exception('Invalid base64 ciphertext'); } // Base64 decode the key $key = base64_decode($base64Key); if ($key === false || strlen($key) !== 32) { throw new Exception('Invalid key size: must be 32 bytes for AES-256'); } // Use the first 16 bytes of the cardHashId as the IV $iv = substr($cardHashId, 0, 16); if (strlen($iv) !== 16) { throw new Exception('Invalid IV size'); } // Decrypt the data return decryptAES($encryptedData, $key, $iv); } // Example usage try { $cardHashId = "your_card_hash_id_here"; // Example card identifier (must be at least 16 bytes) // Original hex string $originalKey = "your_original_key"; // Convert hex string to byte array $keyBytes = hex2bin($originalKey); // Base64 encode the byte array $base64Key = base64_encode($keyBytes); $base64Ciphertext = "your_base64_encrypted_data_here"; $decrypted = decryptBase64AES256CBC($base64Ciphertext, $cardHashId, $base64Key); echo "Decrypted data: $decrypted"; } catch (Exception $e) { echo 'Error decrypting: ' . $e->getMessage(); } ?> NodeJS NodeJS code snippet to help decrypt the encrypted data JavaScript const crypto = require('crypto'); // Decrypt AES-256-CBC encrypted data function decryptAES(encryptedData, key, iv) { const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv); decipher.setAutoPadding(true); // Ensure auto padding is enabled let decrypted = Buffer.concat([decipher.update(encryptedData), decipher.final()]); return decrypted; } // Decrypt Base64-encoded AES-256-CBC ciphertext using the given key and cardHashId as IV function decryptBase64AES256CBC(base64Ciphertext, cardHashId, base64Key) { try { // Base64 decode the ciphertext const encryptedData = Buffer.from(base64Ciphertext, 'base64'); // Base64 decode the key const key = Buffer.from(base64Key, 'base64'); if (key.length !== 32) { throw new Error('Invalid key size: must be 32 bytes for AES-256'); } // Use the first 16 bytes of the cardHashId as the IV const iv = Buffer.from(cardHashId).slice(0, 16); if (iv.length !== 16) { throw new Error('Invalid IV size'); } // Decrypt the data const decryptedData = decryptAES(encryptedData, key, iv); return decryptedData.toString('utf8'); } catch (error) { console.error('Error decrypting:', error.message); return ''; } } // Example usage const cardHashId = "your_card_hash_id_here"; // Example card identifier (must be at least 16 bytes) // Convert hex string to a byte array // Original 32-byte key (as a hex string) const originalKey = "your_original_key"; const bytes = []; for (let i = 0; i < originalKey.length; i += 2) { bytes.push(parseInt(originalKey.substr(i, 2), 16)); } // Convert byte array to Base64 string const byteArray = new Uint8Array(bytes); let binaryString = ''; for (let i = 0; i < byteArray.length; i++) { binaryString += String.fromCharCode(byteArray[i]); } const base64Key = btoa(binaryString); const base64Ciphertext = "your_base64_encrypted_data_here"; const decrypted = decryptBase64AES256CBC(base64Ciphertext, cardHashId, base64Key); console.log('Decrypted data:', decrypted); Java JAVA code snippet to help decrypt the encrypted data Java import javax.crypto.Cipher; import javax.crypto.spec.IvParameterSpec; import javax.crypto.spec.SecretKeySpec; import java.util.Base64; public class AESDecryption { // Decrypt AES-256-CBC encrypted data public static byte[] decryptAES(byte[] encryptedData, byte[] key, byte[] iv) throws Exception { SecretKeySpec secretKeySpec = new SecretKeySpec(key, "AES"); IvParameterSpec ivParameterSpec = new IvParameterSpec(iv); Cipher cipher = Cipher.getInstance("AES/CBC/PKCS5Padding"); cipher.init(Cipher.DECRYPT_MODE, secretKeySpec, ivParameterSpec); return cipher.doFinal(encryptedData); } // Decrypt Base64-encoded AES-256-CBC ciphertext using the given key and cardHashId as IV public static String decryptBase64AES256CBC(String base64Ciphertext, String cardHashId, String base64Key) throws Exception { // Base64 decode the ciphertext byte[] encryptedData = Base64.getDecoder().decode(base64Ciphertext); // Base64 decode the key byte[] key = Base64.getDecoder().decode(base64Key); if (key.length != 32) { throw new IllegalArgumentException("Invalid key size: must be 32 bytes for AES-256"); } // Use the first 16 bytes of the cardHashId as the IV byte[] iv = cardHashId.getBytes("UTF-8"); iv = java.util.Arrays.copyOf(iv, 16); // Ensure the IV is exactly 16 bytes // Decrypt the data byte[] decryptedData = decryptAES(encryptedData, key, iv); return new String(decryptedData, "UTF-8"); } // Helper function to convert hex string to byte array public static byte[] hexStringToByteArray(String hexString) { int len = hexString.length(); byte[] data = new byte[len / 2]; for (int i = 0; i < len; i += 2) { data[i / 2] = (byte) ((Character.digit(hexString.charAt(i), 16) << 4) + Character.digit(hexString.charAt(i + 1), 16)); } return data; } public static void main(String[] args) { try { String cardHashId = "your_card_hash_id_here"; // Example card identifier (must be at least 16 bytes) // Original hex string String originalKey = "your_original_key"; // Convert hex string to byte array byte[] keyBytes = hexStringToByteArray(originalKey); // Base64 encode the byte array String base64Key = Base64.getEncoder().encodeToString(keyBytes); String base64Ciphertext = "your_base64_encrypted_data_here"; String decrypted = decryptBase64AES256CBC(base64Ciphertext, cardHashId, base64Key); System.out.println("Decrypted data: " + decrypted); } catch (Exception e) { System.out.println("Error decrypting: " + e.getMessage()); } } } 3 Display decrypted card details to the customer You can display the decrypted card details to your frontend so the customer can use the details on their online card transaction. You are recommended to have your own encryption mechanism between server and client to ensure that the information is transmitted in a secure manner from your backend to the client application. You are also recommended to have a mechanism to automatically mask the information to your end user after a reasonable duration. You are encouraged to review the guide for the Managing Card Security section. Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve non-sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Set card PIN](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/set-card-pin.md): Understand the process for setting or changing the PIN for a physical card. As this feature is only available for physical cards, this guide covers the secure steps a user must take to manage their PIN. The user in this document pertains to both the individual and business user types. Use Cases You want to implement a feature in your application that will allow users to set their card PIN for ATM and offline transactions. You want to implement a feature in your application that will allow users to reset a compromised or forgotten card PIN. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an active status. API Workflow 1 Ask the user to employ a PIN In your Set PIN page, you can ask the user to employ a PIN. Please note that the system currently only supports a 4-digit PIN . 2 Prepare to generate a PIN block A PIN block is a secure, encrypted data structure used in electronic financial transactions (like those at an ATM or a point-of-sale terminal) to protect a cardholder's Personal Identification Number (PIN) before transmitting it. The PIN block must be encrypted using a ZPK or Zone PIN Key (also known as a PIN Protection Key or PPK ), a cryptographic key used in the financial services industry to secure cardholders' PINs during electronic financial transactions. The ZPK is part of the program resources that will be provided to the partner. 3 Pad the PIN entered by the user Before we generate the PIN block, a padded PIN needs to be generated using a concatenation formula. Padded PIN formula : ‘0’ + {{PIN LENGTH}} + {{USER PIN}} The string needs to be padded with F at the end to complete a 16-digit string. Example: If the user enters PIN: 1234, the constructed string becomes : ‘0’ + ‘4’ + ‘1234’ + ‘FFFFFFFFFF’ Final padded PIN value : 041234FFFFFFFFFF (16-digit string) 4 Pad the user's registered mobile number To add another layer of a secure element associated with the user, we will need to use a padded mobile number. Padded mobile formula : '0 padding prefix to complete a 16-digit string' + {{mobile.mobile_country_code}} + {mobile.number}} Example: If the user is based out of Singapore with a registered mobile number of +65 8888 9999 (mobile.mobile_country_code = 65 and mobile.number = 88889999 ). The (+) sign is excluded in the formula. Which gets us a 10-digit string ( 65 + 88889999). Following the padding formula, we will add six ‘0’ as a prefix to the 10-digit mobile number to complete a 16-digit string . ‘000000’ + ‘65’ + ‘88889999’ Final padded mobile value : 0000006580800000 (16-digit string) 5 Perform Triple-DES encryption Perform an XOR of the padded PIN value and the padded mobile value. Then, encrypt the output using the provided ZPK to get the PIN block. 6 Pass the encrypted PIN block Call the Set Card PIN ( POST /users/wallets/cards/{(card_id})/pins ) passing the encrypted pinblock to set the PIN. Set Card PIN request Bash curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a/pins' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'pinblock=2F08670F5615DE76' Set Card PIN response Plain text { "status": "success" } { "status": "success" } Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Suspend an active card Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Suspend an active card](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/suspend-an-active-card.md): Learn how to temporarily suspend an active card to prevent any new card transactions. This guide explains how to place a temporary hold on a card, which can be reactivated by the user later. The user in this document pertains to both the individual and business user types. Suspend Cards Temporarily places a hold on the card, preventing any new authorizations. However, if a merchant has already pre-validated the card, those specific authorizations can still be processed. Blocked Cards Permanently disables the card, immediately rejecting all new transactions and purchase authorizations Use Cases You want to temporarily lock a specific user card for security and control in cases where fraud is suspected. You want to lock a card temporarily due to contractual reasons. You want to set the card status from the active to a locked state. You want to add a feature to your application that allows users to self-suspend their cards. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an active status. API Workflow 1 [v1] Suspend an active card Call the Suspend Card ( DELETE /users/wallets/cards/{{card_id}} ) without passing any type parameter, as an empty type parameter, which will default to a card suspension or locking. Suspend Card request CURL curl --location --request DELETE 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/x-www-form-urlencoded' Suspend Card response JSON { "id": "180ac588b91dc6bff6a5d42a671d1d6a", "number": "5545XXXXXXXX0000", "status": "locked" } 2 [v2] Suspend an active card The V2 Card Status API is currently only restricted to JIT-configured programs. Call the Update Card Status (Lock) ( PUT /users/wallets/cards/{{card_id}}/status ) to lock or temporarily suspend a card by passing the action , origin , and reason for locking. Update Card Status API (Lock) request parameters: Origin Action Reason Description USER LOCK blank or empty (not required) The User wants to temporarily suspend their card USER LOCK SUSPICIOUS_TRANSACTION The User spots an unrecognised transaction USER LOCK SECURITY The User locks as a precautionary measure USER LOCK MISPLACED_CARD The User has temporarily misplaced their card PARTNER LOCK SUSPECTED_FRAUDULENT_ACTIVITY The Partner risk / fraud engine flags a high-risk transaction or suspicious activity PARTNER LOCK SUSPICIOUS_TRANSACTION The Partner detects suspicious transaction pattern PARTNER LOCK HIGH_RISK_ACTIVITY The Partner identifies elevated risk activity PARTNER LOCK SECURITY The Partner locks for internal compliance or security concerns Update Status (Lock) request CURL curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/{{card_id}}/statuses' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "action": "LOCK", "origin": "USER", "reason": "SUSPICIOUS_TRANSACTION" } ' Update Status (Lock) response JSON { "id": "{{card_id}}", "status": "LOCKED", "reason": "SUSPICIOUS_TRANSACTION", "origin": "USER", "updated_at": "2026-03-17 02:08:10.420987372 +0000 UTC" } 3 Update the card status display to reflect card suspension It is recommended that you update the card status of the suspended card in your frontend and handle the scenarios for a suspended card: Display the status change to your user either as a badge or by graying out the card. Handle restrictions on displaying full card number and security code (CVC/CVV) details. Provide an option to do a self-service unsuspension of their locked card. Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Reactivate a suspended card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Reactivate a suspended card](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/re-activate-a-card.md): Understand how to reactivate a card that has been temporarily suspended. This guide covers the process of lifting a temporary hold to restore the card to an active, usable state. The user in this document pertains to both the individual and business user types. Use Cases You want to reactivate or unsuspend an already suspended card. You want to set the card status from the locked to an active state. You want to add a feature to your application that allows users to self-unsuspend their cards. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an locked or suspended status. API Workflow 1 [v1] Reactivate a locked or suspended card Call the Reactivate Card POST /users/wallets/cards/{{card_id}} by specifying id parameter and setting it to the card_id of the suspended card. Reactivate Card request CURL curl --location --request POST 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/x-www-form-urlencoded'\ --data-urlencode 'id=180ac588b91dc6bff6a5d42a671d1d6a' Reactivate Card response JSON { "id": "180ac588b91dc6bff6a5d42a671d1d6a", "number": "5545XXXXXXXX0000", "status": "active" } When a card is reactivated, all the blocked features, such as card transactions and access to sensitive card details, will be re-enabled. 2 [v2] Reactivate a locked or suspended card The V2 Card Status API is currently only restricted to JIT-configured programs. Call the Update Card Status (Unlock) ( PUT /users/wallets/cards/{{card_id}}/status ) to unlock or reactivate a locked card by passing the action , origin , and reason . Update Card Status (Unlock) API request parameters: Title Action Reason Description USER UNLOCK blank or empty (not required) The User wants to unlock or reactive a locked card PARTNER UNLOCK blank or empty (not required) The Partner wants to unlock or reactive a locked card Card Status (Unlock) request CURL curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/{{card_id}}/statuses' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "action": "UNLOCK", "origin": "USER", "reason": "" } ' Card Status (Unlock) response JSON { "id": "{{card_id}}", "status": "ACTIVE", "origin": "USER", "updated_at": "2026-03-17 02:10:02.261653592 +0000 UTC" } Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Suspend an active card Permanently block a card Card spending control Card payment authentication Card payments Manage card security • [Permanently block a card](https://developer.matchmove.com/matchmove-banking-operating-system/manage-cards/permanently-block-card.md): Learn the process for permanently blocking a card, for instance, if it is reported lost or stolen. This guide explains how to permanently deactivate a card, preventing further use. The user in this document pertains to both the individual and business user types. Blocked Cards Blocking or deletion of a card is irreversible. A blocked card cannot be reactivated. Blocked cards' sensitive card information, such as card number and security code (CVV/CVC), will not be accessible. Permanently disables the card, immediately rejecting all new transactions and purchase authorizations Use Cases You want to permanently block/delete/unlink a specific card from the user account. You want to disassociate a card from a user account and free up a card slot from the allowed cards per user limit. You want to set the card status from the locked (temporary) to a blocked (permanent) state. You want to set the card status directly from the active to a blocked (permanent) state, provided there are no pending unsettled transactions made in the card. You want to permanently block a card in cases of card loss, damage, and theft. You want to block a card due to contractual reasons permanently. You want to add a feature to your application that allows users to self-block or delete their cards. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an locked or active status. The user card has no pending transactions that need to be settled. API Workflow 1 Block or delete an active/suspended card Call the Block Card ( DELETE /users/wallets/cards/{{card_id}} ) by passing the type parameter to block a card. The following values for the type parameter will trigger a card block: lost stolen damaged Block Card request CURL curl --location --request DELETE 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/180ac588b91dc6bff6a5d42a671d1d6a' \ --header 'X-Auth-User-Id: {{user_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data 'type=damaged' Block Card response JSON { "id": "180ac588b91dc6bff6a5d42a671d1d6a", "number": "5545XXXXXXXX0000", "status": "blocked" } 2 [v2] Block or delete an (active or locked) card The V2 Card Status API is currently only restricted to JIT-configured programs. Call the Update Card Status (Block) ( PUT /users/wallets/cards/{{card_id}}/status ) to unlock or reactivate a locked card by passing the action , origin , and reason . Card Status (Block) API request parameters: Origin Action Reason Description USER BLOCK CONFIRMED_FRAUD The user confirms a fraudulent transaction on their card. Card blocking is allowed when there are unsettled transactions, as long as they are already marked as authorized by MM . USER BLOCK STOLEN_CARD The user reports their card as stolen. Card blocking is allowed even if there are unsettled transactions. USER BLOCK LOST_CARD The user reports their card as lost. Card blocking is allowed even if there are unsettled transactions. USER BLOCK DAMAGED_CARD User reports physical card damage. Card blocking is not allowed if there are unsettled transactions. PARTNER BLOCK CONFIRMED_FRAUD The partner confirms fraudulent activity on the card. Card blocking is allowed even if there are unsettled transactions. PARTNER BLOCK COMPROMISED_CARD Card details have been exposed or compromised in a data breach. Card blocking is allowed even if there are unsettled transactions. PARTNER BLOCK CARD_CLOSURE Partner requests card or account closure. Card blocking is not allowed if there are unsettled transactions. Update Card Status (Block) request CURL curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/{{card_id}}/statuses' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "action": "BLOCK", "origin": "USER", "reason": "LOST_CARD" } Update Card Status (Block) response JSON { "id": "{{card_id}}", "status": "BLOCKED", "reason": "LOST_CARD", "origin": "USER", "updated_at": "2026-03-17 02:14:23.426001434 +0000 UTC" } Related Links Card overview Create your card product Issue a card Manage cards Retrieve users cards Retrieve non-sensitive card information Retrieve sensitive card information Set a card PIN Suspend an active card Reactivate a suspended card Card spending control Card payment authentication Card payments Manage card security • [Card spending controls](https://developer.matchmove.com/matchmove-banking-operating-system/card-spending-controls.md): Understand how to configure and manage spending controls for a user's card. This guide covers setting various limits and restrictions to help users manage their spending and enhance security. Control where and how the card is used by your users Every program has a global wallet limit set up during the initial configuration. These program limits are spend limits approved and signed during the commercial agreements between the partner and MatchMove. These limits govern the transactional activity of every user on the platform. However, there will be use cases where the program limits may be too high or not restrictive enough for certain scenarios. Also, there will be cases where certain restrictions will not apply globally but only to certain users. Therefore, there is a need to allow further restrictions on card transactions that are configurable per user. Transaction category Transaction categories are grouping definitions for transactions that carry similar attributes. These transaction categories are defined at the program level and apply globally . Available transaction categories: ATM (All ATM transactions) ATM_DOMESTIC (Domestic ATM transactions) ECOM (All e-commerce transactions) ECOM_DOMESTIC (Domestic E-commerce transactions) POS_CONTACTLESS (Point of sale contactless transactions) POS (Point of sale transactions) Card transactional limits Card transactional limits are more restrictive limits that can be applied to each transaction category. These card transactional limits apply only to individual cards where it is defined. Limits set in these card transactions must be lower than the defined program limits. Partners may want to control spending depending on the transaction category. Below are some use cases where the card transactional category will be useful: Limit ATM withdrawals - the card transactional limit can be set for ATM or ATM_DOMESTIC transaction category, setting the limit to 1000 (or any amount lower than the program limits) at every interval. Intervals can be unit, daily, weekly, monthly, annually, etc. Limit per transaction spending on online purchases - the card transactional limit can be set for ECOM or ECOM_DOMESTIC transaction category, setting the limits to 1000 (or any amount lower than the program limits) at the unit interval. Disable ATM withdrawals for specific card types - some partners employ card tiers where they control the features and benefits being applied to different customer categories, e.g., {bronze, gold, diamond users}. In this example, bronze users can be limited to 0 on ATM withdrawals. While diamond users are allowed to withdraw up to 100,000 monthly. Summary: Program limits are limits set up at the program level and apply globally. Transaction categories are transaction groupings for transactions with similar attributes. Card transactional limits are a more restrictive limit that is defined for each transaction category. These limits will only affect the card where it is defined. Go to the Configure Card Transaction Limits section to learn more about how to set transactional limits on specific cards. Related Links Card overview Create your card product Issue a card Manage card Configure card transactional limits Card payment authentication Card payments Manage card security • [Configure card transactional limits](https://developer.matchmove.com/matchmove-banking-operating-system/card-spending-controls/define-card-transactional-limits.md): Learn how to define specific transactional limits for a card. This guide explains how to set spending caps for different periods or transaction types to control spending. The user in this document pertains to both the individual and business user types. Use Cases You want to add additional transaction limitations on top of the default global limits configured in the user account. You want to set transaction limits on a specific card based on the transaction category of the card transaction. You want to set transaction limits on a specific card, adding interval and velocity parameters. e.g., daily, weekly, and monthly limits. You want to block spending on a specific transaction category. e.g. blocking of ATM withdrawal Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user card must be in an active status. API Workflow 1 Retrieve the platform-defined transaction categories First, we need to get the correct transaction category ID generated in the system during program setup. Call List Transaction Categories ( GET /oauth/consumer/transaction/categories ) to get the list of supported categories defined in the program. Please note that this API is called on the admin scope, so it X-Auth-User-ID should not be passed in the header. List Transaction Categories request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/oauth/consumer/transaction/categories' \ --header 'Authorization: ••••••' List Transaction Categories response JSON [ { "id": "67e63d53432263cbe00fc05fd0643ac8", "name": "ATM", "label": null }, { "id": "386c8cd58faeb68175b6261450a49e53", "name": "ATM_DOMESTIC", "label": null }, { "id": "9789ec5907cc9f5854b5d8f57fa30ed9", "name": "ECOM", "label": null }, { "id": "69ca5d99cc4a8bb16bb170efacb0de5b", "name": "ECOM_DOMESTIC", "label": null }, { "id": "6ae4dd74ea2a4c2a8639645477ecc231", "name": "POS_CONTACTLESS", "label": null }, { "id": "453cd0fb0d5de3f85bf098ea86ac2fc2", "name": "POS", "label": null }, { "id": "d4f9c272aeb7b671a545d75811b7c48c", "name": "TOPUP", "label": "topup" }, { "id": "c1bc4715f4172078e926912f191972d8", "name": "DEDUCT", "label": "deduct" }, { "id": "830eacca2657aa5da668f164626cbafa", "name": "LOAD", "label": "load" }, { "id": "47e22a9490c8e7ba8fde098551cfeaba", "name": "UNLOAD", "label": "unload" }, { "id": "ff26a9df02697cf4396eb70cb8d28b0b", "name": "TRANSFER_IN", "label": "transfer_in" }, { "id": "8d59b769f3107052a6e9e4e9875ae362", "name": "TRANSFER_OUT", "label": "transfer_out" }, { "id": "a712ce34747f7a3496cc4eaa5157d3a9", "name": "REMITTANCE", "label": "remittance" } ] Applicable transaction categories for card transactions: * Domestic will be based on the region where your program and cards are issued. Transaction Category Description ATM Card transaction limits for * domestic and international ATM withdrawals ATM_DOMESTIC Card transaction limits for * domestic ATM withdrawals ECOM Card transaction limits for * domestic and international online e-commerce payments ECOM_DOMESTIC Card transaction limits for * domestic online e-commerce payments POS Card transaction limits for * domestic and international point-of-sale (POS) terminal payments POS_CONTACTLESS Card transaction limits for * domestic point-of-sale (POS) terminal payments 2 Create a card transactional limit for a specific transaction category Call the Create Card Transactional Limit ( POST /users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit ) setting the interval limits for the transaction category. This category limit will only apply to the specific card where it is defined. In this example, we will configure a card transactional limit for the ATM category using the following transaction category id : { "id": "67e63d53432263cbe00fc05fd0643ac8", "name": " ATM ", "label": null }, Create Card Transactional Limit request Bash curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/67e63d53432263cbe00fc05fd0643ac8/limit' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'enable=true' \ --data-urlencode 'values=[ "{\"amount\": 10,\"interval\": \"unit\"}", "{\"amount\": 100,\"interval\": \"daily\",\"count\": 3}", "{\"amount\": 200,\"interval\": \"weekly\",\"count\": 4}", "{\"amount\": 300,\"interval\": \"monthly\",\"count\": 5}", "{\"amount\": 400,\"interval\": \"annual\", \"count\": 6}", "{\"amount\": 500,\"interval\": \"lifetime\",\"count\": 7}" ]' Create Card Transactional Limit response JSON { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "card_limits": [ { "amount": 10, "interval": "unit" }, { "amount": 100, "interval": "daily", "count": 3 }, { "amount": 200, "interval": "weekly", "count": 4 }, { "amount": 300, "interval": "monthly", "count": 5 }, { "amount": 400, "interval": "annual", "count": 6 }, { "amount": 500, "interval": "lifetime", "count": 7 } ], "program_limits": { "pre_kyc": [ { "amount": 0, "count": 0, "interval": "daily" } ], "post_kyc": [ { "amount": 2500, "count": 3, "interval": "daily" } ] }, "wallet_limits": null, "user_details_set": true } 3 List all defined transactional limits for a specific card Call the List Card Transactional Limits ( GET /users/wallets/cards/{{card_id}}/transactions/categories/limit ) to get the list of enabled and disabled card transactional limits affecting the card. List Transactional Limit request Bash curl --location 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/limit' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Transactional Limit response JSON { "ATM": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": true, "program_limits": { "pre_kyc": [ { "amount": 0, "count": 0, "interval": "daily" } ], "post_kyc": [ { "amount": 2500, "count": 3, "interval": "daily" } ] }, "card_limits": [ { "amount": 10, "interval": "unit" }, { "amount": 100, "interval": "daily", "count": 3 }, { "amount": 200, "interval": "weekly", "count": 4 }, { "amount": 300, "interval": "monthly", "count": 5 }, { "amount": 400, "interval": "annual", "count": 6 }, { "amount": 500, "interval": "lifetime", "count": 7 } ] }, "ATM_DOMESTIC": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": false, "user_details_set": false }, "ECOM": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false }, "ECOM_DOMESTIC": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false }, "POS_CONTACTLESS": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false }, "POS": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false }, "TOPUP": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "DEDUCT": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "LOAD": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "UNLOAD": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "TRANSFER_IN": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "TRANSFER_OUT": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 750, "interval": "unit" }, { "amount": 2250, "interval": "daily" }, { "amount": 2250, "interval": "weekly" }, { "amount": 2250, "interval": "monthly" }, { "amount": 15000, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } }, "REMITTANCE": { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": true, "user_details_set": false, "program_limits": { "pre_kyc": [ { "amount": 0, "interval": "unit" }, { "amount": 0, "interval": "daily" }, { "amount": 0, "interval": "weekly" }, { "amount": 0, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": 0, "interval": "lifetime" } ], "post_kyc": [ { "amount": 500000, "interval": "unit" }, { "amount": 500000, "interval": "daily" }, { "amount": 500000, "interval": "weekly" }, { "amount": 1000000, "interval": "monthly" }, { "amount": null, "interval": "annual" }, { "amount": null, "interval": "lifetime" } ] } } } 4 Disable (or enable) a specific card transactional limit for a specific card Call Update Card Transactional Limit (PUT /users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit) passing the enable parameter with a true or false value. Update Card Transactional Limit request (disable) Bash curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v1/users/wallets/cards/{{card_id}}/transactions/categories/{{transaction_category_id}}/limit' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'enable=false' Update Card Transactional Limit response (disable) JSON { "id": "ecfc55bda36d97a00cb650b023cc9544", "enable": false, "card_limits": [ { "amount": 10, "interval": "unit" }, { "amount": 100, "interval": "daily", "count": 3 }, { "amount": 200, "interval": "weekly", "count": 4 }, { "amount": 300, "interval": "monthly", "count": 5 }, { "amount": 400, "interval": "annual", "count": 6 }, { "amount": 500, "interval": "lifetime", "count": 7 } ], "program_limits": { "pre_kyc": [ { "amount": 0, "count": 0, "interval": "daily" } ], "post_kyc": [ { "amount": 2500, "count": 3, "interval": "daily" } ] }, "wallet_limits": null, "user_details_set": true } Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Manage card security • [Card order delivery](https://developer.matchmove.com/matchmove-banking-operating-system/card-order-delivery.md): The Card Order Delivery module serves as a critical validation and tracking engine that ensures physical payment instruments can be successfully fulfilled to a user's specified address. By performing pre-order serviceability checks, the system mitigates fulfillment risks and prevents delivery failures before the production process begins. Once validated, the module provides end-to-end visibility across the entire card lifecycle, from initial order and personalization to final delivery at the customer’s doorstep. • [Check user address serviceability](https://developer.matchmove.com/matchmove-banking-operating-system/card-order-delivery/beta-check-user-address-serviceability.md): Determine whether a user resides in a serviceable area before they finalize their card order. By validating the address against real-time coverage maps, you can provide immediate feedback and prevent the frustration of failed shipments or undeliverable mail. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases [User-scope] You want to check whether a user requesting a physical card can be serviced and if his shipping address is within the service coverage area. [Admin-scope] You want to verify whether a given address is within the serviceable coverage area. Prerequisites [User-scope] Check Card Order Serviceability API The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The program is configured and enabled for physical card issuance to its users. [Admin-scope] Check Card Order Delivery Address Serviceability API No KYC requirement or user active status is required to call the API. API Workflow 1 [User-scope] Check if the user's residence is within the serviceable area Before you allow the user to request a physical card, we must first check whether his billing / shipping address is within our logistic partners' delivery coverage. This is to prevent physical card orders from being created but later being unable to be delivered to the cardholder. Check Card Order Serviceability To check if a user residence is serviceable, we can call Get Card Order Serviceability ( GET /users/wallets/cards/types/{{card_type_code}}/orders/serviceability ) by passing the user ID and card type code of the physical card that the user wants to request. Check Card Order Serviceability request CURL curl --location --request PUT 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/types/{{card_type_code}}/orders/serviceability' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Check Card Order Serviceability response JSON [ { "delivery_available": true, "delivery_provider": "2GO" } ] 2 Issue the physical card to the user Once we have established that the delivery address of the user is serviceable, we can then proceed to issue the physical card. Depending on the type of physical card, we can issue the following: Personalize physical cards by following the Link & activate a non-personalised physical card guide. Non-personalized physical cards by following the Request for a personalised physical card guide. 3 [Admin-scope] Check whether an address is within the serviceable area There is also an admin-scope API that we can use to check whether a given destination address resides within the designated serviceable area of the logistics partner. Check Card Order Delivery Address Serviceability To check whether a given address is serviceable, we can call Check Card Order Delivery Address Serviceability ( POST oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability ) by passing in a full valid shipping/billing address. Note: Remember to sanitize any trailing or leading spaces in the address fields before posting the request to reduce mismatches. [Example 1] Check Card Order Delivery Address Serviceability request For PH programs, when applicable, pass the following: Mandatory Field / Source Optional address_1 Free text Optional address_2 Free text Yes address_3 code value from Get Line 3 (Barangay) Enumeration GET v2/users/enumerations/line_3 Optional address_4 code value from Get Line 4 (Region) Enumeration GET v2/users/enumerations/line_4 Yes city code value from Get Cities Enumeration GET v2/users/enumerations/city Yes state code value from Get State or Province Enumeration GET v2/users/enumerations/state_province Optional zipcode code value from Get Postal Code GET v2/users/enumerations/postal_code Yes country_code code value from Get Countries Enumeration GET v2/users/enumerations/countries Yes country description value from Get Countries Enumeration GET v2/users/enumerations/countries CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "address_1": "8 Furong Street", "address_2": "Nr BDO and Metrobank ATM Machine", "address_3": "PUNTURIN", "address_4": "NCR", "city": "VALENZUELA_CITY_NCR", "state": "NCR", "zipcode": "1447", "country": "Philippines", "country_code": "PHL" }' [Example 1] Check Card Order Delivery Address Serviceability request JSON [ { "delivery_available": true, "delivery_provider": "2GO" } ] [Example 2] Check Card Order Delivery Address Serviceability request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/oauth/consumer/wallets/cards/types/{{card_type_code}}/orders/serviceability' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "address_1": "Victoria Tower D Mother Ignacia St", "address_2": "Unit 9D11A", "address_3": "PALIGSAHAN", "address_4": "NCR", "city": "QUEZON_CITY_NCR", "state": "NCR", "zipcode": "1103", "country": "Philippines", "country_code": "PHL" } ' [Example 2] Check Card Order Delivery Address Serviceability request JSON [ { "delivery_available": true, "delivery_provider": "2GO" } ] • [Retrieve card order details](https://developer.matchmove.com/matchmove-banking-operating-system/card-order-delivery/beta-retrieve-card-order-details.md): Learn the current status, delivery timeline, and fulfillment history of a specific card request. This service provides stakeholders with real-time visibility into the lifecycle of a physical card, from the initial order to successful doorstep delivery. Note: Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process. Use Cases You want to check the current status and details of a card order. You want to check the fulfillment history of a card order. Prerequisites The user must have an approved KYC. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The program is configured and enabled for physical card issuance to its users. The user has an active card order request with a valid card ID of a physical card. API Workflow 1 Retrieve card order details and history The card order details response will only return the latest and active tracking number for the card delivery. A completed card order delivery will have a DELIVERED status, while an unsuccessful delivery will have a DELIVERY_FAILED status. Get Card Order Details To retrieve the card order details of a specific card, you can call Get Card Order Details ( GET /users/wallets/cards/{{card_id}}/orders ) by passing the card ID of the provisioned card. Query parameter sample format: created_date_from : 2026-02-19 06:40:32 created_date_to : 2026-02-19 18:30:45 Get Card Order Details request CURL curl --location 'https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/{{card_id}}/orders?created_date_from=2026-02-19%2006%3A40%3A32&created_date_to=2026-04-19%2018%3A30%3A45&page=1&records_per_page=10' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Get Card Order Details response JSON { "pagination": { "total_records": 1, "records_per_page": 10, "total_pages": 1, "links": { "self": "https://api-sg-cards.matchmove-beta.com/{{program_code}}/v2/users/wallets/cards/cd04c39a33c0f0f1cb92220b3d9f8f35/orders?page=1&records_per_page=1", "next": "https://api-sg-cards.matchmove-beta.com/{{program_code}}/v2/users/wallets/cards/cd04c39a33c0f0f1cb92220b3d9f8f35/orders?page=2&records_per_page=1" } }, "data": [ { "card_order_id": "019581a0-0012-7000-a000-000000000012", "tracking_number": "V1000012L", "status": "DELIVERY_IN_PROGRESS", "sub_status": "DELIVERY_ATTEMPTED", "reason": "", "description": "", "delivery_details": { "provider": "2GO", "name": "Fernando Ramos", "email": "f.ramos@example.com", "mobile": "9180000012", "mobile_country_code": "63", "address": { "address_1": "88 Taft Avenue", "address_2": "Malate", "address_3": "buyon", "address_4": "REGION_04", "city": "ABRA_DE_ILOG_OCCIDEN", "state": "LAUNION", "country": "PHL", "zipcode": "4023" } }, "created_date": "2026-03-18 12:24:56.056304", "updated_date": "2026-03-19 12:24:56.056304" } ] } 2 Monitor the card order delivery status Cards webhooks category The Cards webhook category is available for partners who want to get timely feedback on card order delivery events. Partners can subscribe to the following webhooks to get timely notifications on card orders. Webhook Event Description Required Action CARDS.ORDERS.UPDATE A notification is sent when a card order update changes its status. No action required Go to the Leveraging Webhooks section to learn more about setting up the webhooks. Sample Card Order Update webhook payload JSON { "entities": { "card": { "id": "d237b925639d9dfb40fa7c01767d832b", "type": "{{card_type}}" }, "order": { "card_order_id": "019e7f53-d9ec-7490-8bc2-715dd7ca1b4f", "created_date": "2026-05-28 23:06:00.000000", "delivery_details": { "address": { "address_1": "Billing Line1", "address_2": "Billing Line2", "address_3": "BARANGAY_I", "address_4": "region_07", "city": "BACARRA_ILOCOS_NORTE", "country": "phl", "state": "ILOCOSNORTE", "zipcode": "2921" }, "email": "test@matchmove.com", "mobile": "1066636190", "mobile_country_code": "63", "name": "Juan V Reyes", "provider": "2GO" }, "description": "Card is being physically printed and manufactured", "reason": "", "status": "PROCESSING", "sub_status": "PRINTING_IN_PROGRESS", "tracking_number": "", "updated_date": "2026-06-01 02:37:42.253525" }, "user": { "email": "test@matchmove.com", "id": "6cc89558b0cb4b49b7d2ef86c0260183", "mobile": "1066636190", "mobile_country_code": "63" } }, "entity_id": "019e7f53-d9ec-7490-8bc2-715dd7ca1b4f", "entity_type": "CARD", "event_timestamp": "2026-05-31T18:37:42Z", "message_id": "019e7f53-d9f4-7490-9d22-3b7b7bba425b", "program_code": "{{program_code}}", "version": "V2", "webhook_event": "CARDS.ORDERS.UPDATE" } • [Card payment authentication](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication.md): Understand the different methods for authenticating online card payments. This guide introduces the core concepts behind our 3D Secure (3DS) authentication solutions. Card Transactions with 3D Secure (3DS) What is 3DS authentication? 3D Secure (3DS) is a security protocol designed to add a layer of security before authorization, helping to authenticate online transactions by requiring cardholders to complete an additional verification with their card issuer. When a merchant initiates 3DS, the cardholder is prompted to enter a one-time passcode, typically sent via email or SMS, to complete the purchase. This process usually redirects the user to the card verification page (3DS page) to complete the authentication. For all partner programs, the 3DS authentication page will be managed and serviced by MatchMove. MatchMove 3D-Secure (3DS) Solutions MatchMove, as a platform, provides you the flexibility on how you would like to deploy the 3DS experience to your end-users. We support two options on how you can deliver the 3DS one-time PIN (OTP) to your end-users: Platform-managed 3DS Authentication In platform-managed 3DS, the end-to-end 3DS experience will be managed by MatchMove. In addition to serving up the 3DS authentication page to your users, we will also deliver the OTP to your end user via email / SMS. Assisted 3DS Authentication In this model, the 3DS authentication page will still be displayed and managed by MatchMove, but the responsibility for the second-factor authentication (2FA) can be assumed by the program owner. You can manage the user verification experience using two supported methods: OTP 2FA : You receive the one-time PIN in a webhook and manage the delivery and experience of passing it to your end-users on any of your allowed delivery channels. Biometric 2FA : You handle the in-app biometric approval (e.g., Face ID or fingerprint) entirely within your own application. Related Links Card overview Create your card product Issue a card Manage card Card spending control Assisted 3DS authentication Simulate assisted 3DS authentication Card payments Manage card security • [Platform-managed 3DS authentication](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication/platform-managed-3ds-authentication.md): Learn how to test your Assisted 3DS integration in our staging environment. This guide covers how to simulate different authentication challenge scenarios and outcomes without impacting real users. In this model, the MatchMove banking platform takes direct ownership of the 3D Secure (3DS) authentication process. It acts as the control server that generates One-Time Passwords (OTPs) and delivers the OTPs directly to its cardholders via its own communication infrastructure (SMS or email). How It Works Trigger: A transaction initiates 3DS verification. Generation: The MatchMove banking platform generates the secure OTP internally. Delivery: The platform transmits the OTP using its own integrated notification gateways (e.g., direct SMS integration or internal email servers). Verification: The cardholder inputs the code in the 3DS challenge page, and the platform validates it to authorize the transaction. Cardholder delivery This model places the delivery liability squarely on the MatchMove. MatchMove will be responsible for maintaining high-availability SMS and email gateways. It also ensures its own customer profile data (mobile numbers/emails) is the single source of truth for delivery. Because OTP will only be delivered to the registered mobile and email of the cardholder. By default, OTP will be delivered to the cardholder's mobile number. When configured and enabled, email OTP will also be delivered alongside SMS. • [Assisted 3DS authentication - OTP 2FA](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication/assisted-3ds-authentication-otp-2fa.md): Learn about our Assisted 3DS authentication model — One-time Password (OTP) 2FA , where your platform participates in the authentication flow. This guide explains your role in managing the user challenge process for securing online transactions by utilizing your existing communication channels to serve the OTP. Note: Please be aware that this feature requires a specific change to your program's configuration before it can be enabled. It is not activated by default for new or existing programs. Reach out to your MatchMove Implementation or Sales team to learn more and initiate the setup process. Both Assisted 3DS authentication models use a hybrid approach where MatchMove sends a security code to the partner via a webhook, but they take entirely different paths for the final user verification: Assisted 3DS (OTP): Focuses on Code Delivery In this model, MatchMove handles the security and generation of a One-Time Password (OTP). The partner’s responsibility is strictly last-mile delivery . They take the OTP provided by the webhook and pass it directly to the cardholder through their own channels (like SMS or email) so the user can complete a standard code challenge. Assisted 3DS (Biometric 2FA): Focuses on Native Verification Instead of passing a code to the user, the partner takes full control of the authentication challenge . The webhook acts as a silent trigger, prompting the partner to initiate a native biometric check (like Face ID or a fingerprint) within their app, where the user simply approves or rejects the payment. The security code is never shown to the user; it is only used on the backend to authorize the transaction once the biometric check passes. How It Works: OTP Authentication Flow Challenge Initiated: The platform detects that a transaction requires 3DS verification and presents the cardholder with the OTP authentication challenge page. OTP Generation: The platform creates a secure, time-sensitive One-Time Password (OTP). Webhook Handoff: Instead of directly messaging the user, the platform instantly sends a webhook containing the OTP and transaction details to the partner’s server. Partner Delivery: Upon receiving the webhook, the partner immediately delivers the OTP to the cardholder using their preferred communication channel (SMS, Email, or In-App Push). Final Verification: The cardholder enters the received code. The platform validates the OTP and, if correct, proceeds with transaction authorization. Getting Started with Assisted 3DS Authentication Assisted 3DS Authentication (both OTP and Biometric 2FA) is an OPTIONAL service available for new and existing partners. Default Behavior: Without this service enabled, MatchMove is solely responsible for delivering the standard 3DS OTP to the enabled delivery channels. Assisted 3DS Enabled: When this service is activated, the partner takes control of the authentication experience. Depending on your configuration, you can either take over the direct delivery of the 3DS OTP to your cardholders or participate in a seamless native biometric challenge within your application. 1 Enable OTP 2FA in the program configuration Partners who want to enable Assisted 3DS Authentication - OTP 2FA should contact the MatchMove Implementation team and request to set up and configure it in the platform configuration. 2 Subscribe to the 3DS Authentication webhook Once the service is enabled in the configuration, partners must subscribe to the webhook event CARDS.3DS.AUTHENTICATION . This webhook will deliver a payload containing the card ID and transaction 3DS from a payment authentication request. Upon receipt of the CARDS.3DS.AUTHENTICATION webhook, the partner must consume the payload and prepare for the OTP delivery to their customer. Sample webhook payload 3DS Authentication webhook payload JSON { "entities": { "card": { "id": "9b087b1d479aabd6af63f7d699f25fcc", "type": "{{card_type}}" }, "transaction": { "authentication": { "id": "019f4109-6285-76f3-9201-60c8b6f52af2", "challenge_priority": 1, "created_at": "2026-07-08T17:22:41+08:00", "details": { "channel": "email", "otp": "123456", "otp_expires_at": "2026-07-08T17:25:48+08:00", "otp_generated_at": "2026-07-08T17:22:48+08:00" }, "expires_at": "2026-07-08T17:32:41+08:00", "method": "otp", "retry_count": "0" }, "merchant": { "merchant_name": "Amazon" }, "network": "MASTER", "transaction_amount": "184.00", "transaction_currency": "AED" }, "user": { "email": "test@matchmove.com", //dummy value "id": "9a3f91d0ab3d1db5a97716f0efe5a96c", "mobile": "9876543210",// dummy value "mobile_country_code": "1", "type": "BUSINESS" } }, "entity_id": "019f4109-6285-76f3-9201-60c8b6f52af2", "entity_type": "CARD", "event_timestamp": "2026-07-08T09:22:48Z", "message_id": "019f4109-7cd1-7536-9b51-8432b0397c01", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.3DS.AUTHENTICATION" } Legacy 3DS Authentication webhook payload This legacy payload remains supported for select partners in specific regions. JSON { "entities": { "card": { "id": "defa202f9a61576f3a434b7ccd994c69", "type": "{{card_type}}" }, "transaction": { "authentication": { "channel": "sms", "created_at": "2026-07-10T17:41:38+08:00", "id": "91b16015a1794204a6f2c7e4c646f319", "method": "otp", "otp": "123456", "otp_expires_at": "2026-07-10T17:46:38+08:00", "otp_generated_at": "2026-07-10T17:41:38+08:00", "retry_count": "0" }, "merchant": { "merchant_name": "" }, "network": "MASTERCARD", "transaction_amount": "", "transaction_currency": "" }, "user": { "email": "test@matchmove.com", // dummy value "id": "6dfd16a179e94728b843eafbac92bf17", "mobile": "9912345978", // dummy value "mobile_country_code": "63" } }, "entity_id": "91b16015a1794204a6f2c7e4c646f319", "entity_type": "CARD", "event_timestamp": "2026-07-10T09:41:38Z", "message_id": "d9adf23e8eac44a697cd37a9514b9010", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.3DS.AUTHENTICATION" } 3 Deliver the 3DS OTP (received from the webhook) to your customer The authentication code received from the webhook must be passed or delivered to the cardholder through the allowed channels. Allowed 3DS OTP delivery channels: SMS Email Push notification via the Partner app 4 Validate your integration There are simulation APIs available that can be used to test Assisted 3DS Authentication - OTP 2FA in the staging environment. You can go to the Simulate Assisted 3DS Authentication - OTP 2FA section to learn more about the simulation procedures. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Simulate assisted 3DS authentication Card payments Manage card security • [Assisted 3DS authentication - Biometric 2FA](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication/assisted-3ds-authentication-biometric-2fa.md): Learn about our Assisted 3DS authentication model — Biometic 2FA / Out-of-Band (OOB) where your platform participates in the authentication flow. This guide explains your role in managing the user challenge process for securing online transactions by utilizing biometric authentication in your applications. Note: Please be aware that this feature requires a specific change to your program's configuration before it can be enabled. It is not activated by default for new or existing programs. Reach out to your MatchMove Implementation or Sales team to learn more and initiate the setup process. Both Assisted 3DS authentication models use a hybrid approach where MatchMove sends a security code to the partner via a webhook, but they take entirely different paths for the final user verification: Assisted 3DS (OTP): Focuses on Code Delivery In this model, MatchMove handles the security and generation of a One-Time Password (OTP). The partner’s responsibility is strictly last-mile delivery . They take the OTP provided by the webhook and pass it directly to the cardholder through their own channels (like SMS or email) so the user can complete a standard code challenge. Assisted 3DS (Biometric 2FA): Focuses on Native Verification Instead of passing a code to the user, the partner takes full control of the authentication challenge . The webhook acts as a silent trigger, prompting the partner to initiate a native biometric check (like Face ID or a fingerprint) within their app, where the user simply approves or rejects the payment. The security code is never shown to the user; it is only used on the backend to authorize the transaction once the biometric check passes. How It Works: Biometric Authentication Flow Challenge Initiated: The platform identifies the need for 3DS verification and displays a biometric authentication waiting page to the cardholder. Code Generation: The platform generates a secure, unique backend authentication code. Webhook Handoff: The platform instantly sends a webhook carrying this authentication code and the transaction context to the partner’s server. Partner Prompt & Authentication: The partner receives the webhook and triggers an immediate mobile push notification requesting the cardholder to verify an incoming transaction. Tapping this notification opens the partner's mobile app, prompting the user to authenticate via their device's native biometrics (e.g., Face ID or fingerprint) and explicitly approve the payment. Final Verification: After the cardholder approves the payment via biometrics, the partner sends this confirmation back to the platform by calling an authentication API (passing the secure code and the cardholder's decision). Finally, the platform validates the API payload and authorizes the transaction. Biometric Authentication Waiting Page In the live environment, the cardholder initiates an online or e-commerce payment request directly from a merchant's website or application. If the merchant's payment system requires 3DS authentication, the payment network will initiate an authentication request. Because biometric 2FA is enabled for the program, the system will automatically render the Biometric Authentication Waiting Page . This is where the native biometric 2FA authentication process begins on the MatchMove platform. Getting Started with Assisted 3DS Authentication Assisted 3DS Authentication (both OTP and Biometric 2FA) is an OPTIONAL service available for new and existing partners. Default Behavior: Without this service enabled, MatchMove is solely responsible for delivering the standard 3DS OTP to the enabled delivery channels. Assisted 3DS Enabled: When this service is activated, the partner takes control of the authentication experience. Depending on your configuration, you can either take over the direct delivery of the 3DS OTP to your cardholders or participate in a seamless native biometric challenge within your application. 1 Enable Biometric 2FA in your program configuration Partners who want to enable Assisted 3DS Authentication - Biometric 2FA / Out-of-Band (OOB) should contact the MatchMove Implementation team and request to set up and configure it in the platform configuration. 2 Set Up a Device Registry The Device Registry acts as the central address book and security gatekeeper for the entire Biometric 2FA authentication process. When a user initiates a transaction, the system needs to know exactly who they are, what physical device they use, and how to reach that specific device instantly . Here is a detailed breakdown of what this entails and why each component is critical: The Core Mapping Components To make sure the right person gets the right notification on the right phone, the partner’s backend database must link four specific pieces of information together: User Identifier ( user.id ): This is the unique profile identifier of your customer. When a transaction requires verification, the system flags this specific ID. Card Identifier ( card.id ): This is the unique identifier for your customer's specific card. When a transaction requires verification, the system flags this specific ID. Device Hardware ID: This is a unique, persistent identifier for the user's physical smartphone or tablet. It ensures the authentication request is bound to a "trusted device." If a malicious actor tries to log in from an unknown phone, the hardware ID won't match the registry, adding a vital layer of fraud prevention. Push Tokens (FCM/APNs): These are the digital routing addresses provided by Google and Apple. You cannot send a push notification directly to a phone number. You must send a payload to Apple or Google's servers using this token, and they will relay it to the user's phone. FCM (Firebase Cloud Messaging): The routing service used for Android devices. APNs (Apple Push Notification service): The routing service used for iOS devices. 3 Build App UI & Biometric Integration This step bridges the gap between the complex security happening in the background and the actual experience your customer has on their phone. By bundling the user interface (UI) with the biometric security engine, you ensure that approving a transaction is both frictionless and highly secure. Here is a detailed breakdown of how the visual and technical elements come together: The User Interface (UI) Components The partner is responsible for building clear, intuitive screens within their existing mobile app to handle the lifecycle of Out-of-Band (OOB) authentication: The Biometric Enablement Screen: Before any of this works, the user must opt-in. You need to build a screen that explains the benefits of biometric approvals and asks for their permission to enable it. Biometric login MUST be enabled as the primary login option for your application. The Biometric Login Prompt: The visual prompt that asks the user to scan their face or fingerprint when they open the app to approve a transaction. The Transaction Authentication Screen: Once authenticated, the user must see exactly what they are approving. This screen needs to clearly display critical context: Merchant Name Transaction Amount and Currency Date and Time Approve / Decline Buttons: Prominent, unmistakable calls to action so the user can make their final decision. The Biometric Security Engine The UI is just the surface; the actual verification is powered by integrating the native software development kits (SDKs) provided by Apple and Google. Native OS Integration: The partner app must tie into Face ID / Touch ID (for iOS using the LocalAuthentication framework) and BiometricPrompt (for Android). Local Verification: It is crucial to understand that biometric data (the scan of the face or fingerprint) never leaves the user's physical device. This local validation protects user privacy and ensures that even if your servers were compromised, no biometric data could be stolen. The app simply asks the phone's operating system, "Is this the registered owner?" The OS performs the scan locally and returns a simple "Yes" or "No" (a cryptographic token) to your app. 4 Subscribe to the 3DS Authentication webhook Once the service is enabled in the configuration, partners must subscribe to the webhook event CARDS.3DS.AUTHENTICATION . This webhook will deliver a payload containing the card ID and transaction 3DS from a payment authentication request. Upon receipt of the CARDS.3DS.AUTHENTICATION webhook, the partner must consume the payload and prepare to dispatch a push notification to the cardholder. Sample webhook payload JSON { "entities": { "card": { "id": "13d3f36e3cd6ce50e1c46b2158a60a43", "type": "demodebitpcard" }, "user": { "email": "john.smith@matchmove.com", "id": "db6c498690d3430eac38d8ad0738c9ca", "mobile": "1934943504", "mobile_country_code": "91" }, "transaction": { "network": "Master", "transaction_amount": "3.00", "transaction_currency": "AUD", "merchant": { "merchant_name": "Merchant ABC" }, "authentication": { "id": "019bc664-2a59-7c00-ae12-dc48404fb84d", "created_at": "2026-01-16T18:40:11+08:00", "expires_at": "2026-01-16T18:50:11+08:00", "method": "oob", "challenge_priority": 1, "retry_count": "0", "details": { "type": "biometrics", "code": "2345234534534" } } } }, "entity_id": "019bc664-2a59-7c00-ae12-dc48404fb84d", "entity_type": "CARD", "event_timestamp": "2026-01-16T10:40:13Z", "message_id": "019bc664-30b1-7c01-b438-3e0a675546f4", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.3DS.AUTHENTICATION" } Extract critical routing and tracking identifiers from the webhook payload: Field Purpose entities.user.id Identifies which customer is performing the transaction entities.card.id Identifies which card the customer is performing the transaction on entities.transaction.authentication.id The unique authentication code for the current 3DS session. This value must be retained and passed in the subsequent callback payload. entities.transaction.authentication.details.code The authentication code for the active 3DS session. This value must be retained and passed in the subsequent callback payload. 5 Dispatch a push notification to the cardholder Once you receive and parse the webhook payload, the next step is to alert the cardholder on their registered mobile device. This is achieved by correlating the transaction data with your Device Registry and sending a targeted push notification. How to Dispatch the Notification 1. Identify the Target Device Extract the entities.user.id (or entities.card.id ) from the incoming webhook payload. Query your Device Registry using this identifier to retrieve the user's active Push Token (FCM for Android or APNs for iOS) and verify that they are using a trusted hardware device. 2. Construct the Push Payload Build a push notification payload that includes the necessary transaction details to display to the user, alongside the hidden authentication codes your app will need to process the biometric approval later. Contextual Data (For the App UI): Extract the merchant_name , transaction_amount , and transaction_currency so the user knows exactly what they are approving. Authentication Data (For the API Callback): Include the authentication.id and the authentication.details.code . 3. Send the Push Request Dispatch the constructed payload through your mobile messaging infrastructure (e.g., Firebase Cloud Messaging or Apple Push Notification service). Critical Requirement: This request must be sent as a high-priority "data message." High-priority delivery is essential to bypass standard battery optimizations, immediately wake up your application, and seamlessly trigger your custom Biometric Login Prompt without any delay to the user's transaction flow. 6 App Redirect to Authentication prompt Once the high-priority push notification is dispatched to the cardholder’s device, your mobile application must handle the incoming payload and immediately guide the user to the biometric authorization screen. This step ensures a frictionless transition from the notification tap to the final payment approval. Handling the Notification Lifecycle Depending on the state of the user's mobile device when the push notification arrives, your app should execute the following routing behaviors: App in Background / Device Locked: The user receives a system notification. Tapping the notification should open the partner app, prompting the customer to do a biometric prompt before being granted access to the app. Then, instead of showing the standard home screen or app landing page, the deep link must display the Transaction Authentication Screen directly. App in Foreground: If the user is actively using your app, you should intercept the high-priority data message and immediately overlay the Transaction Authentication Screen, usually presented as an in-app modal, to avoid disrupting their active session while prioritizing the transaction. T he Cardholder Experience When a user taps the push alert, the app guides them through a seamless verification process: Identity Verification: The app opens directly into a biometric security check (via Face ID, Touch ID, or biometric prompt). Contextual Review: Only after biometric clearance does the app reveal the secure transaction data, showing the exact amount, currency, and merchant involved. Final Decision: The user can then confidently finalize the process by selecting a prominent "Approve" or "Decline" button. 7 Execute the Finalization Callback Immediately after the cardholder selects "Approve" or "Decline," the following sequence must occur: Internal Notification: The mobile application alerts the Partner's backend system of the user's decision. Trigger API Callback: The Partner's backend transmits the result to Matchmove's Update Transaction Authentication Status API via the POST /authentications/status endpoint. Required Payload: The request must include the authentication_id , the final status (APPROVED or DECLINED) and the verification_type (FINGERPRINT or FACE_ID). Error Handling: If the Callback API responds with a 500 Internal Server Error, the partner's system is required to automatically retry the request. Update Transaction Authentication Status You can call the Update Transaction Authentication Status ( POST /authentications/status ) to finalize the transaction authorization. Update Transaction Authentication Status request CURL curl --request POST \ --url https://{{cards_base_url}}/{{program_code}}/v2/users/wallets/cards/authentications/status \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "authentication_id": "019735d1-8af7-7c19-97be-371697e2eb78", "status": "APPROVED", "authentication_code": "2345234534534", "verification_type": "FINGERPRINT" }' Parameter Type Description Allowed Values authentication_id String Unique tracker ID from CARDS.3DS.AUTHENTICATION webhook payload entities.transaction.authentication.id status String User's decision APPROVED DECLINED authentication_code String Authentication code from CARDS.3DS.AUTHENTICATION webhook payload entities.transaction.authentication.details.code verification_type String Biometric method used FINGERPRINT FACE_ID IRIS VOICE NONE (use NONE when status is DECLINED) Update Transaction Authentication Status response - 500 In the event that the Transaction Authentication Callback request is met with an HTTP Error 500 , the partner should retry the request. 8 Validate your integration There are simulation APIs available that can be used to test Assisted 3DS Authentication - Biometric 2D in the staging environment. You can go to the Simulate Assisted 3DS Authentication - Biometric 2FA section to learn more about the simulation procedures. 9 [Optional] SMS fallback mechanism The SMS fallback mechanism provides a backup verification route that users must actively select on the 3DS page. The 3DS UI will automatically change according to which authentication mechanisms are enabled in your program. In the example below, email is configured as the primary method with SMS enabled as the secondary option. Once the fallback is chosen, the screen updates to prompt for the text message code. This ensures a seamless checkout experience and reduces cart abandonment even if the primary method is unreachable. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Simulate assisted 3DS authentication Card payments Manage card security • [Simulate assisted 3DS authentication - OTP 2FA](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication/simulate-assisted-3ds-authentication-otp-2fa.md): Simulate Assisted 3DS authentication - OTP 2FA allows you to emulate the behavior of an assisted 3D Secure verification process. This facilitates testing and validation of your integration’s handling of authentication flows, ensuring a smoother user experience during real-world transactions. Prerequisites The partner program has already been enabled and configured for Assisted 3DS authentication — OTP 2FA . The partner must subscribe to the following webhook to receive the payload containing the OTP that will need to be passed to the end-user. Webhook Description CARDS.3DS.AUTHENTICATION Webhook message sent by the MatchMove platform containing the authentication details based on the enabled 3DS authentication mode configured for the program. API Workflow Note: The set of endpoints below is only available and enabled in the staging environment. These endpoints allow you to simulate Initate Card Authentication, Resend Card Authentication, and Verify Card Authentication, and test Assisted 3DS Authentication - OTP 2FA before the live environment. 1 Initiate a card authentication request The Simulate Initiate Card Authentication ( POST /simulate/cards/authentication/start ) will simulate an authentication request for an OTP code. This API will trigger the platform to send a CARDS.3DS.AUTHENTICATION webhook to your backend. Request parameters: card_id - Required. Card ID. challenge_method - Required. Verification method. Allowed value: otp type - Required. OOB category. Allowed value: email , sms Simulate Initiate Card Authentication request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/simulate/cards/authentication/start' \ --header 'X-Auth-User-ID: 08dcfa7946874386a3c081571efc0abc' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic ==' \ --data '{ "card_id": "{{card_id}}", "challenge_method": "otp", "type": "email" }' Simulate Initiate Card Authentication response (success) JSON { "message": "authentication started and email otp sent successfully", "transaction_authentication_id": "01a1ab48-269b-7620-9978-9c6eaf6d3f98" } Simulate Initiate Card Authentication response (card network validation error) JSON { "id": "0cbf291b-7b86-480f-a185-77fbba14fde0", "status": 400, "code": "missing_required_param", "title": "Parameter validation failed", "detail": "card_network is a required field", "timestamp": "2023-05-18 12:57:19.107844122 +0000 UTC" } Simulate Initiate Card Authentication response (invalid card error) JSON { "id": "0cbf291b-7b86-480f-a185-77fbba14fde0", "status": 400, "code": "card_not_supported", "title": "Unsupported Card", "detail": "Currently card is not supported", "timestamp": "2023-05-18 12:57:19.107844122 +0000 UTC" } 2 Resend another card authentication request The Simulate Resend Card Authentication ( POST /simulate/cards/authentication/resend ) will simulate a fresh authentication request for an OTP code. This process is needed when the previous OTP has expired and is invalid for authentication. This API will re-trigger the platform to send a CARDS.3DS.AUTHENTICATION webhook to your backend. Request parameters: transaction_authentication_id - Required. Transaction ID received from Simulate Initiate Card Authentication response. Simulate Resend Card Authentication request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/simulate/cards/authentication/resend' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "transaction_authentication_id":"fc35d12cc5c14b3187fbee26368467d9" }' Simulate Resend Card Authentication response JSON { "message": "Message resent" } 3 Verify the card authentication request The Simulate Verify Card Authentication ( POST /simulate/cards/authentication/verify ) will simulate the verification of the 3DS OTP code entered by the customer. This OTP must be the same OTP that was sent and received in any of the allowed communication channels. Request parameters: transaction_authentication_id - Required. Transaction ID received from Send OTP Response transaction_authentication_value - Required. This is the 3DS OTP that was received from the end-user (the OTP sent through the allowed communication channels). Must be of length = 6. Simulate Verify Card Authentication request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/simulate/cards/authentication/verify' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "transaction_authentication_id":"fc35d12cc5c14b3187fbee26368467d9", "transaction_authentication_value":"595347" }' Simulate Verify Card Authentication response (success) JSON { "message": "Verification done" } Simulate Verify Card Authentication response (invalid OTP) JSON { "id": "0cbf291b-7b86-480f-a185-77fbba14fde0", "status": 400, "code": "invalid_value_param", "title": "Parameter validation failed", "detail": "transaction_authentication_value contains invalid value", "timestamp": "2023-05-18 12:57:19.107844122 +0000 UTC" } Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Assisted 3DS authentication Card payments Manage card security • [Simulate assisted 3DS authentication - Biometric 2FA](https://developer.matchmove.com/matchmove-banking-operating-system/card-payment-authentication/simulate-assisted-3ds-authentication-biometric-2fa.md): Simulate Assisted 3DS authentication — Biometric 2FA / Out-of-Band (OOB) allows you to emulate the behavior of an assisted 3D Secure verification process. This facilitates testing and validation of your integration’s handling of authentication flows, ensuring a smoother user experience during real-world transactions. Prerequisites The partner program has already been enabled and configured for Assisted 3DS authentication — Biometric 2FA / Out-of-Band (OOB). The partner must subscribe to the following webhook to receive the payload containing the OTP that will need to be passed to the end-user. Webhook Description CARDS.3DS.AUTHENTICATION Webhook message sent by the MatchMove platform containing the authentication details based on the enabled 3DS authentication mode configured for the program. API Workflow Note: The set of endpoints below is only available and enabled in the staging environment. These endpoints allow you to simulate Initiate Card Authentication, Resend Card Authentication, and test Assisted 3DS Authentication - Biometric 2FA before the live environment. 1 Initiate a card authentication request The Simulate Initiate Card Authentication ( POST /simulate/cards/authentication/start ) will simulate an authentication request for a biometric authentication code. This API will trigger the platform to send a CARDS.3DS.AUTHENTICATION webhook to your backend. Request parameters: card_id - Required. Card ID. challenge_method - Required. Verification method. Allowed value: oob type - Required. OOB category. Allowed value: biometrics Simulate Initiate Card Authentication request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/simulate/cards/authentication/start' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "card_id": "{{card_id}}", "challenge_method": "oob", "type": "biometrics" }' Simulate Initiate Card Authentication response (success) JSON { "message": "authentication started and oob challenge sent successfully", "transaction_authentication_id": "45ee8cd0-9f57-4704-83d8-97c5b1a0d62a" } 2 Resend another card authentication request The Simulate Resend Card Authentication ( POST /simulate/cards/authentication/resend ) will simulate a fresh authentication request for a biometric authentication code. This process is needed when the previous authentication code has expired and is invalid for authentication. This API will re-trigger the platform to send a CARDS.3DS.AUTHENTICATION webhook to your backend. Request parameters: transaction_authentication_id - Required. Transaction authentication ID received from Simulate Initiate Card Authentication response. Simulate Resend Card Authentication request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/simulate/cards/authentication/resend' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "transaction_authentication_id":"45ee8cd0-9f57-4704-83d8-97c5b1a0d62a" }' Simulate Resend Card Authentication response JSON { "message": "message resent" } Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Assisted 3DS authentication Card payments Manage card security • [Card payment authorization](https://developer.matchmove.com/matchmove-banking-operating-system/card-payments.md): Understand the end-to-end lifecycle of a card payment, including both financial and non-financial transactions. This guide provides a high-level overview of how card activity is processed, from authorization to final settlement. Authorizations Online messages received by the platform as part of processing transactions for cardholder accounts issued in the system There are two(2) types of transaction authorizations: Non-financial Transactions Non-financial transactions are a type of transaction that originates from the card network/payment institutions or merchants. This is a part of the transaction processing lifecycle, which does not have any impact on the customer balances. Financial Transactions Financial transactions are a type of transaction initiated when a cardholder tries to execute and confirm a payment with a merchant or any other payment institution. These transactions, when authorized, will have an impact on the customer balances. Non-financial Transactions Types These are the current non-financial transactions that will be exposed by the platform to you as a platform consumer Account Verification This message is used to verify the status of an account, including whether it is active, inactive, or has any restrictions. It can be initiated by merchants during a transaction or by financial institutions for administrative purposes. Financial Transactions Types As part of card transactions, the system will receive the following types of transactions, which will be shown to the end user. ATM Transactions These are transactions conducted at ATMs. 1. Cash Withdrawals: Withdrawing cash from an ATM using a debit or credit card. 2. Balance Inquiries: Checking the balance of an account using a card. Card Present Transactions These occur when the physical card is present at the point of sale (POS). 1. Swipe Transactions: The card is swiped through a magnetic stripe reader. 2. Chip-and-PIN (EMV) Transactions: The card’s chip is inserted into a reader, and the cardholder enters a PIN. 3. Contactless (Tap) Transactions: The card is tapped near a contactless reader (using NFC technology). Mobile Wallet Transactions These involve the use of digital wallets on mobile devices. 1. In-Store Mobile Wallet Payments: Using apps like Apple Pay, Google Pay, or Samsung Pay to pay at a POS terminal. 2. In-App Mobile Wallet Payments: Paying for goods or services within a mobile app using stored card details. Card Not Present Transaction These occur when the card is not physically present. 1. Online Transactions: The card details are entered on an e-commerce website. 2. Recurring Transactions: Payments are automatically deducted at regular intervals (e.g., subscriptions). Contactless Payments with Wearables Payments that are made using devices like smartwatches or fitness trackers with contactless payment capabilities. Purchase in Different Currencies As long as the regulatory construct allows your card can be used to transact worldwide across all supported merchants by the network, irrespective of where it was issued. Purchases made in currencies/locations different from the country of issuance are classified as cross-border transactions. The MatchMove platform leverages the conversion rates provided by the network to convert the amount into the equivalent currency of your account and do a corresponding balance deduction. This conversion incurs a charge from the network, which is reflected as a separate fee transaction posted to your customer's account. To learn more about the transaction authorization process, refer to the Transactions Authorizations section. Settlements The process of receiving settlement data from networks and reconciling it to compare with authorization data, correcting mismatch entries, and posting the same to cardholders to settle with networks Stages of the Settlement Process Card transactions can be further bifurcated based on the settlement stage that there are in: Clearing Reconciliation Posting Partners can go to the Transaction Settlements section to learn more about the transaction settlement process. Funding Models The MatchMove platform offers different types of funding models that can affect the way a card authorization is processed. Card Authorization Modes The platform gives partners the flexibility to choose the role they want to play in the authorization process. Platform-managed Authorization The MatchMove platform is responsible for end-to-end transaction authorization processing Shared Authorization MatchMove API consumers can configure a synchronous webhook to handle authorization requests, allowing partners to control the final decision before a transaction gets authorized. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Card payment fees Simulate card transactions Transaction authorizations Transaction settlements Manage card security • [Assisted card transaction risk management](https://developer.matchmove.com/matchmove-banking-operating-system/card-payments/transaction-risks.md): Learn to leverage risk insights provided by the payment network and participate in the risk management process. Understand how to analyze merchant profiles and card transaction fraud scores based on automated decision models. Prerequisites: Your card program has enabled the Shared Authorization model for card authorization. Card Transaction Risk Defense Card transaction risk management is the systemic process of identifying, analyzing, and mitigating financial liability and security threats in the payment lifecycle. Unlike basic security, which focuses on "locking the door," it is a dynamic decision-making engine that balances fraud prevention against revenue maximization. If controls are too loose, fraud rises. If controls are too tight, legitimate transactions are rejected (false positives), damaging customer loyalty. Effective risk management relies on a "defense-in-depth" strategy. This approach places multiple security barriers between a fraudster and the funds. In this embedded finance system, risk is managed across three distinct layers, each with specific responsibilities and visibility. Layer 1: The Payment Network Layer (Global Defense) This is the outermost layer of defense, operated by card schemes (e.g., Visa, Mastercard). Because these networks process billions of transactions globally, they have the unique ability to see macro-level attack patterns that a single platform or partner cannot detect. Global Threat Blocking: The network identifies and blocks large-scale attacks, such as "BIN attacks" (automated bots testing thousands of stolen card numbers) or coordinated attacks originating from high-risk geolocations. Catastrophic Stopgaps: Services like "Safety Net" automatically cut off transactions if an issuer or processor is overwhelmed by a fraud spike, preventing massive financial loss during system vulnerabilities. Stand-In Processing: If an issuing bank goes offline, the network can make risk-based approval decisions on their behalf to keep legitimate transactions flowing. Layer 2: The Platform Layer (Aggregated Intelligence) This layer represents the embedded financial system itself. It sits between the global network and the specific partner, aggregating data across all partners to identify trends and enforce baseline security. The MatchMove platform and the regional banking partners (depending on region) go hand-in-hand to secure card transactions at this level. Cross-Partner Velocity Checks: The platform monitors card usage across its entire ecosystem. If a card is used at Partner A and immediately used at Partner B in a suspicious manner, the platform can flag it at the system level. Fraud Checks: Using machine learning, the platform analyzes transaction metadata (device fingerprint, IP address, time of day) to assess transaction risk. Merchant Underwriting & Monitoring: The platform continuously evaluates the health of the partners themselves, ensuring that high chargeback rates or suspicious processing volumes are flagged for review. Layer 3: The Partner Level (Contextual Rules) This is the granular layer where you, the business user, apply controls based on your specific business model and customer knowledge. You understand your "normal" better than any algorithm. Custom Business Rules: You define specific logic relevant to your operations. For example, a high-value electronics retailer might set a rule to "Review all transactions over $1,000," while a digital goods provider might "Block all transactions from a specific country." Manual Review: You have the ability to inspect flagged transactions. You can look at the customer's history, contact them for verification, and make the final decision to capture or void the payment. Allow and Block Lists: You manage specific lists of trusted customers (VIPs) to bypass friction or known bad actors to block permanently, ensuring that your risk strategy evolves with your customer base. Assisted card transaction risk evaluation Partners who have enabled and are participating in the Shared Authorization model of authorizing card payments will also have the capability to participate in the card transaction risk management process. Through the OPENLOOP_PRE_AUTH webhook, the card payment authorization data and the risk data will be included in the payload. Partners will then be able to assess the risk data and decide based on their relationship and customer data. This risk assessment decision can be added as a factor to the authorization decision that is required to be passed as a response to the OPENLOOP_PRE_AUTH webhook before the authorization process can be completed. This authorization response will follow the same response time allowance indicated in the Transaction authorization - Shared Authorization section. In the staging environment, assisted card transaction risk evaluation can be tested by: Enabling the Shared Authorization model. Simulating a card transaction that will invoke the OPENLOOP_PRE_AUTH webhook containing the risk data. See Simulate card transactions section to learn more about the additional request parameter required to activate the risk data feature . Accessing the card transaction risk data Partners using the shared authorization model will receive these data fields in the Card Authorization Webhook under the risk_details payload block. MatchMove will extract and store additional risk information received from Mastercard in DE 48 during the authorization process. Data Field Description DE 48, sub-element 75 Fraud Scoring Data Provides a fraud score between 000–999, where 000 indicates the lowest likelihood of fraud and 999 the highest. Also includes the key factors influencing the score. DE 48, sub-element 56 Security Services Additional Data for Issuers Contains insights from Mastercard’s embedded security services (e.g., Decision Intelligence, Digital Transaction Insights), offering additional data supporting the fraud scores DE 61 Point-of-Service (POS) Data elements Contains point-of-service data about the conditions that exist at the point of service at the time of the transaction. It is made up of multiple subfields, each capturing a specific aspect of the transaction environment DE 22, sub-element 2 POS Terminal PIN Entry Mode Identify whether PIN was entered, bypassed, or not capable at the terminal—supporting stronger fraud detection for card-present transactions. DE 48, sub-element 22.01 Low-Risk Merchant / SCA Exemption Indicator Determine whether a transaction carries a valid SCA exemption signal and the declared basis—low fraud TRA, recurring, low value, MIT, or SCA delegation. DE 48, sub-element 22.02 Single Tap Indicator Distinguish contactless single-tap transactions for targeted velocity controls DE 48, sub-element 22.05 Cardholder / Merchant-Initiated Transaction (MIT) Indicator Identify merchant-initiated vs. cardholder-initiated transactions for accurate liability assessment, and downstream reconciliation DE 48, sub-element 06 Advanced Digital Transaction Data 1 (Phone Number) Phone number submitted by the cardholder as part of the digital transaction Enables partners to cross-reference submitted contact identity against registered cardholder data. Mismatches are a strong fraud signal for card-not-present and e-commerce transactions, particularly in account takeover scenarios. DE 48, sub-element 08 Advanced Digital Transaction Data 3 (Shipping Address) (08.02) Provides the primary address component for shipping-to-billing comparisons at authorization time; enables detection of transactions shipping to addresses inconsistent with the cardholder's known profile (08.03) Enables cross-border shipping detection at authorization time — a high-signal fraud indicator for digital goods and physical merchandise fraud, particularly when the shipping country differs from the cardholder's country of residence (08.04) Adds sub-country precision to shipping address verification, supporting more granular billing-to-shipping mismatch detection and postal-code-level risk controls DE 48, sub-element 39 Account Data Compromise Information (ADC Alerts) Surfaces network-level intelligence on cardholder data exposure directly to partners. Enables risk-based step-up authentication or automated decline for cards with known personal data compromise history Provides a direct signal for PIN-based fraud risk. Cards with a non-zero PIN event count should be subject to heightened scrutiny for PIN-authenticated transactions, particularly at ATMs and POS terminals DE 48, sub-element 71 On-Behalf (OB) Services Results (71.01) Identifies which network-level service acted on the transaction upstream, providing context for authorization decisions and enabling partners to factor in network-applied service logic (71.02) Conveys the outcome of the network-level service action, enabling partners to interpret and respond to upstream processing results within their own authorization logic (71.03) Provides supplementary outcome detail for on-behalf services that return multi-dimensional results, supporting more complete interpretation of upstream service decisions DE 48, sub-element 32 Mastercard Assigned ID Enables network-consistent merchant identification independent of acquirer-assigned IDs; supports cross-transaction correlation and pattern detection at a stable, Mastercard-assigned merchant identity level DE 23 Card Sequence Number Enables precise card-instance-level fraud tracking when multiple physical or virtual cards share a PAN. DE 122, sub-element 1.2 Acceptor Country Subdivision Code Extends geographic precision below the country level already provided by DE 61.13, enabling region-level anomaly detection, geolocation-based spend controls, and more accurate cross-region transaction risk scoring Risk data restrictions: Risk data are raw values extracted from the payment network request payload (with no transformation) and are only passed through by MatchMove. Risk data will only be included in the payload when they are provided by the network. Risk data fields will be omitted when no data is present. Risk data are available only in the Pre-Auth webhook (not in Post-Auth webhooks). Below is the mapping between the risk fields and the webhook parameters: Risk Category Risk Field Description DE 48, sub-element 75 (Fraud Scoring Data) transactions > risk_details > fraud_scoring_data Overall fraud scoring information for the transaction Subfield 1 (Fraud Score) risk_details > fraud_scoring_data > fraud_score Transaction risk score (000–999) Subfield 2 (Fraud Reason Code) risk_details > fraud_scoring_data > fraud_reason_code Factors that influenced the fraud score Subfield 3 (Model Score) risk_details > fraud_scoring_data > model_score Model-based risk score (SafetyNet / Fraud Rule Manager) Subfield 4 (Model Reason Code) risk_details > fraud_scoring_data > model_reason_code Factors influencing the model score DE 48, sub-element 56 (Security Services Additional Data for Issuers) transactions > risk_details > security_services_data Data from Mastercard real-time monitoring services Subfield 1 Security Service Indicator risk_details > security_services_data > indicator Three-character code identifying the security service used Subfield 2 Security Service Data risk_details > security_services_data > insight Additional data supporting the fraud score DE 61, Point-of Service [POS] Data elements pos_data > terminal_attendance pos_data > terminal_location .. pos_data > pos_postal_code Carries detailed information about the conditions present at the point of service when a transaction takes place DE 22, sub-element 2, POS Terminal PIN Entry Mode webhook_transaction > payment_channel > pos_data > pos_pin_entry_mode PIN entry capability and method used at the point of service terminal DE 48, sub-element 22.01, Low-Risk Merchant Indicator webhook_transaction > authorization > additional_transaction_data > multi_purpose_merchant_indicator > low_risk_merchant_indicator Acquirer-declared reason code indicating the basis on which SCA was not applied or an exemption was claimed in the authorization DE 48, sub-element 22.02, Single Tap Indicator webhook_transaction > authorization > additional_transaction_data > multi_purpose_merchant_indicator > single_tap_indicator Flag indicating whether the merchant terminal supports single-tap contactless processing DE 48, sub-element 22.05, Cardholder / MIT Indicator webhook_transaction > authorization > additional_transaction_data > multi_purpose_merchant_indicator > transaction_initiator Indicates whether the transaction was initiated by the cardholder in real time (CIT) or by the merchant on the cardholder's behalf without their active presence (MIT) DE 48.06.02 (Phone Number) webhook_transaction > authorization > additional_transaction_data > digital_transaction_data > cardholder_phone_number Phone number submitted by the cardholder as part of the digital transaction DE 48.08.02 (Shipping Address Line 1) webhook_transaction > authorization > additional_transaction_data > digital_transaction_data > cardholder_shipping_address > shipping_address_line_1 Street-level shipping address submitted with the transaction DE 48.08.03 (Shipping Address Country) webhook_transaction > authorization > additional_transaction_data > digital_transaction_data > cardholder_shipping_address > shipping_address_country Country of the shipping destination submitted with the transaction DE 48.08.04 (Shipping Address Postal Code) webhook_transaction > authorization > additional_transaction_data > digital_transaction_data > cardholder_shipping_address > shipping_address_postal_code Postal code of the shipping destination submitted with the transaction DE 48.39 — ADC Personal Info Event Count webhook_transaction > risk_details > account_data_compromise_info > adc_personal_info_exposure_events Mastercard-issued count of personal information compromise events associated with the card DE 48.39 — ADC PIN Event Count webhook_transaction > risk_details > account_data_compromise_info > adc_pin_exposure_events Mastercard-issued count of PIN compromise events associated with the card DE 48.71.01 (OB Service) webhook_transaction > risk_details > on_behalf_services > on_behalf_service Identifier of the on-behalf service performed by Mastercard or a designated provider during authorization processing DE 48.71.02 (OB Result 1) webhook_transaction > risk_details > on_behalf_services > on_behalf_result_1 Primary result code of the on-behalf service performed DE 48.71.03 (OB Result 2) webhook_transaction > risk_details > on_behalf_services > on_behalf_result_2 Secondary result code of the on-behalf service performed DE 48.32 (Mastercard Assigned ID) webhook_transaction > merchant_details > network_merchant_id Network-assigned identifier for the merchant or transaction entity, consistent across Mastercard's network DE 23 (Card Sequence Number) webhook_payment_instrument > card_sequence_number Sequential identifier distinguishing individual card instances sharing a single PAN DE 122.1.2 (Acceptor Country Subdivision Code) webhook_transaction > merchant_details > country_subdivision_code State, province, or region code of the merchant terminal location Risk Field Values adc_personal_info_exposure_events Values Description Source 0 No personal-information exposure events reported by Mastercard MatchMove decoded, Mastercard DE48 SE39 Any non-zero integer Mastercard-issued count of personal-information exposure events. MatchMove decoded, Mastercard DE48 SE39 adc_pin_exposure_events Values Description Source 0 No PIN exposure events reported by Mastercard MatchMove decoded, Mastercard DE48 SE39 Any non-zero integer Mastercard-issued count of PIN exposure events. Non-zero is the intended scrutiny trigger. MatchMove decoded, Mastercard DE48 SE39 address_verification_data Values Description Source Raw pass-through — no MatchMove-defined value list MatchMove relays the network value unchanged and publishes no full / partial / mismatch value set. Decode follows the Mastercard AVS (Address Verification Service) response convention. Mastercard passthrough, AVS response ecom_authentication_indicator Values Description Source 210 3DS bypassed / not performed — 3DS state: No 3DS MatchMove decoded, Mastercard DE48 SE42.01 211 3DS attempted (non-low-risk smart auth) — 3DS state: Attempted MatchMove decoded, Mastercard DE48 SE42.01 212 3DS authenticated (low-risk smart auth) — 3DS state: Fully authenticated MatchMove decoded, Mastercard DE48 SE42.01 216 Merchant/acquirer risk-based or exempted — 3DS state: Exemption MatchMove decoded, Mastercard DE48 SE42.01 217 Authenticated MIT (merchant-initiated transaction) MatchMove decoded, Mastercard DE48 SE42.01 242 Tokenized authenticated MatchMove decoded, Mastercard DE48 SE42.01 246 Tokenized unauthenticated MatchMove decoded, Mastercard DE48 SE42.01 247 Tokenized MIT (merchant-initiated transaction) MatchMove decoded, Mastercard DE48 SE42.01 fraud_reason_code Values Description Source 01 Suspicious cross-border activity MatchMove decoded, Mastercard DE48 SE75.02 02 Suspicious transaction MatchMove decoded, Mastercard DE48 SE75.02 03 High number of transactions MatchMove decoded, Mastercard DE48 SE75.02 04 High number of transactions at an unattended terminal MatchMove decoded, Mastercard DE48 SE75.02 05 Suspicious recent history of transactions MatchMove decoded, Mastercard DE48 SE75.02 06 Suspicious activity and high number of transactions MatchMove decoded, Mastercard DE48 SE75.02 07 Suspicious cardholder not present activity MatchMove decoded, Mastercard DE48 SE75.02 08 Suspicious activity and low number of transactions MatchMove decoded, Mastercard DE48 SE75.02 09 Suspicious service station activity MatchMove decoded, Mastercard DE48 SE75.02 10 Suspicious online activity MatchMove decoded, Mastercard DE48 SE75.02 11 High amount transaction or high accumulated amount recently spent MatchMove decoded, Mastercard DE48 SE75.02 12 Suspicious gambling activity MatchMove decoded, Mastercard DE48 SE75.02 13 Suspicious phone or mail order activity MatchMove decoded, Mastercard DE48 SE75.02 14 Suspicious grocery store activity MatchMove decoded, Mastercard DE48 SE75.02 15 High-risk country MatchMove decoded, Mastercard DE48 SE75.02 16 High amount, high number of transactions, and cross-border MatchMove decoded, Mastercard DE48 SE75.02 17 Suspicious activity, including previous declined transactions MatchMove decoded, Mastercard DE48 SE75.02 18 Suspicious airline activity MatchMove decoded, Mastercard DE48 SE75.02 19 The score was forced to be 1 because the transaction being scored was a 04xx message. MatchMove decoded, Mastercard DE48 SE75.02 20 Not a financial transaction MatchMove decoded, Mastercard DE48 SE75.02 21 Abnormal geographic activity MatchMove decoded, Mastercard DE48 SE75.02 22 Abnormal, high frequency at the same MCC MatchMove decoded, Mastercard DE48 SE75.02 23 High amount of recent ATM activity MatchMove decoded, Mastercard DE48 SE75.02 24 Suspicious recent ATM activity or suspicious ATM activity following a recent abnormal activity MatchMove decoded, Mastercard DE48 SE75.02 25 Suspicious Telecom Activity MatchMove decoded, Mastercard DE48 SE75.02 26 High number of international ATM transactions MatchMove decoded, Mastercard DE48 SE75.02 27 High cumulative withdrawal amount on international ATM MatchMove decoded, Mastercard DE48 SE75.02 28 High velocity of domestic ATM transactions MatchMove decoded, Mastercard DE48 SE75.02 29 High Risk MCC MatchMove decoded, Mastercard DE48 SE75.02 low_risk_merchant_indicator Values Description Source 1 SCA exemption basis: MIT (merchant-initiated transaction) MatchMove decoded, Mastercard DE48 SE22.01 2 SCA exemption basis: Acquirer low-fraud TRA (transaction risk analysis) MatchMove decoded, Mastercard DE48 SE22.01 3 SCA exemption basis: Recurring payment MatchMove decoded, Mastercard DE48 SE22.01 4 SCA exemption basis: Low-value payment MatchMove decoded, Mastercard DE48 SE22.01 5 SCA exemption basis: SCA delegation MatchMove decoded, Mastercard DE48 SE22.01 6 SCA exemption basis: Secure corporate payment MatchMove decoded, Mastercard DE48 SE22.01 7 SCA exemption basis: Authentication outage exception MatchMove decoded, Mastercard DE48 SE22.01 8 SCA exemption basis: Trusted merchant exemption (Visa) MatchMove decoded, Mastercard DE48 SE22.01 on_behalf_services.on_behalf_service Values Description Source 1 Chip to magnetic stripe conversion MatchMove decoded, Mastercard DE48 SE71 2 M/Chip cryptogram prevalidation MatchMove decoded, Mastercard DE48 SE71 3 M/Chip cryptogram validation stand-in MatchMove decoded, Mastercard DE48 SE71 4 M/Chip cryptogram regeneration MatchMove decoded, Mastercard DE48 SE71 5 3DS AAV (Accountholder Authentication Value) verification MatchMove decoded, Mastercard DE48 SE71 6 3DS AAV verification stand-in MatchMove decoded, Mastercard DE48 SE71 8 Online PIN prevalidation (Europe) MatchMove decoded, Mastercard DE48 SE71 9 Online PIN validation stand-in (Europe) MatchMove decoded, Mastercard DE48 SE71 10 CVC1 validation stand-in MatchMove decoded, Mastercard DE48 SE71 11 CVC1 prevalidation MatchMove decoded, Mastercard DE48 SE71 14 Contactless mapping MatchMove decoded, Mastercard DE48 SE71 15 Dynamic CVC3 prevalidation MatchMove decoded, Mastercard DE48 SE71 16 Dynamic CVC3 validation stand-in MatchMove decoded, Mastercard DE48 SE71 17 In-Control virtual card MatchMove decoded, Mastercard DE48 SE71 18 Fraud scoring service MatchMove decoded, Mastercard DE48 SE71 20 In-Control RCN (real card number) spend control MatchMove decoded, Mastercard DE48 SE71 25 ADC (Account Data Compromise) information MatchMove decoded, Mastercard DE48 SE71 26 Point-of-interaction MatchMove decoded, Mastercard DE48 SE71 31 Chip CVC to CVC1 conversion MatchMove decoded, Mastercard DE48 SE71 32 Chip CVC to CVC1 conversion MatchMove decoded, Mastercard DE48 SE71 33 Send-transactions blocking MatchMove decoded, Mastercard DE48 SE71 37 Merchant-presented QR blocking MatchMove decoded, Mastercard DE48 SE71 50 MDES (Mastercard Digital Enablement Service) PAN mapping MatchMove decoded, Mastercard DE48 SE71 51 MDES prevalidation — SE (secure element) tokens MatchMove decoded, Mastercard DE48 SE71 52 MDES prevalidation — SE (secure element) tokens MatchMove decoded, Mastercard DE48 SE71 54 MDES digital payment data validation MatchMove decoded, Mastercard DE48 SE71 55 Merchant validation MatchMove decoded, Mastercard DE48 SE71 61 MDES prevalidation — cloud tokens MatchMove decoded, Mastercard DE48 SE71 62 MDES prevalidation — cloud tokens MatchMove decoded, Mastercard DE48 SE71 71 TSP (token service provider) cloud payments chip validation stand-in MatchMove decoded, Mastercard DE48 SE71 on_behalf_services.on_behalf_result_1 Values Description Source Raw pass-through — no MatchMove-defined value list Primary result, a single raw character (sample: "C"). Follows the Mastercard OBS (On-Behalf Service) result convention; a failed check such as a CVC2 mismatch surfaces as the raw result character on the relevant service. Decode from the Mastercard specification. Mastercard passthrough, DE48 SE71 on_behalf_services.on_behalf_result_2 Values Description Source Raw pass-through — no MatchMove-defined value list Secondary result, a single raw character (sample: " " / blank). Same Mastercard OBS result convention as on_behalf_result_1. Decode from the Mastercard specification. Mastercard passthrough, DE48 SE71 pos_data.card_presence Values Description Source 0 Card present MatchMove decoded, Mastercard DE61 1 Card not present MatchMove decoded, Mastercard DE61 pos_data.card_capture_capability Values Description Source 0 Terminal not capable of card capture MatchMove decoded, Mastercard DE61 1 Terminal capable of card capture MatchMove decoded, Mastercard DE61 pos_data.cardholder_presence Values Description Source 0 Normal request MatchMove decoded, Mastercard DE61 1 Deferred authorization MatchMove decoded, Mastercard DE61 2 Identity-check phone order MatchMove decoded, Mastercard DE61 3 ATM installment inquiry MatchMove decoded, Mastercard DE61 4 Preauthorized request MatchMove decoded, Mastercard DE61 5 Time-based payment authorization request MatchMove decoded, Mastercard DE61 6 ATC (Application Transaction Counter) update MatchMove decoded, Mastercard DE61 8 Account status inquiry MatchMove decoded, Mastercard DE61 9 Tokenization request notification MatchMove decoded, Mastercard DE61 pos_data.cat_level Values Description Source 0 Not a CAT (Cardholder-Activated Terminal) MatchMove decoded, Mastercard DE61 1 Automated dispensing machine with PIN MatchMove decoded, Mastercard DE61 2 Self-service terminal MatchMove decoded, Mastercard DE61 3 Limited-amount terminal MatchMove decoded, Mastercard DE61 4 In-flight commerce MatchMove decoded, Mastercard DE61 5 Reserved MatchMove decoded, Mastercard DE61 6 E-commerce MatchMove decoded, Mastercard DE61 7 Transponder transaction MatchMove decoded, Mastercard DE61 8 Remote terminal MatchMove decoded, Mastercard DE61 9 mPOS acceptance device MatchMove decoded, Mastercard DE61 pos_data.terminal_input_capability Values Description Source 0 Unknown MatchMove decoded, Mastercard DE61 1 No terminal (voice / ARU / server) MatchMove decoded, Mastercard DE61 2 Magnetic stripe only MatchMove decoded, Mastercard DE61 3 Contactless EMV MatchMove decoded, Mastercard DE61 4 Contactless magnetic stripe MatchMove decoded, Mastercard DE61 5 EMV chip + magnetic stripe MatchMove decoded, Mastercard DE61 6 Key entry only MatchMove decoded, Mastercard DE61 7 Magnetic stripe + key entry MatchMove decoded, Mastercard DE61 8 EMV chip + magnetic stripe + key entry MatchMove decoded, Mastercard DE61 9 EMV chip only MatchMove decoded, Mastercard DE61 pos_data.terminal_attendance Values Description Source 0 Attended terminal MatchMove decoded, Mastercard DE61 1 Unattended terminal (CAT — Cardholder-Activated Terminal) MatchMove decoded, Mastercard DE61 2 No terminal (voice / ARU / server) MatchMove decoded, Mastercard DE61 pos_data.terminal_location Values Description Source 0 On premises of card acceptor facility MatchMove decoded, Mastercard DE61 1 Off premises — remote terminal MatchMove decoded, Mastercard DE61 2 Off premises — cardholder terminal MatchMove decoded, Mastercard DE61 3 No terminal (voice / ARU / server) MatchMove decoded, Mastercard DE61 4 On premises — cardholder terminal MatchMove decoded, Mastercard DE61 8 Additional POS locations MatchMove decoded, Mastercard DE61 pos_data.transaction_security Values Description Source 0 No security concern MatchMove decoded, Mastercard DE61 1 Suspected fraud MatchMove decoded, Mastercard DE61 2 Identity verified MatchMove decoded, Mastercard DE61 pos_entry_mode Values Description Source 0 UNKNOWN MatchMove decoded, Mastercard POS entry mode 1 MANUAL_ENTRY MatchMove decoded, Mastercard POS entry mode 2 AUTO_ENTRY_VIA_MAGSTRIPE MatchMove decoded, Mastercard POS entry mode 3 AUTO_ENTRY_VIA_BARCODE_READER MatchMove decoded, Mastercard POS entry mode 4 AUTO_ENTRY_VIA_OCR MatchMove decoded, Mastercard POS entry mode 5 AUTO_ENTRY_VIA_INTEGRATED_CIRCUIT_CARD MatchMove decoded, Mastercard POS entry mode 7 AUTO_ENTRY_VIA_CONTACTLESS_MCHIP MatchMove decoded, Mastercard POS entry mode 9 PAN_TOKEN_ENTRY_VIA_ECOM MatchMove decoded, Mastercard POS entry mode 10 CARD_ON_FILE MatchMove decoded, Mastercard POS entry mode 79 CHIP_FALLBACK_TO_MAGSTRIPE_READ MatchMove decoded, Mastercard POS entry mode 80 CHIP_FALLBACK_TO_MAGSTRIPE_READ MatchMove decoded, Mastercard POS entry mode 81 MANUALLY_KEYED_ECOM MatchMove decoded, Mastercard POS entry mode 82 AUTO_ENTRY_VIA_SERVER_ECOM MatchMove decoded, Mastercard POS entry mode pos_pin_entry_mode Values Description Source 0 Unknown MatchMove decoded, Mastercard PIN entry mode 1 PIN entry capable MatchMove decoded, Mastercard PIN entry mode 2 Not capable MatchMove decoded, Mastercard PIN entry mode 3 mPOS / SPoC capable MatchMove decoded, Mastercard PIN entry mode 8 Capable but not operative MatchMove decoded, Mastercard PIN entry mode pos_transaction_type Values Description Source 0 Normal request MatchMove decoded, Mastercard DE61 1 Deferred authorization MatchMove decoded, Mastercard DE61 2 Identity-check phone order MatchMove decoded, Mastercard DE61 3 ATM installment inquiry MatchMove decoded, Mastercard DE61 4 Preauthorized request MatchMove decoded, Mastercard DE61 5 Time-based payment authorization request MatchMove decoded, Mastercard DE61 6 ATC (Application Transaction Counter) update MatchMove decoded, Mastercard DE61 8 Account status inquiry MatchMove decoded, Mastercard DE61 9 Tokenization request notification MatchMove decoded, Mastercard DE61 security_services_data.indicator Values Description Source AQV Decision Intelligence – Authorization IQ (GDV-based Spend Ranking), Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 AQS Decision Intelligence – Authorization IQ (Segment Qualifier), Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 AQF Decision Intelligence – Authorization IQ (Frequency-based Spend Ranking), Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 AIQ Digital Transaction Insights – Payment Insights, Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 INC Consumer Controls, Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 DII Digital Transaction Insights – Digital Identity Insights, Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 ARA Decision Intelligence – Authentication Risk Analysis, Known Mastercard security-services indicator relayed as-is (3 characters) Mastercard passthrough, DE48 SE56 Any other 3-character indicator sent by the network Open list — MatchMove holds no closed indicator master list and relays whatever Mastercard sends as repeating indicator + insight pairs. Mastercard passthrough, DE48 SE56 security_services_data.insight Values Description Source 0 Clean / baseline — no elevated risk signalled MatchMove decoded, Mastercard DE48 SE56 Any non-zero 3-character value Elevated risk, scaling with magnitude (consistent with the simulate 409). MatchMove does not translate insight into a named severity — treat any non-zero value as investigate. MatchMove decoded, Mastercard DE48 SE56 transaction_initiator Values Description Source C101 CIT (cardholder-initiated transaction) — card-on-file / unscheduled COF MatchMove decoded, Mastercard DE48 SE22.05 C102 CIT — standing order (recurring) MatchMove decoded, Mastercard DE48 SE22.05 C103 CIT — subscription MatchMove decoded, Mastercard DE48 SE22.05 C104 CIT — installment MatchMove decoded, Mastercard DE48 SE22.05 M101 MIT (merchant-initiated transaction) — card-on-file / unscheduled COF MatchMove decoded, Mastercard DE48 SE22.05 M102 MIT — standing order (recurring) MatchMove decoded, Mastercard DE48 SE22.05 M103 MIT — subscription MatchMove decoded, Mastercard DE48 SE22.05 M104 MIT — installment MatchMove decoded, Mastercard DE48 SE22.05 M205 MIT — e-commerce partial shipment MatchMove decoded, Mastercard DE48 SE22.05 M206 MIT — delayed charge MatchMove decoded, Mastercard DE48 SE22.05 M207 MIT — no-show charge MatchMove decoded, Mastercard DE48 SE22.05 M208 MIT — resubmission MatchMove decoded, Mastercard DE48 SE22.05 Sample Card Transaction OPENLOOP_PRE_AUTH webhook payload You can refer to the Simulate Card Transactions section to learn more on how to invoke, simulate, and test these risk parameters. JSON { "consumer": { "consumer_name": "Corp ABC", "prefund_balance": "10000.000000" }, "debit_credit_indicator": "D", "payment_instrument": { "balance_type": "Shared Balance", "card_brand": "MASTER", "card_form_factor": "physical", "card_sequence_number": "000", "card_type_code": "{{card_type_code}}", "expiry": "2031-05-31", "initial_instrument_id": "57165d4120a3b6d019d4ef2eadffd08b", "masked_number": "XXXXXXXXXXXX7486", "status": "active", "transaction_instrument_id": "3aee99f0ecc09ef58be29a8464960438" }, "time_stamp": "2026-06-02 14:17:46 +0800 UTC", "total_amount": "155.00", "total_currency": "PHP", "transaction": { "additional_fee_details": null, "authentication": { "3ds_version": "", "authentication_ucaf_value": "", "ecom_authentication_indicator": "" }, "authorization": { "card_amount": "155.00", "card_currency": "PHP", "fee_amount": "0.00", "fee_currency": "PHP", "id": "P_b21a09ad676548888e782f075bed0fe6", "local_transaction_timestamp": "", "network": "MASTER", "network_reference_number": "713638931604", "pos_transaction_type": "0", "total_amount": "155.00", "total_currency": "PHP", "transaction_amount": "155.00", "transaction_currency": "PHP", "transaction_type": "PURCHASE" }, "balance": { "post_transaction": { "available": { "amount": "", "currency": "PHP" }, "categories": [ { "amount": "", "currency": "", "name": "" } ] }, "pre_transaction": { "available": { "amount": "0.00", "currency": "PHP" }, "categories": [ { "amount": "0.00", "currency": "PHP", "name": "DEFAULT" } ] } }, "merchant_details": { "country_code": "PHL", "country_subdivision_code": "608", "institution_code": "005913", "merchant_category_code": "5499", "merchant_id": "000004300005002", "name": "BEANLEAF MANILA MANILA PHL", "terminal_id": "30051354" }, "payment_channel": { "channel_name": "POS", "pos_entry_mode": "CONTACTLESS_CHIP", "pos_pin_entry_mode": "1" }, "pos_data": { "card_capture_capability": "1", "card_presence": "0", "cardholder_presence": "0", "cat_level": "0", "pos_country_code": "PHL", "pos_postal_code": "1002 ", "terminal_attendance": "0", "terminal_input_capability": "3", "terminal_location": "0", "transaction_security": "0", "transaction_status": "0" }, "risk_details": { "fraud_scoring_data": [ { "key": "FRAUD_SCORE", "value": "025" }, { "key": "FRAUD_REASON_CODE", "value": "57" }, { "key": "MODEL_SCORE", "value": "025" }, { "key": "MODEL_REASON_CODE", "value": "57" } ], "on_behalf_services": [ { "on_behalf_result_1": "C", "on_behalf_result_2": " ", "on_behalf_service": "18" } ], "security_services_data": [ { "indicator": "AQV", "insight": "000" }, { "indicator": "AQS", "insight": "000" }, { "indicator": "AQF", "insight": "000" } ] }, "transaction_fees": [ { "amount": "", "code": "", "currency": "", "name": "" } ], "transaction_message": "", "transaction_ref": "P_b21a09ad676548888e782f075bed0fe6", "transaction_rules": {}, "transaction_status": "", "verification_details": { "address_verification_data": "" } }, "user": { "email": "test_user@gmail.com", "kyc_status": "post-kyc", "mobile": "9122751494", "mobile_country_code": "63", "user_hash": "33fe978ff6334c718754f1fb3036a0fd" }, "webhook_event": "OPENLOOP_PRE_AUTH" } • [Transaction authorizations](https://developer.matchmove.com/matchmove-banking-operating-system/card-payments/transaction-authorizations.md): Understand the real-time authorization process that occurs at the point of sale. This guide explains how we approve or decline transaction requests based on card status, spending controls, and available funds. Card Authorization Process User, Card, and Account Validation Before the transaction authorization process can happen, the MatchMove system checks the following: The account is active The card is in active Failure to meet any of these conditions will cause the transaction to be rejected. Transaction Controls The system will also check if the transaction is is from a card linked to an active card program is from a card that is associated with a valid cardholder, who has either in a pre_kyc or a post_kyc status. Failure to meet any of these conditions will cause the transaction to not be created. Card Controls The system will also check if the transaction is amount requested for authorization meets the requirements and controls in terms of spending velocity. amount requested for authorization meets the criteria defined for card controls amount requested for authorization meets the criteria defined in the user-level configurations Pre-authorization Flow If the partner is on a shared authorization model, then the payment request is forwarded to the partner at the point of authorization. Partners must then provide a decision on the transaction within an agreed-upon time frame. Otherwise, the transaction will be automatically declined. Transaction Entry Posting This event will happen when a transaction record is created corresponding to a transaction authorization object and added to the card-associated account in relation to the program funding model configured for the platform. Transaction Reversals This event will happen when a transaction that is previously authorized by the system gets rejected by the merchant. Transaction rejection can be due to a variety of reasons, such as in-store refunds, order cancellations, etc. The transaction will be reversed in the system, and the funds will be returned to the cardholder's account. Transaction Key Terms (Financial) Transaction Amount : The exact retail cost of the goods or services at the point of sale. This is always charged in the merchant's local currency (e.g., the cost of a coffee in Japanese Yen). Card Amount : The equivalent base cost of that purchase converted into the cardholder's native issuing currency (your program base currency). This is what the transaction amount looks like in your account's currency before additional markup fees are added. Transaction Fees : The additional costs applied to process the payment, especially during cross-border or foreign exchange transactions. As outlined in the Card transaction fees section, these are calculated as follows: Total Fee = Platform Fee + Partner Fee + Tax Total Amount : The final, bottom-line number deducted from the cardholder's balance will be: Total Amount = Card Amount + Transaction Fees Funding Models The high-level process remains the same across various account funding models supported in the platform. The differences between various funding models when performing a financial transaction are highlighted below: Activity Shared Balance Non-shared Balance Just-in-time (JIT) Balance check will be done on.. Account balance Card account balance Program pre-fund account Transaction posting will be done on.. Account balance Card account balance Program pre-fund account Real-time credit and debit on account balance Authorization Models The MatchMove platform allows partners to decide on how the authorization process will proceed in the program. Two(2) authorization models are available and applicable to all financial and non-financial transactions: Platform-managed - where the MatchMove platform controls the end-to-end process of card authorization Shared authorization - where the partner decides on a segment of the authorization process. The table below highlights the key differences between platform-managed authorization and shared authorization: Activity Platform-managed Authorization Shared Authorization Customer Authentication (for Card-not-present transactions) Managed by the platform Managed by the platform Customer account status check Managed by the platform Managed by the platform Card status and rules check Managed by the platform Managed by the platform Merchant blacklist check Managed by the platform Managed by the platform Transaction type eligibility check Managed by the platform Managed by the platform Fees computation and charge Managed by the platform Managed by the platform Token eligibility check Managed by the platform Managed by the platform Program Card velocity and controls check Managed by the platform Managed by the platform User-level card velocity and controls check Managed by the platform Managed by the platform Decision to approve the transaction Managed by the platform Managed by the partner Transaction records creation Managed by the platform Managed by the platform/partners to define the behavior in the partner's system Clearing and settlement Managed by the platform Managed by the platform/partners to define the behavior in the partner's system End customer notification (if needed) Managed by the partner Managed by the partner Platform-managed Authorization In platform-managed authorization, the MatchMove platform manages the entire card transaction lifecycle. This includes, but is not limited to, the posting of the transactions, adjusting based on settlements, and evaluating business rules as configured in the platform. Webhook Integration Integrating webhooks for the platform-managed authorization is not required. But partners may want to add these webhooks if they want to provide a better transaction experience to the end-users or if the program use case warrants it. Non-financial Transaction Webhooks The non-financial transactions currently supported by the system are Account Status Inquiries (ASI) transactions. Account Verification status webhook Account verification is also known as “account status inquiry” (ASI). This transaction is used to verify the status of an account, including whether it is active, inactive, or has any restrictions. It can be initiated by merchants during a transaction or by financial institutions for administrative purposes. This is primarily used by merchants who want to confirm if the cardholder’s account is active and in good standing before completing a transaction. It aims to reduce the risk of declined transactions and potential fraud for a card-not-present transaction. Webhook Event Name DescriptionDescription CARDS.ACCOUNT_VERIFICATION.STATUS A message containing the verified customer status. This is just a notification message to the partner system about an ASI request from a merchant that was responded to by MatchMove. No action or response is required when this webhook is received. Sample Account Verification Status webhook payload JSON { "entities": { "account": { "balance": { "available": { "balance": "0.00", "currency": "PHP" } }, "balance_type": "Shared Balance", "id": "368ea2999b9b6a6f129951019e89a325" }, "card": { "id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2", "type": "{{card_type_code}}" }, "transaction": { "channel": "ECOM", "created_at": "2025-11-12T22:04:51+08:00", "id": "AV_8e1176affb9c43c89636b855524b6795", "local_transaction_date": "11-12", "local_transaction_time": "", "merchant_details": { "acquiring_country_code": "840", "acquiring_institution": "015611", "institution_code": "015611", "merchant_category_code": "5969", "merchant_id": "CARD ACCPT IDC ", "merchant_name": "Agoda St. Louis USA", "terminal_id": "" }, "network": "MASTER", "reason": "OK", "transaction_amount": "0.00", "transaction_currency": "PHP", "transaction_type": "Account Verification" }, "user": { "email": "*****es8@gmail.com", "id": "b32dced37aed454ebe6379cbb39984f8", "mobile": "9064003872", "mobile_country_code": "63" } }, "entity_id": "AV_8e1176affb9c43c89636b855524b6795", "entity_type": "TRANSACTIONS", "event_timestamp": "2025-11-12T14:04:51Z", "message_id": "01cd517169214b74b9ec06f3456b51a1", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.ACCOUNT_VERIFICATION.STATUS" } Financial Transaction Webhooks Declined Transaction Notification webhooks This webhook event is triggered every time a transaction is declined by the MatchMove platform due to various reasons and errors in the authorization. Please note that MatchMove is a distributed system that interacts with various services. If the decline happens from within or is captured in the system, these decline notifications will be sent. However, for declines that are caught on interfacing services, these notifications are not guaranteed to be sent. But it is important for partners to subscribe to these webhooks to be informed of transaction declines happening in the program and to be able to handle them when they are received. The webhook has a payload that contains the details of the transaction and the reason for decline. Webhook Event Name Description OPENLOOP_DECLINED_INVALID_TRANSACTION Declined transaction message sent to API consumer OPENLOOP_DECLINED_INSUFFICIENT_CONSUMER_BALANCE Declined transaction message sent to API consumer when there is not enough consumer balance to fulfill the transaction (Only applicable for JIT programs where the amount is fulfilled from the prefund) OPENLOOP_DECLINED_INSUFFICIENT_BALANCE Declined transaction message sent to the API consumer when the cardholder's balance is not enough to fulfill the transaction. OPENLOOP_DECLINED_INSUFFICIENT_CATEGORY_BALANCE Declined transaction message sent to API consumer when the category balance is not enough to fulfill the transaction for that category-specific transaction (Only applicable if the fund categories feature is being used) OPENLOOP_DECLINED_CATEGORY_LIMIT_REACHED Declined transaction message sent to the API consumer when the limit for the transaction category is reached. (Only applicable if the fund categories feature is being used) OPENLOOP_DECLINED_CARD_BLOCKED Declined transaction message sent to the API consumer when an authorization request is received for a blocked card OPENLOOP_DECLINED_CARD_SUSPENDED Declined transaction message sent to the API consumer when an authorization request is received for a suspended card OPENLOOP_DECLINED_INVALID_TRANSACTIONTYPE Declined transaction message sent to the API consumer when a transaction type not supported by the card type is received for authorization OPENLOOP_DECLINED_UNSUPPORTED_PROGRAM_MERCHANTS Declined transaction message sent to API consumer if request comes for a merchant that is blacklisted on the program/card_type OPENLOOP_DECLINED_RISKCHECKFAILED Declined transaction message sent to the API consumer when the velocity limits configured are breached. OPENLOOP_DECLINED_ALREADY_AUTHORIZED_TRANSACTION Declined transaction message sent to the API consumer when we receive a duplicate authorization request for a transaction already authorized. The probability of this error message being triggered is very remote OPENLOOP_DECLINED_REFRENCE_NOT_FOUND Declined transaction message sent to API consumer OPENLOOP_DECLINED_AGGREGATE_LIMIT_REACHED Declined transaction message sent to API consumer when the aggregate limit for the user against the bin sponsor is reached (Only applicable if the specific program has a BIN sponsor level limit cap) OPENLOOP_DECLINED_USER_SUSPENDED Declined transaction message sent to the API consumer when the user is suspended OPENLOOP_DECLINED_USER_BLOCKED Declined transaction message sent to the API consumer when the user is blocked OPENLOOP_DECLINED_USER_NOT_FOUND Declined transaction message sent to the API consumer when the user is not found OPENLOOP_DECLINED_UNSUPPORTED_ACQUIRING_MERCHANT_COUNTRY Declined transaction message sent to the API consumer when the acquiring country is not supported by the BIN sponsor OPENLOOP_DECLINED_UNSUPPORTED_TRANSACTION_CURRENCY Declined transaction message sent to the API consumer when the transaction currency is not supported by the bin sponsor OPENLOOP_DECLINED_USERS_LIMITS_BREACHED Declined transaction message sent to the API consumer when the user's limit is breached OPENLOOP_DECLINED_PROGRAM_LIMITS_BREACHED Declined transaction message sent to the API consumer when the program's limit is breached OPENLOOP_DECLINED_PROGRAM_ATM_DOMESTIC_LIMITS_BREACHED Declined transaction message sent to API consumer when ATM_DOMESTIC is not enabled at the program level OPENLOOP_DECLINED_PROGRAM_POS_LIMITS_BREACHED Declined transaction message sent to the API consumer when POS is not enabled at the program level OPENLOOP_DECLINED_PROGRAM_POS_CONTACTLESS_LIMITS_BREACHED Declined transaction message sent to API consumer when POS_CONTACTLESS is not enabled at the program level OPENLOOP_DECLINED_PROGRAM_ECOM_LIMITS_BREACHED Declined transaction message sent to the API consumer when ECOM is not enabled at the program level OPENLOOP_DECLINED_PROGRAM_ATM_LIMITS_BREACHED Declined transaction message sent to the API consumer when the ATM is not enabled at the program level OPENLOOP_DECLINED_USERS_ATM_DOMESTIC_LIMITS_BREACHED Declined transaction message sent to API consumer when ATM_DOMESTIC is not enabled at the user level OPENLOOP_DECLINED_USERS_POS_CONTACTLESS_LIMITS_BREACHED Declined transaction message sent to API consumer when POS_CONTACTLESS is not enabled at the user level OPENLOOP_DECLINED_USERS_POS_LIMITS_BREACHED Declined transaction message sent to the API consumer when the POS is not enabled at the user level OPENLOOP_DECLINED_USERS_ECOM_LIMITS_BREACHED Declined transaction message sent to API consumer when ECOM is not enabled at user level OPENLOOP_DECLINED_CARD_PENDING_ACTIVATION Declined transaction message sent to the API consumer when an authorization request is received for a pending activation card OPENLOOP_DECLINED_OFACCHECKFAILED Declined transaction message sent to the API consumer when the user's OFAC status fails Sample Declined webhook payload JSON { "consumer": { "consumer_name": "Corp ABC", "prefund_balance": "990.000000" }, "debit_credit_indicator": "D", "payment_instrument": { "balance_type": "Shared Balance", "card_brand": "Master", "card_form_factor": "virtual", "card_type_code": "{{card_type}}", "expiry": "2026-03-31", "initial_instrument_id": "c93d916d2a533e4c0c532de2e4e159d0", "masked_number": "XXXXXXXXXXXX9447", "status": "locked", "transaction_instrument_id": "6406c2d54783d5db1f6d1c18caab6d46" }, "time_stamp": "2021-03-30 11:31:44 +0800 UTC", "total_amount": "", "total_currency": "PHP", "transaction": { "authorization": { "card_amount": "1.00", "card_currency": "PHP", "fee_amount": "0.00", "fee_currency": "PHP", "id": "P_ae7f8c0287fc445ebcd4e1fb58ed9ec1", "local_transaction_timestamp": "", "network": "Master", "network_reference_number": "100000000212", "total_amount": "", "total_currency": "PHP", "transaction_amount": "1.00", "transaction_currency": "PHP", "transaction_type": "Purchase" }, "balance": { "post_transaction": { "available": { "amount": "", "currency": "PHP" }, "categories": [{ "amount": "", "currency": "", "name": "" }] }, "pre_transaction": { "available": { "amount": "", "currency": "PHP" }, "categories": [{ "amount": "", "currency": "", "name": "" }] } }, "merchant_details": { "country_code": "SGP", "institution_code": "11255", "merchant_category_code": "742", "merchant_id": "merchant4", "name": "Merchant 4 ALB", "terminal_id": "TEST1234" }, "payment_channel": { "channel_name": "ECom", "pos_entry_mode": "" }, "transaction_fees": [ { "amount": "", "code": "", "currency": "", "name": "" } ], "transaction_message": "Card is suspended for the hash c93d916d2a533e4c0c532de2e4e159d0", "transaction_ref": "P_ae7f8c0287fc445ebcd4e1fb58ed9ec1", "transaction_rules": {}, "transaction_status": "OPENLOOP_DECLINED_CARD_SUSPENDED", "verification_details": { "address_verification_data": "" } }, "user": { "email": "test@matchmove.com", "kyc_status": "post-kyc", "mobile": "09178007959", "mobile_country_code": "63", "user_hash": "a2a6b3e61919527bd5fa4e60a3111e9f" }, "webhook_event": "OPENLOOP_DECLINED_CARD_SUSPENDED" } Successful Transaction Notifications webhook This webhook event is triggered every time a transaction is successfully authorized by the MatchMove platform. It will be vital for partners to subscribe to this webhook so they can be informed of every successful transaction happening in the program. This webhook payload is also important, as it contains details of the authorized transaction. The webhook payload will be the source of the data for the completed transaction notification that can be forwarded to the customers through various channels. Webhook Event Description OPENLOOP_POST_AUTH A successful transaction message containing the transaction details Sample Post Authorization webhook payload JSON { "consumer": { "consumer_name": "Corp ABC", "prefund_balance": "33573.040000" }, "debit_credit_indicator": "D", "payment_instrument": { "balance_type": "Shared Balance", "card_brand": "MASTER", "card_form_factor": "physical", "card_type_code": "{{card_type}}", "expiry": "2026-09-30", "initial_instrument_id": "60a220a10483b2e450c233acc49c7b48", "masked_number": "XXXXXXXXXXXX3466", "status": "active", "transaction_instrument_id": "6a00c3abc9bf6cbf1cf6e159b72a2bd1" }, "time_stamp": "2021-11-24 15:32:10 +0800 UTC", "total_amount": "62.00", "total_currency": "PHP", "transaction": { "authorization": { "card_amount": "62.00", "card_currency": "PHP", "fee_amount": "0.00", "fee_currency": "PHP", "id": "P_fb2e40750edf42548e2a1c10c57d3d92", "local_transaction_timestamp": "", "network": "MASTER", "network_reference_number": "156899249876", "total_amount": "62.00", "total_currency": "PHP", "transaction_amount": "2.00", "transaction_currency": "PHP", "transaction_type": "Purchase" }, "balance": { "post_transaction": { "available": { "amount": "21.00", "currency": "PHP" }, "categories": [ { "amount": "10.00", "currency": "PHP", "name": "DEFAULT" }, { "amount": "11.00", "currency": "PHP", "name": "TRANSFERABLE" } ] }, "pre_transaction": { "available": { "amount": "83.00", "currency": "PHP" }, "categories": [ { "amount": "10.00", "currency": "PHP", "name": "DEFAULT" }, { "amount": "73.00", "currency": "PHP", "name": "TRANSFERABLE" } ] } }, "merchant_details": { "country_code": "PHL", "institution_code": "011255", "merchant_category_code": "1740", "merchant_id": "TESTONL01", "name": "Test Account PHP", "terminal_id": "TSTPOS01" }, "payment_channel": { "channel_name": "POS", "pos_entry_mode": "MANUALLY_KEYED" }, "transaction_fees": [ { "amount": "", "code": "", "currency": "", "name": "" } ], "transaction_message": "Successful Transaction", "transaction_ref": "P_fb2e40750edf42548e2a1c10c57d3d92", "transaction_rules": {}, "transaction_status": "OK", "verification_details": { "address_verification_data": "" } }, "user": { "email": "test@matchmove.com", "kyc_status": "post-kyc", "mobile": "1139092042", "mobile_country_code": "63", "user_hash": "3e4773306c73fcd9ed3fh5e44b4a5e04" }, "webhook_event": "OPENLOOP_POST_AUTH" } Open Loop Reversal webhooks Even though transactions are already authorized, there will still be a chance that this transaction gets reversed. The reasons for reversal can be due to various reasons initiated by the cardholder, the merchant, or the network. The reversal proceedings will be fully managed by the platform, including the return of funds to the cardholder accounts. This webhook payload also contains the details of the transaction and the reason for reversal. These details can also be forwarded to the end-users through various channels. Webhook Event Name Description OPENLOOP_TRANSACTION_REVERSAL A reversal transaction message is sent to the API consumer when a transaction that has already been authorized is reversed. OPENLOOP_REVERSAL_CATEGORY_LIMIT_REACHED Reversal transaction message sent to the API consumer Sample Reversal webhook payload JSON { "consumer":{ "consumer_name":"Corp ABC", "prefund_balance":"320173.950000" }, "debit_credit_indicator":"C", "payment_instrument":{ "balance_type":"Shared Balance", "card_brand":"MASTER", "card_form_factor":"physical", "card_type_code":"{{card_type}}", "expiry":"2026-09-30", "initial_instrument_id":"2da093bf294df1a332c2ac04e3bfa0af", "masked_number":"XXXXXXXXXXXX4186", "status":"active", "transaction_instrument_id":"926ee817356a32efba24a3a1ee9b0256" }, "time_stamp":"2021-12-14 11":"31":56 +0800 UTC", "total_amount":"2.00", "total_currency":"PHP", "transaction":{ "authorization":{ "card_amount":"2.00", "card_currency":"PHP", "fee_amount":"0.00", "fee_currency":"PHP", "id":"P_ee4577d651054a2da047097fb4322faf", "local_transaction_timestamp":", "network":"MASTER", "network_reference_number":"620934262064", "total_amount":"2.00", "total_currency":"PHP", "transaction_amount":"2.00", "transaction_currency":"PHP", "transaction_type":"Purchase" }, "balance":{ "post_transaction":{ "available":{ "amount":"963.50", "currency":"PHP" }, "categories":[ { "amount":"952.00", "currency":"PHP", "name":"DEFAULT" }, { "amount":"0.00", "currency":"PHP", "name":"NON-TRANSFERABLE" }, { "amount":"11.50", "currency":"PHP", "name":"CASHBACK" } ] }, "pre_transaction":{ "available":{ "amount":"961.50", "currency":"PHP" }, "categories":[ { "amount":"950.00", "currency":"PHP", "name":"DEFAULT" }, { "amount":"0.00", "currency":"PHP", "name":"NON-TRANSFERABLE" }, { "amount":"11.50", "currency":"PHP", "name":"CASHBACK" } ] } }, "merchant_details":{ "country_code":"PHL", "institution_code":"011255", "merchant_category_code":"1740", "merchant_id":"TESTECOM01", "name":"Test ECOM PHP", "terminal_id":"TSTECOM1" }, "payment_channel":{ "channel_name":"ECOM", "pos_entry_mode":"MANUALLY_KEYED_ECOM" }, "transaction_fees":[ { "amount":", "code":", "currency":", "name":" } ], "transaction_message":"SUCCESS", "transaction_ref":"P_ee4577d651054a2da047097fb4322faf", "transaction_rules":{ }, "transaction_status":"OK", "verification_details":{ "address_verification_data":" } }, "user":{ "email":"test@matchmove.com", "kyc_status":"post-kyc", "mobile":"9190743150", "mobile_country_code":"63", "user_hash":"aee37c950cb7173b6d394f605b03eceb" }, "webhook_event":"OPENLOOP_TRANSACTION_REVERSAL" } Shared Authorization In shared authorization, partners can choose to participate in the card transaction authorization process, where they provide an authorization decision. This decision may be based on the result of custom business logic. Providing this decision can override the default platform outcome for the specific transaction. The shared authorization can be enabled by subscribing to the pre-authorization webhook. Subscribing to this webhook is a contract that gives partners the responsibility to respond with an “authorize or not authorize” decision within an allotted time frame. Failure to respond to this webhook will automatically decline the transaction request. Timeout limit for pre-auth webhook For compliance with the card network SLA, the partners are expected to respond to the webhook before the timeout limit of 3 seconds . Failure to respond to this webhook will automatically decline the transaction request. Non-financial Transactions Webhooks Account status authorization pre-auth webhook This webhook is triggered every time an account verification request is received. Subscribed partners can then opt to allow or decline the request. Webhook Event Name Description CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION A pre-auth webhook message is sent to a subscribed partner who wants to approve/decline an account verification request. This webhook requires an appropriate response from the partner to allow the ASI request to be completed. Sample Account Verification webhook payload JSON { "entities": { "account": { "balance": { "available": { "balance": "0.00", "currency": "PHP" } }, "balance_type": "Shared Balance", "id": "368ea2999b9b6a6f129951019e89a325" }, "card": { "id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2", "type": "{{card_type}}" }, "transaction": { "channel": "ECOM", "created_at": "2025-11-12T22:04:51+08:00", "id": "AV_8e1176affb9c43c89636b855524b6795", "local_transaction_date": "11-12", "local_transaction_time": "", "merchant_details": { "acquiring_country_code": "840", "acquiring_institution": "015611", "institution_code": "015611", "merchant_category_code": "5969", "merchant_id": "CARD ACCPT IDC ", "merchant_name": "Agoda St. Louis USA", "terminal_id": "" }, "network": "MASTER", "transaction_amount": "0.00", "transaction_currency": "PHP", "transaction_type": "Account Verification" }, "user": { "email": "****@gmail.com", "id": "b32dced37aed454ebe6379cbb39984f8", "mobile": "9064003872", "mobile_country_code": "63" } }, "entity_id": "AV_8e1176affb9c43c89636b855524b6795", "entity_type": "TRANSACTIONS", "event_timestamp": "2025-11-12T14:04:51Z", "message_id": "2d744b1881c14bac8ecc15a77a13340a", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION" } Partners can allow the verification request to proceed by responding with: JSON { "action":"APPROVE", } Partners can allow the verification request to proceed and forward an additional description to the approval by responding with: JSON { "action":"APPROVE", "description":"The action was approved by the system or any other message" } Partners also can choose to reject the verification request and stop it from proceeding by responding with: JSON { "action":"DECLINE", "description":"System decline for reason code PARTNER-001 or any other message" } Aside from the normal verification requests, partners will also need to handle verification request statuses changes with the specific reason codes. Webhook Event Name Description CARDS.ACCOUNT_VERIFICATION.STATUS A message containing the verified customer status. This is just a notification message to the partner system about an ASI request from a merchant that has been responded to by the Partner. No action or response is required when this webhook is received. Sample Account Verification Status webhook payload JSON { "entities": { "account": { "balance": { "available": { "balance": "0.00", "currency": "PHP" } }, "balance_type": "Shared Balance", "id": "368ea2999b9b6a6f129951019e89a325" }, "card": { "id": "7ebe42c5a42a91c6a3a9c86ee5b78fa2", "type": "{{card_type_code}}" }, "transaction": { "channel": "ECOM", "created_at": "2025-11-12T22:04:51+08:00", "id": "AV_8e1176affb9c43c89636b855524b6795", "local_transaction_date": "11-12", "local_transaction_time": "", "merchant_details": { "acquiring_country_code": "840", "acquiring_institution": "015611", "institution_code": "015611", "merchant_category_code": "5969", "merchant_id": "CARD ACCPT IDC ", "merchant_name": "Agoda St. Louis USA", "terminal_id": "" }, "network": "MASTER", "reason": "OK", "transaction_amount": "0.00", "transaction_currency": "PHP", "transaction_type": "Account Verification" }, "user": { "email": "*****es8@gmail.com", "id": "b32dced37aed454ebe6379cbb39984f8", "mobile": "9064003872", "mobile_country_code": "63" } }, "entity_id": "AV_8e1176affb9c43c89636b855524b6795", "entity_type": "TRANSACTIONS", "event_timestamp": "2025-11-12T14:04:51Z", "message_id": "01cd517169214b74b9ec06f3456b51a1", "program_code": "{{program_code}}", "version": "v2", "webhook_event": "CARDS.ACCOUNT_VERIFICATION.STATUS" } Status Description DECLINED_BY_PARTNER Authorization request either declined by the Partner or an invalid response received from Partner TIMEOUT_BY_PARTNER Declined transaction message sent to API consumer due to time out or no response received from Partner within SLA CLIENT_SERVER_ERROR Declined transaction due to connectivity issues between Client server and MatchMove platform typically caused by network problems or server unavailability Financial Transaction Webhooks Pre-auth webhooks This webhook is triggered every time a transaction authorization request is received and the partner is subscribed to the webhook. The category for this webhook event is Pre Auth Webhook Event Name Description OPENLOOP_PRE_AUTH Pre-auth message sent to a subscribed API consumer when a transaction authorization request is received by the system Sample Pre-authorization webhook payload JSON { "consumer": { "consumer_name": "Corp ABC", "prefund_balance": "1000000.00" }, "debit_credit_indicator": "D", "payment_instrument": { "balance_type": "Shared Balance", "card_brand": "MASTER", "card_form_factor": "physical", "card_sequence_number": "000", "card_type_code": "{{card_type}}", "expiry": "2031-05-31", "initial_instrument_id": "57165d4120a3b6d019d4ef2eadffd08b", "masked_number": "XXXXXXXXXXXX7486", "status": "active", "transaction_instrument_id": "3aee99f0ecc09ef58be29a8464960438" }, "time_stamp": "2026-06-02 14:17:46 +0800 UTC", "total_amount": "155.00", "total_currency": "PHP", "transaction": { "additional_fee_details": null, "authentication": { "3ds_version": "", "authentication_ucaf_value": "", "ecom_authentication_indicator": "" }, "authorization": { "card_amount": "155.00", "card_currency": "PHP", "fee_amount": "0.00", "fee_currency": "PHP", "id": "P_b21a09ad676548888e782f075bed0fe6", "local_transaction_timestamp": "", "network": "MASTER", "network_reference_number": "713638931604", "pos_transaction_type": "0", "total_amount": "155.00", "total_currency": "PHP", "transaction_amount": "155.00", "transaction_currency": "PHP", "transaction_type": "PURCHASE" }, "balance": { "post_transaction": { "available": { "amount": "", "currency": "PHP" }, "categories": [ { "amount": "", "currency": "", "name": "" } ] }, "pre_transaction": { "available": { "amount": "0.00", "currency": "PHP" }, "categories": [ { "amount": "0.00", "currency": "PHP", "name": "DEFAULT" } ] } }, "merchant_details": { "country_code": "PHL", "country_subdivision_code": "608", "institution_code": "005913", "merchant_category_code": "5499", "merchant_id": "000004300005002", "name": "RESTO MANILA PHL", "terminal_id": "30051354" }, "payment_channel": { "channel_name": "POS", "pos_entry_mode": "CONTACTLESS_CHIP", "pos_pin_entry_mode": "1" }, "pos_data": { "card_capture_capability": "1", "card_presence": "0", "cardholder_presence": "0", "cat_level": "0", "pos_country_code": "PHL", "pos_postal_code": "1002 ", "terminal_attendance": "0", "terminal_input_capability": "3", "terminal_location": "0", "transaction_security": "0", "transaction_status": "0" }, "risk_details": { "fraud_scoring_data": [ { "key": "FRAUD_SCORE", "value": "025" }, { "key": "FRAUD_REASON_CODE", "value": "57" }, { "key": "MODEL_SCORE", "value": "025" }, { "key": "MODEL_REASON_CODE", "value": "57" } ], "on_behalf_services": [ { "on_behalf_result_1": "C", "on_behalf_result_2": " ", "on_behalf_service": "18" } ], "security_services_data": [ { "indicator": "AQV", "insight": "000" }, { "indicator": "AQS", "insight": "000" }, { "indicator": "AQF", "insight": "000" } ] }, "transaction_fees": [ { "amount": "", "code": "", "currency": "", "name": "" } ], "transaction_message": "", "transaction_ref": "P_b21a09ad676548888e782f075bed0fe6", "transaction_rules": {}, "transaction_status": "", "verification_details": { "address_verification_data": "" } }, "user": { "email": "test@matchmove.com", "kyc_status": "post-kyc", "mobile": "9122751494", "mobile_country_code": "63", "user_hash": "33fe978ff6334c718754f1fb3036a0fd" }, "webhook_event": "OPENLOOP_PRE_AUTH" } Authorize the transaction Partners can approve the transaction authorization request by responding with: JSON { "status":"OK", "description":"Authorization OK" } Partners can decline the transaction authorization request by responding with: JSON { "status":"UNAUTHORIZED", "description":"Unauthorized" } Address and handle failures If the partner were unable to respond to the stipulated response SLA, the transaction will be automatically declined. However, there will be a chance that the partner system might have already authorized the transaction. But the webhook response were not able to make it in time before the response SLA expired. To help ensure the real-time correction of records in these types of scenarios, the MatchMove platform will trigger an auto-reversal advisory message informing of the failure/decline of the transaction with the relevant reasons. Webhook Event Name Description OPENLOOP_TRANSACTION_REVERSAL This is the advisory message sent when the Pre-Auth webhook was sent, but the system is unable to receive the response message from the partner. This results in an automatic decline of the transaction authorization request. Partners receiving this reversal advisory message are encouraged to do real-time corrective actions (if needed) on their ledger or system, which has been previously authorized on their side. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Transaction overview Card payment fees Simulate card transactions Transaction settlements Manage card security • [Card transaction fees](https://developer.matchmove.com/matchmove-banking-operating-system/card-payments/card-payment-fees.md): Learn about the fee structure associated with processing card payments on our platform. This guide provides a transparent overview of the different types of fees that may apply to various card transactions. Bringing Transparency and Automation to Card Payment Fees As of Oct 2025, MatchMove has upgraded its Card Authorization Platform to introduce a robust, transparent, and automated approach to transaction fee management. This update resolves previous limitations regarding visibility and manual processing, ensuring that partners have a clear breakdown of costs and earnings. This guide outlines the changes to the fee model, the new automation capabilities, and the technical implementation details for developers. Why the Change? Previously, the platform utilized a net transaction fee computation. While functional, this "black box" approach created operational inefficiencies: No Breakdown: Fees were lumped together, making it impossible to distinguish between network costs, platform fees, and partner markups. Manual Management: Any change in network fees (e.g., by Mastercard) required manual recalculation for every single card type and program. Limited Visibility: Partners could not automatically extract or verify their specific markup portions. The New Standard The revamped model introduces granular fee attribution . Moving forward, every transaction—whether a cross-border payment or an ATM withdrawal—will feature a transparent breakdown during authorization and settlement. The New Fee Structure The new system moves away from a single "Net Fee" to a component-based formula. Total Fee = Platform Fee + Partner Fee + Tax What is the Platform Fee? The Platform Fee is the baseline fee component charged by MatchMove to cover the essential underlying costs of processing card transactions on the network. It covers key operational costs, including network scheme fees (such as Mastercard fees), BIN sponsorship fees, transaction authorization infrastructure, and platform processing charges. The Platform Fee forms the core processing cost of a transaction (such as cross-border payments, ATM cash withdrawals, or currency exchanges) before any custom partner markup is added. What is the Partner Fee markup? The Partner Fee markup is an additional, custom fee component configured and earned by you (the Partner) on card transactions to generate margin and earnings. While the Platform Fee covers underlying infrastructure and processing costs (such as Mastercard network fees and BIN sponsorship), the Partner Fee represents your custom commercial markup. It is added to the transaction fee structure to generate revenue for your program. The Partner Fee markup is added on top of the base transaction costs and forms part of the overall fee charged during transaction processing (such as cross-border payments, ATM cash withdrawals, or currency exchanges). Definitions Tax: Applicable taxes on the computed total fee. Fee Types: Both platform and partner fees can consist of Fixed (flat rate) and Variable (percentage) components. Important Note: There is no change to the total fees collected . Partners will earn the same amount as before; the only change is that the breakdown of these fees is now visible and structured. Key Features & Benefits 1. Automated Fee Hierarchies The platform now supports fee hierarchies (Region, Network, Partner, Card Type). This eliminates manual updates. Scenario: If Mastercard increases transaction fees by 0.2% for the Singapore region. Action: The system automatically applies this change across all Singapore programs instantly. New Programs: When a new card program is launched, it automatically inherits the relevant platform fee components based on its region and network. 2. Rule-Based Configuration Fees can now be defined dynamically based on transaction attributes, including: Transaction Currency Channel (e.g., ATM, POS, E-com) Issuing Country Merchant Location 3. Enhanced Reporting Partner earnings and fee components are automatically extracted and pushed to Adminnet 2.0 reports , APIs, and webhooks. Fee Configuration: Platform and Partner Fees Both the Platform Fee and the Partner Fee Markup are established at the program configuration level . Here is a breakdown of how each fee is set up, managed, and modified. 1. Platform Fee Configuration The Platform Fee covers the baseline costs of processing card transactions (e.g., network scheme fees, BIN sponsorship, platform infrastructure). Set by MatchMove: This fee is strictly defined and configured by MatchMove in the backend system. Automated Inheritance: It is automatically applied to your program based on the agreed commercial terms, region, network (e.g., Mastercard), and card type. Partners do not need to manually configure this fee. 2. Partner Fee Configuration The Partner Fee is your custom commercial markup. It is entirely optional and provides a way to generate revenue from card transactions. Partner-Defined: You decide the amount (whether a fixed rate, a percentage, or both) you want to charge as a markup on top of the base transaction costs. Card Type Specific: When setting this markup, you must specify the exact card type code(s) ( card_type_code ) to which the partner fee should be applied. Default Value: If you choose not to add a markup, the Partner Fee is automatically defaulted to 0 . Setting Up and Modifying the Partner Fee Because the Partner Fee directly impacts the final transaction amount charged to your end-users, it cannot be configured or modified directly in the dashboard or via the API. All additions, modifications, or removals of a Partner Fee require a formal Change Request Ticket submitted to the MatchMove Support Team. During Implementation (Pre-Launch) Before your program goes live, the MatchMove Implementation team will work with you to finalize your program configurations. As part of this process, the team will explicitly ask if you require a Partner Fee markup to be configured before you formally exit the User Acceptance Testing (UAT) phase. Once you confirm your desired fee structure and the applicable card type codes ( card_type_code ), a Change Request Ticket must be raised to implement it. Post-Launch (Making Changes) If you decide to add, remove, or modify your Partner Fee after your program is live, the process remains exactly the same. You must: Raise a formal Change Request Ticket . Submit the ticket to the MatchMove Support Team , clearly specifying the new fixed and/or variable fee structure, along with the specific card type code(s) where the fee should be charged. The Support Team will configure the updated markup on your behalf. Technical Implementation Rounding Logic To ensure accuracy, fee components are rounded individually to ISO-defined currency decimals before they are summed. Example Calculation: Scenario: A cross-border transaction of SGD 10.10 . Rates: Platform Fee (1.75%), Partner Fee (1.00%). ISO Decimal: SGD uses 2 decimal places. Platform Fee = 1.75% x 10.10 = 0.17675 —> SGD 0.18 Partner Fee = 1.00 x 10.10 = 0.105 —> SGD 0.11 Total Fee = 0.18 + 0.11 = SGD 0.29 Note: Minor rounding differences may occur between the "Total Fee" and the sum of unrounded components. Webhook Updates (For Developers) A new object additional_fee_details , has been added to Authorization, Decline, and Reversal webhooks. Details for the following transaction fees will appear in the additional fee details when the fee code applies to the transaction: Transaction Fees Description ATM Balance Inquiry Fee A fee charged when performing a balance check on the card through an Automated Teller Machine (ATM), and fees may vary depending on the bank ATM used. ATM Cash Withdrawal Fee A fee charged when performing a cash withdrawal through an Automated Teller Machine (ATM), and fees may vary depending on the bank ATM used. Cross Border Fee A fee charged when a payment is made to the merchant who is located/registered in another country using the same currency in which the card was issued. Cross Currency Fee A fee charged when a payment is made to the merchant who is located/registered in the same country where the card is issued, using another currency different from which the card was issued. Cross Border Cross Currency Fee A surcharge applied when you make a transaction that triggers two specific conditions simultaneously: the merchant is located in a different country (cross-border) and the payment requires a foreign exchange conversion (cross-currency). This will be charged using the same currency in which the card was issued. Issuer Forex Fee A fee charged when a payment is made to the merchant who is located/registered in another country using the other country's currency different from which the card was issued. Issuer Surcharge When the issuer charges a surcharge fee for the particular kind of purchase transaction, it is marked as an issuer surcharge Card Authorization webhook payload preview: JSON "additional_fee_details": [ { "cross_border_fee": { "platform_fee": { "fixed_fee": "0.01", "variable_fee": "0.02", "sub_total": "0.03" }, "partner_fee": { "fixed_fee": "0.03", "variable_fee": "0.04", "sub_total": "0.07" } } } ] Additional Fee Details explained: Using the detail in the sample webhook payload above, we have the following transaction fee code: cross_border_fee Fee Description platform_fee.fixed_fee = 0.1 Platform-levied fixed component fee, in the base currency set in the program platform_fee.variable_fee = 0.2 Platform-levied variable component fee, in the base currency set in the program platform_fee.sub_total = 0.3 Platform-levied fee total, from fixed and variable component, in the base currency set in the program partner_fee.fixed_fee = 0.3 Partner-charged fixed component markup fee, in the base currency set in the program partner_fee.variable_fee = 0.4 Partner-charged variable component markup fee, in the base currency set in the program partner_fee.sub_total = 0.7 Platform-charged markup fee total, from fixed and variable component, in the base currency set in the program Applying the formula: Total Fee = Platform Fee + Partner Fee + Tax The total cross-border fee will be calculated as: cross_border_fee (1.0) = platform_fee.sub_total (0.3) + partner_fee.sub_total (0.7) If the base currency of the program is set to USD, then cross-border card transactions will be charged 1.0 USD for transaction fees. Scope and Exclusions: Scope: The card payment fee structure discussed above is only applicable to Mastercard transactions. Exclusions: For the Philippine region, BancNet transactions remain unaffected (no additional platform/partner fees are permitted beyond scheme fees). Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Transaction overview Simulate card transactions Transaction authorizations Transaction settlements Manage card security • [Transaction settlements](https://developer.matchmove.com/matchmove-banking-operating-system/card-payments/transaction-settlements.md): Learn how funds from an authorized card transaction are settled and reflected in a user's account. This guide explains the settlement process and how to interpret the corresponding status updates you receive. Clearing The MatchMove platform receives clearing files from various networks at stipulated timeframes. These files are validated and parsed individually for each respective network. Please note that even though a cardholder might be associated with a single scheme, the transactions for the same card could be processed by different networks. This depends on transaction attributes like domestic vs. cross-border transactions. Thus, customer transactions may be included in different network clearing files. Reconciliation After receiving the clearing files from the network, the MatchMove platform compares the clearing message against the authorized transactions in the system. Possible Outcomes of the Reconciliation Process The clearing record matches an authorized transaction. The clearing record differs in amount from the authorized transaction amount. A clearing record is received, which is a credit issued by the merchant to the cardholder. A clearing record is received, which requires a debit to be issued to the cardholder. A clearing record requires a reversal of the original transaction to the cardholder. No clearing record is received for an authorized transaction by the network beyond the stipulated maximum timeframe imposed by the scheme for the merchant to raise a settlement for a transaction. Some processes may be flagged into an exception queue requiring intervention by the MatchMove operations team. After evaluation, these records are processed again as a separate batch, each falling under one of the above scenarios. Posting Once the clearing records have been reconciled with authorized transactions, the MatchMove system automatically adjusts the cardholder account/wallet balances and program balances (when required) to accommodate the update of transaction values/records. Depending on which bucket a clearing record is placed, as part of the reconciliation process, the MatchMove platform performs actions listed in the table below: Reconciliation Bucket Action Impact on Cardholder Settle The original authorization record is marked as settled The transaction record is reflected as settled. No Auth A new debit transaction record is created. - New transaction record created - If applicable, a new fee record(s) will be created. - Balance reduced by the amount of the transaction + fees (if applicable) Issue Voucher A new transaction record is created. New credit transaction record created - If applicable, a new fee record(s) with a debit entry will be created. - Balance will be increased by the amount of the transaction and fees (if applicable). Reverse Original authorization record marked as reversed - The original transaction record is marked as reversed. - Balance increased with the original transaction amount Adjust Original authorization record marked as reversed and tagged as a mismatch reversal. A new debit record was created with the type as Mismatch Debit, with the final amount. - The original transaction record was identified as a mismatch reversal and reversed. - User balance increased by the amount - New transaction record tagged as Mismatch Debit and balance reduced by the final amount to be charged (this may be higher or lower than the original amount) - User balance decreases by the amount of mismatch debit transaction and associated fees. Settlement Webhooks MatchMove's platform facilitates seamless end-to-end operations for partners by triggering webhooks that notify them of the completion of a clearing batch after every batch execution. Partners can then take appropriate actions within their systems based on these webhook messages. Below are the suggested actions recommended for partners depending on their program construct: Webhook Event Description Standard Program Standard Program with Pre Auth JIT Programs SETTLEMENT_BATCH_SUCCESS The event is triggered when a batch of transactions is posted in the settle bucket and completes reconciliation with a generated settlement report. No Action No Action Update the internal system to mark the transaction as completed. AUTHRELEASE_BATCH_SUCCESS Triggered when a batch of transactions is posted in the reverse bucket completes reconciliation with a generated settlement report - Inform user via SMS / Email / In-App notification - Update the internal system to mark the transaction as reversed - Inform user via SMS / Email / In-App notification - Update the internal system to mark the transaction as reversed and return associated funds/limits to the cardholder. - Inform user via SMS / Email / In-App notification CREDITVOUCHER_BATCH_SUCCESS Triggered when a batch of transactions is posted in the issue voucher bucket completes reconciliation with a generated settlement report - Inform user via SMS / Email / In-App notification - Update the internal system to record new credit type transactions - Inform user via SMS / Email / In-App notification - Update the internal system to create a transaction of type credit and credit-associated funds/limits to the cardholder. - Inform user via SMS / Email / In-App notification NOAUTH_BATCH_SUCCESS Triggered when a batch of transactions is posted in the no auth bucket completes reconciliation with a generated settlement report - Inform user via SMS / Email / In-App notification - Update the internal system to record a new debit-type transaction. - Inform user via SMS / Email / In-App notification - Update the internal system to create a transaction of type debit and debit associated funds/limits to the cardholder. - Inform user via SMS / Email / In-App notification MISMATCH_BATCH_SUCCESS Triggered when a batch of transactions is posted in the adjust bucket completes reconciliation with a generated settlement report - Inform user via SMS / Email / In-App notification - Update the internal system to update the final value of the transaction by posting a debit/credit entry as per the final amount. - Inform user via SMS / Email / In-App notification - Update the internal system to create a transaction of type debit/credit and debit/credit associated funds/limits to the cardholder. - Inform user via SMS / Email / In-App notification Sample settlement webhook payload JSON { "webhook_event": "SETTLEMENT_BATCH_SUCCESS", "program_code": "{{program_code}}", "message_id": "a9a6ae34-0399-428f-9d26-4183c1f26227", "timestamp": "2020-09-08 03:37:23+00:00", "message": { "action": "settlement", "batch_id": "MC_SettledTxns_20200908", "total_records": "5", "successful_records": "5", "failed_records": "0", "download_link": "https://aaa.s3.amazonaws.com/SGMC_SettlementTxns_yyyymmdd_etc.csv&Signature=sss&Expires=1585008320&AWSETC=xyzbgggetc" } } Settlement Reports To enable partners to programmatically process and ingest the outputs of the clearing and reconciliation process, each webhook triggered for a batch includes a linked file containing processed records. The data embedded in these settlement reports follows the structure as illustrated in the table below: Header Description Data Type Max Length process_batch_id Unique reference for the batch Note: If the file contains a batch ID already processed, you can disregard the entire file. string 150 user_hash_id Unique ID for the user who initiated the transaction in the system string 100 wallet_hash_id Unique ID for the wallet used to initiate the transaction in the system string 100 card_hash_id Unique ID for the card used for the transaction in the system string 100 transaction_ref Unique reference for the transaction in the MatchMove system string 100 retrieval_reference_number An optional transaction identifier, if available from the network string 100 acquirer_ref_number Option acquirer reference number, if available from the network string 100 transaction_type Transaction type for the transaction string 100 authorization_transaction_amount The transaction amount as charged during authorization string 100 authorization_transaction_currency The currency in which the original transaction was authorized string 100 authorization_card_amount The equivalent converted amount charged to the card as part of the authorization in the card's currency string 100 authorization_card_currency Charge currency. string 100 authorization_fee_amount Total fee charged as part of the authorization stage, if applicable string 100 authorization_fee_currency Charge currency. string 100 authorization_total_transaction_amount Total amount, including the fees charged to the cardholder as part of the authorization stage string 100 authorization_total_transaction_currency Charge currency. string 100 settled_transaction_amount The transaction amount charged by the merchant as part of the settlement string 100 settled_transaction_currency The currency in which the original transaction settlement was raised by the merchant string 100 settled_card_amount The equivalent converted amount charged to the card as part of the settlement by the merchant in the card's currency string 100 settled_card_currency Charge currency. string 100 settled_fee_amount Total fee charged as part of the settlement stage, if applicable string 100 settled_fee_currency Charge currency. string 100 settled_total_transaction_amount The total amount, including the fees charged to the cardholder, is eventually as part of the settlement process. string 100 settled_total_transaction_currency Charge currency. string 100 debit_credit_indicator Debit / Credit Indicator for the original transaction string 100 merchant_name Name of the merchant who initiated the transaction string 100 McC The merchant category code of the merchant who initiated the transaction string 100 mid Merchant ID of the merchant who initiated the transaction string 100 tid Terminal ID of the terminal on which the transaction was initiated string 100 transaction_status Records successfully processed will be marked as success. Note: When successful transactions fail to be processed for any reason, they are retried and posted independently as part of a separate batch. Eventually, all records would be posted to the cardholder. string 100 date_added Timestamp of the original transaction authorization. Note: Since for actions with no auth and issue voucher, there is no original transaction, this date would be the same as the date it was posted/updated to the cardholder as part of the settlement and reconciliation process. string Format: yyyy-mm-dd H:i:s date_updated Timestamp when the transaction was posted/updated to the cardholder as part of the settlement and reconciliation process string Format: yyyy-mm-dd H:i:s Settlement File Naming Convention Every combination of reconciliation process, along with the outcome of reconciliation results, in a single file output, which the partner can consume for fulfilling their downstream process. The filename is a concatenation of the following values: Reconciliation_bucket (Possible values: reverse , no_auth , adjust , issue_voucher ) Program code File generation timestamp (format: YYYY-MM-DD HH:MM:SS ) Internal process batch ID (Format: Alphanumeric string 512 chars) File Examples : Action Description settle (Settlements) settle_sgmmdemo_2024-06-10 06:00:41_XYASDSDASD324234432.csv settle_sgmmdemo_2024-06-10 00:39:08_AASD3SDASD324234432.csv reverse (Auth Release) reverse_sgmmdemo_2024-06-10 00:20:29_AASD33243D324234432.csv reverse_sgmmdemo_posting_2024-06-10 00:20:29_AASD33243D324234432.csv no_auth (No Authorization) no_auth_sgmmdemo_2024-06-10 00:19:52_ASDEREW42342342_432423.csv no_auth_sgmmdemo_posting_2024-06-10 00:19:52_ASDEREW42342342_432423.csv adjust (Mismatch Adjustment) no_auth_sgmmdemo_2024-06-10 00:19:52_ASDEREW42342342_432423.csv no_auth_sgmmdemo_posting_2024-06-10 00:19:52_ASDEREW42342342_432423.csv issue_voucher (Credit Voucher) issue_voucher_sgmmdemo_2024-06-10 00:21:38_PARFASD23432#MM-OPS_32434.csv issue_voucher_sgmmdemo_posting_2024-06-10 00:21:38__PARFASD23432#MM-OPS_32434.csv This naming convention ensures that each file is easily identifiable by its action type, program code, generation date, and associated batch ID. It is meant to facilitate the efficient location and utilization of the necessary reports by integrators. Settlement Posting Report When adjustments that require additional transactions are made as part of settlements, these are included in the Settlement Postings Report. This report features only a subset of the fields found in the standard report. Its focus is on highlighting the additional transactions performed as necessary for the completion of the match-off process. It's important to note that retrieval and parsing of this report are optional and dependent on the program's specific needs. Field Description Data Type Max Length process_batch_id A batch identifier. Multiple transactions are included in a single batch to describe their contents at a glance. String 150 user_hash_id The user’s MM identifier String 100 wallet_hash_id The user’s wallet account identifier String 100 card_hash_id The card’s unique identifier String 100 transaction_ref The transaction’s unique identifier String 100 retrieval_reference_number The unique transaction identifier created by the acquirer String 100 acquirer_ref_number Unique transaction identifier of the fund exchange between the merchant and cardholder banks String 100 transaction_type The subject transaction’s transaction type String 100 posted_transaction_currency Currency of the total settled amount String 100 posted_total_transaction_amount Total settled amount String 100 debit_credit_indicator Indicates whether the transaction is a debit or a credit String 100 merchant_name The merchant’s name can be found on billing statements. String 100 transaction_status The final result of the transaction’s settlement processing String 100 date_added Date of authorization transaction String Format: yyyy-mm-dd H:i:s date_updated Date of the settlement transaction String Format: yyyy-mm-dd H:i:s Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Transaction overview Card payment fees Simulate card transactions Transaction authorizations Manage card security • [Simulate card transactions](https://developer.matchmove.com/matchmove-banking-operating-system/simulate-card-transactions.md): Learn how to simulate various card payment scenarios in our staging environment. This guide covers how to test different outcomes, such as approved transactions and reversals. Note: The set of endpoints below is only available and enabled in the staging environment. These endpoints will allow you to simulate card authorizations and reversals before the live environment. Prerequisites For programs with standard accounts, the user account should be enough balance to cover the simulated transaction amounts. For programs with mJIT accounts, the must meet the following requirements: a. The Pre Authorization webhook for Shared Authorization must be subscribed. b. The Pre Authorization partner response must be sent within the alloted time. c. The program prefund must have enough balance to cover the intended simulated transaction amounts. Debugging For simulation failures, you can go to the AdminNet dashboard > Cards > Purchase History. Then on Filters > select Status > where status is Failed to reveal your simulated transaction and its reason for failure. Figure: Adminnet dashboard - Card Transactions Simulate Card Authorizations The following mock payload is required to initiate a card transaction authorization request. Partners will need to follow the payload field definitions stated below. Refer to the simulated card authorization API call on the right. Payload Definition Field Description network Network defines the network for transaction, e.g. MASTER, VISA channel Channel defines the channel for transaction, e.g. POS, ECOM, ATM card_hash_id Card ID of the card to be used for transaction card_currency_code Currency code of the card (Use ISO4217 value of currency), e.g. SGD, USD, PHP card_amount Card transaction amount in local currency transaction_currency_code Currency code of the transaction (use ISO4217 value of currency), e.g. SGD, USD, PHP transaction_amount Transaction amount terminal_id Terminal ID of the POS used in the transaction. (should be 8 characters in length) merchant_id Merchant ID of the merchant in the transaction merchant_name Merchant name merchant_category_code Merchant category code (MCC) pos_entry_mode_code POS Entry Mode Code allowed values: MANUALLY_KEYED MAGSTRIPE_READ_GENERAL_TRACK2 MAGSTRIPE_READ_GENERAL_TRACK1 CONTACTLESS_CHIP MANUALLY_KEYED_ECOM MAGSTRIPE_FULL_READ CONTACTLESS_MAGSTRIPE_ORIGIN card_number First 10-digit of card number or PAN to be used for transaction product_code The partner program code assigned to the program, e.g. sgmmcard acquiring_country_code Acquiring country code in ISO3166_alpha3 country code value, e.g. SGP, PHP transaction_type [Optional] Transaction type : Only required for simulation of Account Status Inquiry (ASI) transactions. When the transaction type is passed as account_verification , the card amount & transaction amount will be ignored. Allowed value: account_verification risk_details [Optional] Risk details: Contains additional risk-related data elements received from the network to assist in transaction risk assessment and fraud decisioning. Security services data ( security_services_data ): List of security service indicators and their corresponding insights. Eg - (indicator: AQS, insight: 409) Fraud scoring data ( fraud_scoring_data ): List of fraud scoring key-value pairs for risk assessment. Eg - (key: FRAUD_SCORE, value: 075) pos_data [Optional] POS Data: Contains DE 61 POS data elements. All sub-fields are optional strings. POS data fields (DE 61 POS data elements) terminal_attendance: POS Terminal Attendance. Values: 0, 1, 2 terminal_location: POS Terminal Location. Values: 0, 1, 2, 3, 4, 8 cardholder_presence: POS Cardholder Presence. Values: 0, 1, 2, 3, 4, 5 card_presence: POS Card Presence. Values: 0, 1 card_capture_capability: POS Card Capture Capabilities. Values: 0, 1 transaction_status: POS Transaction Status. Values: 0, 1, 2, 3, 4, 5, 6, 8, 9 transaction_security: POS Transaction Security. Values: 0, 1, 2 cat_level: Cardholder-Activated Terminal Level. Values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 terminal_input_capability: POS Card Data Terminal Input Capability Indicator. Values: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 pos_country_code: 3-character ISO 3166 alpha country code of the POS location. pos_postal_code: Acceptor Postal Code. additional_transaction_data [Optional] Additional transaction data containing DE 48 sub-element 22. All sub-fields are optional strings. Multi-purpose merchant indicator (DE 48 sub-element 22) low_risk_merchant_indicator: Low risk merchant indicator. single_tap_indicator: Single tap indicator. transaction_initiator: Transaction initiator. Digital transaction data cardholder_phone_number: Cardholder phone number. cardholder_shipping_address: Cardholder shipping address. authentication [Optional] Authentication data containing DE 48 sub-element 42. All sub-fields are optional strings. Authentication (DE 48 sub-element 42) ecom_authentication_indicator: Ecom authentication indicator. Simulate an authorized transaction Call the Simulate Card Transaction Authorization s (POST /v1/card-transactions/authorize/test) passing the required simulation parameters. Card transaction simulation only If you only intend to simulate a basic card authorization transaction without evaluating risk data, you can drop the OPTIONAL request parameters, such as transaction_type risk_details pos_data additional_transaction_data authentication These optional fields are mainly used to simulate the evaluation of additional transaction risk data before allowing authorization. See Assisted card transaction risk management section to learn more. Simulate Card Authorizations request (authorized) CURL curl --location --request POST 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/card-transactions/authorize/test' \ --header 'Content-Type: application/json' \ --data-raw '{ "network": "master", "channel": "pos", "card_hash_id":"{{card_id}}", "card_currency_code": "SGD", "card_amount": "50", "transaction_currency_code": "SGD", "transaction_amount": "50", "terminal_id": "RD105401", "merchant_id": "SLIJKOFGKEMGGCQ", "merchant_name": "Test Account SGP", "merchant_category_code": "0780", "pos_entry_mode_code": "MANUALLY_KEYED", "card_number": "5555455521", "product_code": "{{program_code}}", "acquiring_country_code": "SGP", "risk_details": { "security_services_data": [ { "indicator": "AQV", "insight": "111" }, { "indicator": "AQS", "insight": "009" }, { "indicator": "AQF", "insight": "111" } ], "fraud_scoring_data": [ { "key": "MODEL_REASON_CODE", "value": "99" }, { "key": "FRAUD_SCORE", "value": "010" }, { "key": "FRAUD_REASON_CODE", "value": "99" }, { "key": "MODEL_SCORE", "value": "010" } ] }, "pos_data": { "terminal_attendance": "1", "terminal_location": "0", "cardholder_presence": "0", "card_presence": "1", "card_capture_capability": "1", "transaction_status": "4", "transaction_security": "0", "cat_level": "0", "terminal_input_capability": "2", "pos_country_code": "SGP", "pos_postal_code": "018989" }, "additional_transaction_data": { "multi_purpose_merchant_indicator": { "low_risk_merchant_indicator": "02", "single_tap_indicator": "1", "transaction_initiator": "C101" } }, "authentication": { "ecom_authentication_indicator": "210" } }' Simulate Card Transaction Authorizations response (success) CURL { "message": "Transaction Successful", "status": "success" } Simulate Card Transaction Authorizations response (failed) CURL { "message": "Transaction failed", "status": "fail" } Simulate Card Transaction Reversals Before the partner can simulate a reversal, a previously successful card authorization will be required. The transaction reference code of the successful transaction is required to run a reversal simulation. Refer to the simulated reversal API call on the right. Call the Simulate Card Transaction Reversals (POST /v1/card-transactions/reverse/test) passing the required simulation parameters. Simulate a reversed card transaction Simulate Card Transaction Reversals request CURL curl --location 'https://{{cards_simulation_base_url}}/{{program_code}}/v1/card-transactions/reverse/test)' \ --header 'Content-Type: text/plain' \ --header 'Authorization: ••••••' \ --data '{ "transaction_ref_no": "P_8cd9b45e819149f59fba3a8e99310166", "product_code": "{{program_code}}" }' Simulate Card Transaction Reversals response (success) CURL { "message": "Transaction Successful", "status": "success" } Simulate Card Transaction Reversals response (failed) CURL { "message": "Transaction failed", "status": "fail" } Financial Transactions Test Scenarios Scenario Condition Result / Webhook Event Successful - ECOM Purchase Set channel: ecom OPENLOOP_POST_AUTH Successful - POS Purchase Set channel: pos OPENLOOP_POST_AUTH Successful - ATM Withdrawal Set channel: atm OPENLOOP_POST_AUTH Declined - Insufficient Balance Purchase or withdraw more than the wallet/card balance. Set transaction_amount greater than wallet or card balance OPENLOOP_DECLINED_INSUFFICIENT_BALANCE Declined - Card Permanently Blocked First block or delete the card_hash_id or the card ID, then simulate a transaction. OPENLOOP_DECLINED_CARD_BLOCKED Declined - Card Temporarily Suspended First suspend the card_hash_id or the card ID, then simulate a transaction. OPENLOOP_DECLINED_CARD_SUSPENDED Declined - Invalid Transaction Type Try an ATM withdrawal using a virtual card. Set channel: atm and card_hash_id = card ID of a virtual card OPENLOOP_DECLINED_INVALID_TRANSACTIONTYPE Declined - Unsupported Merchant You can blacklist certain merchants or MCC IDs from the program configuration. When blacklisted, you can pass your blacklisted MCCs, or you can also pass the following MCCs, which are blacklisted by default: <7800, 7801, 7802, 7995, 9406> in the merchant_category_code . OPENLOOP_DECLINED_UNSUPPORTED_PROGRAM_MERCHANTS Successful - Reversal for a previous successful transaction Set the transaction_ref_no to the original successful transaction reference number that you want to reverse. OPENLOOP_TRANSACTION_REVERSAL Declined - User Temporarily Suspended First, set the user ID of the user as temporarily locked or suspended via DELETE /users. OPENLOOP_DECLINED_USER_SUSPENDED Declined - User Permanently Blocked First, set the user ID of the user as permanently blocked or deleted via DELETE /users. OPENLOOP_DECLINED_USER_BLOCKED Purchase or Withdrawal more than KYC Limit Set the transaction_amount to be greater than the KYC limit. OPENLOOP_DECLINED_PROGRAM_LIMITS_BREACHED Sample Card Transactions simulation payload CURL { "network": "master", "channel": "ecom", "card_hash_id":"a1bc188acacc2623e7dc4de92931e48d", "card_currency_code": "PHP", "card_amount": "475.75", "transaction_currency_code": "PHP", "transaction_amount": "475.75", "terminal_id": "TSTECOM1", "merchant_id": "TESTECOM01", "merchant_name": "Test ECOM PHP", "merchant_category_code": "1740", "pos_entry_mode_code": "MANUALLY_KEYED_ECOM", "card_number": "5540450200", "product_code": "sgsandbx", "acquiring_country_code": "PHL", "pos_data": { "terminal_attendance": "0", "terminal_location": "4", "cardholder_presence": "5", "card_presence": "0", "card_capture_capability": "0", "transaction_status": "4", "transaction_security": "2", "cat_level": "6", "terminal_input_capability": "0", "pos_country_code": "PHL", "pos_postal_code": "048621" }, "additional_transaction_data": { "multi_purpose_merchant_indicator": { "low_risk_merchant_indicator": "02", "single_tap_indicator": "1", "transaction_initiator": "C101" } }, "authentication": { "ecom_authentication_indicator": "210" } } Non-Financial Test Scenarios Test Scenario Conditions Result / Webhook Event Invoke an ASI (Account Status Inquiry) transaction Set transaction_type: ASI CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION Successful - ASI transaction Set transaction_type: ASI CARDS.ACCOUNT_VERIFICATION.STATUS Declined - Card Permanently Blocked First block or delete the card_hash_id or the card ID, then simulate a transaction. CARD_BLOCKED Declined - Card Temporarily Suspended First suspend the card_hash_id or the card ID, then simulate a transaction. CARD_SUSPENDED Declined - User Temporarily Suspended First, set the user ID of the user as temporarily locked or suspended via DELETE /users. USER_SUSPENDED Declined - User Permanently Blocked First, set the user ID of the user as permanently blocked or deleted via DELETE /users. USER_BLOCKED Declined - Invalid Transaction Type Try an ATM withdrawal using a virtual card. Set channel: atm and card_hash_id = card ID of a virtual card INVALID_TRANSACTIONTYPE Declined - Unsupported Merchant You can blacklist certain merchants or MCC IDs from the program configuration. When blacklisted, you can pass your blacklisted MCCs, or you can also pass the following MCCs, which are blacklisted by default: <7800, 7801, 7802, 7995, 9406> in the merchant_category_code . UNSUPPORTED_PROGRAM_MERCHANTS Successful - Reversal for a previous successful transaction Set the transaction_ref_no to the original successful transaction reference number that you want to reverse. CARDS.ACCOUNT_VERIFICATION.STATUS Sample Card ASI simulation payload CURL { "network": "master", "channel": "atm", "card_hash_id":"a1bc188acacc2623e7dc4de92931e48d", "card_currency_code": "PHP", "transaction_currency_code": "PHP", "terminal_id": "TSTATM1", "merchant_id": "TESTATM01", "merchant_name": "Test ATM PHP", "merchant_category_code": "6011", "card_number": "5540450200", "product_code": "sgsandbx", "acquiring_country_code": "PHL", "transaction_type":"account_verification", "pos_data": { "terminal_attendance": "1", "terminal_location": "1", "cardholder_presence": "0", "card_presence": "1", "card_capture_capability": "1", "transaction_status": "0", "transaction_security": "0", "cat_level": "2", "terminal_input_capability": "2", "pos_country_code": "PHL", "pos_postal_code": "048621" }, "additional_transaction_data": { "multi_purpose_merchant_indicator": { "low_risk_merchant_indicator": "02", "single_tap_indicator": "1", "transaction_initiator": "C101" } }, "authentication": { "ecom_authentication_indicator": "210" } } Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Transaction overview Card payment fees Transaction settlements Manage card security • [On-screen digital card display](https://developer.matchmove.com/matchmove-banking-operating-system/on-screen-digital-card-display.md): Learn how to securely present the digital card form and details to users directly in your mobile or web applications. This section outlines the necessary APIs to safely retrieve and display sensitive information, such as the full card number and CVV, on-screen. By implementing this feature, you can offer a seamless digital payment experience while maintaining strict data security standards. Audience: Partner product, design, and engineering teams building the card surface in a Partner application, and MatchMove teams reviewing that surface before launch. S cope: Non-tokenized virtual card art and the live card data the Partner application presents against it. All virtual card art is horizontal. Not in scope: Tokenized card art. Images shown in a third-party wallet after provisioning through MDES — Google Pay, Apple Pay. Those are specified per wallet project and configured during wallet enablement rather than retrieved from the API. Do not design them against a general specification. Artwork design and submission: Required and prohibited elements in the artwork itself, clear space, color, imagery, and file preparation are covered in Card Design Submission . All virtual card art requires Mastercard approval before use — it is not covered by the physical card design approval. This guide assumes the artwork is approved. Interactive reference The canvas below is an annotated card face as it would appear inside an application. The card is drawn at actual size — 85.6 × 53.98 mm, the ID-1 format defined by ISO/IEC 7810 — and sits inside a phone outline so the proportions read correctly against a real screen. It is landscape only, as every virtual card design must be. Four numbered annotations on the left mark the live fields and the rule for each. Two panels on the right separate what arrives inside the approved image from what the application draws itself. Connector lines tie each annotation to the element it describes. The card, the Partner Pay branding, and the values on the face are all sample data for illustration — not a real card and not a MatchMove design. Select any field or its annotation to read the rule that governs it. Click the card away from a field to see what the artwork layer covers. The eye control on the card edge switches between masked and sensitive mode. Title Cases the canvas does not cover The canvas shows a card whose artwork carries credentials on its front. Two other cases apply. Credentials are not on the front of the artwork. The cardholder name, PAN, expiry, and security code must then appear near the card art in the application rather than over it. Numberless designs. The image omits or masks the PAN, expiry, and security code — either way, credentials are delivered and accessed in the app rather than read off the card face. A numberless design requires an approved DFCP (Digital First Card Program) before the card design can be submitted. The cardholder name may still appear. References Card Design Submission — artwork requirements, clear space, color, file preparation, and the network approval path. Authoritative for card design; this guide defers to it. Mastercard Card Design Standards — authoritative for placement coordinates, minimum sizes, and exact measurements. Gated on Mastercard Connect; route questions through your MatchMove implementation contact. The Mastercard design template (.ai) — authoritative for placement where this guide and the template differ. • [Manage card security](https://developer.matchmove.com/matchmove-banking-operating-system/managing-card-security.md): The cardholder data security and safety are critical to maintaining compliance with the Payment Card Industry Data Security Standard (PCI DSS) and protecting users from fraud or data breaches. Sensitive cardholder data, such as the Primary Account Number (PAN) and Card Verification Value (CVV), must be handled securely to prevent unauthorized access. To this end, the Cards API provides encrypted card data and limits the exposure of sensitive information in API responses. In addition, below is a summary of best practices for you to follow as part of your integration to safeguard your users. Best Practices Secure key management Cryptographic keys are the foundation of your card data security. If keys are compromised, the encryption protecting your cardholder data is rendered useless. Aligning with PCI DSS requirements ensures keys are managed throughout their lifecycle securely. Safeguarding cardholder data is critical for protecting your users against fraud and maintaining compliance with the Payment Card Industry Data Security Standard (PCI DSS). Sensitive information, including the Primary Account Number (PAN) and Card Verification Value (CVV), must be strictly controlled to prevent unauthorized access. To support this, our Cards API actively limits the exposure of sensitive information in API responses and ensures card data is fully encrypted. To further protect your users, we strongly recommend implementing the following security best practices within your integration. Key storage Never hardcode cryptographic keys in source code, configuration files, or plaintext repositories. Utilize dedicated hardware, such as a Hardware Security Module (HSM), or a managed cloud Key Management Service (KMS) to store keys securely. Key access control Enforce the principle of least privilege and strict separation of duties. Access to cryptographic keys should be restricted to the absolute minimum number of authorized personnel required to perform specific tasks. Mandate Multi-Factor Authentication (MFA) for any system or portal where keys are managed. Key rotation Implement automated, scheduled key rotation policies. Cryptographic keys should be rotated at the end of their defined cryptoperiod (e.g., annually) or immediately if a breach or compromise is suspected. Old keys must be retired securely and only retained if needed to decrypt archived data. Key backup Maintain secure backups of your cryptographic keys to ensure business continuity in the event of hardware failure. Backups must be strongly encrypted and subject to the same strict access controls and physical security requirements as the active keys. Secure retrieval and transmission When handling sensitive cardholder data (such as PANs or CVVs) across your API integrations, you must ensure the data is completely protected both in transit and at rest. Secure communication Always transmit sensitive cardholder data over secure, encrypted channels. Ensure your API integrations enforce robust transport-level security using TLS 1.2 or higher. Never transmit unprotected cardholder data over open, unencrypted, or public networks. Secure storage Minimize the storage of sensitive data. If you must store the Primary Account Number (PAN), it must be rendered unreadable using strong one-way hashing, truncation, tokenization, or robust cryptography. Never store Sensitive Authentication Data (SAD), such as the CVV/CVC, after the transaction authorization process is complete. Temporal access Restrict the duration that sensitive data is accessible. Utilize tokenization to exchange card details for a non-sensitive equivalent. If plaintext data must be retrieved for display (e.g., revealing a virtual card number to a user), ensure it is only available ephemerally (just-in-time) and expires from the user interface and local memory as quickly as possible. Handling decrypted data Even if data is transmitted securely, how your application handles decrypted cardholder data in its active memory or backend systems is a common vulnerability point. Avoid logging sensitive data Never write unencrypted Primary Account Numbers (PAN) or Sensitive Authentication Data (SAD) to application logs, system logs, error traces, or analytics platforms. If a transaction reference is needed for debugging, only log truncated versions (e.g., first 6 and last 4 digits) or a tokenized reference. Memory management Treat sensitive card data as highly volatile. Once the decrypted PAN or CVV has served its immediate purpose (such as being rendered on the screen or passed to a payment gateway), immediately clear it from application variables and memory arrays (zeroing out the memory) to prevent exposure through memory dumps or memory-scraping malware. Prevent local caching Ensure your application forms explicitly disable caching and autocomplete (e.g., using autocomplete="off" in HTML) for fields handling sensitive card data. For mobile apps, ensure decrypted card details are not inadvertently captured in background screen snapshots or saved to local device storage. Limit & authenticate user access Protecting card data also requires strict control over who can access it and when . This applies to both your end-users viewing their virtual cards and your internal team managing the platform. Step-up authentication (MFA) Require strong step-up authentication before revealing sensitive card details to an end-user. If a user requests to view their full virtual card PAN or CVV in your app, challenge them with a biometric prompt (FaceID/TouchID), a PIN, or a One-Time Password (OTP) before rendering the data. Role-Based Access Control (RBAC) For your internal staff, strictly enforce RBAC. Customer support agents, developers, and administrators should never have access to full plaintext PANs or CVVs. Dashboards should default to displaying only masked card numbers (e.g., **** **** **** 1234) unless a specific, highly privileged role requires full access for a compliant business reason. Strict session timeouts Implement aggressive idle timeouts for any interface that displays unmasked cardholder data. If a user leaves the screen idle, automatically mask the card details or log the user out after a short duration (e.g., 30 to 60 seconds) to prevent shoulder-surfing or unauthorized access on unattended devices. Related Links Card overview Create your card product Issue a card Manage card Card spending control Card payment authentication Card payments Manage card security • [Collections overview](https://developer.matchmove.com/matchmove-banking-operating-system/collections-overview.md): Receive funds globally The Collection capability enables users to collect funds into their accounts from multiple parties globally using a variety of channels. Domestic bank accounts Add funds via domestic bank accounts (for SGD currency accounts). Overseas bank accounts Add funds via bank accounts around the world (for USD currency accounts). Cash over counter Add funds to your user accounts via 7-11 stores in Singapore (for SGD currency accounts). Receive funds via bank accounts Quickly get started to receive funds via bank accounts. Provision virtual accounts Learn how to issue a dedicated virtual account for a user. Understand how these accounts provide unique details to streamline the process of receiving and sending bank transfers. Receive funds from a bank account Learn how to receive incoming funds from your users' bank accounts to top up their balances. Understand the core concept of bank collections and how they facilitate account funding. Retrieve bank collection transactions Learn how to identify and fetch details for incoming bank-to-bank transfers used to top up user accounts. Understand the methods available to view a comprehensive history of these inbound funding activities. Collection-related API and Webhooks Collection Transactions Category API / Webhook Availability Description Virtual Account Issuance Virtual Accounts v1 Retrieve the linked virtual account details of a user. Collection List User Bank transfer Transactions v1 Retrieve user-specific bank transfer transactions Collection List Program Bank Transfer Transactions v1 Retrieve program-wide bank transfer transactions Collection Simulation Simulate bank transfer-in transactions - USD v1 Simulate transfer-in bank transfer transactions in USD currency Collection Simulation Simulate bank transfer-in transactions - SGD v1 Simulate transfer-in bank transfer transactions in SGD currency Webhooks Category (non-API) Virtual Accounts Advisory, particularly the webhook events: v1 Webhook category to subscribe to receive notifications on virtual account status updates Webhook Event (non-API) CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS See Leverage Webhooks Webhook notification on deposits to an individual user's virtual account Webhook Event (non-API) BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS See Leverage Webhooks Webhook notification on deposits to a business user's virtual account Webhook Event (non-API) CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS See Leveraging Webhooks Webhook notification on deposits to the main partner's corporate virtual account Related Links Receive funds from a bank account Bank collection transactions Simulate bank collections • [Receive funds from a bank account](https://developer.matchmove.com/matchmove-banking-operating-system/receive-funds-from-banks.md): Learn how to receive incoming funds from your users' bank accounts to top up their balances. Understand the core concept of bank collections and how they facilitate account funding. Funds deposited or collected through the retail virtual account of customers and businesses will be directly credited into their accounts/wallets. The user in this document pertains to both the individual and business user types. Use Cases You want to add a feature to your application that will allow the program partner's virtual account to receive funds from a bank transfer. You want to add a feature to your application that will allow users provisioned with a virtual account to receive funds from a bank transfer. You want your users to top up their accounts through a bank transfer to their provisioned virtual accounts. You want the main partner to top up their prefund through a bank transfer to their corporate virtual accounts. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current topup_limits and transfer_in_limits must have enough buffer to accommodate the incoming credit amount. API Workflow 1 Retrieve and display the customer's Virtual Account (VA) details Call List Virtual Accounts ( GET /users/wallets/virtual_accounts ) to get the virtual account details that have been provisioned to the customer. List Virtual Accounts request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \ --header 'X-Auth-User-ID: <user_id>' \ --header 'Authorization: ••••••' List Virtual Accounts response JSON { "total_records": 1, "records_per_page": 10, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://beta-api.mmvpay.com/<program_code>/v1/users/wallets/virtual_accounts?page=1&records_per_page=10", "method": "GET" } ], "data": [ { "id": "24aae1c1-d382-45d6-b8eb-b1b69bb1be9c", "account_id": "a574bd62-6bf1-458e-7b51-3b95c2dbefb2", "account_no": "685395021205085935", "account_holder_name": "John Smith", "account_number": "885395021205085135", "bank_code": "DBSSSGSG", "status": "active", "created_at": "2025-07-15T12:20:07+08:00", "account_bank_name": "DBS", "account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982", "account_bank_country": "Singapore" } ] } Before the customer can initiate a bank transfer to the virtual account, they will need a reference to the virtual account details. These details are required as input to the external bank online fund transfer form: " account_holder_name ": "John Smith", " account_number ": "885395021205085135", " bank_code ": "DBSSSGSG", " account_bank_name ": "DBS" These virtual account details will need to be displayed on the app's frontend and made accessible to customers. 2 Initiate a bank transfer/deposit from the external bank The “incoming fund” transfer will be initiated from the external bank's online application. The external bank's beneficiary details must be filled with the MatchMove virtual account details. In the external bank online fund transfer form, the virtual account details will need to be filled accordingly: External Bank Fund Transfer Form MatchMove Virtual Account Details Beneficiary / Bankholder name / Account holder account_holder_name Beneficiary account / Bank account number account_number Beneficiary bank code / Bank code bank_code Beneficiary bank name / Bank name account_bank_name Transfer comment / Transfer notes Any note for the recipient/internal tracking identifier The transfer comment from the external bank transfer will arrive in the MatchMove collections webhook payload later, as the client_ref_id field. With the increasing prevalence of online fraud and digital scams, MatchMove has instituted a new security measure. A ' Fuzzy Name Matching ' validation has been added for all funds being received through the Virtual Account network. This validation will be applied to the beneficiary name from the external depository bank and the bank holder name of the MatchMove virtual account. This would ensure that the fund beneficiary is really the intended recipient of the depositor. Once the account number and name match are validated, the deposit transaction will be received. Otherwise, the transaction will be rejected. Fuzzy Name Matching Logic This is a probabilistic matching technique that identifies word matches using linguistic and statistical analysis, accepting only those that meet a set threshold. [External Bank] Beneficiary Name [MatchMove VA] Bank Holder Name Match Action on Deposit Francia Smith Francia Smith Yes Received Jin Teo Jinny Teo Yes Received Vicky Logistics Vicky Logistics Pte Ltd Yes Received Sean Singh Shanna Ting No Rejected JBC Pte Ltd ABC Manufacturing Pte Ltd No Rejected 4 Monitor for events happening on virtual accounts Once the bank transfer/deposit transaction is executed from the external bank, the funds will arrive on MatchMove after the bank network has processed the transfer instruction. This transfer instruction processing time will depend on the external bank SLA with the bank network. The Virtual Account Advisory webhook category is available for partners who want to get timely feedback on virtual account events. If a failure or rejection happens, the webhook payload will contain a reason for rejection. Go to the Leverage Webhooks section to learn more about setting up the webhooks. Virtual Account Advisory webhooks Partners have the option to subscribe to the webhook events related to bank collections. These webhooks are prefixed and classified per the account type of the virtual account owner: CONSUMER_ - Individual customer BUSINESS_ - Business customer CORPORATE_ - Main partner or program owner Event Description Action CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS A notification is sent if the transfer to the virtual account is successful and complete. No action required CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED A notification is sent if the transfer to the virtual account encounters an error. No action required CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS A notification is sent if the source bank cancels the transfer to the virtual account. The system will perform a reverse operation. No action required. The user can retry the transfer to the virtual account CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED A notification is sent if the source bank cancels the transfer to the virtual account. The system's reversal attempt failed. No action required. Matchmove will auto-retry the reversal until it is successful Sample webhook payload JSON { "consumer": { "consumer_name": "CLIENT NAME", "prefund_balance": "1349581.800000" }, "debit_credit_indicator": "C", "deducted_amount": "1.950000", "fee_charged": "0.000000", "payment_instrument": { "status": "active", "transaction_instrument_id": "hashidofcard", "virtual_account_number": "6377022712345678", "wallet_number": "6377022712345678" }, "time_stamp": "2023-07-27T14:27:45+08:00", "total_amount": "1.950000", "total_currency": "SGD", "transaction": { "client_ref_id": "CLIENREF001", "purpose_of_transfer": "OTHR", "transaction_message": "Transfer from 6377022712345678 success", "transaction_ref": "CREDIT-generatedtransactionref", "transaction_status": "success", "transfer_in": { "destination_account": { "bank_account_number": "6377022712345678", "bank_code": "MAYPSGS0XXX", "bank_holder_name": "MM HOLDER NAME" }, "source_account": { "bank_account_number": "12345678", "bank_code": "DBSSSGS0XXX", "bank_holder_name": "BANK HOLDER NAME" } } }, "user": { "email": "mmuser@matchmove.com", "kyc_status": "active", "mobile": "12345678", "mobile_country_code": "65", "user_hash": "hashidofuser" }, "webhook_event": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS" } Related Links Collections overview Bank collection transactions Simulate bank collections • [Retrieve bank collection transactions](https://developer.matchmove.com/matchmove-banking-operating-system/retrieve-collection-banks.md): Learn how to identify and fetch details for incoming bank-to-bank transfers used to top up user accounts. Understand the methods available to view a comprehensive history of these inbound funding activities. Use Cases You want to retrieve all the top-up and withdrawal (when available) transactions made on the user's virtual account. You want to retrieve all the top-up transactions made on the main partner's corporate virtual account. You want to display all the top-up and withdrawal (bank-to-bank) transactions made against a virtual account. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. API Workflow 1 Retrieve the customer's Virtual Account (VA) details Call List Virtual Accounts ( GET /users/wallets/virtual_accounts ) to get the virtual account details that have been provisioned to the customer. List Virtual Accounts request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/virtual_accounts' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Virtual Accounts response JSON { "total_records": 1, "records_per_page": 10, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/virtual_accounts?page=1&records_per_page=10", "method": "GET" } ], "data": [ { "id": "24aae1c1-d382-45d6-b8eb-b1b69bb1be9c", "account_id": "a574bd62-6bf1-458e-7b51-3b95c2dbefb2", "account_no": "685395021205085935", "account_holder_name": "John Smith", "account_number": "885395021205085135", "bank_code": "DBSSSGSG", "status": "active", "created_at": "2025-07-15T12:20:07+08:00", "account_bank_name": "DBS", "account_bank_address": "12 Marina Boulevard, DBS Asia Central, Marina Bay Financial Centre Tower 3, Singapore 018982", "account_bank_country": "Singapore" } ] } Take note of the account number of the virtual account. In this example, "account_no": "685395021205085935" The virtual account number will be required in the Get Program Bank Transfer Transactions request. 2 Retrieve virtual account transactions Call List Program Bank Transfer Transactions ( GET /oauth/consumer/account/transactions ) passing the virtual account number of the specific customer transaction you want to retrieve. List Program Bank Transfer Transactions request CURL curl --location 'https://{{collections_base_url}}/{{program_code}}/v1/oauth/consumer/account/transactions?virtual_account_number={{virtual_account_number}}' \ --header 'Authorization: ••••••' List Program Bank Transfer Transactions response JSON { "total_records": 0, "records_per_page": 10, "total_pages": 0, "page": 1, "links": null, "data": [] } Related Links Collections overview Receive funds from a bank account Simulate bank collections • [Simulate bank collections](https://developer.matchmove.com/matchmove-banking-operating-system/simulate-bank-collections.md): Learn how to test your end-to-end collections flow in our staging environment without moving real money. Use this guide to understand how to validate your integration by simulating various collection scenarios. Note: The set of endpoints below are only available and enabled in the staging environment. These endpoints will allow you to simulate incoming bank collections before the live environment. Payload Definition The parameters below apply to specific corridors listed in the remarks. Parameter Description Remarks amount Amount in program currency to be transferred Amount to be transferred client_ref_id Reference ID from the origin For programs configured with SGD as the base currency, the value needs to be prefixed with MOCK- currency Program currency Program currency purpose_of_transfer Standard purpose of transfer For programs configured with SGD as the base currency, the values should come from the Domestic Transfer Purpose Enumeration ( GET /users/wallets/payouts/domestic/enumerations/transfer_purpose) *The enumeration is part of the Payout API category; you can access them by using the {{payouts_base_url}} . See Utilize Enumerations section to learn more. source_account Origination account details Originating account details beneficiary_account Destination account details MatchMove Issued virtual account details simulate_cancellation Optional flag Only applicable for programs configured with SGD as the base currency transaction_type Additional info about transaction type Allowed values are: INCOMING ACT INCOMING TT Only applicable for programs configured with USD as the base currency additional_info Additional info about the transaction Only applicable for programs configured with USD as the base currency payment_details Additional payment details for the transaction Only applicable for programs configured with USD as the base currency Bank Collection simulation endpoints Depending on the base currency configured in the program, the payload parameters will differ as stated in the Payload Definition. These simulation API will perform all the associated processes listed below: Pre-fund balance movement Account holder balance movement Webhooks per API consumers' active subscriptions User status check Risk evaluation status check Account KYC/KYB limit checks Beneficiary name check Reporting data update Prerequisites The user profile risk assessment status must not be risk_flagged . The user profile must be in an active status. The user must have an approved KYC or KYB status The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current topup_limits and transfer_in_limits must have enough buffer to accommodate the incoming credit amount. Simulate a bank collection on a virtual account Simulate Bank Collection - SGD Simulate Bank Transfer-in Transactions request (success) CURL curl --location --request POST 'https://{{va_simulation_base_url}}/{{program_code}}/v1/simulate/transfer_in' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "1.00", "client_ref_id": "MOCK-123456", "currency": "SGD", "purpose_of_transfer": "INV", "source_account": { "number": "000000", "name": "External Bank User", "bank_code": "BKCHSGS0XXX" }, "beneficiary_account": { "number": "6377021219064027", "name": "Matchmove Wallet User", "bank_code": "MAYPSGS0XXX" }, "simulate_cancellation": false }' Simulate Bank Transfer-in Transactions response (success) JSON { "success": true } Simulate Bank Transfer-in Transactions request (failed) CURL curl --location --request POST 'https://{{va_simulation_base_url}}/{{program_code}}/v1/simulate/transfer_in' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "1.00", "client_ref_id": "MOCK-123456", "currency": "SGD", "purpose_of_transfer": "INV", "source_account": { "number": "000000", "name": "External Bank User", "bank_code": "BKCHSGS0XXX" }, "beneficiary_account": { "number": "6377021219064027", "name": "Matchmove Wallet User", "bank_code": "MAYPSGS0XXX" }, "simulate_cancellation": false }' Simulate Bank Transfer-in Transactions response (failed) JSON { "success": false, "description": "Error message description here" } Simulate Bank Transfer-in Transactions - Reversal request Bash curl --location --request POST 'https://{{va_simulation_base_url}}/{{program_code}}/v1/simulate/transfer_in' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "1.00", "client_ref_id": "MOCK-123456", "currency": "SGD", "purpose_of_transfer": "INV", "source_account": { "number": "000000", "name": "External Bank User", "bank_code": "BKCHSGS0XXX" }, "beneficiary_account": { "number": "6377021219064027", "name": "Matchmove Wallet User", "bank_code": "MAYPSGS0XXX" }, "simulate_cancellation": true }' Simulate Bank Transfer-in Transactions - Reversal response (success) JSON { "success": true, "cancellation": { "success": true } } Simulate Bank Transfer-in Transactions - Reversal response (failed) JSON { "success": true, "cancellation": { "success": false, "description": "Error message description here" } } Simulate Bank Collection - USD Simulate Bank Transfer-in Transactions response (success) CURL curl --location --request POST 'https://{{va_simulation_base_url}}/{{program_code}}/v1/simulate/collections/transfer_in' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "1.00", "client_ref_id": "MOCK-123456", "currency": "USD", "purpose_of_transfer": "INV", "additional_info":"", "payment_details":"", "source_account": { "number": "000000", "name": "External Bank User", "bank_code": "BKCHSGS0XXX" }, "beneficiary_account": { "number": "8553956377021219064027", "name": "Matchmove Wallet User", "bank_code": "MAYPSGS0XXX" }, "transaction_type": "INCOMING ACT" }' Simulate Bank Transfer-in Transactions response (success) JSON { "response": "transfer in simulate request submitted for processing successfully" } Simulate Bank Transfer-in Transactions response (failed) CURL curl --location --request POST 'https://{{va_simulation_base_url}}/{{program_code}}/v1/simulate/collections/transfer_in' \ --header 'Authorization: Basic NTc1OWQxYjA3NWU3MTUzNDk2ZmU1MzU0OTY5Mjc4M2I6NjA2OGU0YjE2MDNmNjVlZDU4Y2VmZjk2NmU5NzVjNGNmMDk4OWU0Mw==' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": "1.00", "client_ref_id": "MOCK-123456", "currency": "USD", "purpose_of_transfer": "INV", "additional_info":"", "payment_details":"", "source_account": { "number": "000000", "name": "External Bank User", "bank_code": "BKCHSGS0XXX" }, "beneficiary_account": { "number": "8553956377021219064027", "name": "Matchmove Wallet User", "bank_code": "MAYPSGS0XXX" }, "transaction_type": "INCOMING ACT" }' Simulate Bank Transfer-in Transactions response (failed) JSON { "code": "EUP0400101", "description": "Parameter amount is a required field", "links": [ { "rel": "error EUP0400101", "href": "https://sg-prefund.uat.matchmove-beta.com/error/EUP0400101" } ] } Related Links Collections overview Receive funds from a bank account Bank collection transactions • [Payouts overview](https://developer.matchmove.com/matchmove-banking-operating-system/payouts-overview.md): The payout capability enables you to facilitate payout functionality for your end users to payout to users worldwide. Domestic bank accounts Payouts to other bank accounts domestically (For SGD currency accounts) Overseas bank accounts Payouts to other bank accounts around the world (For USD currency accounts) Payout to a domestic bank account Create a recipient for domestic payment Learn how to securely store a beneficiary's local bank account details for future use. This guide helps you understand the process of creating reusable recipient profiles for domestic bank transfers. Perform a domestic payment Understand the process for initiating a local bank-to-bank transfer to a saved domestic beneficiary. This guide will walk you through the process of making a payment using a previously created recipient profile. Track the status of a domestic payment Learn about the different status updates you will receive for domestic payments via webhooks. Understand how to interpret these events to track a payment's lifecycle from initiation to completion. Simulate domestic payments Learn how to test your complete domestic payment flow in our sandbox environment without moving real money. Use this guide to understand how to validate your integration by simulating various payment outcomes. Payout to an overseas bank account Create a recipient for cross-border payment Learn how to securely store a beneficiary's details for future cross-border payments, supporting both bank accounts and payment providers. This guide helps you understand the process of creating reusable recipient profiles for these transfers. Manage cross-border recipients Learn how to create and maintain beneficiary profiles to facilitate seamless cross-border payouts. Understand the necessary recipient details required by the payout network based on the target currency, country, and remittance mode. Get a quote for cross-border payment Understand how to get a time-limited quote with guaranteed foreign exchange rates and a transparent breakdown of all fees. This guide explains the mandatory step of locking in the financial details of a cross-border transfer. Perform a cross-border payment using an existing beneficiary Learn the standard process for executing a cross-border transfer to a saved beneficiary profile. This guide shows you how to use a previously generated quote to send funds to a known recipient. Perform a cross-border payment without a existing beneficiary Understand how to execute a one-time cross-border payment without first creating a recipient profile. This guide covers transfers where beneficiary details are provided at the time of the transaction, rather than selected from a saved profile. Track the status of a cross-border payment This guide explains the webhook statuses available to receive status updates on cross-border payments. Understand the various lifecycle statuses a cross-border payment goes through until it is completed. Manage cross-border payments Understand the post-initiation operations available for your cross-border payments. Learn how to retrieve transaction details and the appropriate actions to take based on the various status updates you receive. Payout-related API and Webhooks Payout Transactions Category API / Webhook Availability Description Domestic Payouts Create Domestic Payout Recipients v1 Create a beneficiary bank account (receiver) for domestic payout transfers. Domestic Payouts List Domestic Payout Recipients v1 Retrieve all defined beneficiaries associated with a user account Domestic Payouts Delete Domestic Payout Recipients v1 Remove and disassociate a beneficiary from a user account. Domestic Payouts Send Domestic Payout Transactions v1 Initiate a domestic payout to a chosen beneficiary. Domestic Payout Enumerations List Domestic Payout Transfer Agent Enumerations v1 Retrieve the list of supported local banks for domestic payout transfer. Cross-border Payouts List Cross-border Payout Corridors v2 Retrieve the list of all corridors available on the platform. Cross-border Payouts Get Cross-border Payout Corridor Details v2 Retrieve the corridor details of a specific corridor/route Cross-border Payouts List Cross-border Payout Recipient Forms v2 Retrieve the payout recipient form that contains the required fields necessary to create a recipient for a particular corridor. Cross-border Payouts Create Cross-border Payout Recipients v2 Create a recipient passing the requirements listed on the payout recipient form. Cross-border Payouts Update Cross-border Payout Recipients v2 Update a defined recipient's details. Cross-border Payouts Update Cross-border Payout Recipient Statuses v2 Activate, deactivate, block, and delete a recipient status. Cross-border Payouts Enquire Cross-border Payout Quotations v2 Retrieve a quotation or calculation of total deductibles for an intended amount to a specific corridor Cross-border Payouts Send Cross-border Payout Transactions v2 Initiate a transaction using a chosen recipient, corridor, and quotation. Cross-border Payouts List Cross-border Payout Transactions v2 Retrieve all the transactions made by a user. Cross-border Payouts Get Cross-border Payout Transaction Details v2 Retrieve the transaction details of a specific transaction. Cross-border Payouts List Cross-border Payout Transaction Timelines v2 Retrieve the transaction timeline involving the status changes of a specific transaction. Cross-border Payouts List Cross-border Payout Transaction Statuses v2 Retrieve the current status of a specific transaction Cross-border Payouts Create/Replace Cross-border Transaction Documents v2 Create or replace required transaction documents. Cross-border Payouts Confirm Cross-border Transaction Documents v2 Confirm required transaction documents. Cross-border Payouts Enumerations List Cross-border Payout Country Enumerations v2 Retrieve the list of supported receiving countries. Cross-border Payouts Enumerations List Cross-border Payout Currency Enumerations v2 Retrieve the list of supported receiving currencies. Cross-border Payouts Enumerations List Cross-border Payout Institution Enumerations v2 Retrieve the list of supported banks and receiving institutions. Cross-border Payouts Enumerations Get Cross-border Payout Institution Branch Enumerations v2 Retrieve the list of supported banks and receiving institutions' branches. Webhook Category (non-API) Transaction Payout Advisory, particularly the webhook events: See Leverage Webhooks Webhook category to subscribe to receive notifications on payout transaction status updates Webhook Event (non-API) PAYOUT.QUOTE.CROSSBORDER.STATUS See Leverage Webhooks Webhook notification on status updates containing details of quote validity and expiry Webhook Event (non-API) PAYOUT.RECIPIENT.CROSSBORDER.STATUS See Leverage Webhooks Webhook notification on status updates of a recipient Webhook Event (non-API) PAYOUT.TRANSACTION.CROSSBORDER.STATUS See Leverage Webhooks Webhook notification on status updates of a cross-border transaction Webhook Event (non-API) PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS See Leverage Webhooks Webhook notification on status updates on the result of the review made by the payment rail on the transaction Related Links Payout network Domestic payouts Cross-border payouts • [Payout network](https://developer.matchmove.com/matchmove-banking-operating-system/payout-network.md): Supported Payout Sender (Currency) Each partner program's base currency can be set to hold and transact either of the two available configurations: Singapore Dollar (SGD) Singapore-issued accounts (wallets) and virtual accounts can be configured to transact in SGD, which allows sending of payouts from SGD to any other supported currency. US Dollar (USD) Singapore-issued accounts (wallets) and virtual accounts can be configured to transact in USD, which allows sending of payouts from USD to any other supported currency. Supported Payout Receiver (Mode, Route, Currency, and Capabilities) The payout network supports various payout modes , which are determined by the sender and receiver types. A sender or a receiver can be either an individual or a business. Depending on the available routes , which are regions supporting the specific payout modes, a payout transaction can be initiated. Each of these routes also supports a particular currency of the receiver, which will be the terminal currency when the receiver receives the payout amount. The currently available payout product capabilities , enabled for a payout mode, route, and supported currency, are listed below (categorized by Payout Mode). This list will keep expanding as we continue to enable support for more payout routes. Individual to Individual Andorra Cross-border: Remittance: EUR Austria Cross-border: Remittance: EUR Bangladesh Cross-border: Remittance: BDT Belgium Cross-border: Remittance: EUR Bulgaria Cross-border: Remittance: EUR Croatia Cross-border: Remittance: EUR Czech Republic Cross-border: Remittance: EUR Denmark Cross-border: Remittance: EUR Finland Cross-border: Remittance: EUR France Cross-border: Remittance: EUR Germany Cross-border: Remittance: EUR Greece Cross-border: Remittance: EUR Hong Kong Cross-border: Remittance: HKD Hungary Cross-border: Remittance: EUR Iceland Cross-border: Remittance: EUR India Cross-border: Remittance: INR Indonesia Cross-border: Remittance: IDR Ireland Cross-border: Remittance: EUR Italy Cross-border: Remittance: EUR Liechtenstein Cross-border: Remittance: EUR Lithuania Cross-border: Remittance: EUR Luxembourg Cross-border: Remittance: EUR Malaysia Cross-border: Remittance: MYR Malta Cross-border: Remittance: EUR Monaco Cross-border: Remittance: EUR Netherlands Cross-border: Remittance: EUR Norway Cross-border: Remittance: EUR Philippines Cross-border: Remittance: PHP Poland Cross-border: Remittance: EUR Portugal Cross-border: Remittance: EUR Romania Cross-border: Remittance: EUR San Marino Cross-border: Remittance: EUR Singapore Domestic: Bank Transfer: SGD to SGD only Slovakia Cross-border: Remittance: EUR Spain Cross-border: Remittance: EUR Sri Lanka Cross-border: Remittance: LKR Sweden Cross-border: Remittance: EUR Switzerland Cross-border: Remittance: EUR Thailand Cross-border: Remittance: THB United Kingdom Cross-border: Remittance: EUR Vatican City Cross-border: Remittance: EUR Vietnam Cross-border: Remittance: VND - - Business to Business Andorra Cross-border: Remittance: EUR Austria Cross-border: Remittance: EUR Belgium Cross-border: Remittance: EUR Bulgaria Cross-border: Remittance: EUR China Cross-border: Remittance: CNY Croatia Cross-border: Remittance: EUR Czech Republic Cross-border: Remittance: EUR Denmark Cross-border: Remittance: EUR Finland Cross-border: Remittance: EUR France Cross-border: Remittance: EUR Germany Cross-border: Remittance: EUR Greece Cross-border: Remittance: EUR Hungary Cross-border: Remittance: EUR Iceland Cross-border: Remittance: EUR India Cross-border: Remittance: INR Ireland Cross-border: Remittance: EUR Italy Cross-border: Remittance: EUR Liechtenstein Cross-border: Remittance: EUR Lithuania Cross-border: Remittance: EUR Luxemborg Cross-border: Remittance: EUR Malta Cross-border: Remittance: EUR Monaco Cross-border: Remittance: EUR Netherlands Cross-border: Remittance: EUR Poland Cross-border: Remittance: EUR Portugal Cross-border: Remittance: EUR Romania Cross-border: Remittance: EUR San Marino Cross-border: Remittance: EUR Singapore Domestic: Bank to bank: SGD to SGD only Slovakia Cross-border: Remittance: EUR Spain Cross-border: Remittance: EUR Sweden Cross-border: Remittance: EUR Switzerland Cross-border: Remittance: EUR United Kingdom Cross-border: Remittance: GBP, EUR United States of America Cross-border: Remittance: USD Vatican City Cross-border: Remittance: EUR - Cross-border: Bank to bank: NA- Remittance: NA Domestic: Bank to bank: NA Business to Individual Australia Cross-border: Remittance: AUD Hong Kong Cross-border: Remittance: HKD India Cross-border: Remittance: INR Indonesia Cross-border: Remittance: IDR Japan Cross-border: Remittance: JPY Malaysia Cross-border: Remittance: MYR Singapore Domestic: Bank Transfer: SGD to SGD only United Kingdom Cross-border: Remittance: GBP United States of America Cross-border: Remittance: USD - - - Related Links Payouts overview Domestic payouts Cross-border payouts • [Domestic payouts](https://developer.matchmove.com/matchmove-banking-operating-system/domestic-payout.md): Simplifying Domestic Bank Transfers Domestic Payouts Domestic Payments refer to the seamless transfer of funds from a sender's account to a valid recipient's account within the country. These transactions enable individuals and businesses to conduct instant payouts domestically Who is it for? For users with Singapore-issued MatchMove accounts and virtual accounts, who want to send payouts to friends and family, personal and business accounts can be made through banking channels. Where transfers are fast, cheap, and efficient, allowing crediting of funds in real-time through the wide network of participating local banks. Business Users Businesses looking to automate domestic bank transfers to accounts payable, including payments to vendors/suppliers, freelancers, and marketplace purchases. Businesses located in Singapore that need to make domestic bank transfer payments for business operations, managing payroll, and reimbursements. Individual Users Purchase expenses - pay through domestic bank transfers on marketplace purchases, imported goods, stock investments, logistics, travel bookings, and many more. Money transfers - transfer funds via domestic bank transfer to friends, family, and any other local bank accounts. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts • [Create a recipient for domestic payment](https://developer.matchmove.com/matchmove-banking-operating-system/domestic-payout/create-recipient-for-domestic-payout.md): Learn how to securely store a beneficiary's local bank account details for future use. This guide helps you understand the process of creating reusable recipient profiles for domestic bank transfers. The user in this document pertains to both the individual and business user types. Use Cases You want to implement a feature that will allow users to withdraw funds to a domestic/local bank account. You want to implement a feature that will allow users to define their beneficiary recipient before performing a bank withdrawal. You want to implement a feature that will allow users to reuse their previously defined beneficiary recipients for withdrawals. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. API Workflow 1 Retrieve the list of available local banks for transfer In the domestic recipient creation form on the partner application, we need to let the customer (sender) choose from the selection of available banks that can receive a domestic transfer. If the customer's intended bank is not in the selection, then we should not allow him to proceed with the domestic recipient definition. Call the List Domestic Payout Transfer Agent Enumerations ( GET /users/wallets/payouts/domestic/enumerations/transfer_agents ) to retrieve the list of available local banks that can receive a domestic transfer. It is important to filter only the active banks during a particular timeframe, as receiving banks may go on maintenance and be unavailable for certain periods of time. In the below example, the status=active filter is added to only retrieve currently available banks for transfer. Please note that the value of the bank code will be agent_code returned in the response. List Domestic Payout Transfer Agent Enumerations request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?status=active' \ --header 'Authorization: ••••••' *Please note that this is a special API that needs to be called in admin scope, without passing X-Auth-User-ID. List Domestic Payout Transfer Agent Enumerations response JSON { "total_records": 37, "records_per_page": 37, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?page=1&records_per_page=10&return_all=true&status=active", "method": "GET" } ], "data": [ { "agent_code": "ANZBSGS0XXX", "agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/ANZ_BANK.png", "mode": "bank", "name": "ANZ Bank", "status": "active", "bic_code": "ANZBSGS0XXX", "fees": { "fixed": "0.000000", "percentage": "0.000000", "variable": "", "fee_calculation_type": "" }, "transfer_details": [ { "channel_id": "382dd1f29f9411ec875a02b5044dcedc", "channel": "FAST", "min_transfer_amount": "0.01", "max_transfer_amount": "200000.00", "transfer_fulfillment_time": "Instant" } ], "account_number_regex": "^[0-9]*$", "account_number_min_length": "5", "account_number_max_length": "34" }, { "agent_code": "BKCHSGS0XXX", "agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/BANK_OF_CHINA_CREDIT_CARD.png", "mode": "bank", "name": "Bank of China Credit Card", "status": "active", "bic_code": "BKCHSGS0XXX", "fees": { "fixed": "0.000000", "percentage": "0.000000", "variable": "", "fee_calculation_type": "" }, "transfer_details": [ { "channel_id": "382dd1f29f9411ec875a02b5044dcedc", "channel": "FAST", "min_transfer_amount": "0.01", "max_transfer_amount": "200000.00", "transfer_fulfillment_time": "Instant" } ], "account_number_regex": "^[0-9]*$", "account_number_min_length": "5", "account_number_max_length": "34" }, .. ] } Note: The available domestic banks ( agent_code ) list will be different between staging and live environments. Please refrain from hard-coding any agent_code and always pull the updated list from the Domestic Transfer Agents Enumerations API. 2 Define a beneficiary account Before initiating an outgoing transfer through virtual accounts, a beneficiary account must be defined first. Call Create Domestic Payout Recipients ( POST /users/wallets/payouts/domestic/bank_accounts ) passing the beneficiary's local bank account information. Create Domestic Payout Recipients request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••'' \ --data-urlencode 'bank_holder_name=Juan Smith' \ --data-urlencode 'bank_code=<agent_code>' \ --data-urlencode 'bank_account_number=5543213122' Create Domestic Payout Recipients response JSON { "id": "9d1a885d-b264-4b73-9057-eec2565a49c3", "bank_account_number": "5543213122", "bank_holder_name": "Juan Smith", "bank_code": "<agent_code>", "bank_name": "Bank Name", "mode": "bank", "entity_type": null, "status": "active", "is_active": 1, "created_at": "2025-08-07T16:14:45+08:00", "updated_at": "2025-08-07T16:14:45+08:00", "activated_at": "2025-08-07T16:14:45+08:00" } Recipient Cooling-Off Period - Domestic A cooling-off period is a mandatory waiting timeframe that restricts account functions like withdrawals and transfers. This safeguard prevents system abuse and provides a "buffer" to detect fraudulent activity before funds move. In the MatchMove platform, this period occurs between a recipient's creation and activation . It acts as a primary fraud prevention layer, ensuring suspicious actions are intercepted before payouts are authorized. Timing and Logic Initial State: Upon creation, the recipient's user.status is set to PENDING_ACTIVATION . Cooling Period: This waiting period runs simultaneously with the risk evaluation. The recipient will remain in the PENDING_ACTIVATION state until the cooling period lapses. Activation Requirements Becoming Active: Both the cooling period and the risk evaluation must independently finish before the recipient's status transitions to ACTIVE . Sending Payouts: Domestic payouts can only be sent to ACTIVE recipients. Any attempt to send funds to a recipient in a different state will be blocked by the platform. 3 Delete a beneficiary account (optional) Call Delete Domestic Payout Recipients ( DELETE /users/wallets/payouts/domestic/bank_accounts ) passing the beneficiary's generated beneficiary ID. Delete Domestic Payout Recipients request CURL curl --location --request DELETE 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'id=1c255d6e-2f4c-41a6-b380-ac6cb512de70' Delete Domestic Payout Recipients response JSON { "status": "deleted" } 4 Monitor for domestic beneficiary status The Virtual Account Advisory webhook category is available for partners who want to get timely feedback on virtual account events. Listed below are the webhook events available for domestic beneficiary creation and the appropriate action required when they are received. Webhook Event Description Required Action PAYOUT.RECIPIENT.DOMESTIC.STATUS A notification is sent when the domestic beneficiary status has changed. No action required Related Links Payouts overview Payout network Domestic payouts Perform a domestic payment Track the status of a domestic payment Simulate a domestic payment Cross-border payouts • [Perform a domestic payment](https://developer.matchmove.com/matchmove-banking-operating-system/domestic-payout/create-a-domestic-payout.md): Understand the process for initiating a local bank-to-bank transfer to a saved domestic recipient. This guide will walk you through the process of making a payment using a previously created recipient profile. The user in this document pertains to both the individual and business user types. For Singapore-issued customer accounts : Domestic payout refers to the movement of funds from the platform, via a provisioned SGD Virtual Account (VA) , to any Singaporean local bank or financial institution that has enabled the FAST (Fast and Secure Transfers) electronic fund transfer service. For Singapore-issued partner (program owner) accounts : Domestic payout is only enabled for User (Individual/Business) SGD Virtual Accounts . This feature is disabled for Partner SGD Corporate Virtual Accounts . Since the corporate virtual account will be directly tied to the Program Owner Account and the prefund, the direct withdrawal of funds from the program will be restricted. For the withdrawal of surplus prefund and other settlement fund movement, you may reach out to your MatchMove Relationship Manager for specific arrangements. Use Cases You want to implement a feature in your application that will allow users to send domestic payment transactions to their defined recipients. You want to implement a feature in your application that will allow users to withdraw funds to their local bank accounts (defined as a recipient). Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current deduct_limits and transfer_out_limits must have enough buffer to accommodate the incoming debit amount. The user account must have a balance that is equal to or higher than the payment amount. A valid domestic recipient must have already been defined and must be in an active status. API Workflow 1 Retrieve and select a recipient from the active recipient list All the defined recipient accounts belonging to the customer account will be listed. In your frontend, you will need to display this list and allow the user to select the recipient they want to send funds to. Call List Domestic Payout Recipients ( GET /users/wallets/payouts/domestic/bank_accounts ) to get the list of all the recipients associated with a user. List Domestic Payout Recipients request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Domestic Payout Recipients response JSON { "total_records": 8, "records_per_page": 10, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts?page=1&records_per_page=10&return_all=false", "method": "GET" } ], "data": [ { "id": "fd85e7f1-ec52-41a4-916b-88e687af859f", "bank_account_number": "6377021438014797", "bank_holder_name": "John Williams", "bank_code": "MAYPSGS0XXX", "bank_name": "MatchMove Pay Pte Ltd", "mode": "wallet", "entity_type": null, "status": "inactive", "is_active": 0, "created_at": "2024-05-08T17:04:01+08:00", "updated_at": null, "activated_at": null }, { "id": "0f665f5e-462a-4b7c-a75c-479a91ee401b", "bank_account_number": "6377021438014795", "bank_holder_name": "Twelve Success", "bank_code": "MAYPSGS0XXX", "bank_name": "MatchMove Pay Pte Ltd", "mode": "wallet", "entity_type": null, "status": "inactive", "is_active": 0, "created_at": "2024-01-22T17:05:01+08:00", "updated_at": "2024-05-09T17:03:30+08:00", "activated_at": null }, { "id": "bf5c7633-230e-4b83-a890-a21170405753", "bank_account_number": "123123123123333", "bank_holder_name": "Kelvin", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "mode": "bank", "entity_type": null, "status": "inactive", "is_active": 0, "created_at": "2024-04-08T17:45:22+08:00", "updated_at": null, "activated_at": null }, { "id": "a9dbcca8-4f48-4aa9-adce-726f191dcaed", "bank_account_number": "6377021438014796", "bank_holder_name": "Twel Success", "bank_code": "MAYPSGS0XXX", "bank_name": "MatchMove Pay Pte Ltd", "mode": "wallet", "entity_type": null, "status": "active", "is_active": 1, "created_at": "2024-05-08T15:43:21+08:00", "updated_at": "2025-02-24T15:03:35+08:00", "activated_at": null }, { "id": "2fb1eb0f-0b20-461b-9109-ec0798eeaf45", "bank_account_number": "6377021438014708", "bank_holder_name": "Hey Success", "bank_code": "MAYPSGS0XXX", "bank_name": "MatchMove Pay Pte Ltd", "mode": "wallet", "entity_type": null, "status": "inactive", "is_active": 0, "created_at": "2024-05-08T17:14:24+08:00", "updated_at": null, "activated_at": null }, { "id": "bd5ab473-a0a6-451d-abe5-c827e67980e5", "bank_account_number": "6377021438014798", "bank_holder_name": "Gero Success", "bank_code": "MAYPSGS0XXX", "bank_name": "MatchMove Pay Pte Ltd", "mode": "wallet", "entity_type": null, "status": "inactive", "is_active": 0, "created_at": "2024-05-08T17:09:24+08:00", "updated_at": null, "activated_at": null }, { "id": "c2cb551f-3ce5-407b-84dc-2a5d83f7e52d", "bank_account_number": "131246491919", "bank_holder_name": "merry", "bank_code": "BNPASGS0XXX", "bank_name": "BNP Paribas", "mode": "bank", "entity_type": null, "status": "active", "is_active": 1, "created_at": "2024-05-16T20:25:08+08:00", "updated_at": "2024-07-11T13:10:01+08:00", "activated_at": null }, { "id": "9d1a885d-b264-4b73-9057-eec2565a49c3", "bank_account_number": "5543213122", "bank_holder_name": "MATCHMOV HELLO Success", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "mode": "bank", "entity_type": null, "status": "active", "is_active": 1, "created_at": "2025-08-07T16:14:45+08:00", "updated_at": "2025-08-07T16:14:45+08:00", "activated_at": "2025-08-07T16:14:45+08:00" } ] } On the recipient selection screen, only recipient with status=active must be available for selection. Otherwise, the bank transfer transaction will fail later if the recipient is not active. Once the user (sender) has selected their intended domestic recipient, please take note of the bank account ID since this will be required as an input for sending a domestic payout transaction. e.g., from the response above, it will be "id": "fd85e7f1-ec52-41a4-916b-88e687af859f" 4 Send a domestic payout transaction Finally, we initiate the outgoing domestic payout to the selected recipient of the customer. Call the Send Domestic Payout Transactions ( POST /v1/users/wallets/payouts/domestic/fund_transfers/credit ) to send the domestic payout transaction. Send Domestic Payout Transactions request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/fund_transfers/credit' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Accept: application/json' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' \ --data-urlencode 'bank_account_id=9d1a885d-b264-4b73-9057-eec2565a49c3' \ --data-urlencode 'client_ref_id={{transfer_comments}}' \ --data-urlencode 'amount=10' \ --data-urlencode 'currency=SGD' \ --data-urlencode 'purpose_of_transfer={{transfer_purpose}}' Send Domestic Payout Transactions response JSON { "id": "c9535919-cd4d-4b62-4256-a3f89559b452", "client_ref_id": "{{transfer_comments}}", "amount": 10, "fee": 0, "currency": "SGD", "unique_payment_id": "20251208MAYPSGS0BRT1548907", "payment_reference_id": "DEBIT-c9535919-cd4d-4b62-4256-a3f89559b452", "ref_id": "000002F7000000000026000000000018", "purpose_of_transfer": "{{transfer_purpose}}", "transfer_type": "transfer_out", "status": "pending", "description": null, "bank_account": { "id": "9d1a885d-b264-4b73-9057-eec2565a49c3", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "bank_account_number": "5543213122", "bank_holder_name": "MATCHMOV HELLO Success" }, "created_at": "2025-12-08T13:20:31+08:00", "updated_at": null } Domestic Payout API-required fields enumerations : purpose_of_transfer allowed values are listed in the List Domestic Payout Transfer Purpose Enumerations ( GET /v1/users/wallets/payouts/domestic/enumerations/transfer_purpose ) *The enumeration is part of the Payout API category; you can access them by using the {{payouts_base_url}} . See Utilize Enumerations section to learn more. Other field notes: client_ref_id For domestic payouts, this field is used to pass the sender transfer comments {{transfer_comments}} that will be passed to the receiving bank. Once the domestic transfer transaction is sent, its status will initially be set by default to PENDING . The processing time of this transaction will follow the network processing SLA. Since this transaction is asynchronous, notifications on the transaction status updates will be sent via webhooks. Related Links Payouts overview Payout network Domestic payouts Create a recipient for domestic payment Perform a domestic payment Track the status of a domestic payment Simulate a domestic payment Cross-border payouts • [Track the status of a domestic payment](https://developer.matchmove.com/matchmove-banking-operating-system/domestic-payout/track-status-of-domestic-payment.md): Learn about the different status updates you will receive for domestic payments via webhooks. Understand how to interpret these events to track a payment's lifecycle from initiation to completion. The user in this document pertains to both the individual and business user types. Use Cases You want to track the progress of a domestic payment transaction. You want to display the progress and status changes of domestic payment transactions in your application. You want to notify users of real-time status updates of their domestic payment transactions. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. At least one domestic payment has been initiated from the user (sender) account. API Workflow 1 Monitor for domestic payment status The Virtual Account Advisory webhook category is available for partners who want to get timely feedback on virtual account events. Listed below are the webhook events available for domestic payout transactions and the appropriate action required when they are received. Webhook Event Description Required Action CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS (Individual User) BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS (Business User) A notification is sent when a payment to a domestic bank account is successful and completed. No action required CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED (Individual User) BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED (Business User) Notification is sent when a payment to a domestic bank account encounters: an error a timeout a rejection from the recipient bank an invalid recipient bank account No action required An appropriate reversal will be executed for the payment transaction. CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS (Individual User) BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS (Business User) A notification is sent when a payment to a domestic bank account is cancelled by the source (MatchMove) bank. The amount debited from the source account will be reversed. No action required. The user can retry the transfer to the beneficiary. CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED (Individual User) BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED (Business User) A notification is sent when a payment to a domestic bank account is cancelled by the source (MatchMove) bank. The amount debited from the source account was attempted to be reversed, but the system encountered an error. No action required. In the event of a failed reversal, MatchMove will automatically initiate subsequent attempts until the transaction is successfully processed. Go to the Leveraging Webhooks section to learn more about setting up the webhooks. Sample Successful Domestic Payout webhook payload JSON { "consumer": { "consumer_name": "CLIENT NAME", "prefund_balance": "1349581.800000" }, "debit_credit_indicator": "D", "deducted_amount": "1.950000", "fee_charged": "0.000000", "payment_instrument": { "status": "active", "transaction_instrument_id": "hashidofcard", "virtual_account_number": "6377022712345678", "wallet_number": "6377022712345678" }, "time_stamp": "2023-07-27T14:27:45+08:00", "total_amount": "1.950000", "total_currency": "SGD", "transaction": { "client_ref_id": "CLIENREF001", "purpose_of_transfer": "OTHR", "transaction_message": "Transfer to Bank account 12345678 success", "transaction_ref": "DEBIT-generatedtransactionref", "transaction_status": "success", "transfer_out": { "destination_account": { "bank_account_number": "12345678", "bank_code": "DBSSSGS0XXX", "bank_holder_name": "BANK HOLDER NAME" }, "source_account": { "bank_account_number": "6377022712345678", "bank_code": "MAYPSGS0XXX", "bank_holder_name": "MM HOLDER NAME" } } }, "user": { "email": "mmuser@matchmove.com", "kyc_status": "active", "mobile": "12345678", "mobile_country_code": "65", "user_hash": "hashidofuser" }, "webhook_event": "CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS" } Related Links Payouts overview Payout network Domestic payouts Create a recipient for domestic payment Perform a domestic payment Simulate a domestic payment Cross-border payouts • [Simulate domestic payments](https://developer.matchmove.com/matchmove-banking-operating-system/domestic-payout/simulate-a-domestic-payout.md): Learn how to test your complete domestic payment flow in our sandbox environment without moving real money. Use this guide to understand how to validate your integration by simulating various payment outcomes. Domestic payout or transfer out via virtual account is currently only enabled for Singapore-issued virtual accounts. Only bank-to-bank transfers to other local banks participating in the FAST (Fast And Secure Transfers) network are available. The user in this document pertains to both the individual and business user types. Use Cases You want to test a domestic payment transaction using the provisioned user virtual account. You want to test various domestic payment transaction outcome scenarios. You want to simulate sending funds to an external bank account without spending real money. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current deduct_limits and transfer_out_limits must have enough buffer to accommodate the incoming debit amount. The user account must have a balance that is equal to or higher than the payment amount. A valid domestic recipient must have already been defined and must be in an active status. API Workflow 1 Retrieve the list of local banks available for domestic payout Call the List Domestic Payout Transfer Agent Enumerations ( GET /users/wallets/payouts/domestic/enumerations/transfer_agents ) to retrieve the list of available local banks that can receive a domestic transfer. It is important to filter only the active banks during a particular timeframe, as receiving banks may go on maintenance and be unavailable for certain periods of time. In the below example, the status=active filter is added to only retrieve currently available banks for transfer. Please note that the value of the bank code will be agent_code returned in the response. List Domestic Payout Transfer Agent Enumerations request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?status=active' \ --header 'Authorization: ••••••' *Please note that this is a special API that needs to be called in admin scope, without passing X-Auth-User-ID. List Domestic Payout Transfer Agent Enumerations response JSON { "total_records": 37, "records_per_page": 37, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents?page=1&records_per_page=10&return_all=true&status=active", "method": "GET" } ], "data": [ { "agent_code": "ANZBSGS0XXX", "agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/ANZ_BANK.png", "mode": "bank", "name": "ANZ Bank", "status": "active", "bic_code": "ANZBSGS0XXX", "fees": { "fixed": "0.000000", "percentage": "0.000000", "variable": "", "fee_calculation_type": "" }, "transfer_details": [ { "channel_id": "382dd1f29f9411ec875a02b5044dcedc", "channel": "FAST", "min_transfer_amount": "0.01", "max_transfer_amount": "200000.00", "transfer_fulfillment_time": "Instant" } ], "account_number_regex": "^[0-9]*$", "account_number_min_length": "5", "account_number_max_length": "34" }, { "agent_code": "BKCHSGS0XXX", "agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/BANK_OF_CHINA_CREDIT_CARD.png", "mode": "bank", "name": "Bank of China Credit Card", "status": "active", "bic_code": "BKCHSGS0XXX", "fees": { "fixed": "0.000000", "percentage": "0.000000", "variable": "", "fee_calculation_type": "" }, "transfer_details": [ { "channel_id": "382dd1f29f9411ec875a02b5044dcedc", "channel": "FAST", "min_transfer_amount": "0.01", "max_transfer_amount": "200000.00", "transfer_fulfillment_time": "Instant" } ], "account_number_regex": "^[0-9]*$", "account_number_min_length": "5", "account_number_max_length": "34" }, ... more data here ... ] } 2 Create a beneficiary using a naming notation To simulate an intended simulation outcome, we will need to create beneficiaries using the following notation: Naming notation Bankholder Name = First Name + Simulation Outcome e.g. If the intended simulation outcome is to get a successful transaction, the beneficiary bank_holder_name can be John Success Simulation Outcome Description Unavailable Will simulate a Receiving party unavailable error Success Will simulate a successful transaction Invalid Will simulate an invalid receiving account error, and will automatically do an auto debit reversal Other Will simulate other related errors and will automatically do an auto debit reversal Closed Will simulate a beneficiary account closed error, and will automatically do an auto debit reversal Stopped Will simulate a beneficiary account stopped error and will automatically do an auto debit reversal Blocked Will simulate a beneficiary account blocked error, and will automatically do an auto debit reversal Call Create Domestic Payout Recipient s ( POST /users/wallets/payouts/domestic/bank_accounts ) passing the beneficiary details, including the bankholder name, following the naming notation. Create Domestic Payout Recipients request (success outcome) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/bank_accounts' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: : ••••••' \ --header 'X-Auth-User-ID: {{user_id}}' \ --data-urlencode 'bank_account_number=123456' \ --data-urlencode 'bank_holder_name=John Success' \ --data-urlencode 'bank_code={{agent_code}}' Create Domestic Payout Recipients response (success outcome) JSON { "id": "f9ce81d6-47d8-467e-ba74-9c17f92e479f", "bank_account_number": "123456", "bank_holder_name": "John Success", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "mode": "bank", "is_active": 1, "created_at": "2023-07-27T20:06:41+08:00", "updated_at": null } Please take note of the bank account ID of the beneficiary because this will be required on the Simulate a domestic payout step. Otherwise, you can retrieve the same bank account ID by following the Retrieve the bank account ID of the intended beneficiary step. 3 Retrieve the bank account ID of the intended beneficiary Call the List Domestic Payout Recipients ( GET /users/wallets/bank_accounts ) to list down all the defined beneficiaries associated with the active user (sender). List Domestic Payout Recipients request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/bank_accounts' \ --header 'Authorization: ••••••' \ --header 'X-Auth-User-ID: {{user_id}}' List Domestic Payout Recipients response JSON { "total_records": 6, "records_per_page": 10, "total_pages": 1, "page": 1, "links": [ { "rel": "self", "href": "https://{{server}}/{{program_code}}/v1/users/wallets/bank_accounts?page=1&records_per_page=10&return_all=false", "method": "GET" } ], "data": [ { "id": "f9ce81d6-47d8-467e-ba74-9c17f92e479f", "bank_account_number": "123456", "bank_holder_name": "John Success", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "mode": "bank", "is_active": 1, "created_at": "2023-07-27T20:06:41+08:00", "updated_at": null } ... more data here ... ] } Please take note of the bank account ID of the beneficiary, as this will be required during the Simulate a domestic payout step. 4 Simulate a domestic payout Call the Credit Domestic Payout Transactions ( POST /v1/users/wallets/payouts/domestic/fund_transfers/credit ) to simulate a domestic payout transaction. Credit Domestic Payout Transactions request CURL curl --location --request POST 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/fund_transfers/credit' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: : ••••••' \ --data-urlencode 'amount=10' \ --data-urlencode 'bank_account_id=f9ce81d6-47d8-467e-ba74-9c17f92e479f' \ --data-urlencode 'client_ref_id={{transfer_comments}}' \ --data-urlencode 'currency=SGD' \ --data-urlencode 'purpose_of_transfer={{transfer_purpose}}' Credit Domestic Payout Transactions response JSON { "id": "c9535919-cd4d-4b62-4256-a3f89559b452", "client_ref_id": "{{transfer_comments}}", "amount": 10, "fee": 0, "currency": "SGD", "unique_payment_id": "20251208MAYPSGS0BRT1548907", "payment_reference_id": "DEBIT-c9535919-cd4d-4b62-4256-a3f89559b452", "ref_id": "000002F7000000000026000000000018", "purpose_of_transfer": "{{transfer_purpose}}", "transfer_type": "transfer_out", "status": "pending", "description": null, "bank_account": { "id": "f9ce81d6-47d8-467e-ba74-9c17f92e479f", "bank_code": "ANZBSGS0XXX", "bank_name": "ANZ Bank", "bank_account_number": "123456", "bank_holder_name": "John Success" }, "created_at": "2025-12-08T13:20:31+08:00", "updated_at": null } Domestic Payout Webhooks Partners have the option to subscribe to webhook events associated with domestic payout activities. Event Description Action CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS Notification is sent if the transfer is completed and has been acknowledged by the destination bank No action required CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED Notification is sent for any failure cases on the bank transfer No action required. The user can retry the bank transfer CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS Notification is sent if the transfer has been rejected by the destination bank The system will perform a reversal No action required CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED Notification is sent if the transfer has been rejected by the destination bank A reversal performed by the system has failed. No action required. Matchmove will auto-retry the reversal until it is successful Related Links Payouts overview Payout network Domestic payouts Create a recipient for domestic payment Perform a domestic payment Track the status of domestic payment Cross-border payouts • [Cross-border payouts](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts.md): Streamlining Global Financial Transactions International Payouts and Cross-Border Payments International Payouts and Cross-Border Payments refer to the seamless transfer of funds from a sender's account to a recipient in another country. These transactions enable individuals and businesses to conduct cross-border financial activities efficiently and securely. Who is it for? Our International Payouts and Cross-Border Payments solution is designed to cater to a wide range of stakeholders: Business Users Corporations looking to automate global accounts payable, including payments to vendors/suppliers, freelancers, and marketplace purchases. Corporates with global offices, transferring payments for business operations, managing payroll, and reimbursements. Individual Users Remittance by expats and migrants to friends and family in their home country. Purchase expenses - marketplace purchases, imported goods, stock investments, logistics, travel bookings, and many more. Why Choose Our International Payouts and Cross-Border Payments Solution? Global Payments Made Easy : Say goodbye to the hassles, delays, and exorbitant fees associated with traditional banking. Our solution enables you to make global payments to anyone, whether it's an individual or a corporation, without the complexities. Expanded Geographical Reach : Expand your business's reach to new geographies with confidence. Our solution supports transfers to 42 countries and is rapidly expanding, ensuring you can connect with customers and partners worldwide. Competitive Real-Time FX Rates : Enjoy competitive foreign exchange (FX) rates in real-time for currency conversions. Our transparent fee structure ensures you get the best value for your money. Efficient Currency Management : Mitigate currency risk and optimize your financial operations. Take advantage of our quote blocking feature, which allows you to lock in exchange rates for a defined period without requiring recipient information or funds. Monetization Opportunities : Maximize revenue potential by setting up markups and discounts on fees and foreign exchange rates. Our solution empowers you to generate additional income streams from your cross-border payment offerings. Faster Transactions : Experience fast and efficient transaction processing. Most fund transfers arrive on the same day, ranging from instant to T1 day, ensuring your payments are delivered promptly (except for the USA). Superior User Experience : Our user-friendly APIs and seamless transaction fulfillment process ensure a smooth and intuitive experience for both you and your customers. Real-time webhooks enable you to track transaction status and provide timely updates. Regulatory Compliance and Security : Transfer funds globally with confidence. Our solution adheres to strict regulatory compliance and security standards, ensuring the safety and privacy of your transactions. Enhanced Client Servicing : Access comprehensive information and reports through our intuitive one-stop portal, AdminNet. Track corridors, recipients, and transaction details conveniently, enabling you to deliver exceptional client servicing and support. Auto Reconciliation : Say goodbye to the complexities of handling forex and payment reconciliation manually. Our solution automates these processes, saving you time and reducing errors. How does it work? Typical Cross-border Payments workflow The International Payouts and Cross-Border Payments process involves various participants working together seamlessly: Partner Application : Our valued clients integrate our platform into their applications, offering our solutions to their end customers. MatchMove Issued Accounts : Individual and corporate accounts issued by MatchMove, representing the senders in the payment flow. MatchMove : The MatchMove platform offers a comprehensive solution for seamless fund transfers. We ensure the secure passage of funds from the sender to the recipient. Provider : Intermediary parties that MatchMove connects with to provide maximum coverage. We collaborate with trusted providers to ensure global reach and accessibility. Receiving Institutions : The financial institution or entity on the recipient side that has a service relationship with the recipient. This can include banks, mobile wallet providers, or other supported account types in local jurisdictions. Recipient : The individual or corporate entity receiving the funds from the sender. They can be located in any country supported by our solution. Remittance Route An active remittance route should be available before we can initiate a remittance transaction. The enabled routes are configured at the program level as outlined in the contract. Though a remittance route is enabled, it needs to be on available and in an active status to be usable. Several factors can affect a remittance route: 1. Recipient Country The receiving country or region of the cross-border payment. 2. Recipient Institution Type The termination point or the receiving institution of the remittance. e.g., banks, mobile wallets, etc. 2. Remittance Modes The sender type and the recipient type determine the mode of remittance. The list of enabled remittance modes activated for a program is dependent on the contract and program configuration. B2B remittance mode The sender account type is a Business (Corporate) , and the recipient account type is also a Business (Corporate) . B2C remittance mode The sender account type is a Business (Corporate) , and the recipient account type is a Consumer (Individual) . C2B remittance mode The sender account type is a Consumer (Individual) , and the recipient account type is a Business (Corporate) . C2C remittance mode The sender account type is a Consumer (Individual) , and the recipient account type is a Consumer (Individual) . 3. Remittance Rails Each corridor will have an option on which remittance rail the transaction will be processed on. LOCAL Remittances will be processed using the local transfer networks available in the receiving country. Maximum per transaction limit : Varies depending on the corridor and remittance mode. Maximum transacition velocity per N days : Varies depending on the corridor limit. Delivery timeline : 30 minutes to T+1 as long as transactions are initiated within the cut-off time. Cut-off time is dependent on the corridor setting. Quote expiry : 30 minutes to 1 hour Sender name in the transaction: The Sender name sent as part of sender remarks when the transaction is sent will be forwarded to the receiving partner by Matchmove. However, it depends on the receiving institution to display the Sender name in the recipient transaction statements. SWIFT Remittances will be processed using the SWIFT rail from the sender country to the receiving country. Maximum per transaction limit : Normally, transactions can go as high as up to 1 million USD . For transaction value greater than the review threshold amount* , a supplementary document (such as invoices) is mandatory to be uploaded. While, transactions exceeding 1 Million USD , will need to undergo a pre-approval process where additional documents will be solicited offline and approval must be given prior to the initiation of the transaction. * review threshold amount — is a product internal threshold that is set based on risk and may change without notice. Maximum transaction velocity per N days : Varies depending on the corridor limit. Delivery timeline : T+1 as long as transactions are initiated within the cut-off time. Cut-off time: 4:30 PM SGT on the working days excluding bank holidays. Quote expiry : Same currency transfer - up to 10 hours Cross currency transfer - 5 mins Sender name in the transaction: SWIFT will be using the payments-on-behalf-of (POBO) model. Where transactions are processed by a third-party service ( Payment Rail Provider ) on behalf of a business and individual senders. As such, the sender name that will be in the transaction and recipient bank statement is the Payment Rail Provider name, and not the sender details. The MT103 files will also contain the same details irrespective of what information is sent in transaction remarks . The enablement of the remittance routes is based on the enabled routes in the program configuration. This program configuration aligns with the capabilities and features outlined in the contract. Route example 1: (SGP to USA, B2B, Bank, via SWIFT), where the remittance corridor is open for transfer from Singapore to the USA, for Business (sender) to Business (recipient), the receiving institution can be a bank, and the remittance will be processed via the SWIFT network. Route example 2: (SGP to USA, B2B, Bank, via LOCAL), where the remittance corridor is open for transfer from Singapore to the USA, for Business (sender) to Business (recipient), the receiving institution can be a bank, and the remittance will be processed using LOCAL transfer networks available in the receiving region. The availability of the remittance routes can be affected by maintenance schedules on the remittance rail. So it is important to check whether a certain remittance route is active before a remittance transaction is attempted. Components of a Cross-border Payout Successfully sending a cross-border payout or international remittance requires two key components. Remittance Recipient A recipient entity must be defined according to the remittance form requirements of a selected Remittance Route. The remittance form requirements should include the address, bank account details, and other key information required by the regulatory body of the recipient region. The recipient details defined in the recipient profile will be used for risk evaluation. A recipient can only be used for a remittance transaction if its status is active . Remittance Quotation A remittance quotation is a snapshot of the rate and computation of the charges that will be applied to send a particular remittance transaction. A quotation can be generated by providing the intended amount to be remitted and the remittance route details. A quotation can be used for a remittance transaction as long as it is valid and unexpired. 1. Remittance Recipient The platform can send remittance transactions to two types of receiving entities: Individual recipient (Consumer) Consumer information from the individual will be gathered to ensure compliance with the remittance regulatory standards of the receiving country. Business recipient (Corporate) Corporate information from the business will be gathered to ensure compliance with the remittance regulatory standards of the receiving country. Recipient Creation Methods A remittance recipient, regardless of type, can be defined in two ways: Pre-transaction creation - creating a remittance recipient before the actual sending of the remittance transaction. In-transaction creation - creating a remittance recipient alongside the sending of the remittance transaction. When a new remittance recipient is created, it will go through a series of stages before becoming active and ready to use. Recipient Status Only when a remittance recipient is on the active state, will it be allowed to be used for sending a remittance transaction. Status Description CREATED The initial state right after the recipient creation PENDING The risk evaluation is in progress and/or the recipient is in a cooling period state. ACTIVE The recipient is cleared for risk, and the sending of remittance is enabled BLOCKED The recipient is permanently disabled due to the risk. This state is permanent and irreversible DELETED The recipient is removed from the user's recipient list. This state is permanent and irreversible INACTIVE The recipient is temporarily disabled. The state is reversible by reactivation UPDATE_REQUIRED The recipient needs to be updated, because the recipient form fields were updated FAILED The recipient creation failed due to a system error. DEACTIVATED Deprecated as of May 2025 and is replaced by the INACTIVE status. PENDING_REVIEW Deprecated as of May 2025 and is replaced by the PENDING status. Recipient Cooling-Off Period A cooling-off period is a mandatory waiting timeframe imposed on payout recipients during which certain account functionalities, such as withdrawals or transfers, are temporarily restricted. This regulatory safeguard is designed to prevent system abuse by slowing down the velocity of movement, providing a "buffer" to detect and intercept fraudulent activity or unauthorized access. By disabling specific recipient interactions during this window, financial systems can ensure that high-risk actions are verified and intentional before the funds or services become fully accessible again. In MatcMove, the cooling period is effective between recipient creation to activation. It serves as a fraud prevention measure, providing a buffer window during which suspicious activity can be detected before the recipient becomes eligible for payouts. The cooling period starts immediately upon recipient creation and runs in parallel with the risk evaluation. Neither process waits for the other — both must independently complete before the recipient can become ACTIVE . 2. Remittance Quotation When a remittance quotation is generated, the rates and fees will be locked and reserved for a certain period of time. During this time, the quotation can be used for a remittance transaction with the locked computed rates and fees. A quotation will be marked with an expiry timestamp, e.g. "expiry": "2024-04-04T16:31:01 +08:00" , indicating the period on until when it can be used. Also, a quotation and quotation ID can only be used by one remittance transaction. When a quotation is consumed or expired, a fresh quotation must be generated for the transaction. Quotation Modifiers In addition to the intended amount to be remitted and the remittance route details, a few additional modifier fields may be required: Quotation Type Description Variant Supported Use Case Result FORWARD quotation User inputs the sender amount in the sender's currency. Then the recipient amount will be calculated. Fee Included The sender has a fixed amount to be sent (budget), and the fee needs to be included in that amount. e.g., Remittance to families in a home country. The fees will be deducted from the Sender amount (Sender amount - fees), which will decrease the Recipient amount (Converted Sender amount - fees). While the Sender deductible (wallet debit) will remain unchanged (Sender amount). Fee excluded The sender wants to convert the amount to be sent and pay for the additional fees the remittance will incur. e.g., Employee salary, freelancer payments, bill payments in a different currency The fees will not be deducted from the Sender amount (Sender amount), and the Recipient amount will remain intact (Converted Sender amount) While the Sender deductible (wallet debit) will be added with fees (Sender amount + Fees) REVERSE quotation User inputs the recipient amount in the recipient's currency. Then the sender's deductible amount will be calculated. Fee excluded User wants to send a fixed amount in the recipient's currency to the recipient. e.g., Marketplace payments, invoice payments for goods purchased in the destination country. The fees will not be deducted from the *Derived Sender amount (Derived Sender amount), and the Recipient amount will remain intact (Converted Sender amount) While the Sender deductible (wallet debit) will be added with fees (Sender amount + Fees) *Derived sender amount = Recipient amount / FX rate Cross-Border Payout Transaction Lifecycle Every cross-border payout on MatchMove follows one consistent lifecycle, whichever payment provider or rail carries it. We translate each payment provider's own statuses into a single, unified set, so you integrate once and your logic keeps working as we add payment providers. What this gives you: One set of statuses to handle, with no overlapping or ambiguous codes. Clear ownership: you can tell whether a transaction is waiting on MatchMove or on the payment provider. Predictable refunds: every failure path ends with the user's funds returned or held for compliance, never left in limbo. State transitions The previous states were too coarse to show what was really happening with a payment. Different situations shared the same status, so it was hard to tell where the user's money was, who was holding a payment up, or whether a refund had completed. For example: Debit and processing: a payment could show SUCCESS or sit in a generic PROCESSING state just because the user's wallet had been debited. Late exceptions: SUCCESS was treated as final, even though a downstream bank can still freeze funds after a payment succeeds. Reversals: a reversal from the payment provider did not mean the user's wallet had been refunded yet. The updated states give each of these situations its own status, so you get a clearer and more accurate picture of what is really happening with each payment, and what, if anything, to tell the user. The table below shows each deprecated state, the event that triggers the change, and the updated state. Trigger / Event Origin State Next State Payment intent created START INITIATED Payload validation and user risk check INITIATED PROCESSING Manual internal compliance check required PROCESSING UNDER_REVIEW Check fails (before debit) PROCESSING FAILED Review denied (before debit) UNDER_REVIEW REJECTED Wallet debit successful PROCESSING FUNDS_SECURED Recipient risk check passed FUNDS_SECURED CONFIRMED Check fails (after debit) CONFIRMED FAILED Dispatched to payment provider CONFIRMED SUBMITTED Payment provider reports pending, processing or initiated SUBMITTED PENDING Payment provider reports RFI SUBMITTED / PENDING UNDER_REVIEW Payment provider reports success SUBMITTED / PENDING SUCCESS Payment provider reports failed or cancelled SUBMITTED / PENDING FAILED Payment provider reports success (RFI cleared) UNDER_REVIEW SUCCESS Payment provider reports rejected or declined UNDER_REVIEW REJECTED Payment provider sends an explicit reversal SUCCESS PAYMENT_REVERSED Payment provider sends a delayed failed or cancelled SUCCESS DECLINED RFI raised by counterparty SUCCESS UNDER_REVIEW RFI cleared UNDER_REVIEW SUCCESS RFI failed (manual resolution) UNDER_REVIEW REJECTED Wallet refund processed (if debited) FAILED / REJECTED FUNDS_REVERSED Payment provider reversal finalized PAYMENT_REVERSED FUNDS_REVERSED Understanding transaction statuses Use this table to see where a transaction is and what, if anything, your application should do. A payment that fails before FUNDS_SECURED needs no refund, because the user's wallet was never debited. Updated status (new) Sub-status What it means Recommended action INITIATED TRANSACTION_INITIATED Request accepted and queued. If documents are required, submit them via the API. PROCESSING USER_STATUS_ACTIVE , USER_STATUS_INACTIVE , USER_STATUS_CHECK_FAILED Sender account and quote are being validated. Active proceeds. Inactive or failed ends as FAILED ; check the API response for required actions. UNDER_REVIEW PLATFORM_REVIEW_IN_PROGRESS , DOCUMENT_REQUIRED MatchMove's risk checks flagged the payment for manual compliance review. None, unless documents are requested. FUNDS_SECURED FUNDS_DEBIT_SUCCESS , FUNDS_DEBIT_FAILED The user's wallet is debited and the funds are held by MatchMove. If the debit failed, the transaction becomes FAILED ; check the user's wallet balance. CONFIRMED RECIPIENT_RISK_CHECK_COMPLETE , RECIPIENT_RISK_REJECTED Recipient checks are done and the payment is ready for submission. If rejected, verify the recipient details before retrying. SUBMITTED TRANSACTION_SUBMITTED Sent to the payment provider, who has acknowledged receipt. The outcome is not yet confirmed. None. PENDING TRANSACTION_IN_PROGRESS The payment provider is processing or settling the payment. None. UNDER_REVIEW INITIATED , MORE_INFO_REQUIRED , REVIEW_IN_PROGRESS The payment provider paused the payment for a compliance review or Request for Information (RFI). Check webhook payloads. You may need to collect extra KYC or beneficiary details from the user. SUCCESS TRANSACTION_SUCCESS The payment cleared the external network. None, unless a late exception occurs. FAILED TRANSACTION_FAILED A technical or operational failure before or during payment provider processing, such as a timeout, payment provider outage, insufficient balance or a failed pre-submission check. The user's funds are refunded automatically if already debited. Retry if appropriate. REJECTED TRANSACTION_REJECTED , COMPLIANCE_REJECTED The payment failed a compliance or risk check: a denied internal review, or a payment provider review or RFI that ended in disqualification or timeout. Do not simply retry. Resolve the underlying compliance or KYC issue first. The user's funds are refunded, and may be held in a compliance account before they are released. PAYMENT_REVERSED TRANSACTION_REVERSED The payment provider recalled the payment, for example an ACH return or chargeback. Wait for fee calculation to finish. MatchMove calculates any FX adjustments and network or chargeback fees, then returns the principal. REJECTED MANUAL_RESOLUTION_REQUIRED A compliance RFI failed and automated refunds are paused. Open a support ticket with MatchMove to resolve the frozen funds. FUNDS_REVERSED FUNDS_REVERSED_SUCCESS Funds were credited back to the user's wallet after a failure, rejection, decline or reversal. None. The user's balance is restored. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts • [Create a recipient for cross-border payment](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/create-a-recipient-for-cross-border-payment.md): Learn how to securely store a beneficiary's details for future cross-border payments, supporting both bank accounts and remittance providers. This guide helps you understand the process of creating reusable recipient profiles for these transfers. The user in this document pertains to both the individual and business user types. Sender Account Types The platform can send remittance transactions from two types of sender entities : Individual (Consumer) An individual user is a customer onboarded on the platform by submitting personal information to create their user profile. These users were also required to submit KYC documents and have them approved before they could initiate a remittance transaction. Business (Corporate) A business user is a customer onboarded on the platform by submitting business information to create their user profile. These users were also required to submit their KYB documents and have them approved before they could initiate a remittance transaction. Recipient Account Types The platform can send remittance transactions to two types of receiving entities : Individual (Consumer) Consumer information from the individual will be gathered to ensure compliance with the remittance regulatory standards of the receiving country. Business (Corporate) Corporate information from the business will be gathered to ensure compliance with the remittance regulatory standards of the receiving country. Use Cases You want to implement a feature that will allow users to withdraw funds to any local and international bank accounts. You want to implement a feature that will allow users to define their beneficiary recipient before performing a cross-border payment transaction. You want to implement a feature that will allow an individual user to define an individual recipient (C2C remittance mode). You want to implement a feature that will allow a business user to define an individual recipient (B2C remittance mode). You want to implement a feature that will allow a business user to define a business recipient (B2B remittance mode). You want to implement a feature that will allow users to reuse their previously defined recipients for a cross-border payment. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. API Workflow 1 Retrieve the available corridors (remittance routes) for the program Before asking the user (sender) any of their intended remittance details, we need to know the available corridors or remittance routes that are enabled in the program. Corridor enablement will be based on the program configuration (as stated in the contract) along with the remittance rail and SWIFT routes availability. Call the List Cross-border Payout Corridors ( GET /users/wallet/payouts/remittances/corridors ) filtering only the active routes based on the user type of the customer (sender). List Cross-border Payout Corridors request (filter by status and user_type [sender], recipient_type [receiver]) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?status=ACTIVE&recipient_type=INDIVIDUAL&user_type=INDIVIDUAL' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Cross-border Payout Corridors response JSON { "pagination": { "total_records": 5, "records_per_page": 100, "total_pages": 1, "links": { "self": "https://{{server}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?page=1&records_per_page=100&user_type=INDIVIDUAL&recipient_type=INDIVIDUAL" } }, "data": [ { "id": "4b007556de30487d8fd7df0e53d07bd7", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "LOCAL", "charge_types": [], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "0823dde9bcf847bc97723395bb7b69aa", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "1a65c300fe594e18bb1ad9fff831b1b7", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Singapore Dollar", "currency_code": "SGD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "b61d6b7ee37a4708b0c36e9c3cbb7883", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Euro", "currency_code": "EUR", "currency_precision": "2", "status": "ACTIVE" }, { "id": "e6ab8a36a9ca41b7962a2e04948b74ce", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Pound Sterling", "currency_code": "GBP", "currency_precision": "2", "status": "ACTIVE" } ] } You will need to display the list of active corridors available to your users in your frontend. To help the user choose, you will need to display the additional rail parameters, such as payment_rails and charge_types . LOCAL From the corridor list response above, we will see this corridor with a payment_rail set to LOCAL. This means that, if the user decides to use this corridor, his remittance will be sent and processed using the local payment rails that exist in the receiving country. *There are no available charge_types for LOCAL payment rails. This option is only available on SWIFT. { "id": "4b007556de30487d8fd7df0e53d07bd7", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "LOCAL", "charge_types": [], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE } SWIFT Subsequently, we will see this corridor with a payment_rail set to SWIFT. If the user (sender) decides to use this corridor, his remittance will be sent and processed using the global SWIFT network from the sender country to the receiving country. SWIFT transfers also offers charge_types which indicates how the transfer fees will be collected. SHA - overall fees will be shared between the Sender and the Recipient OUR - the entire fee will be borne by the sender. *For SHA, the shared fees charged to the recipient will be charged directly by the receiving institution of the recipient the without the pariticipation of MatchMove. { "id": "0823dde9bcf847bc97723395bb7b69aa", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE" } 2 Define a remittance recipient Once the user has verified that there is an active corridor for his intended recipient country, we can proceed to define a remittance recipient using the following details: Receiving Country & Currency The intended recipient region and currency Sender Type The user type of the sender e.g., {INDIVIDUAL, BUSINESS} Receiver Type The recipient type or the receiver, e.g. {INDIVIDUAL, BUSINESS} Payment Rail The intended payment rail, e.g. {LOCAL, SWIFT} Before we can define a recipient, we will need to know the list of information that is required to define a recipient. Since each region has different regulatory rules and guidelines, the required information on remittance recipients will also differ. Call List Cross-border Payout Recipient Forms ( GET /users/wallets/payouts/remittances/recipients/forms ) to get the list of information required to define a recipient for a specific remittance route. Since these routes differ from each other, the list or form that contains dynamic fields is based on the region requirements at the time it was queried. As regulatory rules evolve, these field requirements may update from time to time. List Cross-border Payout Recipient Forms request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients/forms?recipient_type=INDIVIDUAL&recipient_country=USA&payment_rail=SWIFT' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' *When the payment_rail filter is not specified, the request will default to LOCAL. List Cross-border Payout Recipient Forms response JSON { "version": "1", "recipient_form": [ { "field_group_key": "bank_details", "field_group_label": "Bank Details", "fields": [ { "field_key": "account_number", "field_label": "Bank Account Number", "field_type": "string", "is_mandatory": true, "is_editable": false, "validation": { "max_length": 50, "min_length": 1, "regex": "^[a-zA-Z0-9]*$" }, "field_category": "Bank Details" }, { "field_key": "account_name", "field_label": "Bank Account Name", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 50, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "Bank Details" }, { "field_key": "account_type", "field_label": "Bank Account Type", "field_type": "string", "is_mandatory": true, "is_editable": false, "enum_key": "account_type", "values_supported": [ { "code": "SAVINGS_ACCOUNT", "description": "Savings Account", "value": "Savings Account" }, { "code": "CURRENT_ACCOUNT", "description": "Current Account", "value": "Current Account" } ], "field_category": "Bank Details" }, { "field_key": "code", "field_label": "SWIFT Code", "field_type": "string", "is_mandatory": true, "is_editable": false, "validation": { "max_length": 11, "min_length": 8, "regex": "^[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?$" }, "field_category": "Bank Details" }, { "field_key": "bank_id", "field_label": "Bank Name", "field_type": "string", "is_mandatory": true, "is_editable": false, "field_category": "Bank Details" } ] }, { "field_group_key": "address_details", "field_group_label": "Address Details", "fields": [ { "field_key": "address_line_1", "field_label": "Address Line 1", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 30, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "address_line_2", "field_label": "Address Line 2", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 30, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "address_line_3", "field_label": "Address Line 3", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 30, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "address_line_4", "field_label": "Address Line 4", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 30, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "city", "field_label": "City", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 50, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "state", "field_label": "State/Province", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 50, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,-_)('‘’‚‛′]+$" }, "field_category": "Address Details" }, { "field_key": "postal_code", "field_label": "Postal Code", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 20, "min_length": 1 }, "field_category": "Address Details" }, { "field_key": "country", "field_label": "Country", "field_type": "string", "is_mandatory": true, "is_editable": true, "values_supported": [ { "code": "AUT", "description": "Austria", "value": "Austria" }, { "code": "AND", "description": "Andorra", "value": "Andorra" }, { "code": "ARE", "description": "United Arab Emirates", "value": "United Arab Emirates" }, { "code": "AFG", "description": "Afghanistan", "value": "Afghanistan" }, { "code": "ATG", "description": "Antigua And Barbuda", "value": "Antigua And Barbuda" }, { "code": "AIA", "description": "Anguilla", "value": "Anguilla" }, { "code": "ALB", "description": "Albania", "value": "Albania" }, { "code": "ARM", "description": "Armenia", "value": "Armenia" }, { "code": "AGO", "description": "Angola", "value": "Angola" }, { "code": "ATA", "description": "Antarctica", "value": "Antarctica" }, { "code": "ARG", "description": "Argentina", "value": "Argentina" }, { "code": "ASM", "description": "American Samoa", "value": "American Samoa" }, { "code": "AUS", "description": "Australia", "value": "Australia" }, { "code": "ABW", "description": "Aruba", "value": "Aruba" }, { "code": "ALA", "description": "Åland Islands", "value": "Åland Islands" }, { "code": "AZE", "description": "Azerbaijan", "value": "Azerbaijan" }, { "code": "BIH", "description": "Bosnia & Herzegovina", "value": "Bosnia & Herzegovina" }, { "code": "BRB", "description": "Barbados", "value": "Barbados" }, { "code": "BGD", "description": "Bangladesh", "value": "Bangladesh" }, { "code": "BEL", "description": "Belgium", "value": "Belgium" }, { "code": "BFA", "description": "Burkina Faso", "value": "Burkina Faso" }, { "code": "BGR", "description": "Bulgaria", "value": "Bulgaria" }, { "code": "BHR", "description": "Bahrain", "value": "Bahrain" }, { "code": "BDI", "description": "Burundi", "value": "Burundi" }, { "code": "BEN", "description": "Benin", "value": "Benin" }, { "code": "BLM", "description": "Saint Barthélemy", "value": "Saint Barthélemy" }, { "code": "BMU", "description": "Bermuda", "value": "Bermuda" }, { "code": "BRN", "description": "Brunei Darussalam", "value": "Brunei Darussalam" }, { "code": "BOL", "description": "Bolivia, Plurinational State Of", "value": "Bolivia, Plurinational State Of" }, { "code": "BRA", "description": "Brazil", "value": "Brazil" }, { "code": "BHS", "description": "Bahamas", "value": "Bahamas" }, { "code": "BTN", "description": "Bhutan", "value": "Bhutan" }, { "code": "BVT", "description": "Bouvet Island", "value": "Bouvet Island" }, { "code": "BWA", "description": "Botswana", "value": "Botswana" }, { "code": "BLR", "description": "Belarus", "value": "Belarus" }, { "code": "BLZ", "description": "Belize", "value": "Belize" }, { "code": "CAN", "description": "Canada", "value": "Canada" }, { "code": "CCK", "description": "Cocos (Keeling) Islands", "value": "Cocos (Keeling) Islands" }, { "code": "COD", "description": "Democratic Republic Of Congo", "value": "Democratic Republic Of Congo" }, { "code": "CAF", "description": "Central African Republic", "value": "Central African Republic" }, { "code": "COG", "description": "Republic Of Congo", "value": "Republic Of Congo" }, { "code": "CHE", "description": "Switzerland", "value": "Switzerland" }, { "code": "CIV", "description": "Cote d'Ivoire", "value": "Cote d'Ivoire" }, { "code": "COK", "description": "Cook Islands", "value": "Cook Islands" }, { "code": "CHL", "description": "Chile", "value": "Chile" }, { "code": "CMR", "description": "Cameroon", "value": "Cameroon" }, { "code": "CHN", "description": "China", "value": "China" }, { "code": "COL", "description": "Colombia", "value": "Colombia" }, { "code": "CRI", "description": "Costa Rica", "value": "Costa Rica" }, { "code": "CUB", "description": "Cuba", "value": "Cuba" }, { "code": "CPV", "description": "Cabo Verde", "value": "Cabo Verde" }, { "code": "CXR", "description": "Christmas Island", "value": "Christmas Island" }, { "code": "CYP", "description": "Cyprus", "value": "Cyprus" }, { "code": "CZE", "description": "Czech Republic", "value": "Czech Republic" }, { "code": "DEU", "description": "Germany", "value": "Germany" }, { "code": "DJI", "description": "Djibouti", "value": "Djibouti" }, { "code": "DNK", "description": "Denmark", "value": "Denmark" }, { "code": "DMA", "description": "Dominica", "value": "Dominica" }, { "code": "DOM", "description": "Dominican Republic", "value": "Dominican Republic" }, { "code": "DZA", "description": "Algeria", "value": "Algeria" }, { "code": "ECU", "description": "Ecuador", "value": "Ecuador" }, { "code": "EST", "description": "Estonia", "value": "Estonia" }, { "code": "EGY", "description": "Egypt", "value": "Egypt" }, { "code": "ESH", "description": "Western Sahara", "value": "Western Sahara" }, { "code": "ERI", "description": "Eritrea", "value": "Eritrea" }, { "code": "ESP", "description": "Spain", "value": "Spain" }, { "code": "ETH", "description": "Ethiopia", "value": "Ethiopia" }, { "code": "FIN", "description": "Finland", "value": "Finland" }, { "code": "FJI", "description": "Fiji", "value": "Fiji" }, { "code": "FLK", "description": "Falkland Islands", "value": "Falkland Islands" }, { "code": "FSM", "description": "Micronesia, Federated States Of", "value": "Micronesia, Federated States Of" }, { "code": "FRO", "description": "Faroe Islands", "value": "Faroe Islands" }, { "code": "FRA", "description": "France", "value": "France" }, { "code": "FXX", "description": "France, Metropolitan", "value": "France, Metropolitan" }, { "code": "GAB", "description": "Gabon", "value": "Gabon" }, { "code": "GBR", "description": "United Kingdom", "value": "United Kingdom" }, { "code": "GRD", "description": "Grenada", "value": "Grenada" }, { "code": "GEO", "description": "Georgia", "value": "Georgia" }, { "code": "GUF", "description": "French Guiana", "value": "French Guiana" }, { "code": "GGY", "description": "Guernsey", "value": "Guernsey" }, { "code": "GHA", "description": "Ghana", "value": "Ghana" }, { "code": "GIB", "description": "Gibraltar", "value": "Gibraltar" }, { "code": "GRL", "description": "Greenland", "value": "Greenland" }, { "code": "GMB", "description": "Gambia", "value": "Gambia" }, { "code": "GIN", "description": "Guinea", "value": "Guinea" }, { "code": "GLP", "description": "Guadeloupe", "value": "Guadeloupe" }, { "code": "GNQ", "description": "Equatorial Guinea", "value": "Equatorial Guinea" }, { "code": "GRC", "description": "Greece", "value": "Greece" }, { "code": "SGS", "description": "South Georgia And The South Sandwich Islands", "value": "South Georgia And The South Sandwich Islands" }, { "code": "GTM", "description": "Guatemala", "value": "Guatemala" }, { "code": "GUM", "description": "Guam", "value": "Guam" }, { "code": "GNB", "description": "Guinea-bissau", "value": "Guinea-bissau" }, { "code": "GUY", "description": "Guyana", "value": "Guyana" }, { "code": "HKG", "description": "Hong Kong", "value": "Hong Kong" }, { "code": "HMD", "description": "Heard Island And McDonald Islands", "value": "Heard Island And McDonald Islands" }, { "code": "HND", "description": "Honduras", "value": "Honduras" }, { "code": "HRV", "description": "Croatia", "value": "Croatia" }, { "code": "HTI", "description": "Haiti", "value": "Haiti" }, { "code": "HUN", "description": "Hungary", "value": "Hungary" }, { "code": "IDN", "description": "Indonesia", "value": "Indonesia" }, { "code": "IRL", "description": "Ireland", "value": "Ireland" }, { "code": "ISR", "description": "Israel", "value": "Israel" }, { "code": "IMN", "description": "Isle Of Man", "value": "Isle Of Man" }, { "code": "IND", "description": "India", "value": "India" }, { "code": "IOT", "description": "British Indian Ocean Territory", "value": "British Indian Ocean Territory" }, { "code": "IRQ", "description": "Iraq", "value": "Iraq" }, { "code": "IRN", "description": "Iran, Islamic Republic Of", "value": "Iran, Islamic Republic Of" }, { "code": "ISL", "description": "Iceland", "value": "Iceland" }, { "code": "ITA", "description": "Italy", "value": "Italy" }, { "code": "JEY", "description": "Jersey", "value": "Jersey" }, { "code": "JAM", "description": "Jamaica", "value": "Jamaica" }, { "code": "JOR", "description": "Jordan", "value": "Jordan" }, { "code": "JPN", "description": "Japan", "value": "Japan" }, { "code": "KEN", "description": "Kenya", "value": "Kenya" }, { "code": "KGZ", "description": "Kyrgyzstan", "value": "Kyrgyzstan" }, { "code": "KHM", "description": "Cambodia", "value": "Cambodia" }, { "code": "KIR", "description": "Kiribati", "value": "Kiribati" }, { "code": "COM", "description": "Comoros", "value": "Comoros" }, { "code": "KNA", "description": "Saint Kitts And Nevis", "value": "Saint Kitts And Nevis" }, { "code": "PRK", "description": "Korea, Democratic People's Republic Of", "value": "Korea, Democratic People's Republic Of" }, { "code": "KOR", "description": "Korea, Republic Of", "value": "Korea, Republic Of" }, { "code": "KWT", "description": "Kuwait", "value": "Kuwait" }, { "code": "CYM", "description": "Cayman Islands", "value": "Cayman Islands" }, { "code": "KAZ", "description": "Kazakhstan", "value": "Kazakhstan" }, { "code": "LAO", "description": "Lao People's Democratic Republic", "value": "Lao People's Democratic Republic" }, { "code": "LBN", "description": "Lebanon", "value": "Lebanon" }, { "code": "LCA", "description": "Saint Lucia", "value": "Saint Lucia" }, { "code": "LIE", "description": "Liechtenstein", "value": "Liechtenstein" }, { "code": "LKA", "description": "Sri Lanka", "value": "Sri Lanka" }, { "code": "LBR", "description": "Liberia", "value": "Liberia" }, { "code": "LSO", "description": "Lesotho", "value": "Lesotho" }, { "code": "LTU", "description": "Lithuania", "value": "Lithuania" }, { "code": "LUX", "description": "Luxembourg", "value": "Luxembourg" }, { "code": "LVA", "description": "Latvia", "value": "Latvia" }, { "code": "LBY", "description": "Libya", "value": "Libya" }, { "code": "MAR", "description": "Morocco", "value": "Morocco" }, { "code": "MCO", "description": "Monaco", "value": "Monaco" }, { "code": "MDA", "description": "Moldova", "value": "Moldova" }, { "code": "MNE", "description": "Montenegro", "value": "Montenegro" }, { "code": "MAF", "description": "Saint Martin", "value": "Saint Martin" }, { "code": "MDG", "description": "Madagascar", "value": "Madagascar" }, { "code": "MHL", "description": "Marshall Islands", "value": "Marshall Islands" }, { "code": "MKD", "description": "Macedonia, The Former Yugoslav Republic Of", "value": "Macedonia, The Former Yugoslav Republic Of" }, { "code": "MLI", "description": "Mali", "value": "Mali" }, { "code": "MMR", "description": "Myanmar", "value": "Myanmar" }, { "code": "MNG", "description": "Mongolia", "value": "Mongolia" }, { "code": "MAC", "description": "Macao", "value": "Macao" }, { "code": "MNP", "description": "Northern Mariana Islands", "value": "Northern Mariana Islands" }, { "code": "MTQ", "description": "Martinique", "value": "Martinique" }, { "code": "MRT", "description": "Mauritania", "value": "Mauritania" }, { "code": "MSR", "description": "Montserrat", "value": "Montserrat" }, { "code": "MLT", "description": "Malta", "value": "Malta" }, { "code": "MUS", "description": "Mauritius", "value": "Mauritius" }, { "code": "MDV", "description": "Maldives", "value": "Maldives" }, { "code": "MWI", "description": "Malawi", "value": "Malawi" }, { "code": "MEX", "description": "Mexico", "value": "Mexico" }, { "code": "MYS", "description": "Malaysia", "value": "Malaysia" }, { "code": "MOZ", "description": "Mozambique", "value": "Mozambique" }, { "code": "NAM", "description": "Namibia", "value": "Namibia" }, { "code": "NCL", "description": "New Caledonia", "value": "New Caledonia" }, { "code": "NER", "description": "Niger", "value": "Niger" }, { "code": "NFK", "description": "Norfolk Island", "value": "Norfolk Island" }, { "code": "NGA", "description": "Nigeria", "value": "Nigeria" }, { "code": "NIC", "description": "Nicaragua", "value": "Nicaragua" }, { "code": "NLD", "description": "Netherlands", "value": "Netherlands" }, { "code": "NOR", "description": "Norway", "value": "Norway" }, { "code": "NPL", "description": "Nepal", "value": "Nepal" }, { "code": "NRU", "description": "Nauru", "value": "Nauru" }, { "code": "NIU", "description": "Niue", "value": "Niue" }, { "code": "NZL", "description": "New Zealand", "value": "New Zealand" }, { "code": "OMN", "description": "Oman", "value": "Oman" }, { "code": "PAN", "description": "Panama", "value": "Panama" }, { "code": "PER", "description": "Peru", "value": "Peru" }, { "code": "PYF", "description": "French Polynesia", "value": "French Polynesia" }, { "code": "PNG", "description": "Papua New Guinea", "value": "Papua New Guinea" }, { "code": "PHL", "description": "Philippines", "value": "Philippines" }, { "code": "PAK", "description": "Pakistan", "value": "Pakistan" }, { "code": "POL", "description": "Poland", "value": "Poland" }, { "code": "SPM", "description": "Saint Pierre And Miquelon", "value": "Saint Pierre And Miquelon" }, { "code": "PCN", "description": "Pitcairn", "value": "Pitcairn" }, { "code": "PRI", "description": "Puerto Rico", "value": "Puerto Rico" }, { "code": "PSE", "description": "Palestinian Territory, Occupied", "value": "Palestinian Territory, Occupied" }, { "code": "PRT", "description": "Portugal", "value": "Portugal" }, { "code": "PLW", "description": "Palau", "value": "Palau" }, { "code": "PRY", "description": "Paraguay", "value": "Paraguay" }, { "code": "QAT", "description": "Qatar", "value": "Qatar" }, { "code": "REU", "description": "Reunion", "value": "Reunion" }, { "code": "ROU", "description": "Romania", "value": "Romania" }, { "code": "SRB", "description": "Serbia", "value": "Serbia" }, { "code": "RUS", "description": "Russian Federation", "value": "Russian Federation" }, { "code": "RWA", "description": "Rwanda", "value": "Rwanda" }, { "code": "SAU", "description": "Saudi Arabia", "value": "Saudi Arabia" }, { "code": "SLB", "description": "Solomon Islands", "value": "Solomon Islands" }, { "code": "SYC", "description": "Seychelles", "value": "Seychelles" }, { "code": "SDN", "description": "Sudan", "value": "Sudan" }, { "code": "SWE", "description": "Sweden", "value": "Sweden" }, { "code": "SGP", "description": "Singapore", "value": "Singapore" }, { "code": "SHN", "description": "Saint Helena, Ascension And Tristan Da Cunha", "value": "Saint Helena, Ascension And Tristan Da Cunha" }, { "code": "SVN", "description": "Slovenia", "value": "Slovenia" }, { "code": "SJM", "description": "Svalbard And Jan Mayen", "value": "Svalbard And Jan Mayen" }, { "code": "SVK", "description": "Slovakia", "value": "Slovakia" }, { "code": "SLE", "description": "Sierra Leone", "value": "Sierra Leone" }, { "code": "SMR", "description": "San Marino", "value": "San Marino" }, { "code": "SEN", "description": "Senegal", "value": "Senegal" }, { "code": "SOM", "description": "Somalia", "value": "Somalia" }, { "code": "SUR", "description": "Suriname", "value": "Suriname" }, { "code": "SSD", "description": "South Sudan", "value": "South Sudan" }, { "code": "STP", "description": "São Tomé and Príncipe", "value": "São Tomé and Príncipe" }, { "code": "SLV", "description": "El Salvador", "value": "El Salvador" }, { "code": "SYR", "description": "Syrian Arab Republic", "value": "Syrian Arab Republic" }, { "code": "SWZ", "description": "Swaziland", "value": "Swaziland" }, { "code": "TCA", "description": "Turks And Caicos Islands", "value": "Turks And Caicos Islands" }, { "code": "TCD", "description": "Chad", "value": "Chad" }, { "code": "ATF", "description": "French Southern Territories", "value": "French Southern Territories" }, { "code": "TGO", "description": "Togo", "value": "Togo" }, { "code": "THA", "description": "Thailand", "value": "Thailand" }, { "code": "TJK", "description": "Tajikistan", "value": "Tajikistan" }, { "code": "TKL", "description": "Tokelau", "value": "Tokelau" }, { "code": "TLS", "description": "East Timor", "value": "East Timor" }, { "code": "TKM", "description": "Turkmenistan", "value": "Turkmenistan" }, { "code": "TUN", "description": "Tunisia", "value": "Tunisia" }, { "code": "TON", "description": "Tonga", "value": "Tonga" }, { "code": "TUR", "description": "Turkey", "value": "Turkey" }, { "code": "TTO", "description": "Trinidad And Tobago", "value": "Trinidad And Tobago" }, { "code": "TUV", "description": "Tuvalu", "value": "Tuvalu" }, { "code": "TWN", "description": "Taiwan, Province Of China", "value": "Taiwan, Province Of China" }, { "code": "TZA", "description": "Tanzania, United Republic Of", "value": "Tanzania, United Republic Of" }, { "code": "UKR", "description": "Ukraine", "value": "Ukraine" }, { "code": "UGA", "description": "Uganda", "value": "Uganda" }, { "code": "UMI", "description": "United States Minor Outlying Islands", "value": "United States Minor Outlying Islands" }, { "code": "USA", "description": "United States", "value": "United States" }, { "code": "URY", "description": "Uruguay", "value": "Uruguay" }, { "code": "UZB", "description": "Uzbekistan", "value": "Uzbekistan" }, { "code": "VAT", "description": "Vatican City State", "value": "Vatican City State" }, { "code": "VCT", "description": "Saint Vincent And The Grenadines", "value": "Saint Vincent And The Grenadines" }, { "code": "VEN", "description": "Venezuela, Bolivarian Republic Of", "value": "Venezuela, Bolivarian Republic Of" }, { "code": "VGB", "description": "Virgin Islands (British)", "value": "Virgin Islands (British)" }, { "code": "VIR", "description": "Virgin Islands (US)", "value": "Virgin Islands (US)" }, { "code": "VNM", "description": "Vietnam", "value": "Vietnam" }, { "code": "VUT", "description": "Vanuatu", "value": "Vanuatu" }, { "code": "WLF", "description": "Wallis And Futuna", "value": "Wallis And Futuna" }, { "code": "WSM", "description": "Samoa", "value": "Samoa" }, { "code": "YEM", "description": "Yemen", "value": "Yemen" }, { "code": "MYT", "description": "Mayotte", "value": "Mayotte" }, { "code": "ZAF", "description": "South Africa", "value": "South Africa" }, { "code": "ZMB", "description": "Zambia", "value": "Zambia" }, { "code": "ZWE", "description": "Zimbabwe", "value": "Zimbabwe" } ], "field_category": "Address Details" }, { "field_key": "nationality", "field_label": "Nationality", "field_type": "string", "is_mandatory": false, "is_editable": true, "enum_key": "nationality", "values_supported": [ { "code": "ABW", "description": "Nationality of Aruba", "value": "Aruban" }, { "code": "AFG", "description": "Nationality of Afghanistan", "value": "Afghan" }, { "code": "AGO", "description": "Nationality of Angola", "value": "Angolan" }, { "code": "AIA", "description": "Nationality of Anguilla", "value": "Anguillan" }, { "code": "ALA", "description": "Nationality of Aland Islands", "value": "Landers" }, { "code": "ALB", "description": "Nationality of Albania", "value": "Albanian" }, { "code": "AND", "description": "Nationality of Andorra", "value": "Andorran" }, { "code": "ANT", "description": "Nationality of Netherlands Antilles", "value": "Netherlands Antilles" }, { "code": "ARE", "description": "Nationality of United Arab Emirates", "value": "United Arab Emirates" }, { "code": "ARG", "description": "Nationality of Argentina", "value": "Argentinian" }, { "code": "ARM", "description": "Nationality of Armenia", "value": "Armenian" }, { "code": "ASM", "description": "Nationality of American Samoa", "value": "American Samoan" }, { "code": "ATA", "description": "Nationality of Antarctica", "value": "Antarctican" }, { "code": "ATF", "description": "Nationality of French Southern Territories", "value": "French" }, { "code": "ATG", "description": "Nationality of Antigua and Barbuda", "value": "Antiguan and Barbudan" }, { "code": "AUS", "description": "Nationality of Australia", "value": "Australian" }, { "code": "AUT", "description": "Nationality of Austria", "value": "Austrian" }, { "code": "AZE", "description": "Nationality of Azerbaijan", "value": "Azerbaijani" }, { "code": "BDI", "description": "Nationality of Burundi", "value": "Burundian" }, { "code": "BEL", "description": "Nationality of Belgium", "value": "Belgian" }, { "code": "BEN", "description": "Nationality of Benin", "value": "Beninese" }, { "code": "BFA", "description": "Nationality of Burkina Faso", "value": "Burkinab" }, { "code": "BGD", "description": "Nationality of Bangladesh", "value": "Bangladeshi" }, { "code": "BGR", "description": "Nationality of Bulgaria", "value": "Bulgarian" }, { "code": "BHR", "description": "Nationality of Bahrain", "value": "Bahraini" }, { "code": "BHS", "description": "Nationality of Bahamas", "value": "Bahamian" }, { "code": "BIH", "description": "Nationality of Bosnia and Herzegovina", "value": "Bosnian" }, { "code": "BLM", "description": "Nationality of Saint Barthelemy", "value": "Saint Barth" }, { "code": "BLR", "description": "Nationality of Belarus", "value": "Belarusan" }, { "code": "BLZ", "description": "Nationality of Belize", "value": "Belizian" }, { "code": "BMU", "description": "Nationality of Bermuda", "value": "Bermudian" }, { "code": "BOL", "description": "Nationality of Bolivia", "value": "Bolivian" }, { "code": "BRA", "description": "Nationality of Brazil", "value": "Brazilian" }, { "code": "BRB", "description": "Nationality of Barbados", "value": "Barbadian" }, { "code": "BRN", "description": "Nationality of Brunei Darussalam", "value": "Bruneian" }, { "code": "BTN", "description": "Nationality of Bhutan", "value": "Bhutanese" }, { "code": "BVT", "description": "Nationality of Bouvet Island", "value": "Bouvet Island" }, { "code": "BWA", "description": "Nationality of Botswana", "value": "Tswana" }, { "code": "CAF", "description": "Nationality of Central African Republic", "value": "Central African" }, { "code": "CAN", "description": "Nationality of Canada", "value": "Canadian" }, { "code": "CCK", "description": "Nationality of Cocos (Keeling) Islands", "value": "Cocos Islander" }, { "code": "CHE", "description": "Nationality of Switzerland", "value": "Swiss" }, { "code": "CHL", "description": "Nationality of Chile", "value": "Chilean" }, { "code": "CHN", "description": "Nationality of China", "value": "Chinese" }, { "code": "CIV", "description": "Nationality of Ivory Coast", "value": "Ivoirian" }, { "code": "CMR", "description": "Nationality of Cameroon", "value": "Cameroonian" }, { "code": "COD", "description": "Nationality of Congo, The Democratic Republic", "value": "Congolese" }, { "code": "COG", "description": "Nationality of Congo", "value": "Congolese" }, { "code": "COK", "description": "Nationality of Cook Islands", "value": "Cook Islander" }, { "code": "COL", "description": "Nationality of Colombia", "value": "Colombian" }, { "code": "COM", "description": "Nationality of Comoros", "value": "Comoran" }, { "code": "CPV", "description": "Nationality of Cape Verde", "value": "Cape Verdean" }, { "code": "CRI", "description": "Nationality of Costa Rica", "value": "Costa Rican" }, { "code": "CUB", "description": "Nationality of Cuba", "value": "Cuban" }, { "code": "CXR", "description": "Nationality of Christmas Island", "value": "Christmas Islander" }, { "code": "CYM", "description": "Nationality of Cayman Islands", "value": "Caymanian" }, { "code": "CZE", "description": "Nationality of Czech Republic", "value": "Czech" }, { "code": "DEU", "description": "Nationality of Germany", "value": "German" }, { "code": "DJI", "description": "Nationality of Djibouti", "value": "Djiboutian" }, { "code": "DMA", "description": "Nationality of Dominica", "value": "Dominican" }, { "code": "DNK", "description": "Nationality of Denmark", "value": "Dane" }, { "code": "DOM", "description": "Nationality of Dominican Republic", "value": "Dominican" }, { "code": "DZA", "description": "Nationality of Algeria", "value": "Algerian" }, { "code": "ECU", "description": "Nationality of Ecuador", "value": "Ecuadorean" }, { "code": "EGY", "description": "Nationality of Egypt", "value": "Egyptian" }, { "code": "ERI", "description": "Nationality of Eritrea", "value": "Eritrean" }, { "code": "ESH", "description": "Nationality of Western Sahara", "value": "Western Saharan" }, { "code": "ESP", "description": "Nationality of Spain", "value": "Spaniard" }, { "code": "EST", "description": "Nationality of Estonia", "value": "Estonian" }, { "code": "ETH", "description": "Nationality of Ethiopia", "value": "Ethiopian" }, { "code": "FIN", "description": "Nationality of Finland", "value": "Finn" }, { "code": "FJI", "description": "Nationality of Fiji", "value": "Fijian" }, { "code": "FLK", "description": "Nationality of Falkland Islands (Malvinas)", "value": "Falkland Islander" }, { "code": "FRA", "description": "Nationality of France", "value": "French" }, { "code": "FRO", "description": "Nationality of Faroe Islands", "value": "Faroese" }, { "code": "FSM", "description": "Nationality of Micronesia, Federated States o", "value": "Micronesian" }, { "code": "FXX", "description": "Nationality of France, Metropolitan", "value": "French" }, { "code": "GAB", "description": "Nationality of Gabon", "value": "Gabonese" }, { "code": "GBR", "description": "Nationality of United Kingdom", "value": "British" }, { "code": "GEO", "description": "Nationality of Georgia", "value": "Georgian" }, { "code": "GGY", "description": "Nationality of Guernsey", "value": "Channel Islander" }, { "code": "GHA", "description": "Nationality of Ghana", "value": "Ghanaian" }, { "code": "GIB", "description": "Nationality of Gibraltar", "value": "Gibraltar" }, { "code": "GIN", "description": "Nationality of Guinea", "value": "Guinean" }, { "code": "GLP", "description": "Nationality of Guadeloupe", "value": "Guadeloupian" }, { "code": "GMB", "description": "Nationality of Gambia", "value": "Gambian" }, { "code": "GNB", "description": "Nationality of Guinea-Bissau", "value": "Bissau-Guinean" }, { "code": "GNQ", "description": "Nationality of Equatorial Guinea", "value": "Equatoguinean" }, { "code": "GRC", "description": "Nationality of Greece", "value": "Greek" }, { "code": "GRD", "description": "Nationality of Grenada", "value": "Grenadian" }, { "code": "GRL", "description": "Nationality of Greenland", "value": "Greenlander" }, { "code": "GTM", "description": "Nationality of Guatemala", "value": "Guatemalan" }, { "code": "GUF", "description": "Nationality of French Guiana", "value": "French Guiana" }, { "code": "GUM", "description": "Nationality of Guam", "value": "Guamanian" }, { "code": "GUY", "description": "Nationality of Guyana", "value": "Guyanese" }, { "code": "HKG", "description": "Nationality of Hong Kong", "value": "Hong Konger" }, { "code": "HMD", "description": "Nationality of Heard and Mc Donald Islands", "value": "Australian" }, { "code": "HND", "description": "Nationality of Honduras", "value": "Honduran" }, { "code": "HRV", "description": "Nationality of Croatia (Hrvatska)", "value": "Croatian" }, { "code": "HTI", "description": "Nationality of Haiti", "value": "Haitian" }, { "code": "HUN", "description": "Nationality of Hungary", "value": "Hungarian" }, { "code": "IDN", "description": "Nationality of Indonesia", "value": "Indonesian" }, { "code": "IMN", "description": "Nationality of Isle of Man", "value": "Manx" }, { "code": "IND", "description": "Nationality of India", "value": "Indian" }, { "code": "IOT", "description": "Nationality of British Indian Ocean Territory", "value": "British" }, { "code": "IRL", "description": "Nationality of Ireland", "value": "Irish " }, { "code": "IRN", "description": "Nationality of Iran (Islamic Republic of)", "value": "Iranian" }, { "code": "IRQ", "description": "Nationality of Iraq", "value": "Iraqi" }, { "code": "ISL", "description": "Nationality of Iceland", "value": "Icelander" }, { "code": "ISR", "description": "Nationality of Israel", "value": "Israeli" }, { "code": "ITA", "description": "Nationality of Italy", "value": "Italian" }, { "code": "JAM", "description": "Nationality of Jamaica", "value": "Jamaican" }, { "code": "JEY", "description": "Nationality of Jersey", "value": "Channel Islander" }, { "code": "JOR", "description": "Nationality of Jordan", "value": "Jordanian" }, { "code": "JPN", "description": "Nationality of Japan", "value": "Japanese" }, { "code": "KAZ", "description": "Nationality of Kazakhstan", "value": "Kazakh" }, { "code": "KEN", "description": "Nationality of Kenya", "value": "Kenyan" }, { "code": "KGZ", "description": "Nationality of Kyrgyzstan", "value": "Kyrgyzstani" }, { "code": "KHM", "description": "Nationality of Cambodia", "value": "Cambodian" }, { "code": "KIR", "description": "Nationality of Kiribati", "value": "I-Kiribati" }, { "code": "KNA", "description": "Nationality of Saint Kitts and Nevis", "value": "Kittitian, Nevisian" }, { "code": "KOR", "description": "Nationality of Korea, Republic of", "value": "South Korean" }, { "code": "KWT", "description": "Nationality of Kuwait", "value": "Kuwaiti" }, { "code": "LAO", "description": "Nationality of Lao People's Democratic Republ", "value": "Laotian" }, { "code": "LBN", "description": "Nationality of Lebanon", "value": "Lebanese" }, { "code": "LBR", "description": "Nationality of Liberia", "value": "Liberian" }, { "code": "LBY", "description": "Nationality of Libyan Arab Jamahiriya", "value": "Libyan" }, { "code": "LCA", "description": "Nationality of Saint Lucia", "value": "Saint Lucian" }, { "code": "LIE", "description": "Nationality of Liechtenstein", "value": "Liechtensteiner" }, { "code": "LKA", "description": "Nationality of Sri Lanka", "value": "Sri Lankan" }, { "code": "LSO", "description": "Nationality of Lesotho", "value": "Basotho" }, { "code": "LTU", "description": "Nationality of Lithuania", "value": "Lithuanian" }, { "code": "LUX", "description": "Nationality of Luxembourg", "value": "Luxembourger" }, { "code": "LVA", "description": "Nationality of Latvia", "value": "Latvian" }, { "code": "MAC", "description": "Nationality of Macau", "value": "Macau Chinese" }, { "code": "MAF", "description": "Nationality of Saint Martin", "value": "St. Maarten" }, { "code": "MAR", "description": "Nationality of Morocco", "value": "Moroccan" }, { "code": "MCO", "description": "Nationality of Monaco", "value": "Monacan" }, { "code": "MDA", "description": "Nationality of Moldova, Republic of", "value": "Moldovan" }, { "code": "MDG", "description": "Nationality of Madagascar", "value": "Madagascan" }, { "code": "MDV", "description": "Nationality of Maldives", "value": "Maldivian" }, { "code": "MEX", "description": "Nationality of Mexico", "value": "Mexican" }, { "code": "MHL", "description": "Nationality of Marshall Islands", "value": "Marshallese" }, { "code": "MKD", "description": "Nationality of Macedonia", "value": "Macedonian" }, { "code": "MLI", "description": "Nationality of Mali", "value": "Malian" }, { "code": "MLT", "description": "Nationality of Malta", "value": "Maltese" }, { "code": "MMR", "description": "Nationality of Myanmar", "value": "Burmese" }, { "code": "MNE", "description": "Nationality of Montenegro", "value": "Montenegrin" }, { "code": "MNG", "description": "Nationality of Mongolia", "value": "Mongolian" }, { "code": "MNP", "description": "Nationality of Northern Mariana Islands", "value": "American" }, { "code": "MOZ", "description": "Nationality of Mozambique", "value": "Mozambican" }, { "code": "MRT", "description": "Nationality of Mauritania", "value": "Mauritanian" }, { "code": "MSR", "description": "Nationality of Montserrat", "value": "Montserratian" }, { "code": "MTQ", "description": "Nationality of Martinique", "value": "Martiniquais" }, { "code": "MUS", "description": "Nationality of Mauritius", "value": "Mauritian" }, { "code": "MWI", "description": "Nationality of Malawi", "value": "Malawian" }, { "code": "MYS", "description": "Nationality of Malaysia", "value": "Malaysian" }, { "code": "MYT", "description": "Nationality of Mayotte", "value": "Mahorais" }, { "code": "NAM", "description": "Nationality of Namibia", "value": "Namibian" }, { "code": "NCL", "description": "Nationality of New Caledonia", "value": "New Caledonian" }, { "code": "NER", "description": "Nationality of Niger", "value": "Nigerien" }, { "code": "NFK", "description": "Nationality of Norfolk Island", "value": "Norfolk Islander" }, { "code": "NGA", "description": "Nationality of Nigeria", "value": "Nigerian" }, { "code": "NIC", "description": "Nationality of Nicaragua", "value": "Nicaraguan" }, { "code": "NIU", "description": "Nationality of Niue", "value": "Niuean" }, { "code": "NLD", "description": "Nationality of Netherlands", "value": "Dutch" }, { "code": "NOR", "description": "Nationality of Norway", "value": "Norwegian" }, { "code": "NPL", "description": "Nationality of Nepal", "value": "Nepalese" }, { "code": "NRU", "description": "Nationality of Nauru", "value": "Nauruan" }, { "code": "NZL", "description": "Nationality of New Zealand", "value": "New Zealander" }, { "code": "OMN", "description": "Nationality of Oman", "value": "Omani" }, { "code": "PAK", "description": "Nationality of Pakistan", "value": "Pakistani" }, { "code": "PAN", "description": "Nationality of Panama", "value": "Panamanian" }, { "code": "PCN", "description": "Nationality of Pitcairn", "value": "Pitcairn Islander" }, { "code": "PER", "description": "Nationality of Peru", "value": "Peruvian" }, { "code": "PHL", "description": "Nationality of Philippines", "value": "Filipino" }, { "code": "PLW", "description": "Nationality of Palau", "value": "Palauan" }, { "code": "PNG", "description": "Nationality of Papua New Guinea", "value": "Papua New Guinean" }, { "code": "POL", "description": "Nationality of Poland", "value": "Pole" }, { "code": "PRI", "description": "Nationality of Puerto Rico", "value": "Puerto Rican" }, { "code": "PRK", "description": "Nationality of Korea, Democratic People's Rep", "value": "North Korean" }, { "code": "PRT", "description": "Nationality of Portugal", "value": "Portuguese" }, { "code": "PRY", "description": "Nationality of Paraguay", "value": "Paraguayan" }, { "code": "PSE", "description": "Nationality of Palestine", "value": "Palestinian" }, { "code": "PYF", "description": "Nationality of French Polynesia", "value": "French Polynesian" }, { "code": "QAT", "description": "Nationality of Qatar", "value": "Qatari" }, { "code": "REU", "description": "Nationality of Reunion", "value": "Reunionese" }, { "code": "ROU", "description": "Nationality of Romania", "value": "Romanian" }, { "code": "RUS", "description": "Nationality of Russian Federation", "value": "Russian" }, { "code": "RWA", "description": "Nationality of Rwanda", "value": "Rwandan" }, { "code": "SAU", "description": "Nationality of Saudi Arabia", "value": "Saudi Arabian" }, { "code": "SDN", "description": "Nationality of Sudan", "value": "Sudanese" }, { "code": "SEN", "description": "Nationality of Senegal", "value": "Senegalese" }, { "code": "SGP", "description": "Nationality of Singapore", "value": "Singaporean" }, { "code": "SGS", "description": "Nationality of South Georgia South Sandwich Islands", "value": "South Georgian South Sandwich Islander" }, { "code": "SHN", "description": "Nationality of St. Helena", "value": "Saint Helenians" }, { "code": "SJM", "description": "Nationality of Svalbard and Jan Mayen Islands", "value": "Svalbard" }, { "code": "SLB", "description": "Nationality of Solomon Islands", "value": "Solomon Islander" }, { "code": "SLE", "description": "Nationality of Sierra Leone", "value": "Sierra Leonian" }, { "code": "SLV", "description": "Nationality of El Salvador", "value": "Salvadorean" }, { "code": "SMR", "description": "Nationality of San Marino", "value": "Sammarinese" }, { "code": "SOM", "description": "Nationality of Somalia", "value": "Somali" }, { "code": "SPM", "description": "Nationality of St. Pierre and Miquelon", "value": "French" }, { "code": "SRB", "description": "Nationality of Serbia", "value": "Serbian" }, { "code": "SSD", "description": "Nationality of South Sudan", "value": "South Sudanese" }, { "code": "STP", "description": "Nationality of Sao Tome and Principe", "value": "Sao Tomean" }, { "code": "SUR", "description": "Nationality of Suriname", "value": "Surinamese" }, { "code": "SVK", "description": "Nationality of Slovakia", "value": "Slovak" }, { "code": "SVN", "description": "Nationality of Slovenia", "value": "Slovenian" }, { "code": "SWE", "description": "Nationality of Sweden", "value": "Swede" }, { "code": "SWZ", "description": "Nationality of Swaziland", "value": "Swazi" }, { "code": "SYC", "description": "Nationality of Seychelles", "value": "Seychellois" }, { "code": "SYR", "description": "Nationality of Syrian Arab Republic", "value": "Syrian" }, { "code": "TCA", "description": "Nationality of Turks and Caicos Islands", "value": "Turks and Caicos Islander" }, { "code": "TCD", "description": "Nationality of Chad", "value": "Chadian" }, { "code": "TGO", "description": "Nationality of Togo", "value": "Togolese" }, { "code": "THA", "description": "Nationality of Thailand", "value": "Thai" }, { "code": "TJK", "description": "Nationality of Tajikistan", "value": "Tadjik" }, { "code": "TKL", "description": "Nationality of Tokelau", "value": "Tokelauan" }, { "code": "TKM", "description": "Nationality of Turkmenistan", "value": "Turkmen" }, { "code": "TLS", "description": "Nationality of Timor-Leste", "value": "Timorese" }, { "code": "TMP", "description": "Nationality of East Timor", "value": "Timorese" }, { "code": "TON", "description": "Nationality of Tonga", "value": "Tongan" }, { "code": "TTO", "description": "Nationality of Trinidad and Tobago", "value": "Trinidadian" }, { "code": "TUN", "description": "Nationality of Tunisia", "value": "Tunisian" }, { "code": "TUR", "description": "Nationality of Turkey", "value": "Turk" }, { "code": "TUV", "description": "Nationality of Tuvalu", "value": "Tuvaluan" }, { "code": "TWN", "description": "Nationality of Taiwan", "value": "Taiwanese" }, { "code": "TZA", "description": "Nationality of Tanzania, United Republic of", "value": "Tanzanian" }, { "code": "UGA", "description": "Nationality of Uganda", "value": "Ugandan" }, { "code": "UKR", "description": "Nationality of Ukraine", "value": "Ukrainian" }, { "code": "UMI", "description": "Nationality of United States minor outlying islands", "value": "American" }, { "code": "UNK", "description": "Nationality of Kosovo", "value": "Kosovan" }, { "code": "URY", "description": "Nationality of Uruguay", "value": "Uruguayan" }, { "code": "USA", "description": "Nationality of United States", "value": "American" }, { "code": "UZB", "description": "Nationality of Uzbekistan", "value": "Uzbek" }, { "code": "VAT", "description": "Nationality of Vatican City State", "value": "Vatican" }, { "code": "VCT", "description": "Nationality of Saint Vincent and the Grenadin", "value": "Vincentian" }, { "code": "VEN", "description": "Nationality of Venezuela", "value": "Venezuelan" }, { "code": "VGB", "description": "Nationality of Virgin Islands (British)", "value": "British Virgin Islander" }, { "code": "VIR", "description": "Nationality of Virgin Islands (U.S.)", "value": "Virgin Islander" }, { "code": "VNM", "description": "Nationality of Vietnam", "value": "Vietnamese" }, { "code": "VUT", "description": "Nationality of Vanuatu", "value": "Ni-Vanuatu" }, { "code": "WLF", "description": "Nationality of Wallis and Futuna Islands", "value": "Wallis and Futuna Islander" }, { "code": "WSM", "description": "Nationality of Samoa", "value": "Samoan" }, { "code": "YEM", "description": "Nationality of Yemen", "value": "Yemeni" }, { "code": "ZAF", "description": "Nationality of South Africa", "value": "South African" }, { "code": "ZMB", "description": "Nationality of Zambia", "value": "Zambian" }, { "code": "ZRE", "description": "Nationality of Zaire", "value": "Zairian" }, { "code": "ZWE", "description": "Nationality of Zimbabwe", "value": "Zimbabwean" } ], "field_category": "Address Details" } ] }, { "field_group_key": "identification_details", "field_group_label": "Identification details", "fields": [ { "field_key": "identity_type", "field_label": "Identification Type", "field_type": "string", "is_mandatory": false, "is_editable": true, "enum_key": "id_types", "values_supported": [ { "code": "NRIC", "description": "NRIC", "value": "NRIC" }, { "code": "VOTERS_ID", "description": "Voter's photo ID card", "value": "Voter's photo ID card" }, { "code": "DRIVERS_ID", "description": "Driver's license", "value": "Driver's license" }, { "code": "PASSPORT", "description": "Valid passport", "value": "Valid passport" }, { "code": "PAN", "description": "PAN Card", "value": "PAN Card" }, { "code": "RATION", "description": "Family ration card", "value": "Family ration card" }, { "code": "U_BILL", "description": "Utility bill", "value": "Utility bill" }, { "code": "S_LICENSE", "description": "Shop license", "value": "Shop license" }, { "code": "LOI", "description": "Letter of introduction", "value": "Letter of introduction" }, { "code": "AADHAAR", "description": "Aadhaar", "value": "Aadhaar" }, { "code": "EPFIN", "description": "EP FIN No.", "value": "EP FIN No." }, { "code": "SPASS", "description": "S PASS No.", "value": "S PASS No." }, { "code": "WP", "description": "Work permit", "value": "Work permit" }, { "code": "CMND", "description": "Chứng minh nhân dân", "value": "Chứng minh nhân dân" }, { "code": "MILITARY_ID", "description": "Military Id", "value": "Military Id" }, { "code": "MEDICARE_CARD", "description": "Medicare Card", "value": "Medicare Card" } ], "field_category": "Identification Details" }, { "field_key": "identity_number", "field_label": "Identification Number", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,-_)(']+$" }, "field_category": "Identification Details" }, { "field_key": "country_of_issue", "field_label": "Country of Issue", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "Identification Details" }, { "field_key": "issue_date", "field_label": "Issue Date", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^([0-9]{4})-([0-9]{2})-([0-9]{2})$" }, "field_category": "Identification Details" }, { "field_key": "expiry_date", "field_label": "Expiry Date", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^([0-9]{4})-([0-9]{2})-([0-9]{2})$" }, "field_category": "Identification Details" }, { "field_key": "date_of_incorporation", "field_label": "Date of Incorporation", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^([0-9]{4})-([0-9]{2})-([0-9]{2})$" }, "field_category": "Identification Details" } ] }, { "field_group_key": "user_information", "field_group_label": "User Information", "fields": [ { "field_key": "first_name", "field_label": "First Name", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 50, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "User Information" }, { "field_key": "middle_name", "field_label": "Middle Name", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 50, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "User Information" }, { "field_key": "last_name", "field_label": "Last Name", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 50, "min_length": 1, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "User Information" }, { "field_key": "preferred_name", "field_label": "Preferred Name", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 100, "min_length": 0, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "User Information" }, { "field_key": "gender", "field_label": "Gender", "field_type": "string", "is_mandatory": false, "is_editable": true, "values_supported": [ { "code": "MALE", "description": "Male", "value": "Male" }, { "code": "FEMALE", "description": "Female", "value": "Female" } ], "field_category": "User Information" }, { "field_key": "date_of_birth", "field_label": "Date of Birth", "field_type": "string", "is_mandatory": false, "is_editable": true, "validation": { "max_length": 100, "min_length": 0, "regex": "^([0-9]{4})-([0-9]{2})-([0-9]{2})$" }, "field_category": "User Information" }, { "field_key": "email", "field_label": "Email", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 100, "min_length": 5, "regex": "^[#.0-9a-zA-Z\\s,/\\_:+?')(@#!&-]+$" }, "field_category": "User Information" }, { "field_key": "mobile_country_code", "field_label": "Mobile Country code", "field_type": "string", "is_mandatory": true, "is_editable": true, "values_supported": [ { "code": "43", "description": "Austria", "value": "Austria" }, { "code": "376", "description": "Andorra", "value": "Andorra" }, { "code": "971", "description": "United Arab Emirates", "value": "United Arab Emirates" }, { "code": "93", "description": "Afghanistan", "value": "Afghanistan" }, { "code": "1 268", "description": "Antigua And Barbuda", "value": "Antigua And Barbuda" }, { "code": "1 264", "description": "Anguilla", "value": "Anguilla" }, { "code": "355", "description": "Albania", "value": "Albania" }, { "code": "374", "description": "Armenia", "value": "Armenia" }, { "code": "244", "description": "Angola", "value": "Angola" }, { "code": "672", "description": "Antarctica", "value": "Antarctica" }, { "code": "54", "description": "Argentina", "value": "Argentina" }, { "code": "1 684", "description": "American Samoa", "value": "American Samoa" }, { "code": "61", "description": "Australia", "value": "Australia" }, { "code": "297", "description": "Aruba", "value": "Aruba" }, { "code": "358", "description": "Åland Islands", "value": "Åland Islands" }, { "code": "994", "description": "Azerbaijan", "value": "Azerbaijan" }, { "code": "387", "description": "Bosnia & Herzegovina", "value": "Bosnia & Herzegovina" }, { "code": "1 246", "description": "Barbados", "value": "Barbados" }, { "code": "880", "description": "Bangladesh", "value": "Bangladesh" }, { "code": "32", "description": "Belgium", "value": "Belgium" }, { "code": "226", "description": "Burkina Faso", "value": "Burkina Faso" }, { "code": "359", "description": "Bulgaria", "value": "Bulgaria" }, { "code": "973", "description": "Bahrain", "value": "Bahrain" }, { "code": "257", "description": "Burundi", "value": "Burundi" }, { "code": "229", "description": "Benin", "value": "Benin" }, { "code": "590", "description": "Saint Barthélemy", "value": "Saint Barthélemy" }, { "code": "1 441", "description": "Bermuda", "value": "Bermuda" }, { "code": "673", "description": "Brunei Darussalam", "value": "Brunei Darussalam" }, { "code": "591", "description": "Bolivia, Plurinational State Of", "value": "Bolivia, Plurinational State Of" }, { "code": "55", "description": "Brazil", "value": "Brazil" }, { "code": "1 242", "description": "Bahamas", "value": "Bahamas" }, { "code": "975", "description": "Bhutan", "value": "Bhutan" }, { "code": "47", "description": "Bouvet Island", "value": "Bouvet Island" }, { "code": "267", "description": "Botswana", "value": "Botswana" }, { "code": "375", "description": "Belarus", "value": "Belarus" }, { "code": "501", "description": "Belize", "value": "Belize" }, { "code": "1", "description": "Canada", "value": "Canada" }, { "code": "61", "description": "Cocos (Keeling) Islands", "value": "Cocos (Keeling) Islands" }, { "code": "243", "description": "Democratic Republic Of Congo", "value": "Democratic Republic Of Congo" }, { "code": "236", "description": "Central African Republic", "value": "Central African Republic" }, { "code": "242", "description": "Republic Of Congo", "value": "Republic Of Congo" }, { "code": "41", "description": "Switzerland", "value": "Switzerland" }, { "code": "225", "description": "Cote d'Ivoire", "value": "Cote d'Ivoire" }, { "code": "682", "description": "Cook Islands", "value": "Cook Islands" }, { "code": "56", "description": "Chile", "value": "Chile" }, { "code": "237", "description": "Cameroon", "value": "Cameroon" }, { "code": "86", "description": "China", "value": "China" }, { "code": "57", "description": "Colombia", "value": "Colombia" }, { "code": "506", "description": "Costa Rica", "value": "Costa Rica" }, { "code": "53", "description": "Cuba", "value": "Cuba" }, { "code": "238", "description": "Cabo Verde", "value": "Cabo Verde" }, { "code": "61", "description": "Christmas Island", "value": "Christmas Island" }, { "code": "357", "description": "Cyprus", "value": "Cyprus" }, { "code": "420", "description": "Czech Republic", "value": "Czech Republic" }, { "code": "49", "description": "Germany", "value": "Germany" }, { "code": "253", "description": "Djibouti", "value": "Djibouti" }, { "code": "45", "description": "Denmark", "value": "Denmark" }, { "code": "1 767", "description": "Dominica", "value": "Dominica" }, { "code": "1 809", "description": "Dominican Republic", "value": "Dominican Republic" }, { "code": "213", "description": "Algeria", "value": "Algeria" }, { "code": "593", "description": "Ecuador", "value": "Ecuador" }, { "code": "372", "description": "Estonia", "value": "Estonia" }, { "code": "20", "description": "Egypt", "value": "Egypt" }, { "code": "212", "description": "Western Sahara", "value": "Western Sahara" }, { "code": "291", "description": "Eritrea", "value": "Eritrea" }, { "code": "34", "description": "Spain", "value": "Spain" }, { "code": "251", "description": "Ethiopia", "value": "Ethiopia" }, { "code": "358", "description": "Finland", "value": "Finland" }, { "code": "679", "description": "Fiji", "value": "Fiji" }, { "code": "500", "description": "Falkland Islands", "value": "Falkland Islands" }, { "code": "691", "description": "Micronesia, Federated States Of", "value": "Micronesia, Federated States Of" }, { "code": "298", "description": "Faroe Islands", "value": "Faroe Islands" }, { "code": "33", "description": "France", "value": "France" }, { "code": "33", "description": "France, Metropolitan", "value": "France, Metropolitan" }, { "code": "241", "description": "Gabon", "value": "Gabon" }, { "code": "44", "description": "United Kingdom", "value": "United Kingdom" }, { "code": "473", "description": "Grenada", "value": "Grenada" }, { "code": "995", "description": "Georgia", "value": "Georgia" }, { "code": "594", "description": "French Guiana", "value": "French Guiana" }, { "code": "44", "description": "Guernsey", "value": "Guernsey" }, { "code": "233", "description": "Ghana", "value": "Ghana" }, { "code": "350", "description": "Gibraltar", "value": "Gibraltar" }, { "code": "299", "description": "Greenland", "value": "Greenland" }, { "code": "220", "description": "Gambia", "value": "Gambia" }, { "code": "224", "description": "Guinea", "value": "Guinea" }, { "code": "590", "description": "Guadeloupe", "value": "Guadeloupe" }, { "code": "240", "description": "Equatorial Guinea", "value": "Equatorial Guinea" }, { "code": "30", "description": "Greece", "value": "Greece" }, { "code": "500", "description": "South Georgia And The South Sandwich Islands", "value": "South Georgia And The South Sandwich Islands" }, { "code": "502", "description": "Guatemala", "value": "Guatemala" }, { "code": "1 671", "description": "Guam", "value": "Guam" }, { "code": "245", "description": "Guinea-bissau", "value": "Guinea-bissau" }, { "code": "592", "description": "Guyana", "value": "Guyana" }, { "code": "852", "description": "Hong Kong", "value": "Hong Kong" }, { "code": "672", "description": "Heard Island And McDonald Islands", "value": "Heard Island And McDonald Islands" }, { "code": "504", "description": "Honduras", "value": "Honduras" }, { "code": "385", "description": "Croatia", "value": "Croatia" }, { "code": "509", "description": "Haiti", "value": "Haiti" }, { "code": "36", "description": "Hungary", "value": "Hungary" }, { "code": "62", "description": "Indonesia", "value": "Indonesia" }, { "code": "353", "description": "Ireland", "value": "Ireland" }, { "code": "972", "description": "Israel", "value": "Israel" }, { "code": "44", "description": "Isle Of Man", "value": "Isle Of Man" }, { "code": "91", "description": "India", "value": "India" }, { "code": "246", "description": "British Indian Ocean Territory", "value": "British Indian Ocean Territory" }, { "code": "964", "description": "Iraq", "value": "Iraq" }, { "code": "98", "description": "Iran, Islamic Republic Of", "value": "Iran, Islamic Republic Of" }, { "code": "354", "description": "Iceland", "value": "Iceland" }, { "code": "39", "description": "Italy", "value": "Italy" }, { "code": "44", "description": "Jersey", "value": "Jersey" }, { "code": "1 876", "description": "Jamaica", "value": "Jamaica" }, { "code": "962", "description": "Jordan", "value": "Jordan" }, { "code": "81", "description": "Japan", "value": "Japan" }, { "code": "254", "description": "Kenya", "value": "Kenya" }, { "code": "996", "description": "Kyrgyzstan", "value": "Kyrgyzstan" }, { "code": "855", "description": "Cambodia", "value": "Cambodia" }, { "code": "686", "description": "Kiribati", "value": "Kiribati" }, { "code": "269", "description": "Comoros", "value": "Comoros" }, { "code": "1 869", "description": "Saint Kitts And Nevis", "value": "Saint Kitts And Nevis" }, { "code": "850", "description": "Korea, Democratic People's Republic Of", "value": "Korea, Democratic People's Republic Of" }, { "code": "82", "description": "Korea, Republic Of", "value": "Korea, Republic Of" }, { "code": "965", "description": "Kuwait", "value": "Kuwait" }, { "code": "1 345", "description": "Cayman Islands", "value": "Cayman Islands" }, { "code": "7", "description": "Kazakhstan", "value": "Kazakhstan" }, { "code": "856", "description": "Lao People's Democratic Republic", "value": "Lao People's Democratic Republic" }, { "code": "961", "description": "Lebanon", "value": "Lebanon" }, { "code": "1 758", "description": "Saint Lucia", "value": "Saint Lucia" }, { "code": "423", "description": "Liechtenstein", "value": "Liechtenstein" }, { "code": "94", "description": "Sri Lanka", "value": "Sri Lanka" }, { "code": "231", "description": "Liberia", "value": "Liberia" }, { "code": "266", "description": "Lesotho", "value": "Lesotho" }, { "code": "370", "description": "Lithuania", "value": "Lithuania" }, { "code": "352", "description": "Luxembourg", "value": "Luxembourg" }, { "code": "371", "description": "Latvia", "value": "Latvia" }, { "code": "218", "description": "Libya", "value": "Libya" }, { "code": "212", "description": "Morocco", "value": "Morocco" }, { "code": "377", "description": "Monaco", "value": "Monaco" }, { "code": "373", "description": "Moldova", "value": "Moldova" }, { "code": "382", "description": "Montenegro", "value": "Montenegro" }, { "code": "590", "description": "Saint Martin", "value": "Saint Martin" }, { "code": "261", "description": "Madagascar", "value": "Madagascar" }, { "code": "692", "description": "Marshall Islands", "value": "Marshall Islands" }, { "code": "389", "description": "Macedonia, The Former Yugoslav Republic Of", "value": "Macedonia, The Former Yugoslav Republic Of" }, { "code": "223", "description": "Mali", "value": "Mali" }, { "code": "95", "description": "Myanmar", "value": "Myanmar" }, { "code": "976", "description": "Mongolia", "value": "Mongolia" }, { "code": "853", "description": "Macao", "value": "Macao" }, { "code": "1 670", "description": "Northern Mariana Islands", "value": "Northern Mariana Islands" }, { "code": "596", "description": "Martinique", "value": "Martinique" }, { "code": "222", "description": "Mauritania", "value": "Mauritania" }, { "code": "1 664", "description": "Montserrat", "value": "Montserrat" }, { "code": "356", "description": "Malta", "value": "Malta" }, { "code": "230", "description": "Mauritius", "value": "Mauritius" }, { "code": "960", "description": "Maldives", "value": "Maldives" }, { "code": "265", "description": "Malawi", "value": "Malawi" }, { "code": "52", "description": "Mexico", "value": "Mexico" }, { "code": "60", "description": "Malaysia", "value": "Malaysia" }, { "code": "258", "description": "Mozambique", "value": "Mozambique" }, { "code": "264", "description": "Namibia", "value": "Namibia" }, { "code": "687", "description": "New Caledonia", "value": "New Caledonia" }, { "code": "227", "description": "Niger", "value": "Niger" }, { "code": "672", "description": "Norfolk Island", "value": "Norfolk Island" }, { "code": "234", "description": "Nigeria", "value": "Nigeria" }, { "code": "505", "description": "Nicaragua", "value": "Nicaragua" }, { "code": "31", "description": "Netherlands", "value": "Netherlands" }, { "code": "47", "description": "Norway", "value": "Norway" }, { "code": "977", "description": "Nepal", "value": "Nepal" }, { "code": "674", "description": "Nauru", "value": "Nauru" }, { "code": "683", "description": "Niue", "value": "Niue" }, { "code": "64", "description": "New Zealand", "value": "New Zealand" }, { "code": "968", "description": "Oman", "value": "Oman" }, { "code": "507", "description": "Panama", "value": "Panama" }, { "code": "51", "description": "Peru", "value": "Peru" }, { "code": "689", "description": "French Polynesia", "value": "French Polynesia" }, { "code": "675", "description": "Papua New Guinea", "value": "Papua New Guinea" }, { "code": "63", "description": "Philippines", "value": "Philippines" }, { "code": "92", "description": "Pakistan", "value": "Pakistan" }, { "code": "48", "description": "Poland", "value": "Poland" }, { "code": "508", "description": "Saint Pierre And Miquelon", "value": "Saint Pierre And Miquelon" }, { "code": "872", "description": "Pitcairn", "value": "Pitcairn" }, { "code": "1 787", "description": "Puerto Rico", "value": "Puerto Rico" }, { "code": "970", "description": "Palestinian Territory, Occupied", "value": "Palestinian Territory, Occupied" }, { "code": "351", "description": "Portugal", "value": "Portugal" }, { "code": "680", "description": "Palau", "value": "Palau" }, { "code": "595", "description": "Paraguay", "value": "Paraguay" }, { "code": "974", "description": "Qatar", "value": "Qatar" }, { "code": "262", "description": "Reunion", "value": "Reunion" }, { "code": "40", "description": "Romania", "value": "Romania" }, { "code": "381", "description": "Serbia", "value": "Serbia" }, { "code": "7", "description": "Russian Federation", "value": "Russian Federation" }, { "code": "250", "description": "Rwanda", "value": "Rwanda" }, { "code": "966", "description": "Saudi Arabia", "value": "Saudi Arabia" }, { "code": "677", "description": "Solomon Islands", "value": "Solomon Islands" }, { "code": "248", "description": "Seychelles", "value": "Seychelles" }, { "code": "249", "description": "Sudan", "value": "Sudan" }, { "code": "46", "description": "Sweden", "value": "Sweden" }, { "code": "65", "description": "Singapore", "value": "Singapore" }, { "code": "290", "description": "Saint Helena, Ascension And Tristan Da Cunha", "value": "Saint Helena, Ascension And Tristan Da Cunha" }, { "code": "386", "description": "Slovenia", "value": "Slovenia" }, { "code": "47", "description": "Svalbard And Jan Mayen", "value": "Svalbard And Jan Mayen" }, { "code": "421", "description": "Slovakia", "value": "Slovakia" }, { "code": "232", "description": "Sierra Leone", "value": "Sierra Leone" }, { "code": "378", "description": "San Marino", "value": "San Marino" }, { "code": "221", "description": "Senegal", "value": "Senegal" }, { "code": "252", "description": "Somalia", "value": "Somalia" }, { "code": "597", "description": "Suriname", "value": "Suriname" }, { "code": "211", "description": "South Sudan", "value": "South Sudan" }, { "code": "239", "description": "São Tomé and Príncipe", "value": "São Tomé and Príncipe" }, { "code": "503", "description": "El Salvador", "value": "El Salvador" }, { "code": "963", "description": "Syrian Arab Republic", "value": "Syrian Arab Republic" }, { "code": "268", "description": "Swaziland", "value": "Swaziland" }, { "code": "1 649", "description": "Turks And Caicos Islands", "value": "Turks And Caicos Islands" }, { "code": "235", "description": "Chad", "value": "Chad" }, { "code": "262", "description": "French Southern Territories", "value": "French Southern Territories" }, { "code": "228", "description": "Togo", "value": "Togo" }, { "code": "66", "description": "Thailand", "value": "Thailand" }, { "code": "992", "description": "Tajikistan", "value": "Tajikistan" }, { "code": "690", "description": "Tokelau", "value": "Tokelau" }, { "code": "670", "description": "East Timor", "value": "East Timor" }, { "code": "993", "description": "Turkmenistan", "value": "Turkmenistan" }, { "code": "216", "description": "Tunisia", "value": "Tunisia" }, { "code": "676", "description": "Tonga", "value": "Tonga" }, { "code": "90", "description": "Turkey", "value": "Turkey" }, { "code": "1 868", "description": "Trinidad And Tobago", "value": "Trinidad And Tobago" }, { "code": "688", "description": "Tuvalu", "value": "Tuvalu" }, { "code": "886", "description": "Taiwan, Province Of China", "value": "Taiwan, Province Of China" }, { "code": "255", "description": "Tanzania, United Republic Of", "value": "Tanzania, United Republic Of" }, { "code": "380", "description": "Ukraine", "value": "Ukraine" }, { "code": "256", "description": "Uganda", "value": "Uganda" }, { "code": "1", "description": "United States Minor Outlying Islands", "value": "United States Minor Outlying Islands" }, { "code": "1", "description": "United States", "value": "United States" }, { "code": "598", "description": "Uruguay", "value": "Uruguay" }, { "code": "998", "description": "Uzbekistan", "value": "Uzbekistan" }, { "code": "379", "description": "Vatican City State", "value": "Vatican City State" }, { "code": "1 784", "description": "Saint Vincent And The Grenadines", "value": "Saint Vincent And The Grenadines" }, { "code": "58", "description": "Venezuela, Bolivarian Republic Of", "value": "Venezuela, Bolivarian Republic Of" }, { "code": "1 284", "description": "Virgin Islands (British)", "value": "Virgin Islands (British)" }, { "code": "1 340", "description": "Virgin Islands (US)", "value": "Virgin Islands (US)" }, { "code": "84", "description": "Vietnam", "value": "Vietnam" }, { "code": "678", "description": "Vanuatu", "value": "Vanuatu" }, { "code": "681", "description": "Wallis And Futuna", "value": "Wallis And Futuna" }, { "code": "685", "description": "Samoa", "value": "Samoa" }, { "code": "967", "description": "Yemen", "value": "Yemen" }, { "code": "262", "description": "Mayotte", "value": "Mayotte" }, { "code": "27", "description": "South Africa", "value": "South Africa" }, { "code": "260", "description": "Zambia", "value": "Zambia" }, { "code": "263", "description": "Zimbabwe", "value": "Zimbabwe" } ], "field_category": "User Information" }, { "field_key": "mobile", "field_label": "Mobile Number", "field_type": "string", "is_mandatory": true, "is_editable": true, "validation": { "max_length": 31, "min_length": 1 }, "field_category": "User Information" }, { "field_key": "occupation", "field_label": "Occupation", "field_type": "string", "is_mandatory": false, "is_editable": true, "enum_key": "occupations", "values_supported": [ { "code": "GENERAL_WORKER", "description": "General Worker", "value": "General Worker" }, { "code": "BUSINESSMAN", "description": "Businessman", "value": "Businessman" }, { "code": "PROFESSIONAL", "description": "Professional", "value": "Professional" }, { "code": "SUPERVISOR", "description": "Supervisor", "value": "Supervisor" }, { "code": "TOURIST", "description": "Tourist", "value": "Tourist" }, { "code": "SECURITY_GUARD", "description": "Security Guard", "value": "Security Guard" }, { "code": "HOUSE_MAID", "description": "House Maid", "value": "House Maid" }, { "code": "DOMESTIC_HELPER", "description": "Domestic Helper", "value": "Domestic Helper" }, { "code": "HOUSE_WIFE", "description": "House Wife", "value": "House Wife" }, { "code": "OTHERS", "description": "Others", "value": "Others" } ], "field_category": "User Information" } ] }, { "field_group_key": "additional_data", "field_group_label": "Additional Data", "fields": [ { "field_key": "purpose_of_payment", "field_label": "Purpose of Payment", "field_type": "string", "is_mandatory": true, "is_editable": true, "enum_key": "purpose_of_payment", "values_supported": [ { "code": "FAMILY_MAINTENANCE", "description": "Family Maintenance", "value": "Family Maintenance" }, { "code": "HOUSEHOLD_MAINTENANCE", "description": "Household Maintenance", "value": "Household Maintenance" }, { "code": "DONATION_OR_GIFTS", "description": "Donation or Gifts", "value": "Donation or Gifts" }, { "code": "PAYMENT_OF_LOAN", "description": "Payment of Loan", "value": "Payment of Loan" }, { "code": "PURCHASE_OF_PROPERTY", "description": "Purchase of Property", "value": "Purchase of Property" }, { "code": "FUNERAL_EXPENSES", "description": "Funeral Expenses", "value": "Funeral Expenses" }, { "code": "WEDDING_EXPENSES", "description": "Wedding Expenses", "value": "Wedding Expenses" }, { "code": "MEDICAL_EXPENSES", "description": "Medical Expenses", "value": "Medical Expenses" }, { "code": "PAYMENT_OF_BILLS", "description": "Payment of bills", "value": "Payment of bills" }, { "code": "EDUCATION", "description": "Education", "value": "Education" }, { "code": "SAVINGS", "description": "Savings", "value": "Savings" }, { "code": "EMPLOYEE_COLLEAGUE", "description": "Employee Colleague", "value": "Employee Colleague" }, { "code": "BUSINESS_OR_INVESTMENT", "description": "Business or Investment", "value": "Business or Investment" }, { "code": "SALARY", "description": "Salary", "value": "Salary" }, { "code": "PAYMENT_OF_GOODS_AND_SERVICES", "description": "Payment of goods and services", "value": "Payment of goods and services" } ], "field_category": "Additional Data" }, { "field_key": "user_recipient_relationship", "field_label": "User Relationship with Recipient", "field_type": "string", "is_mandatory": false, "is_editable": true, "enum_key": "user_recipient_relationship", "values_supported": [ { "code": "FATHER", "description": "Father", "value": "Father" }, { "code": "MOTHER", "description": "Mother", "value": "Mother" }, { "code": "DAUGHTER", "description": "Daughter", "value": "Daughter" }, { "code": "SON", "description": "Son", "value": "Son" }, { "code": "SISTER", "description": "Sister", "value": "Sister" }, { "code": "BROTHER", "description": "Brother", "value": "Brother" }, { "code": "WIFE", "description": "Wife", "value": "Wife" }, { "code": "HUSBAND", "description": "Husband", "value": "Husband" }, { "code": "FATHER_IN_LAW", "description": "Father in Law", "value": "Father in Law" }, { "code": "MOTHER_IN_LAW", "description": "Mother in Law", "value": "Mother in Law" }, { "code": "AUNTY", "description": "Aunty", "value": "Aunty" }, { "code": "UNCLE", "description": "Uncle", "value": "Uncle" }, { "code": "COUSIN", "description": "Cousin", "value": "Cousin" }, { "code": "NEPHEW", "description": "Nephew", "value": "Nephew" }, { "code": "NIECE", "description": "Niece", "value": "Niece" }, { "code": "GRAND_MOTHER", "description": "Grand Mother", "value": "Grand Mother" }, { "code": "GRAND_FATHER", "description": "Grand Father", "value": "Grand Father" }, { "code": "GRAND_DAUGHTER", "description": "Grand Daughter", "value": "Grand Daughter" }, { "code": "GRAND_SON", "description": "Grand Son", "value": "Grand Son" }, { "code": "FRIEND", "description": "Friend", "value": "Friend" }, { "code": "FRIENDS_FATHER", "description": "Friend's Father", "value": "Friend's Father" }, { "code": "FRIENDS_MOTHER", "description": "Friend's Mother", "value": "Friend's Mother" }, { "code": "SELF", "description": "Self", "value": "Self" } ], "field_category": "Additional Data" } ] } ] } Let's examine one of the fields in the recipient form: JSON { "field_key": "account_type", "field_label": "Bank Account Type", "field_type": "string", "is_mandatory": true, "is_editable": false, "enum_key": "account_type", "values_supported": [ { "code": "SAVINGS_ACCOUNT", "description": "Savings Account", "value": "Savings Account" }, { "code": "CURRENT_ACCOUNT", "description": "Current Account", "value": "Current Account" } Important field parameters: field_key — is the field name and key; you will use this to define the key:value pairs during recipient creation. is_mandatory — is the flag that determines whether the field is required or not is_editable — is the flag that determines if the field can be edited or updated after the recipient's creation values_supported — will appear when an enum is the required value for the field All fields that are marked as mandatory must be provided by the customer (sender). Call Create Cross-border Payout Recipients ( POST /users/wallets/payouts/remittances/recipients ) passing the route, remittance mode definition, and required beneficiary data. Create Cross-border Payout Recipients request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "receiving_institution_type": "BANK", "recipient_type": "INDIVIDUAL", "receiving_currency": "USD", "recipient_country": "USA", "recipient_data": { "user_information": { "first_name": "Steven", "last_name": "Smith", "email": "stevensmith@matchmove.com", "mobile_country_code": "1", "mobile": "2125550123" }, "address_details": { "address_line_1": "1500", "address_line_2": "Broadway", "city": "New York", "state": "NY", "postal_code": "10036", "country": "USA" }, "bank_details": { "account_type": "SAVINGS_ACCOUNT", "account_name": "Steven Smith", "account_number": "2988638169", "code": "123456789", "bank_id": "786bbfd4344a489391582eb8ba931604" }, "additional_data": { "purpose_of_payment": "FAMILY_MAINTENANCE" } } } ' Create Cross-border Payout Recipients response JSON { "id": "f3dc5d8578a14603bab94f51943a53a3", "receiving_institution_type": "BANK", "recipient_type": "INDIVIDUAL", "receiving_currency": "USD", "recipient_country": "USA", "status": "PENDING", "created_by": "1d2f696095bfe563058484b66d0a25fa", "created_at": "2025-12-16T15:48:45 +08:00", "updated_by": "", "updated_at": "", "deleted_by": "", "deleted_at": "", "user": { "id": "1d2f696095bfe563058484b66d0a25fa", "type": "INDIVIDUAL" }, "payment_rail": "LOCAL", "additional_data": { "purpose_of_payment": "Family Maintenance", "user_recipient_relationship": "" }, "address_details": { "address_line_1": "1500", "address_line_2": "Broadway", "address_line_3": "", "address_line_4": "", "city": "New York", "country": "USA", "nationality": "", "postal_code": "10036", "state": "NY" }, "bank_details": { "account_name": "Steven Smith", "account_number": "2988638169", "account_type": "Savings Account", "bank_id": "786bbfd4344a489391582eb8ba931604", "bank_name": "1ST SECURITY BANK OF WASHINGTON", "branch_code": "", "code": "123456789" }, "identification_details": { "country_of_issue": "", "date_of_incorporation": "", "expiry_date": "", "identity_number": "", "identity_type": "", "issue_date": "" }, "user_information": { "date_of_birth": "", "email": "stevensmith@matchmove.com", "first_name": "Steven", "gender": "", "last_name": "Smith", "middle_name": "", "mobile": "2125550123", "mobile_country_code": "1", "occupation": "", "preferred_name": "" } } Recipient Cooling-Off Period - Cross-border A cooling-off period is a mandatory waiting timeframe that restricts account functions like withdrawals and transfers. This safeguard prevents system abuse and provides a "buffer" to detect fraudulent activity before funds move. In the MatchMove platform, this period occurs between a recipient's creation and activation . It acts as a primary fraud prevention layer, ensuring suspicious actions are intercepted before payouts are authorized. Timing and Logic Parallel Execution: The cooling period begins at creation and runs simultaneously with the risk evaluation. During this stage the user state will be set to user.status = PENDING , while the user.sub_status will indicate the progress: RISK_EVALUATION_IN_PROGRESS — will block user activation COOLING_PERIOD_IN_PROGRESS — will block user activation RISK_EVALUATION_CLEAR — will allow user activation if the cooling period is also completed. RISK_EVALUATION_PENDING_REVIEW — risk evaluation requires manual review and will block user activation. COOLING_PERIOD_COMPLETED — will allow user activation if the risk evaluation has cleared the user. Activation Requirement: Both the cooling period and risk evaluation must independently finish before a recipient user.status transitions from the CREATED to PENDING to ACTIVE . A customer (sender) will only be able to send a remittance to ACTIVE recipients; otherwise, the transaction will be blocked by the platform. 3 Monitor the status changes on recipients Cross-border payout events will need to be handled properly for a smoother payout journey for the customer. If the partner wants to be notified of cross-border payout events, they must subscribe to the “Transaction Payouts Advisory” webhook category and events. This webhook will notify the partner for risk-cleared results and for cases when the recipient status is risk-flagged. The webhook receipt will be the signal for the partner to initiate the MatchMove Compliance — Risk Exemption Process to exempt the recipient in cases of false-positive hits. Go to the Leveraging Webhooks section to learn more about setting up the webhooks. Event Description Action PAYOUT.RECIPIENT.CROSSBORDER.STATUS A notification is sent if the recipient profile status has changed. ACTIVE - no action, you may proceed with a remittance transaction PENDING_REVIEW - initiate the MatchMove Compliance - Risk Exemption Process. Sample Recipient Status webhook payload JSON { "event_data": { "event_timestamp": "2025-12-08 07:54:49+0000", "version": "v2", "webhook_event": "PAYOUT.RECIPIENT.CROSSBORDER.STATUS", "program_code": "{{program_code}}", "message_id": "f612ecb8f3364ede8fafccf1bac9ae64", "entity_type": "Transaction", "entities": { "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Brother", "user_source_of_income": "Salary" }, "address_details": { "address_line_1": "211 Montrose", "address_line_2": "Stillorgan Rd", "address_line_3": "", "address_line_4": "", "city": "Dublin", "country": "IRL", "nationality": "", "postal_code": "D04AE48", "state": "Dublin" }, "bank_details": { "account_name": "A******a", "account_type": "Savings Account", "bank_id": "a69b7f1919414b7ab8079eb498d72ac0", "bank_name": "AIB BANK", "iban": "IE06AIBK93357078188028" }, "created_at": "2025-06-28T14:36:49 +08:00", "created_by": "976603fdeb4b97ebc1372253770efb6e", "deleted_at": "", "deleted_by": "", "id": "9c3a7a5ade2e41e58969d742aa8968a7", "identification_details": { "country_of_issue": "", "date_of_incorporation": "", "expiry_date": "", "identity_number": "", "identity_type": "", "issue_date": "" }, "payment_rail": "SWIFT", "receiving_currency": "EUR", "receiving_institution_type": "BANK", "recipient_country": "IRL", "recipient_type": "INDIVIDUAL", "status": "PENDING", "sub_status": "COOLING_PERIOD_IN_PROGRESS" "updated_at": "2025-06-28T14:37:01 +08:00", "updated_by": "SYSTEM", "user": { "email": "paw****ma@yahoo.com", "id": "976603fdeb4b97ebc1372253770efb6e", "mobile": "9819340970", "mobile_country_code": "91", "type": "INDIVIDUAL" }, "user_information": { "date_of_birth": "", "email": "ad******ma@gmail.com", "first_name": "A***i", "gender": "", "last_name": "V***a", "middle_name": "", "mobile": "870379717", "mobile_country_code": "353", "occupation": "", "preferred_name": "" } }, "event_name": "PAYOUT.RECIPIENT.CROSSBORDER.STATUS", "product_code": "{{program_code}}", "service_name": "svc-transactions-payouts-crossborder", "trace_id": "0a045ecc7d4e499d9805715f0172b7d9" } } Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Get a quote for cross-border payment Create a cross-border payment using an existing recipient Create a cross-border payment without an existing recipient Track the status of cross-border payment Manage cross-border payments • [Manage cross-border recipients](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/manage-cross-border-recipients.md): Learn how to create and maintain beneficiary profiles to facilitate seamless cross-border payouts. Understand the necessary recipient details required by the payout network based on the target currency, country, and remittance mode. Use Cases You want to implement a feature that will allow the user to see the list of recipients associated with their accounts. You want to implement a feature that will allow a user to update a recipient's details, following a change in the recipient form for the receiving country. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. At least one cross-border recipient has already been created or defined. API Workflow 1 Retrieve all recipients associated with a user (sender) Call the List Cross-border Payout Recipients ( GET /users/wallets/payouts/remittances/recipients ) to retrieve all the defined recipients associated with a user (sender). Each recipient can be identified by its recipient ID . List Cross-border Payout Recipients request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients?page=1&records_per_page=100&recipient_type={{recipient_type}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••'' List Cross-border Payout Recipient response JSON { "pagination": { "total_records": 70, "records_per_page": 100, "total_pages": 1, "links": { "self": "https://transactions-payouts-crossborder.uat.matchmove-beta.com/{{program_code}}/v2/users/wallets/payouts/remittances/recipients?page=1&recipient_type=INDIVIDUAL&records_per_page=100" } }, "data": [ { "id": "9e100879d19249389b442bb8fc730677", "receiving_institution_type": "BANK", "recipient_type": "INDIVIDUAL", "receiving_currency": "THB", "recipient_country": "THA", "status": "UPDATE_REQUIRED", "created_by": "892c95e28d33d59b898986430a422aeb", "created_at": "2025-12-08T17:42:03 +08:00", "updated_by": "SYSTEM", "updated_at": "2025-12-08T17:42:11 +08:00", "deleted_by": "", "deleted_at": "", "user": { "id": "892c95e28d33d59b898986430a422aeb", "type": "BUSINESS" }, "payment_rail": "LOCAL", "additional_data": { "purpose_of_payment": "Family Maintenance", "user_recipient_relationship": "Aunty" }, "address_details": { "address_line_1": "123", "address_line_2": "Thani", "address_line_3": "Street", "address_line_4": "", "city": "Bangkok", "country": "THA", "nationality": "Thai", "postal_code": "123456", "state": "Bangkok" }, "bank_details": { "account_name": "Jane Smith", "account_number": "123456677", "account_type": "Savings Account", "bank_id": "1280041c4a92449a8fe9aa35075113c4", "bank_name": "AIA COMPANY LIMITED", "code": "BOPITHMM" }, "identification_details": { "country_of_issue": "Virgin Islands", "date_of_incorporation": "2024-08-22", "expiry_date": "3001-10-20", "identity_number": "uy0109x", "identity_type": "Military Id", "issue_date": "2001-10-20" }, "user_information": { "date_of_birth": "2023-05-29", "email": "john.smith@matchmove.com", "first_name": "John", "gender": "Male", "last_name": "Smith", "middle_name": "Williams", "mobile": "9522430905", "mobile_country_code": "63", "occupation": "General Worker", "preferred_name": "John Smith" } }, .. ] } 2 Updating remittance recipient details, due to a remittance form update A remittance recipient, though created, cannot be used for a transaction unless it has been cleared of risk. Also, a remittance recipient cannot be used if not all of its required fields are up to date. Thus, we need to manage the various states that a recipient can go through. Recipient Form Updates Since the recipient forms are dependent on the remittance transaction regulatory requirements of any given region. When these requirements change, an existing recipient impacted by the change must also be updated before it can be used for a transaction. If a recipient requires updating, its status will be changed to UPDATE_REQUIRED . It will only be reactivated again once the necessary changes are made to the recipient profile. To get the updated requirements, the partner must call the List Cross-border Payout Recipient Forms ( GET /users/wallets/payouts/remittances/recipients/forms ) to reveal the new and updated fields. These new and updated fields must be filled up and the updates pushed to the recipient profile. In this example, the recipient form, where a recipient was defined, has a field trading_name that was previously not mandatory. Then this recipient form was updated to require trading_name as a mandatory field. Example remittance form change/update {.. "field_key": "trading_name", "field_label": "Trading Name", "field_type": "string", "is_mandatory": false, —> "is_mandatory": true "is_editable": true ..} Call the Update Cross-border Payout Recipients ( POST /users/wallets/payouts/remittances/recipients ) to pass the updated fields. Update Cross-border Payout Recipients request CURL curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients/<recipient_id>' \ --header 'X-Auth-User-ID: <user_id>' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "recipient_data": { "business_information" : { "trading_name" : "XYZ Corp" } } }' Update Cross-border Payout Recipients response JSON { "id": "3795fb24fa81485ebf014206d2e1383c", "receiving_institution_type": "BANK", "recipient_type": "BUSINESS", "receiving_currency": "EUR", "recipient_country": "AND", "status": "ACTIVE", "created_by": "705392daffe8b3f554ee02f31979c114", "created_at": "2025-08-12T18:36:17 +08:00", "updated_by": "705392daffe8b3f554ee02f31979c114", "updated_at": "2025-08-13T15:05:37 +08:00", "deleted_by": "", "deleted_at": "", "user": { "id": "705392daffe8b3f554ee02f31979c114", "type": "BUSINESS" }, "additional_data": { "purpose_of_payment": "Donation or Gifts", "user_recipient_relationship": "" }, "address_details": { "address_line_1": "123", "address_line_2": "Grove St", "address_line_3": "", "address_line_4": "", "city": "Andorra la Vella", "country": "AND", "postal_code": "12345", "state": "Andorra" }, "bank_details": { "account_name": "Juan Smith", "account_type": "Savings Account", "bank_id": "c925e488e6734d0a9a55845bcaca28d3", "bank_name": "ANDORRA BANC AGRICOL REIG S.A.", "iban": "AD3456789012345678901234" }, "business_information": { "business_email": "contactus@xyz.com", "registered_org_name": "XYZ Corp", "registration_number": "", "tax_id": "", "trading_name": "XYZ Corp" }, "identification_details": { "country_of_issue": "", "date_of_incorporation": "", "expiry_date": "", "identity_number": "", "identity_type": "", "issue_date": "" }, "representative_info": { "first_name": "Juan", "last_name": "Smith", "middle_name": "", "mobile": "333333", "mobile_country_code": "376", "preferred_name": "" } } 3 Ad hoc recipient information updates In cases where a recipient's information requires an update that is not demanded by a remittance recipient form update, the update can still be pushed using the same Update Cross-border Payout Recipient s ( POST /users/wallets/payouts/remittances/recipients ) method. However, only the fields marked "is_editable": true are allowed to be updated. If the information that the recipient wants to update is not marked as editable, then the only way to push those updates is through a new recipient creation. For this, we will need to delete the existing recipient and recreate it using the updated details. We can delete an existing recipient using the Update Cross-border Payout Recipient Statuses ( PUT users/wallets/payouts/remittances/recipients/{id}/statuses ). This API can also be used to deactivate or reactivate a recipient. Update Cross-border Payout Recipient Statuses request CURL curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/recipients/{{recipient_id}}/statuses' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "status": "DELETE" }' Update Cross-border Payout Recipient Statuses response JSON { "id": "3795fb24fa81485ebf014206d2e1383c", "message": "Recipient has been deleted successfully.", "status": "DELETED", "updated_by": "705392daffe8b3f554ee02f31979c114", "updated_at": "2025-08-13T15:35:10 +08:00" } • [Get a quote for cross-border payment](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/get-a-quote-for-cross-border-payment.md): Understand how to get a time-limited quote with guaranteed foreign exchange rates and a transparent breakdown of all fees. This guide explains the mandatory step of locking in the financial details of a cross-border transfer. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve a quotation (test calculation) containing the deductible amount and all fees charged for the cross-border payment transaction. You want to implement a feature in your application that takes in the user's desired route and amount and generates a quotation. You want to display the breakdown of all the deductibles from the user (sender) and the receivables of the recipient (receiver). You want to display the foreign exchange effect on the deductible and receivable amounts. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. API Workflow 1 Retrieve the available corridors (remittance routes) for the program Before asking the user (sender) any of their intended remittance details, we need to know the available corridors or remittance routes that are enabled in the program. Corridor enablement will be based on the program configuration (as stated in the contract) along with the remittance rail and SWIFT routes availability. Call the List Cross-border Payout Corridors ( GET /users/wallet/payouts/remittances/corridors ) filtering only the active routes based on the user type of the customer (sender). List Cross-border Payout Corridors request (filter by status and user_type [sender], recipient_type [receiver]) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?status=ACTIVE&recipient_type=INDIVIDUAL&user_type=INDIVIDUAL' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' List Cross-border Payout Corridors response JSON { "pagination": { "total_records": 5, "records_per_page": 100, "total_pages": 1, "links": { "self": "https://{{server}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors?page=1&records_per_page=100&user_type=INDIVIDUAL&recipient_type=INDIVIDUAL" } }, "data": [ { "id": "4b007556de30487d8fd7df0e53d07bd7", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "LOCAL", "charge_types": [], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "0823dde9bcf847bc97723395bb7b69aa", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "1a65c300fe594e18bb1ad9fff831b1b7", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Singapore Dollar", "currency_code": "SGD", "currency_precision": "2", "status": "ACTIVE" }, { "id": "b61d6b7ee37a4708b0c36e9c3cbb7883", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Euro", "currency_code": "EUR", "currency_precision": "2", "status": "ACTIVE" }, { "id": "e6ab8a36a9ca41b7962a2e04948b74ce", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "charge_types": [ "OUR", "SHA" ], "currency": "Pound Sterling", "currency_code": "GBP", "currency_precision": "2", "status": "ACTIVE" } ] } You will need to display the list of active corridors available to your users in your frontend. To help the user choose, you will need to display the additional rail parameters, such as payment_rails and charge_types . Once the user has selected a corridor, take note of the corridor ID. You can use this to call the Get Cross-border Payout Corridor Details ( GET /users/wallet/payouts/remittances/corridors/{corridor_id} ) by passing the chosen corridor ID of the remittance route. This will reveal more details such as corridor rates and fees, per-transaction limits, etc. You can also display this additional corridor information for the user to help him have a more informed decision before proceeding to get a quotation. Get Cross-border Payout Corridor Details request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallet/payouts/remittances/corridors/{{corridor_id}}' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Get Cross-border Payout Corridor Details response JSON { "id": "0823dde9bcf847bc97723395bb7b69aa", "receiving_country": "United States", "receiving_country_code": "USA", "mobile_country_code": "+1", "user_type": "INDIVIDUAL", "recipient_type": "INDIVIDUAL", "institute_type": "BANK", "payment_rail": "SWIFT", "currency": "US Dollar", "currency_code": "USD", "currency_precision": "2", "status": "ACTIVE", "rates": { "platform": [ { "charge_type": "OUR", "transfer_fee_amount": "1.50", "transfer_fee_currency": "USD", "transfer_fee_percentage": "0.000000000" }, { "charge_type": "SHA", "transfer_fee_amount": "1.50", "transfer_fee_currency": "USD", "transfer_fee_percentage": "0.000000000" } ], "program": [ { "charge_type": "OUR", "exchange_rate_markup": "0.000000000", "transfer_fee_amount": "2.50", "transfer_fee_currency": "USD", "transfer_fee_percentage": "0.000000000" }, { "charge_type": "SHA", "exchange_rate_markup": "0.000000000", "transfer_fee_amount": "2.50", "transfer_fee_currency": "USD", "transfer_fee_percentage": "0.000000000" } ] }, "limits": { "transaction_limits": { "delivery_time": "T+1", "maximum_amount": "500000.00", "maximum_amount_currency": "USD", "minimum_amount": "100.00", "minimum_amount_currency": "USD", "transaction_cutoff": "04:00 PM", "transaction_cutoff_timezone": "Asia/Singapore" }, "velocity_limits": { "max_per_transaction": "25000.00", "transaction_limit_currency": "USD", "transaction_rolling_in_days": 30, "max_transaction_rolling_days_sender": "125000.00", "max_transaction_rolling_days_receiver": "125000.00", "max_transaction_sender_currency": "USD", "max_transaction_receiver_currency": "USD" } }, "permitted_purposes": [ "FAMILY_MAINTENANCE", "HOUSEHOLD_MAINTENANCE", "DONATION_OR_GIFTS", "PAYMENT_OF_LOAN", "PURCHASE_OF_PROPERTY", "FUNERAL_EXPENSES", "WEDDING_EXPENSES", "MEDICAL_EXPENSES", "PAYMENT_OF_BILLS", "EDUCATION", "SAVINGS", "EMPLOYEE_COLLEAGUE", "BUSINESS_OR_INVESTMENT", "SALARY", "PAYMENT_OF_GOODS_AND_SERVICES" ] } }} Corridor Limits Transaction Limits This is the transaction amount limit per transaction. Velocity Limits This is the transaction amount limit within a rolling period. The velocity spending is the accumulated sum of all the successful (completed) and pending (outstanding) transaction amounts within the rolling period. 2 Enquire for a quote for a cross-border payout transaction A quote or quotation is a detailed computation of fees, the charged amount (sender), and the recipient amount (recipient). When all the required parameters are ready, call Enquire Cross-border Payout Quotations ( POST /users/wallets/payouts/remittances/quotes ) to retrieve the calculated quotation for the incoming remittance transaction of the customer. A quotation can be identified by its quotation ID . Enquire Cross-border Payout Quotations request (LOCAL) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "amount": "300", "recipient_country": "USA", "receiving_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "quote_type": "REVERSE", "payment_rail": "LOCAL", "fees": { "included": false } }' Enquire Cross-border Payout Quotations response (LOCAL) JSON { "quotes": [ { "id": "KljS2wEM5IDM3gTN2cTMtUFRTVVTNd0Ut8UVRB", "expiry": "2025-12-16T16:31:30 +08:00", "delivery_time": "NEXT DAY", "status": "CONFIRMED", "type": "REVERSE", "source_country": "SGP", "source_currency": "USD", "destination_country": "USA", "destination_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "payment_rail": "LOCAL", "charge_type": null, "user": { "id": "1d2f696095bfe563058484b66d0a25fa", "email": "hinanshu@matchmove.com", "mobile_country_code": "91", "mobile": "8054042741", "type": "INDIVIDUAL" }, "charged_amount": { "amount": "306.75", "currency": "USD" }, "converted_amount": { "amount": "300.00", "currency": "USD" }, "recipient_amount": { "amount": "300.00", "currency": "USD" }, "fees": { "included": false, "fixed_amount": { "amount": "6.00", "currency": "USD" }, "percentage_value": "0.250000000", "percentage_amount": { "amount": "0.75", "currency": "USD" }, "total": { "amount": "6.75", "currency": "USD" }, "details": { "platform_charge": { "fixed_amount": { "amount": "5.00", "currency": "USD" }, "percentage_value": "0.050000000", "percentage_amount": { "amount": "0.15", "currency": "USD" }, "total": { "amount": "5.15", "currency": "USD" } }, "markup": { "program": { "fixed_amount": { "amount": "1.00", "currency": "USD" }, "percentage_value": "0.200000000", "percentage_amount": { "amount": "0.60", "currency": "USD" }, "total": { "amount": "1.60", "currency": "USD" } }, "total_markup": { "fixed_amount": { "amount": "1.00", "currency": "USD" }, "percentage_value": "0.200000000", "percentage_amount": { "amount": "0.60", "currency": "USD" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } }, "created_by": "1d2f696095bfe563058484b66d0a25fa", "created_at": "2025-12-16T15:31:30 +08:00" } ] } Enquire Cross-border Payout Quotations request (SWIFT) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "amount": "300", "recipient_country": "USA", "receiving_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "quote_type": "REVERSE", "payment_rail": "SWIFT", "charge_type": "OUR", "fees": { "included": false } }' Enquire Cross-border Payout Quotations response (SWIFT) JSON { "quotes": [ { "id": "JJlWUNTM4ADM3gTN2cTMtUFRTVVTNd0Ut8UVRB", "expiry": "2025-12-16T16:28:01 +08:00", "delivery_time": "NEXT DAY", "status": "CONFIRMED", "type": "REVERSE", "source_country": "SGP", "source_currency": "USD", "destination_country": "USA", "destination_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "payment_rail": "SWIFT", "charge_type": "OUR", "user": { "id": "1d2f696095bfe563058484b66d0a25fa", "email": "johnsmith@matchmove.com", "mobile_country_code": "91", "mobile": "8054042741", "type": "INDIVIDUAL" }, "charged_amount": { "amount": "379.45", "currency": "USD" }, "converted_amount": { "amount": "300.00", "currency": "USD" }, "recipient_amount": { "amount": "300.00", "currency": "USD" }, "fees": { "included": false, "fixed_amount": { "amount": "79.00", "currency": "USD" }, "percentage_value": "0.150000000", "percentage_amount": { "amount": "0.45", "currency": "USD" }, "total": { "amount": "79.45", "currency": "USD" }, "details": { "platform_charge": { "fixed_amount": { "amount": "76.50", "currency": "USD" }, "percentage_value": "0.150000000", "percentage_amount": { "amount": "0.45", "currency": "USD" }, "total": { "amount": "76.95", "currency": "USD" } }, "markup": { "program": { "fixed_amount": { "amount": "2.50", "currency": "USD" }, "percentage_value": "0.000000000", "percentage_amount": { "amount": "0.00", "currency": "USD" }, "total": { "amount": "2.50", "currency": "USD" } }, "total_markup": { "fixed_amount": { "amount": "2.50", "currency": "USD" }, "percentage_value": "0.000000000", "percentage_amount": { "amount": "0.00", "currency": "USD" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } }, "created_by": "1d2f696095bfe563058484b66d0a25fa", "created_at": "2025-12-16T15:28:01 +08:00" } ] } Cross-border Payout Quotation Expiry A cross-border payout quote will only be valid for a specified period and will have an expiry time. During this period, the forex rate, converted amount, and total fees will be reserved. Once the quote has expired, you will need to pull a fresh quotation using the Enquire Quotes API. If the quote expiry happens while the customer is about to send the remittance transaction, an appropriate error message regarding quote expiry will be emitted. 3 [SWIFT] Prepare for supplementary document upload for high-value transactions For SWIFT cross-border payments, a supporting document such as an invoice will be mandatory when: the transfer amount is greater than the review threshold*; and, the document requirement is enabled for selected transfer mode: ( user_type to recipient_type ) combination *review threshold — is not a fixed value, it may adjust following compliance and risk reviews. This requirement will block the processing of the transaction until the requirement is satisfied. When a quotation is requested and the intended transaction amount breaches the threshold, an additional indicator field will be added to the payload. You will need to prepare to collect a document from the user (sender) intending to send the cross-border payment. Enquire Cross-border Payout Quotation request (SWIFT) with high-value transaction amount CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/quotes' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "amount": "100000", "recipient_country": "USA", "receiving_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "quote_type": "FORWARD", "charge_type": "OUR", "payment_rail": "SWIFT", "fees": { "included": false } }' Enquire Cross-border Payout Quotation response (SWIFT) with high-value transaction amount JSON { "quotes": [ { "id": "Sh1UNlzN4ETO1kTN2cTMtUFRTVVTNd0Ut8UVRB", "expiry": "2025-12-17T17:13:07 +08:00", "delivery_time": "2 DAYS", "status": "CONFIRMED", "sub_status": "DOCUMENT_REQUIRED", "document_required_types": [ "INVOICE" ], "document_requirements": { "types": [ "INVOICE" ], "accepted_formats": [ "pdf", "jpg", "png" ], "max_file_size": "5MB" }, "type": "FORWARD", "source_country": "SGP", "source_currency": "USD", "destination_country": "USA", "destination_currency": "USD", "recipient_type": "INDIVIDUAL", "receiving_institution_type": "BANK", "payment_rail": "SWIFT", "charge_type": "OUR", "user": { "id": "7b61722fb9f94a232a6dbe5df53d6d49", "email": "john.smith@matchmove.com", "mobile_country_code": "65", "mobile": "2076071232", "type": "INDIVIDUAL" }, "charged_amount": { "amount": "100229.23", "currency": "USD" }, "converted_amount": { "amount": "100000.00", "currency": "USD" }, "recipient_amount": { "amount": "100000.00", "currency": "USD" }, "fees": { "included": false, "fixed_amount": { "amount": "79.00", "currency": "USD" }, "percentage_value": "0.150000000", "percentage_amount": { "amount": "0.23", "currency": "USD" }, "total": { "amount": "79.23", "currency": "USD" }, "details": { "platform_charge": { "fixed_amount": { "amount": "76.50", "currency": "USD" }, "percentage_value": "0.150000000", "percentage_amount": { "amount": "0.23", "currency": "USD" }, "total": { "amount": "76.73", "currency": "USD" } }, "markup": { "program": { "fixed_amount": { "amount": "2.50", "currency": "USD" }, "percentage_value": "0.000000000", "percentage_amount": { "amount": "0.00", "currency": "USD" }, "total": { "amount": "2.50", "currency": "USD" } }, "total_markup": { "fixed_amount": { "amount": "2.50", "currency": "USD" }, "percentage_value": "0.000000000", "percentage_amount": { "amount": "0.00", "currency": "USD" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } }, "created_by": "7b61722fb9f94a232a6dbe5df53d6d49", "created_at": "2025-12-17T16:13:07 +08:00" } ] } Let's examine the indicator field for document upload requirements on high-value cross-border payment: "status": "INITIATED", "sub_status": "DOCUMENT_REQUIRED", ← The quote sub_status indicating document requirement "document_requirements" : { "types": ["INVOICE"],"accepted_formats": ["pdf","jpg","png"],"max_file_size": "5MB"} ← List of accepted documents (New) "document_required_types": [ "invoice", "bank_statement"] , ← List of accepted documents (Deprecated) The required document will need to be uploaded right after the cross-border payment is sent and the quotation (quotation ID) is consumed. Go to the Perform a cross-border payment using an existing beneficiary or without an existing beneficiary section to learn more. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Create a recipient for cross-border payment Create a cross-border payment using an existing recipient Create a cross-border payment without an existing recipient Track the status of cross-border payment Manage cross-border payments • [Perform a cross-border payment using an existing recipient](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/perform-a-cross-border-payment-using-an-existing-recipient.md): Learn the standard process for executing a cross-border transfer to a saved recipient profile. This guide shows you how to use a previously generated quote to send funds to a known recipient. The user in this document pertains to both the individual and business user types. Use Cases You want to execute a cross-border payment transaction to a defined recipient. You want to implement a feature that will allow individual users to perform cross-border payments to defined individual recipients (C2C remittance mode). You want to implement a feature that will allow business users to perform cross-border payments to defined individual recipients (B2C remittance mode). You want to implement a feature that will allow business users to perform cross-border payments to defined business recipients (B2B remittance mode). Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current deduct_limits and transfer_out_limits must have enough buffer to accommodate the incoming debit amount. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. The user account must have a balance that is equal to or higher than the payment amount. A valid recipient must have already been defined and must be in an activated status. The selected recipient ID of the individual or business to whom the user wants to send funds. The selected quotation ID of the remittance quotation that the user wishes to use to send funds. The quotation and quotation ID are still active and have not yet expired before initiating the payment transaction. API Workflow 1 Initiate a remittance transaction (with a recipient ID) Before initiating a new remittance transaction, the sender must read and agree to the Remittance Terms of Service (TOS) . A link/view to the full terms and conditions page, along with a checkbox requiring confirmation of acceptance, must be presented in the application. This must be done every time a new remittance transaction is about to be sent. The TOS acceptance timestamp and details must be recorded, and the details sent in the Send Remittance Transaction request. Call the Send Cross-border Payout Transactions ( POST /users/wallets/payouts/remittances/transactions ) and pass the selected recipient ID and quotation ID . Send Cross-border Payout Transactions API-related field enumerations: user_recipient_relationship allowed values are listed in the List Mobile Country Code Enumerations ( GET /users/enumerations/mobile_country_code ). user_source_of_income allowed values are listed in the List Source of Income Enumerations ( GET /users/enumerations/main_income_source ). user_occupation allowed values are listed in the List Occupation Enumerations ( GET /users/enumerations/occupations ). Send Cross-border Payout Transactions request (with quotation ID and recipient ID) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data '{ "quote_id": "CVEMKp0MwkzM3gTN2cTMtUFRTVVTNd0Ut8UVRB", "recipient_id": "f3dc5d8578a14603bab94f51943a53a3", "user_recipient_relationship": "FATHER", "user_source_of_income":"SALARY", "tos_acceptance": { "date": "2023-07-23T10:59:12+08:00", "ip": "8.8.8.8", "service_agreement": "string", "user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "device_id": "string" }, "remarks": "Remittance comments here" }' Send Cross-border Payout Transactions response (with quotation ID and recipient ID) JSON { "id": "OVERBt0NwEDN3gTN2cTMtUFRTVVTNd0Ut4EWUB", "status": "INITIATED", "sub_status": "TRANSACTION_INITIATED", "message": "Request received, processing started", "source": [], "user": { "id": "1d2f696095bfe563058484b66d0a25fa", "email": "johnsmith@matchmove.com", "mobile_country_code": "91", "mobile": "8054042741", "country": "SGP", "currency": "USD", "type": "INDIVIDUAL" }, "recipient": { "id": "f3dc5d8578a14603bab94f51943a53a3", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "1ST SECURITY BANK OF WASHINGTON", "receiving_institution_code": "123456789", "account_name": "Steven Smith", "account_number": "2988638169", "account_type": "Savings Account" }, "quote": { "id": "CVEMKp0MwkzM3gTN2cTMtUFRTVVTNd0Ut8UVRB", "type": "REVERSE", "status": "CONFIRMED", "fees": { "included": false, "fixed_amount": { "currency": "USD", "amount": "6.00" }, "percentage_value": "0.250000000", "percentage_amount": { "currency": "USD", "amount": "0.75" }, "total": { "currency": "USD", "amount": "6.75" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.15" }, "total": { "currency": "USD", "amount": "5.15" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "1.00" }, "percentage_value": "0.200000000", "percentage_amount": { "currency": "USD", "amount": "0.60" }, "total": { "currency": "USD", "amount": "1.60" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "1.00" }, "percentage_value": "0.200000000", "percentage_amount": { "currency": "USD", "amount": "0.60" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "306.75" }, "converted_amount": { "currency": "USD", "amount": "300.00" }, "recipient_amount": { "currency": "USD", "amount": "300.00" }, "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "Salary" }, "tos": { "tos_acceptance_date": "2023-07-23 02:59:12", "tos_acceptance_device_id": "string", "tos_acceptance_ip": "8.8.8.8", "tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "tos_acceptance_service_agreement": "string" }, "remarks": "Any String", "created_by": "1d2f696095bfe563058484b66d0a25fa", "created_at": "2025-12-16T16:35:07 +08:00", "updated_at": "2025-12-16T16:35:07 +08:00" } The initiated remittance transaction will be set to the INITIATED status upon transaction confirmation, and this transaction will be queued for processing. 2 [SWIFT] Upload supplementary documents for high-value transactions (when required) Document Upload Requirement Depending on the configuration, some SWIFT cross-border payments may require a supporting document (e.g., invoices) when: the transfer amount is greater than the review threshold* the document requirement is enabled for selected transfer mode: ( user_type to recipient_type ) combination the payment rail for the remittance route is enabled for document upload RFI Requirement Other high-value transactions may be issued an RFI when: the transactions require some additional information before the payment rail provider can process the transaction the transfer amount is greater than the review threshold* the payment rail for the remittance route is NOT enabled for document upload These RFI will be a manual process and will require email communication between the Partner payouts team and MatchMove Finance teams for resolutions. * review threshold — is not a fixed value; it may adjust following compliance and risk reviews. This requirement will block the processing of the transaction until the requirement is satisfied. An additional indicator field will be added in the payment response for transaction amounts that have breached the threshold. Failure to upload the required document within the quote expiry period will move the transaction state to EXPIRED and remove the transaction from the processing queue. Send Cross-border Payout Transactions response (with quotation ID and recipient ID) with high-value transaction amount JSON { "id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "status": "INITIATED", "sub_status": "DOCUMENT_REQUIRED", "document_required_types": [ "INVOICE". "SOURCE_OF_FUNDS" ], "document_requirements": { "types": [ "INVOICE", "SOURCE_OF_FUNDS" ], "accepted_formats": [ "pdf", "jpg", "png" ], "max_file_size": "5MB" }, "message": "Documents are required for this high-value transfer. Upload and confirm to proceed.", "source": [], "user": { "id": "7b61722fb9f94a232a6dbe5df53d6d49", "email": "testqa0711122023@matchmove.com", "mobile_country_code": "65", "mobile": "2076071232", "country": "SGP", "currency": "USD", "type": "INDIVIDUAL" }, "recipient": { "id": "3fe6e9ab35354e4a9cbd9429dcfd9560", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "1ST SECURITY BANK OF WASHINGTON", "receiving_institution_code": "123456789", "account_name": "Steven Smith", "account_number": "2118639169", "account_type": "Savings Account" }, "quote": { "id": "Sh1UNlzN4ETO1kTN2cTMtUFRTVVTNd0Ut8UVRB", "type": "FORWARD", "status": "CONFIRMED", "fees": { "included": false, "fixed_amount": { "currency": "USD", "amount": "79.00" }, "percentage_value": "0.150000000", "percentage_amount": { "currency": "USD", "amount": "0.23" }, "total": { "currency": "USD", "amount": "79.23" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "76.50" }, "percentage_value": "0.150000000", "percentage_amount": { "currency": "USD", "amount": "0.23" }, "total": { "currency": "USD", "amount": "76.73" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "2.50" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" }, "total": { "currency": "USD", "amount": "2.50" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "2.50" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "100229.23" }, "converted_amount": { "currency": "USD", "amount": "100000.00" }, "recipient_amount": { "currency": "USD", "amount": "100000.00" }, "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "Salary" }, "tos": { "tos_acceptance_date": "2023-07-23 02:59:12", "tos_acceptance_device_id": "string", "tos_acceptance_ip": "8.8.8.8", "tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "tos_acceptance_service_agreement": "string" }, "remarks": "Remittance comment here", "created_by": "7b61722fb9f94a232a6dbe5df53d6d49", "created_at": "2025-12-17T16:19:46 +08:00", "updated_at": "2025-12-17T16:19:46 +08:00" } Let's examine the indicator field for document upload requirements on high-value cross-border payment: "status": "INITIATED", "sub_status": "DOCUMENT_REQUIRED", ← The quote sub_status indicating document requirement "document_requirements" : { "types": ["INVOICE, SOURCE_OF_FUNDS"],"accepted_formats": ["pdf","jpg","png"],"max_file_size": "5MB"} ← List of accepted documents (New) To upload the required supplementary document for the cross-border payment transaction, you can call Create/Replace Cross-border Payout Transaction Documents ( POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) passing in the transaction ID of the cross-border payment that was initiated and is requiring a document upload. Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 5MB per file No. of files: maximum 1 file Document types supported: INVOICE Verifies the underlying purpose of the transaction. It acts as proof that the funds are being sent for a legitimate reason, such as paying a vendor, settling a bill, or purchasing goods and services. SOURCE_OF_FUNDS Validates the legal origin of the sender's money. This typically involves documents like payslips, bank statements, or tax returns to ensure the money entering the system does not stem from illicit activities. Create/Replace Cross-border Payout Transaction Documents request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: •••••' \ --form 'file=@"/Users//invoice.png"' \ --form 'document_type="INVOICE"' \ --form 'category="TRANSFER_PURPOSE"' Create/Replace Cross-border Payout Transaction Documents response JSON { "submission_id": "75a7218c835043169eee5eaf32e04196", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "category": "TRANSFER_PURPOSE", "status": "UPLOADED", "documents": [ { "id": "36xtPDySJj6jgETNx2XZZ44tNsA", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "created_at": "2025-12-17T16:27:03 +08:00", "type": "INVOICE", "category": "TRANSFER_PURPOSE", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png", "link_expires_at": "2025-12-17T16:42:03 +08:00", "status": "UPLOADED" } ], "count": 1 } After the document is successfully uploaded, you will need to finalize the requirement completion and put the transaction on resume the queue for processing. You can do this by calling Confirm Cross-border Payout Transaction Documents ( PUT /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) passing the transaction ID . Confirm Cross-border Payout Transaction Documents request CURL curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Confirm Cross-border Payout Transaction Documents response JSON "OK" You can also call List Cross-border Payout Transaction Documents ( GET /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) to view and verify the document submitted for the high-value transaction. List Cross-border Payout Transaction Documents request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' List Cross-border Payout Transaction Documents response JSON { "data": [ { "id": "36xtPDySJj6jgETNx2XZZ44tNsA", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "created_at": "2025-12-17T16:27:03 +08:00", "type": "INVOICE", "category": "TRANSFER_PURPOSE", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png", "link_expires_at": "2025-12-17T16:42:03 +08:00", "status": "UPLOADED" } ] } If during your document verification, you noticed that you have uploaded the wrong file or the file is in bad condition (such as blurry images). You will be able to replace the file using the same Create/Replace Cross-border Payout Transaction Documents ( POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) endpoint discussed above. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Create a recipient for cross-border payment Get a quote for cross-border payment Create a cross-border payment without an existing recipient Track the status of cross-border payment Manage cross-border payments • [Perform a cross-border payment without an existing recipient](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/perform-a-cross-border-payment-without-an-existing-recipient.md): Understand how to execute a one-time cross-border payment without first creating a recipient profile. This guide covers transfers where the recipient details are provided at the time of the transaction, rather than selected from a saved profile. The user in this document pertains to both the individual and business user types. Use Cases You want to execute a cross-border payment transaction without a predefined recipient. You want to implement a feature that will allow individual users to perform cross-border payments to ad hoc individual recipients (C2C remittance mode). You want to implement a feature that will allow business users to perform cross-border payments to ad hoc individual recipients (B2C remittance mode). You want to implement a feature that will allow business users to perform cross-border payments to ad hoc business recipients (B2B remittance mode). Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. The user account's current deduct_limits and transfer_out_limits must have enough buffer to accommodate the incoming debit amount. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. The user account must have a balance that is equal to or higher than the payment amount. The selected quotation ID of the remittance quotation that the user wishes to use to send funds. The quotation and quotation ID are still active and have not yet expired before initiating the payment transaction. API Workflow 1 Initiate a remittance transaction (without a recipient ID) Before initiating a new remittance transaction, the sender must read and agree to the Remittance Terms of Service (TOS). A link/view to the full terms and conditions page, along with a checkbox requiring confirmation of acceptance, must be presented in the application. This must be done every time a new remittance transaction is about to be sent. The TOS acceptance timestamp and details must be recorded and sent in the Send Remittance Transaction request. Call the Send Cross-border Payout Transactions ( POST /users/wallets/payouts/remittances/transactions ) and passing the selected quotation ID and the recipient details based on the remittance form requirement of the recipient country, payment_rail, and remittance mode. You can call List Cross-border Payout Recipient Forms ( GET /users/wallets/payouts/remittances/recipients/forms ) to get the list of information required for a recipient for a specific remittance route. You can go to the Create a recipient for cross-border payment to know more about how to construct a recipient based on the remittance form requirements. Send Cross-border Payout Transactions API-related field enumerations: user_recipient_relationship allowed values are listed in the List Mobile Country Code Enumerations ( GET /users/enumerations/mobile_country_code ). user_source_of_income allowed values are listed in the List Source of Income Enumerations ( GET /users/enumerations/main_income_source ). user_occupation allowed values are listed in the List Occupation Enumerations ( GET /users/enumerations/occupations ). Send Cross-border Payout Transactions request (without a recipient ID) CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions' \ --header 'X-Auth-User-ID: 1d2f696095bfe563058484b66d0a25fa' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' \ --data-raw '{ "quote_id": "UNUMYhUO5UDN3gTN2cTMtUFRTVVTNd0Ut8UVRB", "user_recipient_relationship": "FATHER", "user_source_of_income": "SALARY", "recipient_details": { "receiving_institution_type": "BANK", "recipient_type": "INDIVIDUAL", "receiving_currency": "USD", "recipient_country": "USA", "payment_rail": "SWIFT", "recipient_data": { "user_information": { "first_name": "James", "last_name": "Smith", "email": "jamesmith@matchmove.com", "mobile_country_code": "1", "mobile": "2145520123" }, "address_details": { "address_line_1": "1500", "address_line_2": "Broadway", "city": "New York", "state": "NY", "postal_code": "10036", "country": "USA" }, "bank_details": { "account_type": "SAVINGS_ACCOUNT", "account_name": "Steven Smith", "account_number": "2118639169", "code": "123456789", "bank_id": "786bbfd4344a489391582eb8ba931604" }, "additional_data": { "purpose_of_payment": "FAMILY_MAINTENANCE" } } }, "tos_acceptance": { "date": "2023-07-23T10:59:12+08:00", "ip": "8.8.8.8", "service_agreement": "string", "user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "device_id": "string" }, "remarks": "Remittance comment here" }' Send Cross-border Payout Transactions response (without a recipient ID) JSON { "id": "00kRIBzM2cDN3gTN2cTMtUFRTVVTNd0Ut4EWUB", "status": "INITIATED", "sub_status": "TRANSACTION_INITIATED", "message": "Request received, processing started", "source": [], "user": { "id": "1d2f696095bfe563058484b66d0a25fa", "email": "hinanshu@matchmove.com", "mobile_country_code": "91", "mobile": "8054042741", "country": "SGP", "currency": "USD", "type": "INDIVIDUAL" }, "recipient": { "id": "cdd9f88ca7794da8bf3ccbf5ae0a2bcc", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "1ST SECURITY BANK OF WASHINGTON", "receiving_institution_code": "123456789", "account_name": "Steven Smith", "account_number": "2118639169", "account_type": "Savings Account" }, "quote": { "id": "UNUMYhUO5UDN3gTN2cTMtUFRTVVTNd0Ut8UVRB", "type": "REVERSE", "status": "CONFIRMED", "fees": { "included": false, "fixed_amount": { "currency": "USD", "amount": "6.00" }, "percentage_value": "0.250000000", "percentage_amount": { "currency": "USD", "amount": "0.75" }, "total": { "currency": "USD", "amount": "6.75" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "5.00" }, "percentage_value": "0.050000000", "percentage_amount": { "currency": "USD", "amount": "0.15" }, "total": { "currency": "USD", "amount": "5.15" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "1.00" }, "percentage_value": "0.200000000", "percentage_amount": { "currency": "USD", "amount": "0.60" }, "total": { "currency": "USD", "amount": "1.60" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "1.00" }, "percentage_value": "0.200000000", "percentage_amount": { "currency": "USD", "amount": "0.60" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "306.75" }, "converted_amount": { "currency": "USD", "amount": "300.00" }, "recipient_amount": { "currency": "USD", "amount": "300.00" }, "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "Salary" }, "tos": { "tos_acceptance_date": "2023-07-23 02:59:12", "tos_acceptance_device_id": "string", "tos_acceptance_ip": "8.8.8.8", "tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "tos_acceptance_service_agreement": "string" }, "remarks": "Remittance comment here", "created_by": "1d2f696095bfe563058484b66d0a25fa", "created_at": "2025-12-16T16:46:03 +08:00", "updated_at": "2025-12-16T16:46:03 +08:00" } The initiated remittance transaction will be set to the INITIATED status upon transaction confirmation, and this transaction will be queued for processing. 2 [SWIFT] Upload supplementary documents for high-value transactions Document Upload Requirement Depending on the configuration, some SWIFT cross-border payments may require a supporting document (e.g., invoices) when: the transfer amount is greater than the review threshold* the document requirement is enabled for selected transfer mode: ( user_type to recipient_type ) combination the payment rail for the remittance route is enabled for document upload RFI Requirement Other high-value transactions may be issued an RFI when: the transactions require some additional information before the payment rail provider can process the transaction the transfer amount is greater than the review threshold* the payment rail for the remittance route is NOT enabled for document upload These RFI will be a manual process and will require email communication between the Partner payouts team and MatchMove Finance teams for resolutions. * review threshold — is not a fixed value; it may adjust following compliance and risk reviews. This requirement will block the processing of the transaction until the requirement is satisfied. An additional indicator field will be added in the payment response for transaction amounts that have breached the threshold. Failure to upload the required document within the quote expiry period will move the transaction state to EXPIRED and remove the transaction from the processing queue. Send Cross-border Payout Transactions response (with quotation ID and recipient ID) with high-value transaction amount JSON { "id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "status": "INITIATED", "sub_status": "DOCUMENT_REQUIRED", "document_required_types": [ "INVOICE", "SOURCE_OF_FUNDS" ], "document_requirements": { "types": [ "INVOICE", "SOURCE_OF_FUNDS" ], "accepted_formats": [ "pdf", "jpg", "png" ], "max_file_size": "5MB" }, "message": "Documents are required for this high-value transfer. Upload and confirm to proceed.", "source": [], "user": { "id": "7b61722fb9f94a232a6dbe5df53d6d49", "email": "testqa0711122023@matchmove.com", "mobile_country_code": "65", "mobile": "2076071232", "country": "SGP", "currency": "USD", "type": "INDIVIDUAL" }, "recipient": { "id": "3fe6e9ab35354e4a9cbd9429dcfd9560", "country": "USA", "currency": "USD", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "1ST SECURITY BANK OF WASHINGTON", "receiving_institution_code": "123456789", "account_name": "Steven Smith", "account_number": "2118639169", "account_type": "Savings Account" }, "quote": { "id": "Sh1UNlzN4ETO1kTN2cTMtUFRTVVTNd0Ut8UVRB", "type": "FORWARD", "status": "CONFIRMED", "fees": { "included": false, "fixed_amount": { "currency": "USD", "amount": "79.00" }, "percentage_value": "0.150000000", "percentage_amount": { "currency": "USD", "amount": "0.23" }, "total": { "currency": "USD", "amount": "79.23" }, "details": { "platform_charge": { "fixed_amount": { "currency": "USD", "amount": "76.50" }, "percentage_value": "0.150000000", "percentage_amount": { "currency": "USD", "amount": "0.23" }, "total": { "currency": "USD", "amount": "76.73" } }, "markup": { "program": { "fixed_amount": { "currency": "USD", "amount": "2.50" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" }, "total": { "currency": "USD", "amount": "2.50" } }, "total_markup": { "fixed_amount": { "currency": "USD", "amount": "2.50" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "USD", "amount": "0.00" } } } } }, "fx_rate": { "value": "1.000000000", "details": { "platform_rate": "1.000000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.000000000" } } }, "charged_amount": { "currency": "USD", "amount": "100229.23" }, "converted_amount": { "currency": "USD", "amount": "100000.00" }, "recipient_amount": { "currency": "USD", "amount": "100000.00" }, "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "Salary" }, "tos": { "tos_acceptance_date": "2023-07-23 02:59:12", "tos_acceptance_device_id": "string", "tos_acceptance_ip": "8.8.8.8", "tos_acceptance_user_agent": "AMozilla/5.0 (iPhone14,3; U; CPU iPhone OS 15_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Version/10.0 Mobile/19A346 Safari/602.1", "tos_acceptance_service_agreement": "string" }, "remarks": "Remittance comment here", "created_by": "7b61722fb9f94a232a6dbe5df53d6d49", "created_at": "2025-12-17T16:19:46 +08:00", "updated_at": "2025-12-17T16:19:46 +08:00" } Let's examine the indicator field for document upload requirements on high-value cross-border payment: "status": "INITIATED", "sub_status": "DOCUMENT_REQUIRED", ← The quote sub_status indicating document requirement "document_requirements" : { "types": ["INVOICE", "SOURCE_OF_FUNDS"],"accepted_formats": ["pdf","jpg","png"],"max_file_size": "5MB"} ← List of accepted documents (New) To upload the required supplementary document for the cross-border payment transaction, you can call Create/Replace Cross-border Transaction Documents ( POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) passing in the transaction ID of the cross-border payment that was initiated and is requiring a document upload. Document upload restrictions: File format: PNG, JPEG, PDF File size: maximum 5MB per file No. of files: maximum 1 file Document types supported: INVOICE Verifies the underlying purpose of the transaction. It acts as proof that the funds are being sent for a legitimate reason, such as paying a vendor, settling a bill, or purchasing goods and services. SOURCE_OF_FUNDS Validates the legal origin of the sender's money. This typically involves documents like payslips, bank statements, or tax returns to ensure the money entering the system does not stem from illicit activities. Create/Replace Cross-border Payout Transaction Documents request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: •••••' \ --form 'file=@"/Users//invoice.png"' \ --form 'document_type="INVOICE"' \ --form 'category="TRANSFER_PURPOSE"' Create/Replace Cross-border Payout Transaction Documents response JSON { "submission_id": "75a7218c835043169eee5eaf32e04196", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "category": "TRANSFER_PURPOSE", "status": "UPLOADED", "documents": [ { "id": "36xtPDySJj6jgETNx2XZZ44tNsA", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "created_at": "2025-12-17T16:27:03 +08:00", "type": "INVOICE", "category": "TRANSFER_PURPOSE", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png", "link_expires_at": "2025-12-17T16:42:03 +08:00", "status": "UPLOADED" } ], "count": 1 } After the document is successfully uploaded, you will need to finalize the requirement completion and put the transaction on resume the queue for processing. You can do this by calling Confirm Cross-border Payout Transaction Documents ( PUT /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) passing the transaction ID . Confirm Cross-border Payout Transaction Documents request CURL curl --location --request PUT 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••' Confirm Cross-border Payout Transaction Documents response JSON "OK" You can also call Get Cross-border Payout Transaction Documents ( GET /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) to view and verify the document submitted for the high-value transaction. Get Cross-border Payout Transaction Documents request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_id}}/files' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/json' \ --header 'Authorization: ••••••'' Get Cross-border Payout Transaction Documents response JSON { "data": [ { "id": "36xtPDySJj6jgETNx2XZZ44tNsA", "transaction_id": "NZkQHJlN4UTO1kTN2cTMtUFRTVVTNd0Ut4EWUB", "created_at": "2025-12-17T16:27:03 +08:00", "type": "INVOICE", "category": "TRANSFER_PURPOSE", "link": "https://storage.uat.matchmove-beta.com/api/v1/files/sgmmusdu/document/download/36xtPDySJj6jgETNx2XZZ44tNsA.png", "link_expires_at": "2025-12-17T16:42:03 +08:00", "status": "UPLOADED" } ] } If during your document verification, you noticed that you have uploaded the wrong file or the file is in bad condition (such as blurry images). You will be able to replace the file using the same Create/Replace Cross-border Payout Transaction Documents ( POST /users/wallets/payouts/remittances/transactions/{transaction_id}/files ) endpoint discussed above. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Create a recipient for cross-border payment Get a quote for cross-border payment Create a cross-border payment using an existing recipient Track the status of cross-border payment Manage cross-border payments • [Track the status of a cross-border payment](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/track-the-status-of-a-cross-border-payment.md): This guide explains the webhook statuses available to receive status updates on cross-border payments. Understand the various lifecycle statuses a cross-border payment goes through until it is completed. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the outstanding status of a cross-border payment. You want to notify users of the status update of their cross-border payment, using the information received from the webhook payload. You want to display the timeline and status changes of cross-border payment transactions in your application. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. At least one cross-border payment or remittance transaction has been initiated from the user (sender) account. API Workflow 1 Retrieve the status of a specific cross-border transaction (via webhook) There are webhooks available that deliver the various cross-border payout updates. These webhooks are under the Transaction Payout Advisory category. These webhook events will carry a payload containing the status and details of a remittance transaction. Cross-border Payout Transactions webhook events These are transaction status webhooks available under the Transaction Payout Advisory webhook category. API consumers are expected to subscribe to the webhook and handle the remittance transaction states as outlined below. Deprecation notice: As part of our platform terminology update from "transactions" to "payments," these legacy webhook events have been renamed. Partners are encouraged to subscribe to the updated webhook names below to continue receiving status updates. Webhook Event Description Expected Action PAYOUT.TRANSACTION.CROSSBORDER.STATUS Deprecated PAYOUT.PAYMENTS.CROSSBORDER.STATUS New, replacement The notification is sent for transaction status change events. This notification event is triggered when a transaction is submitted and moves into pending, processing, successful, failed, and reversed states. No action required PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS Deprecated PAYOUT.PAYMENTS.CROSSBORDER.REVIEW.STATUS New name, replacement The notification is sent whenever additional information is required, an update of new information is in progress, or the requirement for new information is closed or completed. MatchMove will contact the program owner/partner if additional information is needed for the transaction. The program owner will need to respond with the additional information before the transaction can proceed with processing. The payload received from the webhooks above will contain some details of the application. Using this information, you should be able to notify your users of any progress on their cross-border payments. 2 Retrieve the status timeline of a specific cross-border transaction (deprecated) The status timeline will reveal the status changes of a remittance transaction from the time it was initiated to its terminal status. Deprecation notice: Partners are encouraged to switch to the enhanced method of tracking transaction cross-border transaction statuses. See the replacement method at 3. Retrieve the status timeline of a specific cross-border transaction (new). Call List Cross-border Payout Transaction Timelines ( GET /users/wallets/payouts/remittances/transactions/{transaction_reference_id}/timelines ) passing the transaction reference identifier of the remittance transaction. List Cross-border Payout Transaction Timelines request CURL curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_reference_id}}/timelines' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: : ••••••' List Cross-border Payout Transaction Timelines response JSON { "pagination": { "total_records": 7, "records_per_page": 10, "total_pages": 1, "links": { "self": "https://{{server}}/{{program}}/v2/users/wallets/payouts/remittances/transactions/W9kWJljNwUDM5gjM0cTMtUFRTVVTNd0Ut4EWUB/timelines" } }, "data": [ { "id": "d146c3b413f1491886aa2ac6d47a3098", "status": "INITIATED", "sub_status": "TRANSACTION_INITIATED", "message": "Request received, processing started", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:06 +08:00" }, { "id": "0730b317d1de4f1c95ed0f5285856bbf", "status": "PROCESSING", "sub_status": "USER_STATUS_ACTIVE", "message": "User active, proceeding", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:07 +08:00" }, { "id": "fcea02430319412493a9cd88ffd7e22b", "status": "PROCESSING", "sub_status": "FUNDS_DEBIT_SUCCESS", "message": "Funds have been successfully debited from your account.", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:07 +08:00" }, { "id": "905332ca3e704e01bab919172cd81a93", "status": "PROCESSING", "sub_status": "RECIPIENT_RISK_CHECK_COMPLETE", "message": "Recipient risk is cleared", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:08 +08:00" }, { "id": "cdb9fa662e484627a22403213e2cb22e", "status": "SUBMITTED", "sub_status": "TRANSACTION_SUBMITTED", "message": "Transaction is submitted to rail provider", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:08 +08:00" }, { "id": "53e5450a39404bacadbd04e6fd45e818", "status": "PENDING", "sub_status": "TRANSACTION_IN_PROGRESS", "message": "Payment responds with pending payment", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:10 +08:00" }, { "id": "d88572e89b044d8aa269a619272a0981", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful payment", "updated_by": "SYSTEM", "updated_at": "2025-03-26T00:18:14 +08:00" } ] } 3 Retrieve the status timeline of a specific cross-border payment (new) The status timeline will reveal the status changes of a remittance payment from the time it was initiated to its terminal status. Call List Cross-border Payout Payment Timelines ( GET /users/wallets/payouts/remittances/payments/{payment_id}/timelines ) passing the payment reference ID of the remittance transaction. List Cross-border Payout Payment Timelines request CURL curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/{{payment_id}}/timelines' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: : ••••••' List Cross-border Payout Payment Timelines response JSON { "pagination": { "total_records": 5, "records_per_page": 10, "total_pages": 1, "links": { "self": "http://{{}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/C5UORBzN3ADN2kTM5cTMtQ0UV1UTHNVLOhFV/timelines?page=1&records_per_page=10" } }, "data": [ { "id": "fc61eb98a8f24aaeb9e92bdcc83837e7", "status": "INITIATED", "sub_status": "TRANSACTION_INITIATED", "message": "Request received, processing started", "updated_by": "f88934dbba144b9ca0955b2ce3f149ea", "updated_at": "2026-10-14T21:17:57 +08:00" }, { "id": "eb40a5d94f6044c0980db09571d1cf38", "status": "PROCESSING", "sub_status": "USER_STATUS_ACTIVE", "message": "User active, proceeding", "updated_by": "f88934dbba144b9ca0955b2ce3f149ea", "updated_at": "2026-10-14T21:17:59 +08:00" }, { "id": "23a0b2e6ad564766b0554d5a20823518", "status": "FUNDS_SECURED", "sub_status": "FUNDS_DEBIT_SUCCESS", "message": "Funds have been successfully debited from your account.", "updated_by": "f88934dbba144b9ca0955b2ce3f149ea", "updated_at": "2026-10-14T21:18:00 +08:00" }, { "id": "eadd5b612fb643a485f0311763529555", "status": "CONFIRMED", "sub_status": "RECIPIENT_RISK_CHECK_COMPLETE", "message": "Recipient risk is cleared", "updated_by": "f88934dbba144b9ca0955b2ce3f149ea", "updated_at": "2026-10-14T21:18:01 +08:00" }, { "id": "0282b53d06d14f9bb9addb26b3a4789d", "status": "SUBMITTED", "sub_status": "TRANSACTION_SUBMITTED", "message": "Transaction is submitted to rail provider", "updated_by": "f88934dbba144b9ca0955b2ce3f149ea", "updated_at": "2026-10-14T21:18:02 +08:00" }, { "id": "53e5450a39404bacadbd04e6fd45e818", "status": "PENDING", "sub_status": "TRANSACTION_IN_PROGRESS", "message": "Payment responds with pending payment", "updated_by": "553cbc85ad41fa69a4ed5d183d5b8e31", "updated_at": "2025-03-26T00:15:10 +08:00" }, { "id": "98e5450a39404bacadbd04e21d45e811", "status": "UNDER_REVIEW", "sub_status": "INITIATED", "status_message": "The RFI Team requires additional information.", "activity_type": "STATUS_UPDATE_WEBHOOK", "created_at": "2026-10-01 14:30:00", "under_review_history": [ { "status": "UNDER_REVIEW", "sub_status": "INITIATED", "provider_review_ref": "evt_d3n3iavvima100lp71kg", "platform_review_ref": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "event_type": "payout.compliance_hold", "response_status": "", "created_at": "2026-10-01 14:30:00", "updated_at": "", "review_requests": [ { "platform_review_ref": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "entity_type": "payout_details", "entity_request_data": [ { "...": "..." } ], "created_at": "2026-10-01 14:30:00" } ] } ] } { "id": "d88572e89b044d8aa269a619272a0981", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful payment", "updated_by": "SYSTEM", "updated_at": "2025-03-26T00:18:14 +08:00" } ] } 4 Retrieve the current status of a specific cross-border transaction (new, via API) Use this method to retrieve the latest, real-time status of a specific remittance transaction. Call Get Cross-border Payout Payment Status ( GET /users/wallets/payouts/remittances/payments/{payment_id}/statuses ) passing the payment reference ID of the remittance transaction. List Cross-border Payout Payment Statuses request CURL curl --location --globoff 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/payments/{{payment_id}}/statuses' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: : ••••••' List Cross-border Payout Payment Statuses response JSON { "status": "FUNDS_SECURED", "sub_status": "FUNDS_DEBIT_SUCCESS", "status_message": "Funds have been debited from the user's wallet.", "created_at": "2026-10-01 14:30:00" } Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Create a recipient for cross-border payment Get a quote for cross-border payment Create a cross-border payment using an existing recipient Create a cross-border payment without an existing recipient Manage cross-border payments • [Manage cross-border payments](https://developer.matchmove.com/matchmove-banking-operating-system/cross-border-payouts/manage-cross-border-payments.md): Understand the post-initiation operations available for your cross-border payments. Learn how to retrieve transaction details and the appropriate actions to take based on the various status updates you receive. The user in this document pertains to both the individual and business user types. Use Cases You want to retrieve the list of cross-border payment transactions made by a specific user. You want to retrieve the details of a specific cross-border payment transaction. You want to know the appropriate handling of failed and rejected cross-border payments. The customer wants to view all the cross-border payout transactions initiated from their accounts. Prerequisites The user must have an approved KYC status. The user profile must be in an active status. The user profile risk assessment status must not be risk_flagged (v1). This is not applicable in v2. The user account or wallet must be in an active status. The user's virtual account must be in an active status. At least one cross-border payout capability { LOCAL, SWIFT } is enabled in your program. At least one cross-border payment or remittance transaction has been initiated from the user (sender) account. API Workflow 1 Retrieve all the remittance transactions made on an account For audit and reporting purposes, or if you need to display all the transactions made on a specific account of a customer, we can: Call Get Cross-border Payout Transactions ( GET /users/wallets/payouts/remittances/transactions ) to list down all the remittance transactions ever made on an account. Get Cross-border Payout Transactions request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions' \ --header 'X-Auth-User-ID: 3b1bec69292d41a5071e6ce747ba38d7' \ --header 'Authorization: Basic ' Get Cross-border Payout Transactions / Payments response JSON { "pagination": { "total_records": 26, "records_per_page": 10, "total_pages": 3, "links": { "self": "https://{{server}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions?page=1&records_per_page=10", "next": "https://{{server}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions?page=2&records_per_page=10" } }, "data": [ { "id": "KhDNPpVN0QDN5ADN0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "77030550348a45f79a612732efd50398", "country": "VNM", "currency": "VND", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "ASIA COMMERCIAL BANK", "receiving_institution_code": "VNACVNVX", "account_name": "asdasdasdas", "account_number": "123123123", "account_type": "Savings Account" }, "quote": { "id": "HllTGN0N0IDN5ADN0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "19028.583333333", "details": { "platform_rate": "19028.583333333", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "16.83" }, "converted_amount": { "currency": "SGD", "amount": "12" }, "recipient_amount": { "currency": "VND", "amount": "228343" }, "additional_data": { "purpose_of_payment": "Family Maintenance", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-04-08 06:40:43", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.147", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-04-08T14:40:45 +08:00", "updated_at": "2025-04-08T14:45:51 +08:00" }, { "id": "5I0VGBVO4UDM1YzM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "c3270ca26ac042b2875ea23cd0c789f5", "country": "THA", "currency": "THB", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "BANGKOK BANK PUBLIC COMPANY LIMITED", "receiving_institution_code": "BKKBTHBKXXX", "account_name": "Test", "account_number": "123412341234", "account_type": "Savings Account" }, "quote": { "id": "CVlMMpUO1IDM1YzM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "25.402000000", "details": { "platform_rate": "25.402000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "14.83" }, "converted_amount": { "currency": "SGD", "amount": "10.00" }, "recipient_amount": { "currency": "THB", "amount": "254.02" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-04-03 03:23:07", "tos_acceptance_device_id": "", "tos_acceptance_ip": "104.23.175.160", "tos_acceptance_user_agent": "MaxiPay/5 CFNetwork/1568.300.101 Darwin/24.2.0", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-04-03T11:23:09 +08:00", "updated_at": "2025-04-03T11:28:16 +08:00" }, { "id": "MdkM2cENxADM1YzM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "1a3b5b6e5b8e460eb8817c7b14fa2bd8", "country": "THA", "currency": "THB", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "AIA COMPANY LIMITED", "receiving_institution_code": "AIACTHBK", "account_name": "Hahhahga", "account_number": "66777766611", "account_type": "Savings Account" }, "quote": { "id": "FNVRSR1M5kTO0YzM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "25.402000000", "details": { "platform_rate": "25.402000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "14.83" }, "converted_amount": { "currency": "SGD", "amount": "10.00" }, "recipient_amount": { "currency": "THB", "amount": "254.02" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Mother", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-04-03 03:13:33", "tos_acceptance_device_id": "", "tos_acceptance_ip": "104.23.175.161", "tos_acceptance_user_agent": "MaxiPay/5 CFNetwork/1568.300.101 Darwin/24.2.0", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-04-03T11:13:34 +08:00", "updated_at": "2025-04-03T11:18:39 +08:00" }, { "id": "14kVUR0M0ATNzIzM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "1a3b5b6e5b8e460eb8817c7b14fa2bd8", "country": "THA", "currency": "THB", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "AIA COMPANY LIMITED", "receiving_institution_code": "AIACTHBK", "account_name": "Hahhahga", "account_number": "66777766611", "account_type": "Savings Account" }, "quote": { "id": "ERFOxEkMzATNzIzM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "25.038000000", "details": { "platform_rate": "25.038000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "19.83" }, "converted_amount": { "currency": "SGD", "amount": "15.00" }, "recipient_amount": { "currency": "THB", "amount": "375.57" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Mother", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-29 07:57:21", "tos_acceptance_device_id": "", "tos_acceptance_ip": "172.68.225.235", "tos_acceptance_user_agent": "MaxiPay/5 CFNetwork/3826.400.120 Darwin/24.3.0", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-29T15:57:23 +08:00", "updated_at": "2025-03-29T16:02:29 +08:00" }, { "id": "NVlR480NwcDM2EzM0cTMtg0UDlEWNd0Ut4EWUB", "status": "REJECTED", "sub_status": "TRANSACTION_REJECTED", "message": "Maximum cumulative transactions exceeded by recipient.", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "abbb9c16edd7485886e763e6ed2e1cc2", "country": "IND", "currency": "INR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "AIRTEL PAYMENTS BANK LIMITED", "receiving_institution_code": "AIRP0000001", "account_name": "Bahjaha", "account_number": "6161771", "account_type": "Savings Account" }, "quote": { "id": "FVkUF10MwYDM2EzM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "63.327142857", "details": { "platform_rate": "63.327142857", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "17.45" }, "converted_amount": { "currency": "SGD", "amount": "14.00" }, "recipient_amount": { "currency": "INR", "amount": "886.58" }, "additional_data": { "purpose_of_payment": "Construction", "user_occupation": "", "user_recipient_relationship": "Mother", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-28 11:18:26", "tos_acceptance_device_id": "", "tos_acceptance_ip": "172.68.164.36", "tos_acceptance_user_agent": "MaxiPay/5 CFNetwork/3826.400.120 Darwin/24.3.0", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-28T19:18:27 +08:00", "updated_at": "2025-03-28T19:18:32 +08:00" }, { "id": "HZUVOFkMzcTO5gDM0cTMtg0UDlEWNd0Ut4EWUB", "status": "REJECTED", "sub_status": "TRANSACTION_REJECTED", "message": "Maximum cumulative transactions exceeded by recipient.", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "fbbd0cd8b8304e539f1a428ec2f7254e", "country": "IND", "currency": "INR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "ABHYUDAYA COOPERATIVE BANK LIMITED", "receiving_institution_code": "ABHY0065002", "account_name": "LINDA", "account_number": "123412341234", "account_type": "Savings Account" }, "quote": { "id": "INUTQhUMxcTO5gDM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "64.478571429", "details": { "platform_rate": "64.478571429", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "17.45" }, "converted_amount": { "currency": "SGD", "amount": "14.00" }, "recipient_amount": { "currency": "INR", "amount": "902.70" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Daughter", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-02 07:15:30", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.152", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-02T15:15:32 +08:00", "updated_at": "2025-03-02T15:15:40 +08:00" }, { "id": "RR1VHp1N1MTO5gDM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful payment", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "715724569c634b72ac6805fe10a047e6", "country": "MYS", "currency": "MYR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "MALAYAN BANKING BERHAD (MAYBANK)", "receiving_institution_code": "MBBEMYKL", "account_name": "charles ling", "account_number": "123123", "account_type": "Savings Account" }, "quote": { "id": "YhVOMZjNzMTO5gDM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "3.285714286", "details": { "platform_rate": "3.285714286", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "16.05" }, "converted_amount": { "currency": "SGD", "amount": "12.60" }, "recipient_amount": { "currency": "MYR", "amount": "41.40" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-02 07:09:16", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.152", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-02T15:09:17 +08:00", "updated_at": "2025-03-02T15:14:23 +08:00" }, { "id": "BB1SBNEN1ETO5gDM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful payment", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "715724569c634b72ac6805fe10a047e6", "country": "MYS", "currency": "MYR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "MALAYAN BANKING BERHAD (MAYBANK)", "receiving_institution_code": "MBBEMYKL", "account_name": "charles ling", "account_number": "123123", "account_type": "Savings Account" }, "quote": { "id": "XtUWJZlM0ETO5gDM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "3.285833333", "details": { "platform_rate": "3.285833333", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "15.45" }, "converted_amount": { "currency": "SGD", "amount": "12.00" }, "recipient_amount": { "currency": "MYR", "amount": "39.43" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-02 07:05:52", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.152", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-02T15:05:54 +08:00", "updated_at": "2025-03-02T15:11:03 +08:00" }, { "id": "Ud1UERzMzATO5gDM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful payment", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "715724569c634b72ac6805fe10a047e6", "country": "MYS", "currency": "MYR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "MALAYAN BANKING BERHAD (MAYBANK)", "receiving_institution_code": "MBBEMYKL", "account_name": "charles ling", "account_number": "123123", "account_type": "Savings Account" }, "quote": { "id": "Id0UwIjMyATO5gDM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "3.285000000", "details": { "platform_rate": "3.285000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "13.45" }, "converted_amount": { "currency": "SGD", "amount": "10.00" }, "recipient_amount": { "currency": "MYR", "amount": "32.85" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-02 07:03:52", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.153", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-02T15:03:53 +08:00", "updated_at": "2025-03-02T15:08:59 +08:00" }, { "id": "Sl1VWJFMxYDO5gDM0cTMtg0UDlEWNd0Ut4EWUB", "status": "PROCESSING", "sub_status": "RECIPIENT_RISK_CLEAR", "message": "Transaction is in progress as recipient risk is cleared", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "715724569c634b72ac6805fe10a047e6", "country": "MYS", "currency": "MYR", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "MALAYAN BANKING BERHAD (MAYBANK)", "receiving_institution_code": "MBBEMYKL", "account_name": "charles ling", "account_number": "123123", "account_type": "Savings Account" }, "quote": { "id": "UljRUJTO2QDO5gDM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "EXPIRED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "3.45" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "3.45" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "3.285833333", "details": { "platform_rate": "3.285833333", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "15.45" }, "converted_amount": { "currency": "SGD", "amount": "12.00" }, "recipient_amount": { "currency": "MYR", "amount": "39.43" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Father", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-03-02 06:56:49", "tos_acceptance_device_id": "", "tos_acceptance_ip": "162.158.192.152", "tos_acceptance_user_agent": "okhttp/4.9.2", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-03-02T14:56:50 +08:00", "updated_at": "2025-03-02T14:57:00 +08:00" } ] } 2 Retrieve the details of a specific remittance transaction Call Get Cross-border Payout Transaction Details ( GET /users/wallets/payouts/remittances/transactions/{id} ) to get all the details of a transaction, including the beneficiary details and the quotation details applied to the transaction. Get Cross-border Payout Transaction Details request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/wallets/payouts/remittances/transactions/{{transaction_reference_id}}' \ --header 'X-Auth-User-ID: <user_id>' \ --header 'Authorization: : ••••••' Get Cross-border Payout Transaction Details response JSON { "id": "MdkM2cENxADM1YzM0cTMtg0UDlEWNd0Ut4EWUB", "status": "SUCCESS", "sub_status": "TRANSACTION_SUCCESS", "message": "Payment responds with successful transaction", "source": [], "user": { "id": "3b1bec69292d41a5071e6ce747ba38d7", "country": "SGP", "currency": "SGD", "type": "INDIVIDUAL" }, "recipient": { "id": "1a3b5b6e5b8e460eb8817c7b14fa2bd8", "country": "THA", "currency": "THB", "type": "INDIVIDUAL" }, "receiving_institution": { "receiving_institution_type": "BANK", "receiving_institution": "AIA COMPANY LIMITED", "receiving_institution_code": "AIACTHBK", "account_name": "Hahhahga", "account_number": "66777766611", "account_type": "Savings Account" }, "quote": { "id": "FNVRSR1M5kTO0YzM0cTMtg0UDlEWNd0Ut8UVRB", "type": "FORWARD", "status": "CONSUMED", "fees": { "included": false, "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" }, "details": { "platform_charge": { "fixed_amount": { "currency": "SGD", "amount": "4.83" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "4.83" } }, "markup": { "program": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" }, "total": { "currency": "SGD", "amount": "0.00" } }, "total_markup": { "fixed_amount": { "currency": "SGD", "amount": "0.00" }, "percentage_value": "0.000000000", "percentage_amount": { "currency": "SGD", "amount": "0.00" } } } } }, "fx_rate": { "value": "25.402000000", "details": { "platform_rate": "25.402000000", "markup": { "partner": "0.000000000", "total": "0.000000000" }, "net_markup": "0.100000000" } } }, "charged_amount": { "currency": "SGD", "amount": "14.83" }, "converted_amount": { "currency": "SGD", "amount": "10.00" }, "recipient_amount": { "currency": "THB", "amount": "254.02" }, "additional_data": { "purpose_of_payment": "Advertising", "user_occupation": "", "user_recipient_relationship": "Mother", "user_source_of_income": "" }, "tos": { "tos_acceptance_date": "2025-04-03 03:13:33", "tos_acceptance_device_id": "", "tos_acceptance_ip": "104.23.175.161", "tos_acceptance_user_agent": "MaxiPay/5 CFNetwork/1568.300.101 Darwin/24.2.0", "tos_acceptance_service_agreement": "string" }, "remarks": "I agree with terms of services.", "created_by": "3b1bec69292d41a5071e6ce747ba38d7", "created_at": "2025-04-03T11:13:34 +08:00", "updated_at": "2025-04-03T11:18:39 +08:00" } 3 Handle remittance transaction status updates received from the webhook Payout transactions are facilitated through a network of intermediary partners. Any participant in this chain can influence the transaction's fulfillment and can affect it. When a transaction is actively rejected, its status is set to REJECTED , and a corresponding reason for the rejection will be populated in the sub_status field of the response payload. Additionally, technical or operational issues experienced by any partner may result in a transaction failure, marked with the status FAILED . While MatchMove strives to ensure transaction fulfillment, certain failure scenarios are inevitable. The possible sub_status codes for failures are listed below. To ensure end-user clarity, we recommend you display both the status and sub_status . This allows the user to understand the reason for failure and take the necessary corrective action to re-initiate the transaction successfully. Status Message Description / Expected Action REJECTED The quote utilised is invalid. The quote utilised for a transaction is invalid. Please create a new quote and try again. Transaction not permitted due to administrative or regulatory reasons The transaction has failed due to regulatory reasons. Please contact support. The transaction expired before the recipient took the necessary actions to receive funds Please create a new quote and try again with a new transaction. No routing option for the recipient URI provided Please rectify the recipient's bank details and try again. The card or issuer does not support receiving payments. Please check with the recipient for the proper receiving institution details. The sending amount is greater than the maximum allowed per transaction. Please try with a smaller amount for a transaction. The maximum cumulative transactions exceeded by the recipient. The maximum number of transactions for a recipient has been exceeded. Please try again after some time. The maximum cumulative amount exceeded by the recipient. The cumulative amount received by a recipient has exceeded. Please try again after some time. The maximum cumulative transactions exceeded by the receiving institution The cumulative transaction count by a receiving institution has exceeded. Please try again after some time. The maximum cumulative amount exceeded by the receiving institution The cumulative amount received by a receiving institution has exceeded. Please try again after some time. Invalid routing tag Recipient's bank details are invalid. Please check the recipient's bank information. The recipient account is not eligible to receive funds. Recipient's bank details are invalid. Please check the recipient's bank information. The recipient cannot receive funds due to an inactive account. Recipient's account is inactive. Please check the recipient's bank details. Recipient name does not match the account. The recipient name doesn't match with the account name. Please check the recipient details. The International Bank Account Number (IBAN) provided is invalid. The IBAN used for the transaction is invalid. Please check the recipient bank details. Incorrect IFSC or BIC code. Recipient's bank details are incorrect. Please check the recipient details. The recipient has not registered to receive payments. Recipient has not registered to receive payments. Please check the recipient details. Recipient is a minor, and RI does not support payments to minors. Recipient is a minor and does not support payments to minors. Please check the recipient details. The recipient address is suspected to be a bank address Need to use the recipient's address instead of the bank's address. Please check the recipient details. FAILED Internal server error The transaction failed due to some issues. Please retry after some time. The transaction timed out since the Receiving Institution did not respond The receiving institution appears not to be responding. Please try again after some time. Transaction cancelled via the system. The transaction was cancelled due to internal reasons. Please contact support. Payment routed correctly, unknown error provided by the Receiving provider. The transaction failed at the receiving institution. Please contact support. Related Links Payouts overview Payout network Domestic payouts Cross-border payouts Create a recipient for cross-border payment Get a quote for cross-border payment Create a cross-border payment using an existing recipient Create a cross-border payment without an existing recipient Track the status of cross-border payment • [Leverage webhooks](https://developer.matchmove.com/matchmove-banking-operating-system/leverage-webhooks.md): Webhooks are a form of server-to-server communication that sends notifications as soon as specific events occur. By subscribing to webhooks, you can reduce the number of API calls. Instead, design your solution to react to important events in real time upon receipt of the webhook notification. This guide explains how to subscribe to webhooks and contains an explanation and sample payload for each webhook event. Evaluate the webhooks that are important to your use cases and subscribe to receive information about system events as they occur. These webhooks are primarily intended for asynchronous activities or actions initiated by your end user from outside your ecosystem. Integrating Webhooks When an event occurs for which you, as a consumer, have subscribed to webhooks, the MatchMove platform sends an HTTPS POST request containing information about the event to a pre-configured endpoint hosted on a consumer's system. As a consumer of these webhooks, you are expected to ensure that your system can process the message received as part of the webhooks and respond as expected on certain business use cases. The webhook messages may also be upgraded periodically, as aligned with the platform upgrade policies. Webhook types The platform supports two types of webhook delivery systems: Standard Webhooks These are basic webhooks triggered by the platform in response to events occurring within the MatchMove platform. These events are triggered once and are fire-and-forget events. Enhanced Webhooks These are webhooks with the following added capabilities : Has a send retry on the webhook message in case of timeout (20 seconds) / network issues/errors on the partner's backend. Ability to self-track the endpoint tracking by having a retry count for the message delivered. Carries a message signature for each request to allow the partners to validate the message authenticity. Additional Metadata Enhanced webhooks have additional metadata provided in the headers that enable their enhanced capabilities: Header field Description MatchMove-Webhook-Id Unique identifier of this exact webhook message, with the same ID shared even on re-delivery MatchMove-Webhook-Subscription-Id Identifier of a subscription to which a message belongs MatchMove-Webhook-Event-Type The event type of the webhook notification MatchMove-Request-Id Unique identifier per delivery of webhook MatchMove-Webhook-Attempt Incremental count for every failed delivery attempt (maximum of 20 attempts over 7 days) MatchMove-Webhook-Signature Signature hash generated with the webhook payload as a safety mechanism against misuse of the webhook Dynamic response handling The enhanced webhooks will continue to retry sending until an explicit 200 is received from the api consumer's backend host during the attempt period. You can also choose to dynamically decide to manage the behavior of webhooks and subscriptions by responding with the corresponding HTTP codes as highlighted by the table below: Response code Webhook behaviour 2xx The platform will assume the successful delivery of the webhook 410 The service marks the delivery as rejected and cancels the subscription on this particular callback URL 422 The delivery is marked as rejected, and no retry will be attempted Content Verification To ensure that the webhook comes from an authentic source, a signature hash is provided in the HTTP header as a MatchMove-Webhook-Signature field. This safety mechanism should protect against misuse of the webhook address. The signature is generated via the HMAC SHA256 algorithm using: The provided API credential secret will be used as the HMAC key The request body is the data Partners must use the same algorithm to encrypt their responses and match them to the signature received from the webhook header. If both signatures match, the request can be considered valid. Otherwise, the request may be denied. Refer to the HMAC SHA256 encryption sample codes below: Go import( "crypto/hmac" "crypto/sha256" "io" ) func generateHMACSHA256(hmacKey string, requestBody string) string { hash := hmac.New(sha256.New, []byte(hmacKey)) io.WriteString(hash, requestBody) return fmt.Sprintf("%x", hash.Sum(nil)) } PHP public function generateHMACSHA256($hmacKey, $requestBody) { $hash = hash_hmac('sha256', $requestBody, $hmacKey); return $hash; } Python import hmac import hashlib def generateHMACSHA256(hmacKey, requestBody): return hmac.new( hmacKey.encode("utf-8"), requestBody.encode("utf-8"), hashlib.sha256 ) JavaScript const crypto = require('crypto'); const generateHMACSHA256 = (hmacKey, requestBody) => crypto.createHmac('sha256', hmacKey).update(requestBody); Java public static String generateHMACSHA256(String hmacKey, String requestBody) { try { // Initialize HMAC with SHA256 Mac sha256Hmac = Mac.getInstance("HmacSHA256"); SecretKeySpec secretKeySpec = new SecretKeySpec(hmacKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256"); sha256Hmac.init(secretKeySpec); // Compute the HMAC byte[] hmacData = sha256Hmac.doFinal(requestBody.getBytes(StandardCharsets.UTF_8)); // Convert byte array to hexadecimal string StringBuilder sb = new StringBuilder(); for (byte b : hmacData) { sb.append(String.format("%02x", b)); } return sb.toString(); } catch (NoSuchAlgorithmException | InvalidKeyException e) { throw new RuntimeException("Failed to generate HMACSHA256", e); } } Configure Webhook Subscriptions Each webhook category and event has its purpose depending on the use case it is associated with. Subscribing to webhooks eliminates the need to pull updates through the API manually. Instead, partners can listen and anticipate when an event will occur, be notified, and respond accordingly. Go to the Subscribe to webhooks section to learn more about subscribing to and managing webhooks. FAQ Do I subscribe to a category or individual events under a category? Consumers can choose which level they want to subscribe to. If they subscribe to a category, then all events under that category will be subscribed to automatically. Is there any restriction on the URL to be configured? The URLs must be HTTPS domains. The SSL certificate associated with the domain should support a minimum TLS version of 1.2 . Example of a valid webhook URL: https://example.com/callback/matchmove Example of invalid webhook URL: http://example.com/callback/matchmove https://example.com:3002/callback/matchmove What happens if I configure a URL that doesn't meet the above standards? The platform security controls will not allow webhooks to be triggered if the above rules are not followed. Webhook-related API Webhooks Category API / Webhook Availability Description Webhook Subscription Get (Platform) Webhook List v1 Retrieve all webhooks available in the platform Webhook Subscription Get (Subscribed) Webhook List v1 Retrieve all the active webhook subscriptions Webhook Subscription Create Webhook v1 Subscribe to a webhook category or event Webhook Subscription Get Webhook v1 Retrieve details of a webhook subscription Webhook Subscription Update Webhook v1 Update details of a webhook subscription Webhook Subscription Delete Webhook v1 Delete a webhook subscription Related Links Start your implementation Begin technical integration Implementation checklist Build with Gen AI Utilize enumerations • [Webhook categories](https://developer.matchmove.com/matchmove-banking-operating-system/leverage-webhooks/webhook-categories.md): Learn about the various webhook categories available and the events associated with each. Note: Please be aware that webhooks are subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation to confirm availability in your area and begin the setup process. Webhook Category Description Enhanced Webhooks Webhook Events KYC Service Advisory These are webhooks triggered for activities related to KYC and eKYC onboarding. Enabled ACCOUNT.KYC.VERIFICATION_START ACCOUNT.KYC.VERIFICATION_COMPLETED ACCOUNT.KYC.VERIFICATION_FAILED ACCOUNT.KYC.VERIFICATION_REJECTED ACCOUNT.KYC.VERIFICATION_APPROVED USER.DOCUMENT_VERIFICATION.STATUS ASSOCIATED_PARTY.DOCUMENT_VERIFICATION.STATUS USER.STATUS OFAC Service Advisory These are webhooks triggered for activities related to risk assessments. Enabled ACCOUNT.OFAC.VERIFICATION_REJECTED ACCOUNT.OFAC.VERIFICATION_CLEARED Virtual Accounts Advisory These are webhooks triggered for activities related to virtual account lifecycle updates, virtual account collections, and payout transactions. Enabled BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED PREFUND_ACCOUNT.VIRTUAL_ACCOUNT.STATUS INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS Payouts Beneficiary Advisory These are webhooks triggered for activities related to the status updates of a cross-border payout recipient. Enabled PAYOUT.RECIPIENT.CROSSBORDER.STATUS Quote Payouts Advisory These are webhooks triggered for activities related to the status updates on the validity of a cross-border quotation. Enabled PAYOUT.QUOTE.CROSSBORDER.STATUS Transaction Payouts Advisory These are webhooks triggered for activities related to the status updates of a cross-border payout transaction. Enabled PAYOUT.TRANSACTION.CROSSBORDER.STATUS Payouts Request For Information Advisory These are webhooks triggered for activities related to the status updates of an RFI associated with a cross-border payout transaction. Enabled PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS Card Transaction (Non-financial) These are webhooks triggered for zero-value card status and authorization initiated by the merchant. Enabled CARDS.ACCOUNT_VERIFICATION.STATUS CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION Pre Auth These are webhooks triggered when a card transaction authorization request is received from the payment network. Subscription to this will be required if you want to enable the Shared Authorization model. Not available OPENLOOP_PRE_AUTH Successful Transaction Notifications These are webhooks triggered when a card transaction request is successfully passed authorization and is completed. Not available OPENLOOP_POST_AUTH Decline Transaction Notifications These are webhooks triggered when a card transaction request is declined due to various reasons. Not available OPENLOOP_DECLINED_USER_NOT_FOUND OPENLOOP_DECLINED_UNSUPPORTED_ACQUIRING_MERCHANT_COUNTRY OPENLOOP_DECLINED_UNSUPPORTED_TRANSACTION_CURRENCY OPENLOOP_DECLINED_USERS_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_ATM_DOMESTIC_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_POS_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_POS_CONTACTLESS_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_ECOM_LIMITS_BREACHED OPENLOOP_DECLINED_PROGRAM_ATM_LIMITS_BREACHED OPENLOOP_DECLINED_USERS_ATM_DOMESTIC_LIMITS_BREACHED OPENLOOP_DECLINED_USERS_POS_CONTACTLESS_LIMITS_BREACHED OPENLOOP_DECLINED_USERS_POS_LIMITS_BREACHED OPENLOOP_DECLINED_USERS_ECOM_LIMITS_BREACHED OPENLOOP_DECLINED_OFACCHECKFAILED PREAUTH_TIMEOUT_DECLINE (Not available) PREAUTH_GENERAL_DECLINE (Not available) Open Loop Reversals These are webhooks triggered when an authorized card transaction is reversed. Not available OPENLOOP_REVERSAL_AGGREGATE_LIMIT_REACHED OPENLOOP_REVERSAL_CATEGORY_LIMIT_REACHED OPENLOOP_TRANSACTION_REVERSAL Settlement Advice These are webhooks triggered when the settlement reports from the payment network are ready. Not available NOAUTH_BATCH_SUCCESS MISMATCH_BATCH_SUCCESS CREDITVOUCHER_BATCH_SUCCESS AUTHRELEASE_BATCH_SUCCESS SETTLEMENT_BATCH_SUCCESS Payment Acceptance Advisory These are webhooks triggered for activities related to the payment gateway and acceptance services. Enabled PAYGW_TRANSACTION_SUCCESS PAYGW_TRANSACTION_FAILED User Details and Associated Parties These are webhooks triggered for activities related to user profile status updates. Enabled USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS USER.PROFILE.UPDATES ASSOCIATED_PARTIES.PROFILE.UPDATES ASSOCIATED_PARTIES.PROFILE.STATUS Cardholder Authentication These are webhooks triggered for activities related to assisted 3DS authentication. Enabled CARDS.3DS.AUTHENTICATION Card Order and Delivery These are webhooks triggered for activities related to card orders for programs with card delivery service enabled. Enabled CARDS.UPDATE.STATUS CARDS.ORDERS.UPDATE • [Subscribe to webhooks](https://developer.matchmove.com/matchmove-banking-operating-system/leverage-webhooks/subscribe-to-webhooks.md): Understand how to configure your system to receive the necessary real-time event notifications for all transaction status updates. API Workflow 1 Retrieve the list of available webhooks for subscription Each specific webhook is called an EVENT, and each event can be identified using its event ID and code. Webhook events are grouped into use case CATEGORIES, and a webhook category can be identified using its category ID . Partners can subscribe to a particular event or do a group subscription using categories. Call List Webhook Categories ( GET /v1/oauth/consumer/{{consumer_key}}/event/categories ) to retrieve all the webhooks available for the program. Where {{consumer_key}} is the API credential username provided for the program. List Webhook Categories request CURL curl --location 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/event/categories' \ --header 'Authorization: ••••••' Refer to the Begin technical integration section to learn more about the base URL configurations. List Webhook Categories response JSON [ { "id": "62a827dc956b0cf18d04f9fa01346f0e", "name": "Pre Auth", "events": [ { "id": "3cfb7df8871badb099f1926d703aefc8", "name": "Pre auth transaction", "code": "OPENLOOP_PRE_AUTH" } ] }, { "id": "4a31898cbe8f7e2d386b3181cf5a2f60", "name": "Succesful Transaction Notifications", "events": [ { "id": "b70f5601f8f6a4e96022456f7c1f4893", "name": "Post auth transaction", "code": "OPENLOOP_POST_AUTH" } ] }, { "id": "3b00b6957aa14d43a44dd1f37bd21357", "name": "Decline Transaction Notifications", "events": [ { "id": "88a2bd58d9b53a77c5056e6f1d3dad55", "name": "Invalid transaction", "code": "OPENLOOP_DECLINED_INVALID_TRANSACTION" }, { "id": "aab307782f877d59fd1c0bf4778ddaef", "name": "Insufficient prefund balance", "code": "OPENLOOP_DECLINED_INSUFFICIENT_CONSUMER_BALANCE" }, { "id": "70bc46a648164b6a35903c735d28b17b", "name": "Invalid user balance", "code": "OPENLOOP_DECLINED_INSUFFICIENT_BALANCE" }, { "id": "1c50750165f454b16982340e797826e4", "name": "Insufficient category balance", "code": "OPENLOOP_DECLINED_INSUFFICIENT_CATEGORY_BALANCE" }, { "id": "25eee8531e2814374ab2116f391fa3c7", "name": "Category limit reached", "code": "OPENLOOP_DECLINED_CATEGORY_LIMIT_REACHED" }, { "id": "5b2d7fdd41fdc16f7ed4a11e3ad9d39c", "name": "User card is blocked", "code": "OPENLOOP_DECLINED_CARD_BLOCKED" }, { "id": "d04492778e878895eb01db600c45a3a7", "name": "User card is suspended", "code": "OPENLOOP_DECLINED_CARD_SUSPENDED" }, { "id": "7583bbb1cd25a29ec1e850c30b13bb49", "name": "Invalid transaction type", "code": "OPENLOOP_DECLINED_INVALID_TRANSACTIONTYPE" }, { "id": "befcf0ac3399dba61579a247664907fd", "name": "Unsupported merchants", "code": "OPENLOOP_DECLINED_UNSUPPORTED_PROGRAM_MERCHANTS" }, { "id": "079f95eedd447911eec531f683fb3245", "name": "Transaction limit reached", "code": "OPENLOOP_DECLINED_RISKCHECKFAILED" }, { "id": "dd85c117bde9c15a8e1b967a91618a2c", "name": "Transaction is already authorized", "code": "OPENLOOP_DECLINED_ALREADY_AUTHORIZED_TRANSACTION" }, { "id": "e94b3e30e219be9cc05f4ca9864b1ea1", "name": "Refernce id not found", "code": "OPENLOOP_DECLINED_REFRENCE_NOT_FOUND" }, { "id": "cba40729dee1cf5c896229c7fb5997a1", "name": "Aggredated limit reached", "code": "OPENLOOP_DECLINED_AGGREGATE_LIMIT_REACHED" }, { "id": "eab29eeced6e199c09cf2bbccd2ffbeb", "name": "User is suspended", "code": "OPENLOOP_DECLINED_USER_SUSPENDED" }, { "id": "dec3d2392587f3bf73423d0efee73706", "name": "User is blocked", "code": "OPENLOOP_DECLINED_USER_BLOCKED" }, { "id": "91f7f0db6b0271689f24b7e717d05b43", "name": "User card is still on pending activation", "code": "OPENLOOP_DECLINED_CARD_PENDING_ACTIVATION" }, { "id": "c77ad7738e62ff49232dc9ea978cc877", "name": "User not found", "code": "OPENLOOP_DECLINED_USER_NOT_FOUND" }, { "id": "4ad416f07be17419fe5295c2d770ff1e", "name": "Acquiring merchant country is not supported", "code": "OPENLOOP_DECLINED_UNSUPPORTED_ACQUIRING_MERCHANT_COUNTRY" }, { "id": "ce15c4bbb10272cbeb838c22baa09f63", "name": "Transaction currency is not supported", "code": "OPENLOOP_DECLINED_UNSUPPORTED_TRANSACTION_CURRENCY" }, { "id": "df970772d76a0bb45169db435e8b3f1a", "name": "User Limit Breached", "code": "OPENLOOP_DECLINED_USERS_LIMITS_BREACHED" }, { "id": "32cb266f1bda54262ec870f7c94fd6db", "name": "Program limit exceeded", "code": "OPENLOOP_DECLINED_PROGRAM_LIMITS_BREACHED" }, { "id": "7d2c3775085121ce40880be6068902e0", "name": "ATM_DOMESTIC is not enable at program level", "code": "OPENLOOP_DECLINED_PROGRAM_ATM_DOMESTIC_LIMITS_BREACHED" }, { "id": "f8f78053c68605cf42e9dadb12999d82", "name": "POS is not enable at program level", "code": "OPENLOOP_DECLINED_PROGRAM_POS_LIMITS_BREACHED" }, { "id": "d2efd1b09dc4d82e5e1096bb69f7c518", "name": "POS_CONTACTLESS is not enable at user program level", "code": "OPENLOOP_DECLINED_PROGRAM_POS_CONTACTLESS_LIMITS_BREACHED" }, { "id": "9530f023ead486b86252d8ac843da90c", "name": "ECOM is not enable at program level", "code": "OPENLOOP_DECLINED_PROGRAM_ECOM_LIMITS_BREACHED" }, { "id": "b96800fba1298e79637a8f36ff170634", "name": "ATM is not enable at program level", "code": "OPENLOOP_DECLINED_PROGRAM_ATM_LIMITS_BREACHED" }, { "id": "7a4474ae3cf9565c24a61ab58ab6b57c", "name": "ATM is not enable at user level", "code": "OPENLOOP_DECLINED_USERS_ATM_DOMESTIC_LIMITS_BREACHED" }, { "id": "69e39f93cdf663cb97ed5236e944b103", "name": "POS_CONTACTLESS is not enable at user level", "code": "OPENLOOP_DECLINED_USERS_POS_CONTACTLESS_LIMITS_BREACHED" }, { "id": "590cebdd0b3cb76ae3b20d78e9ff7112", "name": "POS is not enable at user level", "code": "OPENLOOP_DECLINED_USERS_POS_LIMITS_BREACHED" }, { "id": "20e1d33223932a0525aa87e709e8de1b", "name": "ECOM is not enable at user level", "code": "OPENLOOP_DECLINED_USERS_ECOM_LIMITS_BREACHED" }, { "id": "7d7b88f293e87f1abdf55359a9874619", "name": "Preauth decline because of timeout", "code": "PREAUTH_TIMEOUT_DECLINE" }, { "id": "9a2102cab0009bed212deb36e235d478", "name": "General preauth failure", "code": "PREAUTH_GENERAL_DECLINE" }, { "id": "1a8a8b2d3fbd9a96c40a048675bdc50e", "name": "User's OFAC check failed", "code": "OPENLOOP_DECLINED_OFACCHECKFAILED" } ] }, { "id": "bf1d70bc1f5f1ee0de513e503b817879", "name": "Open Loop Reversals", "events": [ { "id": "da4179e8276b7ed169303d5ef0044351", "name": "Reversal transaction", "code": "OPENLOOP_TRANSACTION_REVERSAL" }, { "id": "538eac15761a3b1b72329cdff0743ccd", "name": "Reversal category limit reached", "code": "OPENLOOP_REVERSAL_CATEGORY_LIMIT_REACHED" }, { "id": "ada335601419c9670f72d3e59fbeffc0", "name": "Reversal aggregate limit reached", "code": "OPENLOOP_REVERSAL_AGGREGATE_LIMIT_REACHED" } ] }, { "id": "f544f5c43a91ee87a1a311555ca95bb1", "name": "Settlement Advice", "events": [ { "id": "5eda0dbfc0701b5fe0189da744fb70de", "name": "Settlement Batch Success", "code": "SETTLEMENT_BATCH_SUCCESS" }, { "id": "a56963ea6c6627f73e3cee1c566ae4d7", "name": "Auth Released Batch Success", "code": "AUTHRELEASE_BATCH_SUCCESS" }, { "id": "05c563ca90a1840b935e6327872b8325", "name": "Credit Voucher Batch Success", "code": "CREDITVOUCHER_BATCH_SUCCESS" }, { "id": "b31da1630d9b24226677dfdde3fef81c", "name": "Mismatch Batch Success", "code": "MISMATCH_BATCH_SUCCESS" }, { "id": "74cfd20f96e723ba996adaa8edb3690c", "name": "No Auth Batch Success", "code": "NOAUTH_BATCH_SUCCESS" } ] }, { "id": "b76f265693a47ba3dac4603223856d4d", "name": "KYC Service Advisory", "events": [ { "id": "d933faeec8e6fd0c754f8ac5f80a8c38", "name": "KYC Initiate Verification Started", "code": "ACCOUNT.KYC.VERIFICATION_START" }, { "id": "1f51bf72d0322bf07be422e072b43a66", "name": "KYC Verification Completed", "code": "ACCOUNT.KYC.VERIFICATION_COMPLETED" }, { "id": "671b8658f5506da39635a276627dad7e", "name": "KYC Verification Failed", "code": "ACCOUNT.KYC.VERIFICATION_FAILED" }, { "id": "04bf7161fd543994d9b8e52ecfa78f80", "name": "KYC Verification Approved", "code": "ACCOUNT.KYC.VERIFICATION_APPROVED" }, { "id": "d0f3a8ce573691085fec0ba81ca49196", "name": "KYC Verification Rejected", "code": "ACCOUNT.KYC.VERIFICATION_REJECTED" }, { "id": "8cd383f74bdf4d3f9a53d2e17d3ad98c", "name": "KYC Document Verification Update", "code": "USER.DOCUMENT_VERIFICATION.STATUS" } ] }, { "id": "e3f8cd88cabd276054203c7349df8b58", "name": "Virtual Accounts Advisory", "events": [ { "id": "443013887ac43a2e184fd7b6419d9622", "name": "Bank Transfer Credit Success", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS" }, { "id": "73fb2d5f2964edad1682e7d6cfbad5f8", "name": "Bank Transfer Credit Failed", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED" }, { "id": "f7a772c85cabfb6f5791f00806c49ac2", "name": "Bank Transfer Debit Success", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS" }, { "id": "17154d4e3bd6baa1e247ac982457a296", "name": "Bank Transfer Debit Failed", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED" }, { "id": "577c17e8892403dbad9f323cf3b71aac", "name": "Corporate Bank Transfer Credit Success", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS" }, { "id": "fc476fe75f7a54c49b0a933ca39a0b04", "name": "Corporate Bank Transfer Credit Failed", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED" }, { "id": "3f3cb479c0b0271fbaf08ffcaca26b31", "name": "Bank Transfer Debit Reversal Success", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS" }, { "id": "7fb6d7c6b616a4a5e89af997137728b3", "name": "Bank Transfer Debit Reversal Failed", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED" }, { "id": "b4be316271f22c8a666c206a9b85cc81", "name": "Bank Transfer Credit Reversal Success", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS" }, { "id": "ca483404b7a142b1adeca52b22430a60", "name": "Bank Transfer Credit Reversal Failed", "code": "CONSUMER_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED" }, { "id": "8eb34e1cf1574d949a12e86774fb5d76", "name": "Bank Transfer Corporate Credit Reversal Success", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS" }, { "id": "47e34a62af98dc84f0501aced94479f9", "name": "Bank Transfer Corporate Credit Reversal Failed", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED" }, { "id": "62bb5a6908625877dc98e26a847355b5", "name": "Corporate Bank Transfer Debit Success", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS" }, { "id": "85516664270973bbfc3ca6d37378f332", "name": "Corporate Bank Transfer Debit Failed", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED" }, { "id": "06adf7ec5332ddb04074ac71f7b22ba2", "name": "Corporate Bank Transfer Debit Reversal Success", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS" }, { "id": "186659a848fc40f056497767910c4463", "name": "Corporate Bank Transfer Debit Reversal Failed", "code": "CORPORATE_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED" }, { "id": "1c35b5962b16908bb8776c5ec9f138d4", "name": "Corporate VA Creation", "code": "BUSINESS_ACCOUNT.VIRTUAL_ACCOUNT.STATUS" }, { "id": "7ccb304aeb974eed7783447da984a377", "name": "Consumer VA Creation", "code": "INDIVIDUAL_ACCOUNT.VIRTUAL_ACCOUNT.STATUS" }, { "id": "eb1079435e306066542aa17e6089d391", "name": "Prefund VA Creation", "code": "PREFUND_ACCOUNT.VIRTUAL_ACCOUNT.STATUS" }, { "id": "443013887ac43a2e184fd7b6419d9624", "name": "Business Bank Transfer Credit Success", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.SUCCESS" }, { "id": "73fb2d5f2964edad1682e7d6cfbad5f9", "name": "Business Bank Transfer Credit Failed", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT.FAILED" }, { "id": "deefde3e607a11ef8c230281e1d7a895", "name": "Business Bank Transfer Debit Success", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.SUCCESS" }, { "id": "e7a0412e607a11ef8c230281e1d7a895", "name": "Business Bank Transfer Debit Failed", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT.FAILED" }, { "id": "f347d1ed607a11ef8c230281e1d7a895", "name": "Business Bank Transfer Debit Reversal Success", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.SUCCESS" }, { "id": "fb04142d607a11ef8c230281e1d7a895", "name": "Business Bank Transfer Debit Reversal Failed", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_DEBIT_REVERSAL.FAILED" }, { "id": "01e879dd607b11ef8c230281e1d7a895", "name": "Business Bank Transfer Credit Reversal Success", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.SUCCESS" }, { "id": "0b2b57ae607b11ef8c230281e1d7a895", "name": "Business Bank Transfer Credit Reversal Failed", "code": "BUSINESS_ACCOUNT.BANK_TRANSFER_CREDIT_REVERSAL.FAILED" } ] }, { "id": "e3f8cd88cabd276054203c7349df8b69", "name": "OFAC Service Advisory", "events": [ { "id": "e1f3a8ce573691085fec0ba81ca49169", "name": "OFAC Verification Rejected", "code": "ACCOUNT.OFAC.VERIFICATION_REJECTED" }, { "id": "f2f3a8ce573691085fec1ca81ca50169", "name": "OFAC Verification Approved", "code": "ACCOUNT.OFAC.VERIFICATION_CLEARED" } ] }, { "id": "dc7edc47e618cad1c473d026590bb925", "name": "Payment Acceptance Advisory", "events": [ { "id": "a905c3171499e8769fc29bf4cf39d12b", "name": "Payment Acceptance Failed", "code": "PAYGW_TRANSACTION_FAILED" }, { "id": "336db362040122242a7d33efc5875d40", "name": "Payment Acceptance Success", "code": "PAYGW_TRANSACTION_SUCCESS" } ] }, { "id": "24fa3364c14328ec330990fc1190d11e", "name": "Transaction Payouts Advisory", "events": [ { "id": "e238f9dc7ffe310e398190ea9638e852", "name": "Payout Quote Crossborder Status", "code": "PAYOUT.QUOTE.CROSSBORDER.STATUS" }, { "id": "7d2034d248f040dc9304cfa63fabcd9d", "name": "Payoute Recipient Crossborder Status", "code": "PAYOUT.RECIPIENT.CROSSBORDER.STATUS" }, { "id": "f1f172d5bfa674690bd09e0220b1194b", "name": "Payout Transaction Crossborder Status", "code": "PAYOUT.TRANSACTION.CROSSBORDER.STATUS" }, { "id": "31244512cf5054d6cc0d449860c0d90e", "name": "Payout Transaction Crossborder Review Status", "code": "PAYOUT.TRANSACTION.CROSSBORDER.REVIEW.STATUS" }, { "id": "b08c52f818b6780844edfe5ba2d8e287", "name": "Accounts Payout Crossborder Transaction Status", "code": "ACCOUNTS.PAYOUT.CROSSBORDER.TRANSACTION.STATUS" } ] }, { "id": "e1t71u4bzzqq9fo7l6nz80yu64k9gkiq", "name": "Domestic Payouts Beneficiary", "events": [ { "id": "2pr5ps2znxeex3cv9ubn5ovr4s8x486e", "name": "Domestic Payouts Beneficiary", "code": "PAYOUT.RECIPIENT.DOMESTIC.STATUS" } ] }, { "id": "e1t71u4bzzqq9fo7l6nz80yu64k9gkij", "name": "Card Transactions - Non Financial", "events": [ { "id": "11a32152b03a749d6bfcc5865300518e", "name": "CARDS.ACCOUNT_VERIFICATION.STATUS", "code": "CARDS.ACCOUNT_VERIFICATION.STATUS" }, { "id": "480eb54452f63abfa7f2eb0ffb1c62fe", "name": "CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION", "code": "CARDS.ACCOUNT_VERIFICATION.AUTHORIZATION" } ] }, { "id": "ff5810f459364c82b845ddc0e6d748f2", "name": "User Details", "events": [ { "id": "f7fa32d64fc1450283b99d68fcd0f4f6", "name": "Individual user information update", "code": "USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS" } ] }, { "id": "695824e1003f7a4bd56aa01e878e6ee9", "name": "Cardholder Authentication", "events": [ { "id": "09725074ac90314f0f2985435338ad62", "name": "CARDS.3DS.AUTHENTICATION", "code": "CARDS.3DS.AUTHENTICATION" } ] } ] List Webhook Categories response (except) {.. "id": " 62a827dc956b0cf18d04f9fa01346f0e ", ← Webhook category ID "name": " Pre Auth ", ← Webhook category name "events": [ {"id": " 3cfb7df8871badb099f1926d703aefc8 ", ← Webhook event ID "name": " Pre auth transaction ", ← Webhook event name "code": " OPENLOOP_PRE_AUTH " ← Webhook event code }, ..} 2 Subscribe to an entire webhook category Subscribing to an entire category will redirect all events to a single callback URL. Partners can distinguish which webhook event was fired by the webhook event code . Call Create Webhook s ( POST /v1/oauth/consumer/{consumer_key}/webhooks ) passing in the callback url and the category_hash . Create Webhooks request This example is using the webhook category ID of the Pre Auth category (from the List Available Webhook Categories response above). CURL curl --location 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'category_hash=62a827dc956b0cf18d04f9fa01346f0e Create Webhooks response JSON { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://partner.com/webhook/preauth", "event_hash": "3cfb7df8871badb099f1926d703aefc8", "event_name": "Pre auth transaction", "event_code": "OPENLOOP_PRE_AUTH", "status": "Success", "description": "Subscription processed successfully" } 3 Subscribe to an individual event in a webhook category Partners have the flexibility to subscribe to individual events and set a different callback URL for each of them. Call Create Webhooks ( POST /v1/oauth/consumer/{consumer_key}/webhooks ) passing in the callback url and the event_hash . Create Webhooks request This example is using the event ID of the Post Auth Transaction event under the Successful Transaction Notification category (from the List Available Webhook Categories response above). CURL curl --location 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --data-urlencode 'event_hash=b70f5601f8f6a4e96022456f7c1f4893 Create Webhooks response JSON { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://partner.com/webhook/postauth", "event_hash": "b70f5601f8f6a4e96022456f7c1f4893", "event_name": "Post auth transaction", "event_code": "OPENLOOP_POST_AUTH", "status": "Success", "description": "Subscription processed successfully" } 4 Retrieve the list of all subscribed webhooks Call List Webhooks ( GET /v1/oauth/consumer/{consumer_key}/webhooks ) to retrieve the list of webhooks that your program is currently subscribed to. List Webhooks request CURL curl --location 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks' \ --header 'Authorization: ••••••' List Webhooks response JSON { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://partner.com/webhook/preauth", "event_hash": "3cfb7df8871badb099f1926d703aefc8", "event_name": "Pre auth transaction", "event_code": "OPENLOOP_PRE_AUTH" }, { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://partner.com/webhook/postauth", "event_hash": "b70f5601f8f6a4e96022456f7c1f4893", "event_name": "Post auth transaction", "event_code": "OPENLOOP_POST_AUTH" } } 5 Retrieve particular webhook details Call Get Webhook Details ( GET /v1/oauth/consumer/{consumer_key}/webhooks/{webhook_id} ) passing the webhook ID of the webhook that you want to retrieve. Get Webhook Details request CURL curl --location —-request PUT 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks/{{webhook_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/x-www-form-urlencoded' Get Webhook Details response JSON [ { "id": "55b83a9336134fc08358ebf82e39bd3d", "url": "https://partner.com/webhook/preauth", "event_hash": "3cfb7df8871badb099f1926d703aefc8", "event_name": "Pre auth transaction", "event_code": "OPENLOOP_PRE_AUTH" } ] 6 Update a webhook subscription Partners can update the callback URL in a webhook subscription, whether the subscription is for an event or category. Call Update Webhooks ( PUT /v1/oauth/consumer/{consumer_key}/webhooks/{webhook_id} ) passing the webhook ID of the webhook that you want to update. Update Webhooks request CURL curl --location —-request PUT 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks/{{webhook_id}}' \ --header 'Authorization: ••••••' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'url=http://www.partner.com/new/preauth' Update Webhooks response JSON { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://www.partner.com/new/postauth", "event_hash": "b70f5601f8f6a4e96022456f7c1f4893", "event_name": "Post auth transaction", "event_code": "OPENLOOP_POST_AUTH", "status": "Success", "description": "Subscription updated successfully" } 7 Unsubscribe from a webhook subscription Partners can delete an existing webhook subscription and stop the defined callback URL from receiving the specific webhook payload. Call Delete Webhooks ( DELETE /v1/oauth/consumer/{{consumer_key}}/webhooks/{{webhook_id}} ) passing the webhook ID of the webhook that you want to unsubscribe from. Delete Webhooks request CURL curl --location --request DELETE 'https://{{platform_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/webhooks/{{webhook_id}}' \ --header 'Authorization: ••••••'' Delete Webhooks response JSON { "id": "2256a9f6635d40e8af2f82abaef47502", "url": "https://partner.com/webhook/postauth", "event_hash": "b70f5601f8f6a4e96022456f7c1f4893", "event_name": "Post auth transaction", "event_code": "OPENLOOP_POST_AUTH", "status": "Success", "description": "Subscription deleted successfully" } • [MatchMove FAQs](https://developer.matchmove.com/matchmove-banking-operating-system/matchmove-faqs.md): Answers to the most common questions from partners building embedded finance — payments, accounts, and card issuance — with the MatchMove Banking Operating System. If your question isn't covered here, contact your MatchMove Account Manager or the Matchmove Sales team. A. Getting Started & Onboarding (A) Questions and answers [A1] What is the MatchMove Banking Operating System, and what can I embed into my product? It is a Banking-as-a-Service (BaaS) platform for embedded finance — it lets you embed accounts, card issuance, collections, and payouts directly into your own product via APIs (Application Programming Interfaces), so financial services become a native part of your customer experience rather than a redirect to a bank. You operate the customer experience; MatchMove operates the regulated payment infrastructure underneath. Core building blocks include customer onboarding, wallets and accounts, prepaid cards, fund collection, and disbursement rails. Reference: Platform overview [A2] What sample use cases can I run as a program on MatchMove? Common embedded finance programs include corporate expense and spend-management cards, payroll and benefits disbursement, gig-economy and marketplace payouts, consumer wallet and neobank-style propositions, loyalty and rewards wallets, and B2B (Business-to-Business) supplier payments. Each combines the same building blocks — onboarding, wallets, cards, collections, and payouts — configured to the use case. Your MatchMove Account Manager can walk you through reference programs closest to your business model. Reference: Use cases [A3] I don't have my own app — can MatchMove provide one? MatchMove provides the backend financial infrastructure, accessible via API. The frontend — whether a mobile or web application — is the partner's responsibility to build and operate. This keeps you in full control of your brand and user experience, with the developer portal's guides and process documentation supporting your build. Reference: MatchMove API overview [A4] What does partner onboarding look like, and how long does it take? Onboarding starts with commercial scoping and KYB (Know Your Business) due diligence, after which your integration requirements are gathered and used to configure your dedicated UAT (User Acceptance Testing) stack environment. Once the stack is created, your API access credentials are released, and integration, UAT, and production go-live follow. Timelines depend on use case complexity and compliance review, with your MatchMove Implementation Manager supporting you throughout. [A5] Do I need my own payment or e-money licence to launch? No — you operate under MatchMove's regulatory licenses and authorizations in each supported market. You remain responsible for your own business conduct and any sector-specific obligations. Licensing coverage is market-dependent, so confirm the scope for each country you plan to launch in. [A6] Which markets and currencies are supported? At the base, SGD and USD are supported alongside the local currencies of each operating market, with cross-border payout corridors extending currency reach further. Currency availability depends on region and program configuration. Product availability also differs by market — so validate your target market's feature and currency set with your MatchMove Account Manager during scoping. [A7] What information and documents do I need to provide for onboarding as a partner? KYB due diligence typically requires company registration documents, details of directors and UBOs (Ultimate Beneficial Owners), proof of registered address, and a description of your business model and intended use case. Additional documents may be requested depending on your industry, market, and risk profile. Having these prepared in advance is the single biggest factor in a fast onboarding. [A8] Are there restricted industries or prohibited business categories? Yes — certain business categories are restricted or prohibited under regulatory requirements, card network rules, and MatchMove's own risk policies, consistent with industry practice. Your use case is assessed during KYB, and approval is scoped to the business model you present. Discuss any higher-risk elements of your model openly during scoping to avoid surprises later. Reference: Prohibited industries , High-risk industries [A9] Does MatchMove's role and operating model differ between markets? Yes — depending on the market, MatchMove may operate under its own license or in partnership with a locally licensed or regulated institution, which affects program structure, timelines, and responsibilities. The capabilities exposed to you through the platform remain consistent, but the underlying regulatory arrangement differs. Your MatchMove Account Manager will confirm the operating model for each target market during scoping. [A10] Does our company need a business entity in the program's region to sign the contract and start a program? MatchMove will request the Partner to have an entity in the jurisdiction designated for the partnership. However, this does not need to hold up signing: MatchMove can sign based on the Partner's existing entity and novate the agreement — transfer it to the designated entity — after it is established. Raise your corporate structure with your MatchMove Account Manager early so the contracting path can be planned alongside the prerequisites. B. Products & Capabilities (B) Questions and answers [B1] What account and wallet capabilities are available? You can create customer-level accounts (wallets) that hold balances, receive funds, and pay out, with full transaction history via API. Accounts support funding models including standard prefunding and mJIT™ (MatchMove Just-in-Time funding), where funds move at transaction time. Multi-purpose wallet structures let you separate balances by use case. Reference: Accounts overview [B2] What is a virtual account? A virtual account is the banking interface of a user account — a bank-account-style number attached to a wallet so it can receive funds through the banking system. All deposits made to the virtual account land in the underlying wallet, credited automatically with no manual reconciliation needed. Availability of virtual account assignment depends on market and program configuration. Reference: Virtual accounts overview [B3] What are fund categories (multi-pocket wallets)? A fund category — also called a pouch or pocket — is a compartment within a wallet that holds its own balance, enabling use cases such as separating meal, transport, and general-spend funds. Each pocket can be restricted to specific usage, for example, by MCC (Merchant Category Code), and funds can be transferred between categories. A default category automatically handles any transaction where none is specified. [B4] What are closed-loop and open-loop transactions? A closed-loop transaction is a direct debit or credit to a wallet that never touches the card network — for example, loading funds from your prefund balance to a user's wallet. An open-loop transaction originates from the card network — a purchase at a merchant — and is routed to MatchMove for authorization. Both types are retrievable via the transaction APIs and are reported separately. Reference: Transactions overview [B5] What card products can I issue? The platform supports virtual and physical prepaid and debit cards on major card networks, issued instantly via API. Virtual cards are online-only cards used for e-commerce payments, while physical cards work at in-person terminals, POS (Point of Sale), and ATMs (Automated Teller Machines), and can be ordered as personalized or non-personalized. Multiple card types and card designs can be configured within a single program. Reference: Cards overview [B6] Do you issue credit cards? No — MatchMove issues prepaid and debit cards, not credit cards. Credit-like experiences can sometimes be approximated through program design, for example employer-funded expense cards with controlled limits. If your use case requires true credit issuance, discuss alternatives with your MatchMove Account Manager. [B7] How do collections (transfer-ins) work? Collections let your customers or counterparties fund accounts through local and international bank transfers via the virtual accounts, depending on market. Incoming funds are credited to the target wallet and surfaced via API and webhooks. Reconciliation data is available per transaction. Reference: Collections overview [B8] What payout (transfer-out) and disbursement options exist? Payouts feature two modes: direct transfers, where funds move from a wallet to an external bank account or beneficiary, and POBO (Payments On Behalf Of), where payouts are made to end beneficiaries on your behalf — initiated from your corporate float or from a user account. Both cover domestic transfers over local rails and cross-border payouts to bank accounts, cash pickup points, and mobile wallets, depending on the corridor. You initiate payouts via API with status tracking through to completion or return. Reference: Payouts overview [B9] Which sender-to-recipient combinations are supported for cross-border payouts? All four combinations are supported: C2C (Consumer-to-Consumer), C2B (Consumer-to-Business), B2B (Business-to-Business), and B2C (Business-to-Consumer). The originating entity type follows your program setup — a corporate program originates as a business, a consumer program as an individual — and each program supports one entity type. Beneficiaries are risk-screened at creation, and rail-level limits maintained by providers also apply, so confirm corridors and limits during scoping. Reference: Cross-border payouts [B10] Can I run a spend-management or expense use case, such as corporate cards for staff? Yes — issue cards tied to controlled wallets and set per-card limits, funded either through standard prefunding or just-in-time funding, where cards only draw funds at authorisation time. Transaction-level data — merchant, MCC (Merchant Category Code), and amount — supports expense categorisation. Real-time webhooks let you build approval logic or alerts into your own application. Reference: Corporate Expense Management & Payroll [B11] Does the platform support multiple currencies, and how are FX rates determined? Cross-border payouts involve FX (Foreign Exchange) conversion, with rates quoted by the underlying payment rails and providers at transaction time and visible in the transaction record. Supported currencies and corridors depend on your markets and the rails in scope for your program. For card transactions, FX rates are set by the card network, while card payment fees and markup are set at the program level. Reference: Card transaction fees , Get a quote for cross-border payment [B12] How quickly do funds settle — for collections coming in and payouts going out? Settlement timing depends on the rail: domestic real-time rails credit in near real time, while cross-border transfers and card-network settlements follow their respective cycles. Payout completion is tracked via API status and webhooks through to a terminal state. Expected timelines per rail and corridor are confirmed during scoping. Reference: Transaction settlements [B13] How does prefunding and float management work day to day? You maintain a program prefund account — your pool account in the program — that transactions draw down from. A dedicated corporate virtual account can be tied to this program prefund and used to top up the prefund balance by bank transfer. Low-balance email alerts can be configured at thresholds you set in AdminNet, alongside balance visibility via API. Reference: Program prefund , Program virtual account [B14] Can I send bulk or batch payouts? Yes — high-volume disbursement use cases such as payroll, marketplace seller payouts, or rewards are supported through the payout APIs, with each payout individually tracked. Design your integration for idempotent submission and webhook-driven status handling at scale. Flag expected batch sizes and frequency during scoping so limits and float are provisioned accordingly. [B15] What happens if a payout fails or is returned? Failed or returned payouts — for example, due to incorrect beneficiary details or a closed account — move to a failure or returned status visible via API and webhooks, with funds credited back to the source wallet. Where a transfer succeeds on the platform side but is rejected by the upstream bank, an associated reversal transaction returns the funds. Your integration should handle these states and surface them to your users or operations team. C. Integration & APIs (C) Questions and answers [C1] What is the API architecture and how do I authenticate? The platform exposes RESTful (Representational State Transfer) JSON APIs organized by domain: customers, accounts, cards, collections, payouts, and platform. Authentication uses HTTP Basic Authentication with your API Consumer Key and Secret, issued per environment and used against the endpoint carrying your program code — keep credentials server-side only. Endpoint requests are only accepted from your whitelisted IP (Internet Protocol) addresses, and OpenAPI specifications are published on the developer portal for every module. Reference: Access the endpoints [C2] Is there a sandbox I can test in? MatchMove provides a dedicated UAT stack environment rather than a public self-serve sandbox. Since programs differ in configuration and enabled features, a UAT or staging stack environment programmed to your requirements can only be provisioned after signing, with test credentials released once stack provisioning is complete. The environments are functionally almost identical. Whatever you develop against UAT works unchanged in production, with only the endpoint base URLs and API credentials differing. However, due to network or payout rail partner rules, some transactions can only be tested in the real-world environment, in the live environment. Reference: Staging and live environments [C3] What are the limitations of the UAT environment — what can't I test there? UAT provides simulators in place of live external parties — for example, an authorization simulator for open-loop card transactions and bank-transfer simulators in select markets — and physical cards are not actually produced there. No pre-loaded test data is provided: you create your own by registering users, wallets, and cards through the APIs; never use real customer data. Load or performance testing is not supported, and anything that can only be validated on live rails belongs in your production pilot. Reference: Staging and live environments , Simulate card transactions [C4] Can I start evaluating or integrating before contracts are signed? The developer portal — API references, guides, and process documentation — is publicly accessible, so your technical team can evaluate the integration effort immediately. Hands-on access is provided post-signing: UAT environment credentials are issued once your stack has been created. Plan your pre-contract evaluation around the public documentation and scoping discussions with your MatchMove Account Manager. [C5] Where do I get my API access credentials? Your credentials will be provided to you by your MatchMove Implementation Manager when the stack setup is completed and include the API URL endpoint, the API Consumer Key and Secret, and your AdminNet portal URL. A separate set of credentials is issued for UAT and for production. [C6] What is the basic integration sequence, and is there an entity hierarchy? The foundational sequence is: create a user, put the user through KYC (Know Your Customer), and once KYC is approved, proceed to create accounts, virtual accounts, and cards — then the other financial features such as transfers, collections, and payouts become usable. The hierarchy is strict: a user holds a wallet, and a wallet holds zero or more virtual and/or physical cards, so a wallet or card cannot be created before its user exists. Reference: Begin technical integration [C7] Do you support webhooks for asynchronous events? Yes — webhooks notify your system of events such as transaction authorizations, funding credits, payout status changes, and KYC (Know Your Customer) outcomes. You register endpoint URLs and should verify payload authenticity and implement idempotent processing. Webhooks are the recommended way to track event outcomes, so design your integration to be event-driven from the start. Reference: Leverage webhooks [C8] What API versioning and deprecation policy applies? APIs are versioned per module — for example customer v1 and v2 — and versions may carry regional availability restrictions, so confirm which versions apply to your markets. Breaking changes can occur, including within a version, but partners are given ample time to adapt to breaking or required API upgrades before they take effect. Migration guides are published when versions change, and monthly release notes document all platform changes, including deprecations. Reference: Releases and updates [C9] Are there SDKs, or is integration purely via REST? Integration is primarily direct REST using the published OpenAPI specifications, which you can also use to generate API client libraries in your preferred language. Outside of specific components such as the eKYC (electronic Know Your Customer) SDKs (Software Development Kits), integration is spec-driven REST rather than SDK-based. The developer portal's API reference is the source of truth for requests and schemas. Reference: MatchMove API overview [C10] What are the rate limits and expected API performance? Rate limits and throughput expectations are environment- and contract-dependent and are shared during technical onboarding. Note that the UAT or staging environment is deliberately throttled down relative to production, so UAT response times and throughput are not indicative of production performance. Design for retries with exponential backoff and idempotency to handle transient errors gracefully, and flag high-volume use cases during scoping so capacity can be provisioned. D. Security (D) Questions and answers [D1] How is the platform secured and what certifications does MatchMove hold? The platform is operated to industry security standards, including PCI DSS (Payment Card Industry Data Security Standard) compliance for card data handling. Transport is encrypted via TLS (Transport Layer Security), credentials are scoped per partner and environment, and access to the platform and its endpoints is restricted to whitelisted partner system IP (Internet Protocol) addresses. Formal certification attestations can be shared under NDA (Non-Disclosure Agreement) during due diligence. Reference: Secure endpoint integration [D2] Do I ever touch raw card data such as the PAN or CVV? No — sensitive card data such as the PAN (Primary Account Number) and CVV (Card Verification Value) is handled entirely within MatchMove's PCI-compliant boundary. Card details are exposed to cardholders through secure display mechanisms rather than through your servers, keeping card data out of your systems entirely. Reference: Retrieve sensitive card information [D3] Is my business required to be PCI DSS compliant before I can start a program? No — PCI DSS (Payment Card Industry Data Security Standard) certification is not a prerequisite for launching a program, because sensitive card data is handled within MatchMove's PCI DSS-certified boundary, and you ride on that certification. You are, however, required to follow PCI DSS guidelines in how you build and operate your application and to keep sensitive card data out of your own systems, logs, and support tickets. If your product independently handles card data outside the platform, raise this during scoping, as it changes your compliance obligations. [D4] How are API credentials managed and rotated? Credentials are issued per environment (UAT and production) and must be stored server-side in a secrets manager — never in client-side applications or code repositories. Rotation can be requested through your support channel, and compromised credentials should be reported immediately for revocation. Credentials are scoped to the modules your program uses, following the principle of least privilege. [D5] Is IP whitelisting required to access the platform? Yes — your source IP (Internet Protocol) addresses must be whitelisted before you can access the MatchMove platform, and this applies both to API access from your servers and to AdminNet portal access by your operations team. Whitelisting applies to all environments, UAT and production alike, so submit your static IP addresses for each during technical onboarding and notify MatchMove ahead of any infrastructure changes that alter them. Requests from non-whitelisted IPs are rejected, so keep your registered list current to avoid disruption. Reference: Access the endpoints [D6] Can I whitelist MatchMove's IP addresses on my side? MatchMove's outbound services run on a dynamic pool of cloud provider IP (Internet Protocol) addresses, so whitelisting individual MatchMove IPs on your firewall is not recommended. Where your security policy requires restriction, use domain-based whitelisting instead — the list of domains is available from technical support. Design your webhook receivers to authenticate payloads rather than rely on source IP alone. [D7] Do I need to perform security testing (VAPT) on my own application? Yes — if you operate your own application consuming the platform APIs, you are expected to perform VAPT (Vulnerability Assessment and Penetration Testing) on it and remediate any findings. The platform's certifications cover MatchMove's side of the boundary; your application, servers, and credential handling remain your responsibility. Regular VAPT is also commonly expected by regulators, auditors, and card networks. [D8] Is my data mixed with other partners' data? No — each partner runs on its own dedicated stack, and your program data is maintained separately from that of other partners. This segregation applies across users, wallets, cards, and transaction data. Stack-level isolation also means your configuration, limits, and card types are specific to your program. [D9] What fraud and transaction-monitoring controls are in place? Transaction monitoring, velocity limits, and card controls — limits, channel blocks, and geographic controls — operate at the platform level, complemented by controls you configure per card or wallet. Suspicious activity flows into MatchMove's compliance monitoring as the regulated entity. With shared authorization enabled on your program, you can layer your own risk logic using real-time webhooks, allowing you to decide on the transaction before it is approved. [D10] How is customer data protected and where is it stored? Personal data is processed in line with the applicable data protection laws of each operating market, with encryption at rest and in transit. Some markets require on-soil data storage or processing, and MatchMove operates local infrastructure where regulation requires it; residency specifics are covered in the data processing terms of your agreement. Access is role-restricted and audit-logged. [D11] Where are customer funds held, and how are they safeguarded? Customer funds are safeguarded in accordance with the regulatory requirements of each operating market, under the supervision of the relevant financial regulator. Funds held in wallets are segregated from MatchMove's own operating funds as required by regulation. Market-specific safeguarding arrangements can be detailed during due diligence. E. Compliance & Regulatory (E) Questions and Answers [E1] Who is responsible for KYC of end users — the partner or MatchMove? End-user KYC is performed through the platform's native identity verification capabilities as part of customer onboarding, with MatchMove as the regulated party setting the requirements. You integrate the onboarding APIs and collect the required documents and data within your own user experience. Verification outcomes — approved, rejected, or pending — are returned via API and webhooks. Reference: Identity & onboarding overview [E2] What does the KYC flow look like for an end user? The user submits identity data and documents through your app to the onboarding APIs, which run document verification, liveness and selfie checks, and screening. Results are returned asynchronously with a clear status you can act on in your user experience. The KYC journey may differ from user to user based on residence region and user and industry risk levels. Reference: [v2] Onboard individual user [E3] Do KYC requirements differ by market? Yes — mandatory KYC fields, documents, and verification methods are driven by each market's local regulation, so requirements are not uniform across regions. The platform enforces the correct requirement set per program and market, and accepted field values can also differ by region. Factor these differences into your onboarding user experience for each market you launch in. Reference: Region-specific onboarding [E4] What eKYC options are available — and can I use my own provider? MatchMove eKYC (electronic Know Your Customer) is the primary verification method, with verification performed by partner banks where required in some regions. As the regulated entity, MatchMove is mandated to conduct its own due diligence on its platform users; therefore, verification through a partner's own eKYC provider cannot be relied upon in its place. Contact your MatchMove Account Manager if you require further clarification on the verification setup for your target markets. Reference: Perform individual eKYC [E5] What AML obligations do I take on as a partner? AML (Anti-Money Laundering) screening, sanctions checks, and transaction monitoring run at the platform level, but you must operate within your approved program scope and cooperate with information requests. Your use case is assessed during KYB and must remain within the approved scope. Notify MatchMove of any material changes to your business model. [E6] Are there limits on wallet balances and transactions? Yes — limits are driven by regulation, such as e-money limits in some markets, and by the KYC status of the end user. Per-transaction, daily, and balance caps are configurable within regulatory ceilings. Limit structures are agreed upon during program setup and can differ per market. [E7] Who is the issuer of record for cards, and who holds cardholder funds? MatchMove (or its locally licensed partner institution, depending on market) is the issuer of record with the card network and the regulated holder of cardholder funds. You are the program brand, while regulatory accountability for issuance and funds sits with the licensed entity. This split is documented in your program agreement and can be explained to your own auditors or regulators as needed. [E8] What data privacy obligations do I have as a partner? You act as a data controller (or the equivalent role under local law) for the personal data you collect from your customers, with your own obligations around consent, notices, and lawful processing. MatchMove processes that data for regulated service delivery under the data processing terms of your agreement, which define roles and responsibilities. Ensure your privacy policy accurately reflects the data shared with MatchMove for onboarding and transaction processing. Reference: Understand account limits , Configure card transactional limits [E9] Why might an end user's onboarding be rejected, and can it be reviewed? Rejections typically result from failed identity verification, screening matches, incomplete or inconsistent documents, or risk evaluation hits. Rejection statuses are returned via API so you can guide the user — for example, prompting a document resubmission where permitted. Cases requiring manual review are handled through your operational support channel, though certain compliance outcomes are final and cannot be disclosed in detail. [E10] Can I submit customer data and KYC documents in local languages such as Chinese, Vietnamese, Korean, or Arabic? It depends on which layer the data is going to. API parameters must be in Latin script — names and addresses in local scripts should be transliterated before submission, because the card networks, banking rails, and screening systems the platform connects to all exchange data in Latin characters, and interoperability across them depends on it. KYC (Know Your Customer) documents are the exception: identity documents issued in a local language can be uploaded as they are, and the platform applies auto-translation during verification — so build your onboarding to transliterate the typed fields while accepting documents untouched. F. Card Programs (F) Questions and answers [F1] How does physical card distribution work end to end? Three models are supported: personalized cards delivered directly to cardholders; non-personalized stock handed over for you to distribute and link to customers, including QR code-based linking; and assign-and-deliver, where cards are assigned before delivery. Card ordering and delivery are managed through the Card Order and Delivery Service. Activation is a controlled final step before first use. Reference: Card order and delivery [F2] Can I customise the card design with my own branding? Yes — cards carry your brand within card network and issuer design rules covering logo placement, the BIN (Bank Identification Number) area, orientation, and mandatory elements. Design guidelines specify what can and cannot be altered on the card front and back. Artwork goes through an approval cycle with the card network before production. Reference: Create your card product, Launching a card program [F3] What happens on a card authorisation in a just-in-time funding model? With mJIT™, an authorization triggers a real-time funding check and transfer from the designated funding source at transaction time, rather than requiring the card wallet to be prefunded. The shared authorization model must be enabled to allow you, as the partner, to decide on the transaction — the authorisation request is passed to you in real time, and your approval determines the outcome. If funds are available and the transaction is approved, the amount is settled from the funding account, minimizing idle float while keeping approval latency low. Reference: mJIT™ accounts , Transaction authorizations [F4] How do refunds, reversals, and chargebacks work? Refunds and reversals from merchants are credited back to the card wallet and are visible via transaction APIs and webhooks. Chargeback and dispute handling follows card network rules, with MatchMove managing the scheme process as the issuer. You surface dispute intake in your user experience and coordinate evidence through support channels. Reference: Transaction settlements [F5] Are online card transactions protected with 3DS or strong customer authentication? Yes — e-commerce transactions are supported with 3DS (3-D Secure) authentication in line with card network requirements, with cardholder verification such as OTP (One-Time Password) challenges during checkout. 3DS authentication is merchant-initiated: whether a challenge is triggered depends on the merchant and their acquirer, alongside market regulation. 3DS behaviour for your program is confirmed during card program setup. Reference: Platform-managed 3DS authentication [F6] Can issued cards be added to mobile wallets such as Apple Pay or Google Pay? Mobile wallet tokenization availability depends on the card program, network, and market and is scoped as part of your program setup rather than enabled by default. Where supported, cardholders can provision their card to the device wallet and transact via NFC (Near Field Communication). Confirm tokenization support for your target markets with your MatchMove Account Manager. [F7] What is the difference between a shared BIN and a dedicated BIN, and when do I need my own? On a shared BIN (Bank Identification Number), your cards are issued under a BIN range shared with other programs — the fastest and most cost-effective way to launch. A dedicated BIN gives you your own range, enabling deeper customization and program-level distinctiveness, but involves network setup lead time and higher cost. Most programs launch on a shared BIN and move to a dedicated one when scale or product requirements justify it. Reference: Launching a card program [F8] What is a BIN sponsor, and do I need one? A BIN (Bank Identification Number) sponsor is a locally licensed bank or financial institution that sponsors the BIN and card network membership needed to issue open-loop cards in a given market. In markets where MatchMove holds the required license directly, no separate sponsor is involved; in others, MatchMove operates with a local sponsor institution. Either way, this is handled within your program setup rather than something you arrange yourself. Reference: Launching a card program [F9] Can cards be used internationally and for foreign-currency transactions? International acceptance follows the card network, so cards can transact abroad and online with foreign merchants where the program configuration permits it. Foreign-currency transactions are converted at FX rates set by the card network, with any fees and markup defined at the program level. Cross-border usage can be enabled, restricted, or controlled per card depending on your use case and market rules. Reference: Card transaction fees [F10] What happens when a card is lost, stolen, or compromised? The card can be blocked instantly via API — by the cardholder through your app or by your operations team through AdminNet — stopping further authorisations immediately. A new card with a fresh PAN (Primary Account Number) can then be issued to the same wallet, so the balance and history carry over. Suspected compromise events should also be reported through your support channel so network-level actions can be taken where needed. Reference: Permanently block a card , Suspend an active card G. Testing & Go-Live (G) Questions and answers [G1] What does UAT sign-off require before production access? You demonstrate your critical flows end to end in UAT — onboarding, funding, spending or payout, and error and edge cases — against an agreed test plan. Compliance and operational readiness, including your support process and reconciliation approach, are reviewed alongside technical UAT. Production credentials are released after sign-off. Reference: Demo and go-live checklist [G2] Is there a recommended pilot approach at launch? Yes — launch with a limited cohort, such as internal users or a friendly customer group, to validate live-rail behaviour before scaling volume. Monitor webhooks, reconciliation, and support tickets closely during the pilot window. Scale-up thresholds can be agreed with your MatchMove Customer Growth account manager. Reference: Technical readiness H. Operations & Support (H) Questions and answers [H1] What support is provided during integration and after go-live? During integration you work with your MatchMove Implementation Manager alongside the developer portal documentation; after launch, support runs through MatchMove's support desk portal — your corporate email domain is registered during onboarding — with severity-based response. AdminNet, the operations portal, gives your operations team self-service visibility into customers, accounts, cards, and transactions. Escalation paths exist for production incidents. Reference: Support & servicing readiness [H2] How do I reconcile funds and transactions daily? Transaction APIs and reports provide the data needed for daily reconciliation between your ledger, wallet balances, and settlement movements. Settlement reports in CSV (Comma-Separated Values) format can be downloaded from AdminNet at any time and are also delivered via settlement webhooks on a regular schedule after each settlement processing run. Automated reconciliation via API pull is the recommended pattern at scale. Reference: AdminNet Reports dashboard [H3] What monitoring and incident communication can I expect? Platform incidents and maintenance windows are communicated through official partner channels, and release notes flag operationally relevant changes. You should implement your own health checks on API responsiveness and webhook delivery. Production-impacting issues follow a severity-based escalation and resolution process. Reference: Subscribe to platform health alerts [H4] Does MatchMove send notifications directly to end users? Yes, for specific events: transaction OTPs (One-Time Passwords) for e-commerce authentication, mobile wallet tokenization lifecycle events, and card and account lifecycle actions taken via AdminNet. Delivery is via SMS and/or email depending on the event, with SMS coverage varying by country and messages sent under the MatchMove sender ID by default. All other end-user communications are yours to design and send from your own product. Reference: Retrieve transaction history [H5] How do my customers get payment status, proof of payment, or receipts? Transaction status is available in real time via API and webhooks, so you can build self-serve status tracking into your own user experience rather than routing every query to support. Transaction records provide the detail needed to generate receipts or proof of payment for your product. For cases your own data can't resolve — for example, a beneficiary claiming non-receipt — raise the case through your support channel. Reference: AdminNet overview [H6] Can I provide account statements for end-user wallets? Full transaction history per wallet is available via API, giving you the data to generate periodic statements within your own product. AdminNet's Transactions and Reports modules support operational exports for your back office. Statement formatting and delivery to end users is implemented on your side using this data. [H7] What information should I include when raising a support ticket? Include the environment (UAT or production), the affected API endpoints, the full request and response payloads with sensitive data redacted, relevant transaction or customer identifiers, timestamps, and the business impact. Never include full card numbers or CVV (Card Verification Value) data in tickets. Well-formed tickets are resolved significantly faster because they skip the information-gathering round trip. Reference: Support and servicing readiness I. Roadmap & Ecosystem (I) Questions and answers [I1] How do I stay informed about new platform capabilities? Monthly release notes on the developer portal document new endpoints, behavior changes, and regional availability updates. After the implementation process, a dedicated MatchMove Customer Growth account manager will be assigned, responsible for growing your program. Reference: Releases and updates [I2] Can the platform grow with me into new markets or products? Yes — the modular design means you can start with one capability in a single market, such as virtual cards, and add payouts, collections, or new markets using the same integration patterns. Each market addition involves its own regulatory and commercial scoping. Reusing the same API domains keeps incremental build cost low. [I3] What differentiates MatchMove from other BaaS providers? Deep local expertise in each operating market — local licences, local rails, and in-market compliance experience — combined with a full-stack offering spanning wallets, cards, collections, and payouts on one platform. Distinctive capabilities such as mJIT™ funding and flexible card distribution models suit embedded finance use cases. Market coverage is often the deciding factor, so evaluate against your target markets. Regional availability varies by market. Commercial terms, including pricing and volume commitments, are agreed per program — contact your MatchMove Account Manager or the MatchMove Sales team for details. Interested to learn more? Reach out to our MatchMove Sales team at [ sales@matchmove.com ]. • [Glossary of terms](https://developer.matchmove.com/matchmove-banking-operating-system/glossary-of-terms.md): This glossary defines terms used across the MatchMove developer portal. Terms are grouped by category and listed alphabetically within each group, with acronyms spelled out on first use. Card Operations & Payment Ecosystem Term Definition Acquirer / Acquiring Bank The financial institution that processes a payment on behalf of the merchant. BIN (Bank Identification Number) The first 6 to 8 digits of a payment card that identify the issuing bank, payment network, and card tier. BIN Sponsor / BIN Sponsorship Allows non-bank businesses to issue payment cards by leveraging a licensed bank's access to networks like Visa or Mastercard. In a two-party model , the bank provides both regulatory compliance and backend technology directly to the card program. In a three-party model , a separate Technology Provider acts as middleware to handle software APIs and processing, allowing the program owner to launch much faster. Card Lifecycle The sequence of states a card moves through — typically Issued, Activated, Suspended, Blocked, Expired, and Terminated. Card Network / Scheme The central infrastructure (such as Mastercard or Visa) that connects the Acquirer and the Issuer to securely route transactions. Cardholder The individual to whom a card is issued and who is authorized to use it. Chargeback A forced reversal of a transaction, initiated by the cardholder's Issuer, that returns disputed funds from the merchant back to the cardholder. Closed Loop A payment system restricted to within the platform, typically between accounts in the same ecosystem. CVC / CVV (Card Verification Code / Value) The 3-digit security code used to validate online or Card-Not-Present purchases. DFCP (Digital First Card Program) A form submitted to and approved by the network when a card design is numberless — one that omits or masks the PAN or other card details — required before card art can be submitted for approval. Dispute A cardholder's formal challenge to a transaction (e.g., as fraudulent or incorrect), which may lead to a chargeback if upheld. Embossing / Personalization Printing or engraving cardholder-specific details (name, PAN, expiry) onto a physical card during production. Form Factor The physical or digital medium of the card (e.g., virtual, physical, or tokenized). Instant Issuance Making a card (typically virtual) usable immediately upon approval, without waiting for physical production or delivery. Interchange Fee A fee paid by the Acquirer to the Issuer for each card transaction, set by the Card Network. Issuer / Issuing Bank The financial institution that provides the card to the consumer and holds the funds. MCC (Merchant Category Code) A 4-digit code classifying a business type (e.g., airlines, retail), used to set spending rules or block certain purchases. MID (Merchant ID) A unique identifier assigned to a merchant's business to process payments. Non-Personalized Physical Card A physical card produced with generic (non-cardholder-specific) data, allowing it to be issued instantly from stock rather than manufactured to order. Open Loop A payment system where a card can be used anywhere its network (such as Mastercard) is accepted. PAN (Primary Account Number) The 16-digit card number printed on the card or generated virtually. Personalized Physical Card A physical card manufactured to order with the cardholder's specific name, PAN, and other embossed or printed details. Platform-Managed Authorization An authorization flow where MatchMove's platform evaluates and approves or declines a transaction directly, without the partner's own system in the loop. POS (Point of Sale) The physical terminal or digital checkout page where a customer makes a payment. PPM (Prepaid Program Management) The formal registration process a prepaid card program must complete with the network before it can be launched; not required for debit-only programs or those already covered under an existing approved PPM. Program Manager The entity responsible for designing and operating a card program on top of an Issuer's licensed infrastructure — managing product rules, partner relationships, and day-to-day operations. Push Provisioning Adding a tokenized card directly into a mobile wallet (e.g., Apple Pay, Google Pay) from within a partner's own app, without the cardholder manually entering card details. Shared Authorization An authorization flow where MatchMove and the partner jointly evaluate a transaction, with the partner able to weigh in before it is approved or declined. TID (Terminal ID) A unique number assigned to the specific POS machine processing a transaction. Virtual Card / Physical Card The two form factors a card can take — a virtual card exists only as digital data for online or in-app use, while a physical card is a tangible card that can be used at a POS terminal. White-labeling Issuing cards under your own company's branding while leveraging a partner's (like MatchMove's) banking license and infrastructure. Security, Compliance & Authentication Term Description 2FA (Two-Factor Authentication) Requiring a secondary verification factor, such as a One-Time Password (OTP) or biometrics, to approve a transaction. 3DS (3-D Secure) An additional security layer for online transactions. Platform-Managed 3DS : MatchMove hosts the authentication screen. Assisted 3DS : Partners embed the OTP or biometric flow into their own app. AML / CFT (Anti-Money Laundering / Combating the Financing of Terrorism) The regulatory frameworks requiring financial platforms to monitor and prevent illicit financial activities. Cooling-Off Period Regulatory controls (like delay windows for adding new payment recipients) designed to protect users from fraud. Biometric Authentication Verifying a user's identity using a physical characteristic, such as a fingerprint or facial scan, in place of or alongside a password or OTP. eKYC / KYC (Know Your Customer) The mandatory digital process of verifying an individual user's identity using official IDs and biometrics. Fuzzy Name Matching A screening technique that flags likely matches against watchlists or sanctions lists even when a name is misspelled, abbreviated, or formatted differently. KYB (Know Your Business) The process of verifying a legal entity, its ownership structure, and directors. Maker-Checker (Four-Eyes Principle) A security control where one administrator initiates a sensitive action and a second, independent administrator must approve it. MDES (Mastercard Digital Enablement Service) Mastercard's service that facilitates the secure provisioning of tokens into mobile wallets (like Apple Pay). OTP (One-Time Password) A single-use, time-limited code sent to a user (via SMS, app, or email) to verify their identity or authorize a transaction. PCI DSS (Payment Card Industry Data Security Standard) A set of security standards that organizations handling card data must comply with to protect cardholder information. PEP (Politically Exposed Person) An individual holding a prominent public position, subject to enhanced due diligence under AML regulations because of a higher risk of involvement in bribery or corruption. Risk Scoring Assigning a numeric or categorical risk level to a user or transaction based on behavioral, identity, and transactional signals. Sanctions Screening Checking a user or transaction against government and international sanctions lists to prevent dealings with restricted individuals or entities. SAR (Suspicious Activity Report) A report filed with a regulator when a financial institution identifies a transaction or pattern of activity that may indicate money laundering or other financial crime. Tokenization Replacing a card's real PAN with a unique, randomized digital placeholder (token) for secure payments. Velocity Limits / Spend Controls Rules that cap the frequency, amount, or type of transactions a user can make within a given time period. Accounts, Money Movement & Accounting Term Description Authorization The instant approval and holding of funds when a card is swiped. Beneficiary / Recipient The end party designated to receive funds in a payout or transfer. Clearing The back-end process where the Acquirer and Issuer exchange final transaction data to confirm exact amounts owed. Collections Funds received into the platform from an external source (e.g., a bank transfer or card payment) on a user's or program's behalf. Credit Prefund Balance A prefund model where a program draws down against a pre-approved credit facility to cover real-time transactions, replenishing the facility periodically rather than depositing cash upfront. Cross-border Payouts Moving money internationally, which incorporates real-time Foreign Exchange (FX) rates. Debit Prefund Balance A prefund model where a business deposits actual cash in advance — a pool of collateral held to cover real-time user transactions and platform fees. Domestic Payouts Transferring funds via local bank clearing rails (like ACH). Float The total physical money held in a master bank account corresponding to the digital balances in users' wallets. Fund Category A configurable sub-account or spending bucket within a wallet, used to partition funds and enforce granular limits — each with a name, a maximum amount (fixed or percentage-based), and an optional MCC filter restricting which merchant types it can spend at. Balances can be transferred between a user's categories via a from / to / amount request. FX Rate (Foreign Exchange Rate) The rate at which one currency is converted into another, applied in real time to cross-border transactions and payouts. Ledger The core database that records every single financial transaction (credits and debits) within the system. mJIT™ (Just-In-Time) Accounts MatchMove's proprietary model where an account sits at a zero balance until a transaction occurs, instantly pulling the exact amount from a master funding pool. P2P (Peer-to-Peer) Transfer Internal ledger transfers of funds directly between two accounts on the same platform. Partner Ledger The subset of the platform ledger scoped to a single partner, recording every transaction across that partner's programs and accounts. Program Prefund Account The account into which a program's prefund balance (credit or debit) is held before being drawn down for user transactions and fees. Program Virtual Account A Virtual Account issued at the program level, used to route incoming funds for that program as a whole rather than for an individual user. Quote A time-limited FX rate offered for a specific transfer amount and currency pair, locked in for the user to accept before the transfer is executed. Refund Returning funds to a cardholder for a previously completed transaction, typically initiated by the merchant. Remittance The transfer of money, often cross-border, from one party to another — commonly used to describe person-to-person international transfers. Reversal Canceling an authorization or transaction before it settles, releasing the held funds back to the cardholder. Settlement The actual, physical movement of money between banks to fulfill obligations established during clearing (usually 1–3 days later). Shared Balance An account's balance is pooled and accessible across multiple cards (shared) owned by the user. Standard Accounts Accounts that hold a persistent stored-value balance for an end user. Virtual Accounts Proxy or "dummy" bank numbers assigned to users to automatically route incoming external bank transfers into a master corporate account. Wallet / Multi-currency Wallet A digital store of value tied to a user, which may hold one or more currencies and funds cards, transfers, and payments. Technical Integrations & Administration Term Description AdminNet MatchMove's administrative back-office management console for inspecting ledgers, generating reports, and overseeing accounts. API (Application Programming Interface) The set of rules allowing your software to communicate with MatchMove's servers. Callback URL The partner-hosted endpoint that MatchMove sends webhook notifications or redirect responses to. Enumerations (Enums) Predefined lists of strictly allowed API values (e.g., status fields accepting only ACTIVE or SUSPENDED). Idempotency / Idempotent Request A safeguard ensuring that if an API request (like charging a card) is accidentally sent twice, the system recognizes the unique key and only processes it once. OAuth 2.0 / Bearer Token An authorization framework where API requests carry a token in the request header to prove the caller's identity and permissions. Pagination Splitting a large API response into smaller, sequential pages of results to reduce payload size per request. Payload The actual data package (usually JSON) sent to the API to request an action (e.g., user details for onboarding). Program Code (program_code) A unique identifier for a partner's program, used in API paths and payloads to scope requests to that program. Rate Limiting Restricting the number of API requests a client can make within a given time window, to protect platform stability. Request ID / Correlation ID A unique identifier attached to an API request, used to trace and troubleshoot that specific call across logs and systems. Sandbox / UAT / Production The environment tiers a partner integrates against: Sandbox and UAT (User Acceptance Testing) for development and testing, Production for live transactions. SDK (Software Development Kit) A packaged set of tools, libraries, and code samples that simplify integrating with an API in a specific programming language. Webhooks Automated server-to-server push notifications triggered by platform events (e.g., an instant alert when a payment succeeds). Platform Architecture & System Entities Term Description Account ID The unique identifier assigned to a specific account or wallet within a user's profile, used to reference it in API calls. BaaS (Banking as a Service) A model where a licensed institution like MatchMove exposes its banking infrastructure through APIs, letting a partner build and brand its own financial products on top of it. Card ID The unique identifier assigned to a specific card record, used to reference it in API calls. Client Reference ID (client_ref_id) A partner-supplied identifier attached to a request so the partner can trace and reconcile it against their own system of record. Partner The business entity that has a commercial and technical relationship with MatchMove to build and operate one or more programs on its platform. Program An instance of a specific card or wallet offering that a Partner operates on the platform, scoped and identified in the API by a program_code (see Program Code). User ID The unique identifier assigned to a User / Customer Profile, used to reference that end user in API calls. Virtual Account ID The unique identifier assigned to a Virtual Account, used to reference it in API calls. • [MatchMove API overview](https://developer.matchmove.com/matchmove-banking-operating-system/matchmove-api-overview.md): The MatchMove API provides a straightforward set of functions that enable developers to create various applications on the MatchMove payment platform. MatchMove is a service that allows groups to collect, manage, and spend money. With the API, users can develop applications that facilitate different types of transactions using accounts, virtual accounts, and virtual or physical cards. The API is built on RESTful principles, and responses are formatted in JSON. MatchMove APIs are server-to-server protocols. To deploy the functionality to the end user, the partner will not be able to access the APIs directly. You must have middleware available that accesses MatchMove APIs and provides functionality to your end user. Your middleware must only access APIs using static IP addresses that have been whitelisted in the MatchMove platform. As an API consumer, you can bring your technology stack and embed the functionality into any business use case described in this document. MatchMove APIs allow you to collect, store, and payout funds. The APIs also allow for compliant onboarding of end users (individuals/businesses) onto the platform. MatchMove's REST API structure is based on the OpenAPI 3.1 specification, and it includes the following entities: Partner The partner refers to a MatchMove customer who has taken the platform for any of the payment use cases to be fulfilled. Program A unique configuration of a financial product that is enabled for a client. Each program has a unique program_code identifier that is used for calling the APIs. As a partner, you can subscribe to multiple programs. The MatchMove platform treats each program⁣ as a separate tenant. The data of each tenant is kept separate and isolated from the other tenants. Users The client onboards the business or individual customer. A unique reference ID identifying each customer onboarded, called the User ID is generated by the MatchMove system, which is to be used for all future interactions with that entity. Account (Wallet) An account can be created that belongs to the business or individual customer onboarded onto the platform. Each account created will have a unique Account ID that is returned and to be utilized for any future interaction with the account or fetching account details. Virtual Account Each user in the system can be issued a virtual account. Each virtual account will have a unique Virtual Account ID assignment in the system. Card Type A distinct card product configured in the system for your end users. Each card product will have a unique Card Type Code configuration that encapsulates the configurations required for a custom card product. Cards A business or individual customer can have multiple cards, physical and virtual. Each card will have a unique Card ID generated in the system, which is to be used for any further operations or interactions to be done on the card. • [Prepare for implementation](https://developer.matchmove.com/matchmove-banking-operating-system/prepare-for-implementation.md): Learn how to access and set up your staging environment, credentials, and configurations. Understand the core system concepts and essential requirements before starting development. • [Staging and live environments](https://developer.matchmove.com/matchmove-banking-operating-system/prepare-for-implementation/environments.md): The MatchMove platform provides two environments for integration: UAT environment (staging) The UAT environment is a custom-built environment based on your product configuration and the product suites to which you have subscribed. This is the environment in which you should test the integration before deploying your code base to production. Production environment (live) The production environment, as the name suggests, is a real-world production setting in which all financial and regulatory constraints are fully expected to be met. Each transaction in this environment undergoes the necessary checks to ensure compliance. Any financial transaction completed here results in actual debits and credits to funds, as well as the corresponding financial consequences. • [Access the endpoints](https://developer.matchmove.com/matchmove-banking-operating-system/prepare-for-implementation/authenticating-api-access.md): Accessing MatchMove APIs MatchMove APIs are only accessible to authenticated entities, in an agreed-upon manner, and from a specified source. To access the APIs successfully, you must have the following items available and aligned with you as an API consumer. Consumer Key and Secret To begin using MatchMove APIs, you must first obtain access to the consumer key and credentials. The consumer key and secret are unique to each program and environment. If you have multiple programs, each program will have a different consumer key and consumer secret, which you must use to access that particular product. Static IP Whitelisting To ensure secure access, the MatchMove API only responds if the IP address of the middleware server sending the request is whitelisted. This does not refer to the IP address of the device in use. As an API consumer, you are expected to collaborate with your cloud or data center provider to ensure that requests to the MatchMove API server are only from whitelisted IP addresses. Scope of Access The default access granted to you has a default scope. APIs are accessed using the default scope function, just as they should be when accessed by an end user. Example: If a user account is blocked, the user should be unable to access the account information. Similarly, if a user is flagged for risk evaluation, they should be unable to access their account until it has been evaluated and exempted. The MatchMove platform also allows you to access resources via Admin scope, which means that even if the resources are not technically intended to be visible to end users, you, as an API consumer, can access them. Encryption Data Key For specific APIs, an additional encryption data key is provided to secure the transmission of API information, which you must use as a consumer to decrypt sensitive messages transmitted on specific payloads. • [Handle endpoint errors](https://developer.matchmove.com/matchmove-banking-operating-system/prepare-for-implementation/manage-api-errors.md): MatchMove uses standard HTTP response codes to indicate the status of a request made to the MatchMove platform. API consumers must ensure that HTTP status and status messages are handled accordingly with straight-through processing. Anatomy of an error message The error message consists of the HTTP response code and the response body. The response body is comprised of: an HTTP status code an HTTP status message a response body The response body elaborates more information on the error, which the partner may need to address or handle at run time. Refer to the status codes table on the right. About error messages The MatchMove platform returns various types of errors to allow you to distinctly understand the failure that happened and how to manage it. These scenarios can cover payment failures, invalid calling of the API, using the API to perform functionality that is not allowed or temporarily prohibited, or, in extreme scenarios, platform issues. Every API specification specifies the HTTP status codes and error codes that can be returned for that API call. Parse error data As an API consumer, you are encouraged to parse and manage the error object appropriately. Depending on the type of error, your handling of it will be different and broadly divided into one of the categories listed below. The MatchMove error objects are made up of a combination of the properties listed in the table below. Error property Description id ID of the request status The status of the error response code The code of the error response title The title for the error response detail The details for the error response source The optional string for the source of the validation error (optional) timestamp The timestamp of when the request was processed Error handling and management User communication As part of the integration, you are encouraged to investigate the error and respond by displaying a human-readable message to your end user. Scenarios could include a user attempting to access functionality that is not permitted or not allowed. Validate your integration In addition, ensure that validation_errors are properly handled and managed. Any entity or object related to payments will have the MatchMove platform as the source of truth. You should wait until the entity has been successfully created in the Matchmove system before committing its attributes. A validation_error indicates that there is a problem with the supported characters of validations in terms of value for a specific field, and you should investigate and correct the integration. Payment & transaction failures Some failures may be the result of payment failures, which can be attributed to any party in the value chain. The error code allows you to narrow down the reason and appropriately handle customer service. • [Secure endpoint integration](https://developer.matchmove.com/matchmove-banking-operating-system/prepare-for-implementation/securing-your-integration.md): Using TLS and HTTPS TLS refers to the process of securely transmitting data between the client—the app or browser that their customer is using—and their server. This was originally performed using the SSL (Secure Sockets Layer) protocol. However, this is outdated and no longer secure and has been replaced by TLS. The term “SSL” continues to be used colloquially when referring to TLS and its function to protect transmitted data. Payment pages must make use of a modern version of TLS (e.g., TLS 1.2) as it significantly reduces the risk of consumers or their customers being exposed to a man-in-the-middle attack. TLS attempts to accomplish the following: Use the default TLS port 443 for your web applications. MatchMove only allows server-side communications through port 443. Encrypt and verify the integrity of traffic between the client and servers Verify that the client is communicating with the correct server. In practice, this usually means verifying that the owner of the domain and the owner of the server are the same entity. This helps prevent man-in-the-middle attacks. Without it, there’s no guarantee that they are encrypting traffic to the right recipient. Additionally, customers are more comfortable sharing sensitive information on pages visibly served over HTTPS, which can help increase their customer conversion rate. If need be, consumers can test their integration without using HTTPS and enable it once they are ready to accept live charges. However, all interactions between their server and MatchMove must use TLS 1.2 (i.e., when using our libraries). Setting up TLS Serving resources securely, MatchMove consumers should make sure that any resources (JavaScript, CSS, images, etc.) are also served over TLS to avoid a mixed content warning being shown to their customers in their browser. A digital certificate—a file issued by a certification authority (CA)—is needed to use TLS. When installed, this certificate assures the client that it’s communicating with the server it expects to be talking to, not an impostor. They should get a digital certificate from a reputable certificate provider, such as Let’s Encrypt DigiCert NameCheap Certificates can vary in cost, depending on the type of certificate and provider. Let’s Encrypt is a certificate authority that provides certificates for free. Conceptually, setting up TLS is very straightforward: a certificate is purchased from a suitable provider, and then their server is configured to use it. The actual process does tend to be somewhat complex, and we recommend they follow the installation guide of the provider they use. As TLS is a complex suite of cryptographic tools, it’s easy to miss a few details. We recommend using the SSL Server Test by Qualys SSL Labs to make sure they have everything set up securely. Additional security considerations Including JavaScript from other websites can pose a security risk because consumers' security becomes dependent on it. If they are ever compromised, an attacker may be able to run arbitrary code on their website. In practice, many websites use JavaScript for services such as Google Analytics, even on secure pages. Nonetheless, it is something consumers should be aware of and, ideally, minimize. If consumers use webhooks, we recommend using TLS for the endpoint to avoid traffic interception and notification changes. Compliance with the Data Security Standards is important, but it should not be the end of their security considerations. Here are some good resources for learning about web security: OWASP SANS NIST Storage of non-sensitive card data MatchMove returns non-sensitive card information in response to various API calls. This includes the card type, the card's last four digits, and its expiration date. This information is not subject to PCI compliance, so customers can store any of these properties in their database. They can also store anything returned by our API that is not related to the card objects. • [Start your implementation](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation.md): Understand the fundamental steps and milestones needed to begin building your embedded financial solution for both individual and business users. Implementation milestones 1 Project kickoff and program configuration confirmation Prerequisite: A contract has already been signed between MatchMove and the partner to integrate the MatchMove platform. A dedicated MatchMove Implementation team will be assigned to assist you with building your embedded finance applications. The project kickoff will introduce the project roster between MatchMove and the partner. In addition, the partner use cases and MatchMove capabilities that must be enabled will be discussed during this meeting. We will finalize the platform configuration settings that will be applied to your custom platform instance (staging environment). The MatchMove Implementation team will request technical items from you (such as IP addresses) in order to prepare your custom platform instance. 2 Staging environment preparation and configuration Every partner will receive a custom platform instance that is tailored to the capabilities enabled in the program configuration. This custom platform instance will first be available on the staging environment and will only be accessible to the whitelisted partner IP addresses. The MatchMove Implementation team will coordinate all activities with the internal MatchMove teams to build your custom platform instance. 3 Resources handover and start of technical implementation Once the custom platform instance is live on the staging environment, the MatchMove Implementation team will hand over to the partner the following, among other things: API credentials to access the endpoint Private encryption keys that are required for some capabilities Access to the project communication channels Access to the project tracking dashboards and tools Access to internal technical resources At this point, the partner can commence implementation, following: Begin Technical Implementation API usage guide on authorization, access scopes, and endpoint URL construction. Implementation Checklist Use case guides containing step-by-step API implementation workflows. The MatchMove Implementation team will also hold weekly project meetings to discuss technical issues and other topics until the project is completed. 4 Customer onboarding and compliance discussions To ensure the partner aligns with the program's regulatory policies, customer onboarding requirements, and practices, the MatchMove Implementation team will also schedule discussions between the MatchMove Legal and Compliance teams and the partner. Matters involving onboarding customers from sanctioned and high-risk countries, requirements for translation of non-English documents, and the SOP for all scenarios involving user onboarding will be discussed in these meetings. For the customer due diligence requirements required by the API, you can review the Regional-specific Onboarding section. The MatchMove Legal and Compliance team will dictate all aspects regarding user onboarding. 5 Card design and setup (optional) Before a card (virtual or physical) can be issued, several activities must be completed. These activities may include card design, card approval with the payment network, card ordering, card and stationery (card kit) printing, and card delivery. To help you with building your card products, the MatchMove Card Operations team will conduct discussions and guide you through all the required processes. See Launching a card program section to learn more. The MatchMove Card Operations discussions and card issuance activities will run in parallel alongside the technical implementation. 6 Technical and operational training The partner will receive several trainings to help them understand the platform's processes and operations. These trainings will be required for you to perform platform operations once the application goes live. These trainings include, but are not limited to: Compliance standard operating procedures (SOP) Tooling and platform administration (e.g., AdminNet dashboard) Card ordering and delivery management Finance and settlement cycles (e.g., reconciliation) Ticketing and support escalations The MatchMove Implementation team will schedule these trainings based on the partner's needs and implementation progress. 7 Implementation security and completion verification Implementation security focuses on conducting rigorous tests to identify and remediate security flaws within the API architecture before it goes live. Completion verification then serves as the final audit to ensure the API integration is functionally sound and that all identified security risks have been successfully mitigated. Implementation Verification A period of UAT verification testing (usually 3 days to 1 week) will be arranged depending on the implementation progress. The verification will focus on the success rate of the API calls against the failures and correctness of API usage. During this period, the technical teams will be monitoring and verifying API calls made through the program. It is recommended that the partner run and test the APIs implemented from the use cases listed in the Implementation Checklist. When needed, a report or list of implementation issues for the identified failures will be communicated to the partner. Implementation Security As a regulated financial entity, MatchMove adheres to and complies with industry-standard security practices available. One of these is the Payment Card Industry Data Security Standard (PCI-DSS), which standardizes the management of card data. Though MatchMove is PCI-DSS compliant, we do not require our partners to be PCI-DSS compliant as well. However, to ensure that the MatchMove endpoints are secure and that their use does not expose any vulnerabilities, all partner systems that consume the MatchMove API must go through Vulnerability and Penetration Testing (VAPT). Major and critical issues identified must be rectified, and the final VAPT result report must be submitted to MatchMove. The MatchMove Implementation and Infosec team will discuss with you how to complete this requirement. 8 Application demo and UAT sign-off Before a partner can go live with their embedded finance application, an end-to-end demo (from user onboarding to issuance to test transactions) or a “show-and-tell” of the product they built will be required. This demo will be attended by all the MatchMove internal stakeholder teams involved in the project. The sign-off will focus on ensuring the following but is not limited to: All technical implementation requirements are completed and verified All regulatory requirements are met Risk communications to customers are handled properly The terms and conditions and other required legal disclaimers are displayed The card data are securely displayed and accessible The users are onboarded based on the agreed-upon methods Demo and Go-live Checklist A checklist of all the review items that will be covered in the demo evaluation by the project stakeholders. The MatchMove Implementation team will collect all feedback from the stakeholders. Depending on the feedback, the UAT sign-off may be given or delayed until any highlighted items are corrected. 9 Live environment resources handover A snapshot of the outstanding program configuration in the staging environment will be taken, which includes the initial program configuration and any other changes applied during project implementation. This snapshot will be used to promote the staging instance to the live environment. Since this will be the live environment, the following configurations will need to be reconfirmed: The final markup details that will be applied to financial transactions The production IP addresses that will be used to access the live environment The finalized branding resources that will be used on the platform The finalized sender ID that will be used for SMS messages (when required) Once the staging environment has been promoted to the live environment, a new set of environment resources, such as API credentials and encryption keys, will be provided . The partner will need to use these new API credentials and point the endpoints to the production hostnames to gain access to the live environment. The same implementation codebase used in the staging environment should work for the new live environment. Except for webhook subscriptions, which must be updated to point to your live environment's callback URL. 10 Closed beta testing on the live environment and project handover MatchMove recommends that before the partner releases their new application to the general end-users, they should conduct a closed beta test with a select group of users. The following tests can be done on the closed beta stage: Test the user onboarding scenarios and validate if you are handling the events properly (e.g., user is risk-flagged, user gets KYC approved) Test the card transactions on the top merchants in the top regions where it will be used Test cross-border payout in the top regions where you expect your user base to transact Test the domestic payout on select local bank accounts Test the bank collections on any active virtual accounts Validate if you are receiving any of the webhooks that you have subscribed to As the project approaches its implementation stage completion, the MatchMove Implementation team will begin to gradually hand over the project to the MatchMove Customer Growth team. Until the Customer Growth team achieves self-sufficiency and the program becomes stable. The MatchMove ticketing platform will be your primary point of contact for incidents and platform-related questions. The MatchMove Customer Growth team will serve as your advisor and helper to maintain and grow your program. At this point, the program implementation is complete. If a new platform capability or product is added to the program, the cycle will start over from the project kickoff. • [Begin technical integration](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation/begin-technical-integration.md): This guide provides a comprehensive overview of the technical requirements, security protocols, and architectural structure for integrating with the MatchMove API ecosystem. API Authorization & Access Scopes The API utilizes a dual-layered authorization model to ensure that requests are both authenticated and correctly scoped to the intended data level. Partner IP whitelisting Before you begin consuming the API, we need to make sure that the middleware static IP has already been whitelisted from the MatchMove network securitty. Otherwise, you will receive a 403: Forbidden response when you attempt to call an API. Authentication Mechanism All requests must use Basic Authentication. This involves passing your unique consumerKey and consumerSecret in the HTTP header. Header : Authorization: Basic <base64(consumerKey:consumerSecret)> Access Scopes Access is divided into two distinct levels. Your application must determine the scope based on the endpoint's purpose: User Scope Used for actions tied to a specific end-user (e.g., checking a card balance or initiating a payout). Requirement : Header: Basic Authentication Header: X-Auth-User-ID (User Identifier or user.ID) URL: program_code URL: correct module hostname or base URL Admin Scope Used for broad (non-user-specific) program management (e.g., pulling partner-level reports or platform configurations). Requirement : Header: Basic Auth URL: program_code URL: correct module hostname or base URL The program_code is a mandatory parameter that identifies your specific program in the platform. This identifier will be assigned to your program during the stack setup and program configuration stage. Add end user context The MatchMove Banking API requires four auth context headers: X-Auth-User-IP , X-Auth-Device-ID , X-Auth-User-Agent , and X-Auth-User-ID . The first three travel on every request, while X-Auth-User-ID is required only on user-scoped calls that act on behalf of a specific individual or business user. Header Description Example X-Auth-User-IP Public Internet Protocol (IP) address of the end user's device, as seen from the public internet. IPv4 or IPv6. 203.0.113.47 X-Auth-Device-ID Stable identifier for the device or browser installation. 9f1c2b4e-7a3d-4c58-b0e1-2d6f8a91c4de X-Auth-User-Agent Identifier for the client application and runtime environment. AcmePay/2.4.1 (Android 14; Pixel 8; build 2401) X-Auth-User-ID Identifier of the individual or business user in the MatchMove platform that the request acts on behalf of. Required on user-scoped calls only. 3d9bfe49b16e47ddb423829831cae88c The Capture End User Context guide covers how to source each value correctly on Android, iOS, and web, and how to attach them through a single interception point. API Base URL Architecture To provide high availability and modularity, hostnames are segregated by product or capability type. You must route your API calls to the specific base URL corresponding to the service you are utilizing. UAT (User Acceptance Testing) Used for development, staging, and certification. Product or Capability Base URL Description Identity {{identity_base_url}} api-sg-identity.matchmove-beta.com User onboarding, KYC, and KYB-related API Accounts {{accounts_base_url}} api-sg-accounts.matchmove-beta.com Accounts or wallets, virtual account, and wallet transaction-related API Cards {{cards_base_url}} api-sg-cards.matchmove-beta.com Cards and card transaction-related API Collection {{collections_base_url}} api-sg-collections.matchmove-beta.com Collections or incoming transfer-related API Payouts {{payouts_base_url}} api-sg-payouts.matchmove-beta.com Domestic and cross-border payout or outgoing transfer-related API Platform {{platform_base_url}} api-sg-platform.matchmove-beta.com Admin-related and general-purpose APIs, such as webhooks Simulations (Collection) {{va_simulation_base_url}} api-sg-collections.matchmove-beta.com Collection transaction simulation-related API. Only available in the staging environment. Simulations (Cards) {{cards_simulation_base_url}} api-sg-cards.matchmove-beta.com Collection authentication and authorization simulation-related API. Only available in the staging environment. Live (Production or Live) Used exclusively for live, real-world financial transactions. Product or capability Base URL Description Identity {{identity_base_url}} api-sg-identity.mmvpay.com User onboarding, KYC, and KYB-related API Accounts {{accounts_base_url}} api-sg-accounts.mmvpay.com Accounts or wallets, virtual account, and wallet transaction-related API Cards {{cards_base_url}} api-sg-cards.mmvpay.com Cards and card transaction-related API Collection {{collections_base_url}} api-sg-collections.mmvpay.com Collections or incoming transfer-related API Payouts {{payouts_base_url}} api-sg-payouts.mmvpay.com Domestic and cross-border payout or outgoing transfer-related API Platform {{platform_base_url}} api-sg-platform.mmvpay.com Admin-related and general-purpose APIs, such as webhooks API Request Example A standard request for a user-specific action in the UAT environment: Request (Admin scope) using {{identity_base_url}} CURL curl --location 'https://api-sg-identity.matchmove-beta.com/{{program_code}}/v1/users/enumerations/countries' \ --header 'Authorization: ••••••' Response (Admin scope) JSON { "countries": [ { "code": "AFG", "description": "Afghanistan" }, { "code": "ALA", "description": "Aland Islands" }, { "code": "ALB", "description": "Albania" }, .. Request (User scope) using {{identity_base_url}} CURL curl --location 'https://api-sg-identity.matchmove-beta.com/{{program_code}}/v1/users' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Authorization: ••••••' Response (User scope) JSON { "id": "6ea4a36ac4984065bf5d4eefa4b756b9", "email": "john.smith@matchmove.com", "title": "", "name": { "first": "John", "middle": "", "last": "Smith", "preferred": "John Smith" }, .. Technical Implementation Workflow The "Technical Implementation Workflow" diagram outlines the end-to-end journey for integrating new partners into the financial platform. It maps out the critical transition from initial testing in a secure staging environment to a fully operational live deployment. Structured across four distinct phases, this workflow ensures security, compliance, and functional readiness before the final launch. Here is the step-by-step breakdown of the integration process: User Onboarding: The process begins once the staging environment is handed over, starting with the creation of a user profile and submitting it for KYC (Know Your Customer) approval. Financial Asset Provisioning: Once KYC is approved, the system provisions financial assets by creating a wallet, with optional steps for generating virtual accounts (VA) and cards. Additional Features & Testing: Developers then integrate additional features, subscribe to webhooks, and rigorously simulate transactions to ensure system stability. Exit Procedures: The final readiness checks involve a Vulnerability and Penetration Test (VAPT) followed by a partner application demo. Go-Live: After securing the final stakeholder sign-off, the fully vetted application transitions out of staging and into the live environment. Figure 1: Technical Implementation Workflow diagram Related Links Start your implementation Implementation checklist Build with Gen AI Utilize enumerations Leverage webhooks • [Implementation checklist](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation/implementation-checklist.md): Learn how to ensure all required technical integrations are complete and understand the key steps for moving from staging to a production environment. Before you begin your implementation, please review the API usage and setup guide in the Begin technical integration section. 1) Identity and Onboarding Applicable To Guide Description All programs — Individual onboarding enabled ☐ [v2] Register individual profile Define a user entity for an individual passing the required regulatory information. All programs — Individual onboarding enabled ☐ [v2] Update individual profile Update a user entity for an individual passing the required regulatory information. All programs — Philippines ☐ [v2] [PH] Document-based verification (Manual approval) ☐ [v2] [PH] Authentication-based verification (Semi-automated approval) Submit the required KYC documents for individual verification. All programs — Singapore and others ☐ [v2] [SG] Document-based verification (Automated approval) ☐ [v2] [SG] Authentication-based verification (Automated approval) Perform an automated eKYC to submit documents and other requirements for individual profile verification. All programs — Singapore and others ☐ [v2] Partner-assisted verification (Automated approval) The partner will assist in collecting and uploading the user's KYC documents, and the user will undergo eKYC for liveliness detection and EDD (when required). All programs — Business onboarding enabled ☐ [v2] Register business profile Define a user entity for a business passing the required regulatory information. All programs — Business onboarding enabled ☐ [v2] Perform business eKYC (Automated approval) Perform an automated eKYC to submit documents and other requirements for business profile verification. 2) Accounts Applicable To Guide Description All programs ☐ Provision user accounts Issue and associate an account with an individual user to enable holding of funds. All programs ☐ Access account information Retrieve a user account along with its related information. All programs — Collections feature enabled ☐ Provision virtual accounts Issue and associate a virtual account with an account (wallet) to enable bank transfers. 3) Ledger and Funds Applicable To Guide Description All programs ☐ Credit funds to a user account Transfer funds from the partner prefund (source) to a user account (recipient). All programs ☐ Debit funds from a user account Transfer funds from a user account (source) to the partner prefund (recipient) . All programs ☐ Reverse debited funds from a user account Reverse a debit transaction made against a user account (recipient). Where the source is either the partner prefund or another user account. All programs ☐ Perform an account-to-account (P2P) transfer Transfer funds from a user account (source) to another user account (recipient) . All programs ☐ Retrieve transaction history Retrieve wallet or card transaction history 4) Cards Applicable To Description Description All programs — Cards feature enabled ☐ Issue a card Issue a virtual card Link & activate a non-personalised physical card Request for a personalised card Activate a personalized card Provision virtual or physical cards, associate them with user accounts, and activate (if needed) them to enable card payments. All programs — Cards feature enabled ☐ Manage cards Retrieve user cards Retrieve non-sensitive card information Retrieve sensitive card information Set card PIN Suspend an active card Reactivate a suspended card Permanently block a card Manage the card lifecycle, retrieve card information, and set a card PIN. All programs — Cards feature and card delivery options enabled ☐ Card order delivery Check user address serviceability Retrieve card order details Manage the card order and delivery lifecycle. (Optional) All programs — Cards feature enabled By default, card transactions are restricted by program-configured account/wallet limits. ☐ Configure card transactional limits Define transaction category spending limits on a card. Card transactional limits will be added on top of the account/wallet limits. (Optional) All programs — Cards feature enabled By default, MatchMove will be responsible for 3DS OTP delivery. ☐ Assisted 3DS authentication - OTP 2FA ☐ Assisted 3DS authentication - Biometric 2FA Assume end-user delivery of 3DS OTP for 3DS-enabled card transactions. Assisted 3DS will need to be enabled in the program configuration. All programs — Cards feature enabled ☐ Transaction authorizations For mJIT ™ accounts configuration, it is required to implement the Shared Authorization capability. For standard accounts configuration, implementing the Shared Authorization is optional. 5) Collections Applicable To Guide Description All programs — Collections feature enabled ☐ Receive funds from a bank account Collect funds from external bank account transfers 6) Payouts Applicable Description Title All programs — Payouts (domestic) feature enabled ☐ Create a recipient for domestic payment Define a recipient or beneficiary for a domestic payment All programs — Payouts (domestic) feature enabled ☐ Perform a domestic payment Transfer funds to a domestic payment beneficiary via a bank-to-bank transfer All programs — Payouts (domestic) feature enabled ☐ Track the status of a domestic payment Retrieve the status of a domestic transaction or subscribe to webhook notifications for updates on domestic payment status. All programs — Payouts (cross-border) feature enabled ☐ Create a recipient for cross-border payment Define and manage a recipient or beneficiary for a cross-border payment All programs — Payouts (cross-border) feature enabled ☐ Manage cross-border recipients Manage the lifecycle of the defined cross-border recipients All programs — Payouts (cross-border) feature enabled ☐ Get a quote for cross-border payment Retrieve a quotation with calculated fees for a cross-border route and intended transfer amount. All programs — Payouts (cross-border) feature enabled ☐ Perform a cross-border payment using an existing beneficiary Send a cross-border payment transaction to a predefined beneficiary All programs — Payouts (cross-border) feature enabled ☐ Perform a cross-border payment without an existing beneficiary Send a cross-border payment transaction without a predefined beneficiary All programs — Payouts (cross-border) feature enabled ☐ Track the status of a cross-border payment Retrieve the status of a cross-border payment transaction or subscribe to webhook notifications for updates on the status of cross-border payments. All programs — Payouts (cross-border) feature enabled ☐ Manage cross-border payments Retrieve cross-border payment transactions for an account and manage the cross-border payment lifecycle. 7) Testing and Simulation Applicable To Guide Description All programs — Cards feature enabled ☐ Simulate card transactions Simulate a card payment or transaction in the staging environment. All programs — Payouts (domestic) feature enabled ☐ Simulate domestic payments Simulate a domestic outgoing transfer from a virtual account to an external bank. This capability is currently available for SGD virtual accounts. All programs — Collections feature enabled ☐ Simulate bank collections Simulate a domestic or international incoming bank transfer to the MatchMove virtual account. All programs — Cards feature and Assisted 3DS - OTP 2FA enabled ☐ Simulate assisted 3DS authentication - OTP 2FA Simulate assisted 3DS authentication via OTP 2FA All programs — Card feature and Assisted 3DS - Biometric 2FA enabled ☐ Simulate assisted 3DS authentication - Biometric 2FA Simulate assisted 3DS authentication via Biometric 2FA 8) Platform Utilities Applicable To Description Title All programs ☐ Subscribe to webhooks Subscribe to various platform webhook notifications. All programs ☐ Capture request context headers Capture and pass additional request context headers. Related Links Start your implementation Begin technical integration Build with Gen AI Utilize enumerations Leverage webhooks • [Capture request context headers](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation/capture-request-context-headers.md): Every call to the MatchMove Banking Operating System (BOS) API comes from your backend. MatchMove never sees the person, device, or network behind an action unless you forward that information. Request context headers carry it. You send one header that says who the request is on behalf of (an end user, one of your operators, or an automated system) and, for end-user actions, three more that carry the user's IP address, a device identifier, and a client descriptor. The rules for each actor type are below. Why these headers are needed MatchMove is a licensed financial institution, and in most markets so are you. Several obligations both of us carry depend on knowing who acted, from where, and on what device. When your backend is all the platform can see, none of them can be answered from MatchMove's records. Transaction monitoring. Anti-money-laundering and counter-terrorism financing (AML/CFT) monitoring scores an action against the behavior of the person taking it. Velocity, impossible travel, and multi-accounting patterns stay invisible while every request carries your server's IP address. Audit trail. Retention rules require a transaction to be reconstructable years after it settled, including the actor behind it. A datacenter IP address identifies no one, and the record cannot be corrected later. Fraud and scam liability. The scam frameworks in force across the region assume a platform can tell a device it has seen before from one it has not and can challenge an action when it cannot. That rests on the device identifier alone. Reporting obligations. Where MatchMove has to account for how an account was accessed, the answer is limited to what your integration forwarded at the time. That includes suspicious transaction reporting, where a filing naming the account but not the device or network behind it is materially weaker. The obligations run both ways. These values are also the evidence your compliance team needs to demonstrate the controls on your program. These headers are the first of several changes to how you authenticate to and describe requests to the platform. Additional authentication modes for tighter security and simpler credential management are coming in later releases, and the context you send today carries over unchanged. How it works Your integration is server-to-server. Your backend authenticates to MatchMove with its API credential and calls the API for the person or process that triggered the action. Three things follow: The source IP that reaches MatchMove is your server's, not the user's. MatchMove has no connection to the user's device and cannot observe it. The standard User-Agent header on your call describes your HTTP library ( okhttp/4.12.0 , axios/1.7.2 ), not the user's client. The request context headers close that gap. The flow for a user-initiated action is: The user acts in your app or website. Your client sends the request to your backend along with a device identifier it has stored. Your backend records the user's IP from its own edge, the device identifier, and the client's user agent, at the moment the action arrives. Your backend validates the three values, then calls MatchMove with X-Auth-Actor: end-user and the three context headers. MatchMove records them against the acting user and uses them in risk evaluation. Once enforcement is in effect, a missing or invalid value is rejected with 400 . For an operator or system action, there is no user IP, device, or client to capture. You send X-Auth-Actor with an identifier for the operator or system and omit the three context headers. Actor types Value Description Endpoints Examples end-user A person using your app, website, or an assisted channel initiated the action. Endpoints that act on a customer's own account, such as onboarding, card lifecycle, transfers, and balance reads. Login, Know Your Customer (KYC) submission, transfer, card freeze, PIN reset, beneficiary change, limit change. operator One of your staff initiated the action from your own tooling, whether or not it affects a customer. Any endpoint, including program configuration. Compliance override, support-initiated card replacement, manual KYC review. system An automated process initiated the action. No person is behind it. Any endpoint, including program configuration. Batch settlement, reconciliation, webhook acknowledgement, balance polling. Not every endpoint can have a person behind it. Program configuration, prefund, card product setup, webhook subscription, and report retrieval are called by your operators or your systems, never by a customer, so end-user is never a true statement on them. Each endpoint's reference page lists the actors it accepts, in one line: Actors: operator, system . Everywhere else, the same endpoint takes a different actor depending on who triggered the call. A card suspension from your support tool is operator . The same call from your app is end-user with all three context headers. Your system polling a balance overnight is system ; the user viewing that balance in your app is end-user . A request with no X-Auth-Actor is treated as end-user . That is the strict path: the three context headers are then required. Once enforcement is in effect, automated traffic that does not send the actor header is rejected for missing context. Add X-Auth-Actor: system to it. Set the actor per call site, not once as a client-wide default, so machine-only calls carry operator or system . Warning: Never declare operator or system on an action a person initiated to avoid capturing their context. System-declared traffic on end-user operations gets the strictest risk treatment, never the relaxed one. Never send made-up end-user values. They are worse than no value. A datacenter IP misrepresents the audit trail, a random device identifier makes device history unbuildable, and one identifier shared across many users looks like multi-accounting fraud and triggers automatic account locks against your own customers. The four headers X-Auth-Actor answers who the request is on behalf of, and goes on every call. The other three answer questions about an end user's session: X-Auth-User-IP say from what network the user acted, X-Auth-Device-ID says from which device, and X-Auth-User-Agent says what client they used, on what platform, and at what version. Much of their risk value comes from checking them against one another. A device identifier with iOS history that shows up with an Android user agent is only visible when all three are present. Send all three whenever the actor is end-user ; none substitute for another. These rules apply to every context header: Send X-Auth-Actor on every request. Send the other three only when the actor is end-user . Capture each value fresh when the action reaches your backend. Never make one up, and never pass a client value through without checking it. Send one value per header, exactly as you captured it. Rules by header: X-Auth-Actor The operator and system need an ID. The end-user must not have one. The type and the ID are case-sensitive. Do not use an email address, a person's name, or your program code as the ID. X-Auth-User-IP Send the one address to your own edge saw. Private and internal ranges are accepted, but they give no risk signal. Do not add a port, a CIDR suffix, brackets, or a second address. Do not send your own server's address. X-Auth-Device-ID Pick one case convention and keep to it. Values are compared exactly. The value should mean nothing on its own. Do not use hardware IDs (IMEI, MEID, serial, MAC, ICCID) or advertising IDs (IDFA, GAID). Do not use contact details or anything built from the user's identity. Do not add your tenant name. MatchMove does that on receipt. X-Auth-User-Agent Keep it under 1024 bytes. Longer values are rejected, not shortened. Send it exactly as you received it. No re-casing, encoding, or wrapping. Short strings from privacy-focused browsers are fine. Pass them on unchanged. Do not send your HTTP library's user agent or a string you rebuilt yourself. Do not send device nicknames, account numbers, tokens, location, or free text the user typed. The table below gives the shape of each value. The integration guide that follows explains how to capture each one. Header Required Specification X-Auth-Actor Required on every request Type: Enum, with an optional id parameter Pattern: <type>[; id=<value>] , with id matching ^[A-Za-z0-9_-]{8,128}$ Values: end-user , operator , system Example: operator; id=op_7f3a9c21 X-Auth-User-IP Required when X-Auth-Actor: end-user . Do not pass the header for operator and system Type: String, one IPv4 or IPv6 address Example: 203.0.113.42 , 2001:0db8:85a3:0000:0000:8a2e:0370:7334 (full uncompressed) X-Auth-Device-ID Required when X-Auth-Actor: end-user . Do not pass the header for operator and system Type: String, opaque Pattern: ^[A-Za-z0-9_-]{16,128}$ Values: A UUIDv4 or hex-encoded hash generated and persisted by your client Example: c3f2a1b0-6d4e-4a19-9f83-71b2c0d5e8a7 , 8f14e45fceea167a5a36dedd4bea2543 , dvc_2NkqR7pWx4LmZ9vT X-Auth-User-Agent Required when X-Auth-Actor: end-user . Do not pass the header for operator and system Type: String, descriptive Pattern: Browser: the browser's User-Agent verbatim. Native app: <app-name>/<app-version> (<platform> <os-version>; <device-model>; build:<build-number>) Assisted: <app-name>/<app-version> (channel:<type>; ...) . Printable US-ASCII, 0x20 to 0x7E , no CR, LF, or NUL. See Build the user agent for the channel values Example: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) Integration guide MatchMove does not publish client-side software development kits (SDKs), so capture, persistence, and forwarding are yours to build. MatchMove's risk models are tuned against the approach below. Copy it rather than inventing a variant. 1. X-Auth-Actor : Declare the actor on every request Add X-Auth-Actor to every outbound MatchMove call. It is a backend-only change, and it is what lets MatchMove tell your automated traffic from your users' traffic. For end-user , send the type alone. For operator and system , add an id parameter. JSON X-Auth-Actor: end-user X-Auth-Actor: operator; id=op_7f3a9c21 X-Auth-Actor: system; id=treasury-monitor-prod-0001 The operator ID is an opaque value from your own staff directory. Do not send an email address or a person's name; the value lands in logs and Console activity views. The system ID names the calling system, environment, and instance. Use a distinct ID per backend system so audit trails stay legible. Make the actor a required argument of your MatchMove client so a call site cannot omit it, and do not hardcode a client-wide default. A default of end-user breaks your machine-only calls; a default of system misdeclares your users' actions. 2. X-Auth-User-IP : Capture the end user's IP address Read the user's IP on your own edge, per request, at the moment the action arrives. Then forward that single value in X-Auth-User-IP . Do not use X-Forwarded-For to carry the IP to MatchMove. MatchMove's edge (Amazon CloudFront in front of an Application Load Balancer) appends to and rewrites X-Forwarded-For in transit, so anything you put there is overwritten or indistinguishable from infrastructure hops. X-Auth-User-IP passes through unmodified. Five rules: Per request, not per session. A mobile user's IP changes between cellular and Wi-Fi and across carrier network address translation (NAT) pools. A login-time IP cached for the session produces false risk signals. Resolve it from your own trusted proxy chain. If your client reaches your backend through a content delivery network (CDN) or load balancer, take the leftmost untrusted entry of your own X-Forwarded-For , or your provider's dedicated header ( CF-Connecting-IP , True-Client-IP , X-Real-IP ). Never trust a header your client app supplies; an app can spoof any header your server accepts. Prefer the network-observed IP. The address your edge sees on the TCP connection is far harder to forge than one the app reports about itself. On retry, resend the original. If you retry a failed call for the same user action, send the IP captured at the original action, not the IP at retry time. On web, capture server-side. Take it when the browser calls your backend. Do not have the browser ask a third-party "what is my IP" service; it is spoofable and adds a data-sharing dependency. 3. X-Auth-Device-ID : Generate and persist a device identifier The device identifier is the highest-value signal in the risk stack because it persists where IP addresses do not. It tells MatchMove which device acted, independent of who is signed in. Your client generates it once, stores it so it survives restarts, and sends it to your backend with every action. The identifier must describe the device and nothing else. Derive it from the user and it becomes a second user identifier, silently defeating the multi-accounting detection it exists to support. Requests carrying a hardware identifier (IMEI, MEID, serial number, MAC address, SIM ICCID, Build.SERIAL ), an advertising identifier (IDFA, GAID), contact details, or anything derived from the user's identity are rejected. Their use also breaches Apple App Store and Google Play policy, and the data protection laws in MatchMove's markets. The algorithm is the same on every platform: Read the persisted identifier from platform storage. If present and well-formed, return it. If absent or malformed, generate a UUIDv4 from a cryptographic random number generator, persist it, and return it. Guard the read, generate, and persist path with a lock so two concurrent first-launch callers cannot create two identifiers. Cache in memory for the process lifetime. Never regenerate mid-process. The identifier should persist across app restart, device reboot, OS update, session expiry, and a different user logging in. It should reset on factory reset, restore from backup onto a new handset, clear browser data, and reinstall Android app. The same user on a phone and a tablet produces two distinct values. Never rotate it on a schedule, per session, or per request; a rotating value is indistinguishable from a fraud pattern. 4. X-Auth-User-Agent : Build the user agent The user agent is descriptive, not identifying. It tells MatchMove what kind of client acted, on what platform, and at what version. Unlike the device identifier, it is expected to change on every app release and browser update. Its value comes from being truthful and verbatim. Do not overwrite the standard User-Agent on your outbound MatchMove call. HTTP libraries set it themselves, connection pools reset it, and MatchMove's edge uses it for client diagnostics. X-Auth-User-Agent is a separate field that passes through unmodified. The format depends on the channel. Web browser. Forward the browser's User-Agent exactly as your server received it. Do not normalize, re-case, strip tokens, or rebuild it from a parsing library. The EMV 3-D Secure (3DS) browser channel carries this field, and the card issuer's risk engine compares it against what the browser itself reports. A reconstructed string does not match. Reduced strings from privacy-focused browsers are expected; forward them as-is. Plain text X-Auth-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 X-Auth-User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36 Native mobile app. There is no browser user agent. Build a product token following RFC 9110 syntax. Use the machine-readable device model ( iPhone15,3 , SM-S918B ), not the marketing name; marketing names vary by region and cannot be parsed. <app-name>/<app-version> (<platform> <os-version>; <device-model>; build:<build-number>) Plain text X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) X-Auth-User-Agent: PartnerPay/4.2.1 (Android 14; SM-S918B; build:4210) X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) X-Auth-User-Agent: PartnerPay/4.2.1 (Android 14; SM-S918B; build:4210) Hybrid app or embedded webview. Send the webview's user agent with your app token appended. This keeps the browser engine visible while identifying the wrapper. Plain text X-Auth-User-Agent: Mozilla/5.0 (Linux; Android 14; SM-S918B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/127.0.6533.103 Mobile Safari/537.36 PartnerPay/4.2.1 X-Auth-User-Agent: Mozilla/5.0 (Linux; Android 14; SM-S918B) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/127.0.6533.103 Mobile Safari/537.36 PartnerPay/4.2.1 React Native and cross-platform frameworks. Use the native format and append a framework token. Plain text X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) ReactNative/0.76.1 X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210) ReactNative/0.76.1 Assisted and non-browser channels. Where the user has no client software in hand (a branch agent, interactive voice response (IVR), unstructured supplementary service data (USSD), a kiosk), do not fabricate a browser string. Send a channel descriptor instead. Assisted channels carry a different risk profile from self-service; declaring them gets them scored correctly, disguising them as browser traffic gets them scored as anomalies Plain text X-Auth-User-Agent: PartnerPayAgent/2.1 (channel:agent-assisted; terminal:BR-SG-041) X-Auth-User-Agent: PartnerPayIVR/1.0 (channel:ivr) X-Auth-User-Agent: PartnerPayUSSD/1.0 (channel:ussd; gateway:globe-ph) X-Auth-User-Agent: PartnerPayKiosk/3.4 (channel:kiosk; terminal:KIOSK-MNL-12) X-Auth-User-Agent: PartnerPayAgent/2.1 (channel:agent-assisted; terminal:BR-SG-041) X-Auth-User-Agent: PartnerPayIVR/1.0 (channel:ivr) X-Auth-User-Agent: PartnerPayUSSD/1.0 (channel:ussd; gateway:globe-ph) X-Auth-User-Agent: PartnerPayKiosk/3.4 (channel:kiosk; terminal:KIOSK-MNL-12) Channel values. Whichever format you send, the channel: token names the channel. Recognized values: web (browser) mobile-app (native app) hybrid (app webview) agent-assisted (customer served by agent) ivr (automated phone line) ussd (phone code menu) kiosk (self-service terminal) pos (point of sale) partner-portal (your own web portal) Deferred actions. If a queued job completes something a user submitted earlier, forward the user agent and IP recorded at submission, not values observed when the job runs. Persist all three context values alongside the job. 5. Validate before you forward Your client sends the device identifier and user agent to your backend, which forwards them to MatchMove. Validate at that boundary. Never pass a client value through unchecked, and never let your own HTTP library's user agent leak into the field. On web, prefer the server-side cookie over anything the page sends in a request body. On mobile the client value is the only source available, which is why the identifier is a risk signal and not an authentication factor. 6. Send the request Attach the actor header and, for end-user , the three context headers to the MatchMove call. The example below calls Create Credit or Transfer Transaction API, moving funds from one user's wallet to another. A user tapping "send" in your app is the clearest case for the context headers: the action is theirs, so all three describe their session, not your backend. The source user is identified by X-Auth-User-ID and the recipient by the email in the payload. X-Auth-User-ID is an existing requirement of this endpoint and is not a context header; it names the account the call acts on, while X-Auth-User-IP describes the network the person acted from. Create Credit or Transfer Transaction request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/users/wallets/funds' \ --header 'X-Auth-User-ID: {{user_id}}' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --header 'Authorization: ••••••' \ --header 'X-Auth-Actor: end-user' \ --header 'X-Auth-User-IP: 203.0.113.42' \ --header 'X-Auth-Device-ID: c3f2a1b0-6d4e-4a19-9f83-71b2c0d5e8a7' \ --header 'X-Auth-User-Agent: PartnerPay/4.2.1 (iOS 17.5; iPhone15,3; build:4210)' \ --data-urlencode 'email=john.doe@example.com' \ --data-urlencode 'amount=50' Create Credit or Transfer Transaction response JSON { "id": "edde2e3c44428660970d11e0b53888b9c3de744c82a3568c70c6f5c8c0023e98", "ref_id": "000002C1000000000003000000000278", "user_id": "cb532825ef5397a0571b3b66f20780d7", "wallet_id": "4cc5efa24dc483f578dcccc17ac6b459", "confirm": "skip", "sor_transaction": null, "category_details": [ { "name": "DEFAULT", "amount": "50.00", "currency": "USD" } ] } The response body is the endpoint's normal response. Context headers add nothing to a successful response. Where no end user is behind the call, send the actor header alone. The example below calls Get Program Credit (Partner) Prefund, which returns the outstanding balance of the partner pool account. No customer is involved, so the actor is operator or system . Get Program Credit (Partner) Prefund request CURL curl --location 'https://{{accounts_base_url}}/{{program_code}}/v1/oauth/consumer/{{consumer_key}}/prefund/credit' \ --header 'Authorization: ••••••' \ --header 'X-Auth-Actor: system; id=treasury-monitor-prod-0001' Get Program Credit (Partner) Prefund response JSON { "balance": "91224459.010000" } 7. Handle rejections Once enforcement is in effect, a header that fails validation returns 400 Bad Request with the standard MatchMove error object, where code identifies the failing condition and source names the header that failed. Handle it as you would any other 400 from the platform. See Handle endpoint errors for the object and the general handling rules. Treat every rejection as an integration defect, not a transient failure. The request was not processed. Fix the value and resubmit; retrying it unchanged returns the same error. Degraded values are different. A private IP or a leaked HTTP library user agent is accepted and carries no code, so the request goes through and nothing in the response tells you. These appear in your weekly coverage report instead. Treat any non-zero rate on a production end-user endpoint as a defect to fix before enforcement. Conformance tests Run these before go-live. Each has one correct outcome. Run the device identifier tests again after any change to your client storage layer. Device identifier Force-quit and relaunch the app. Identical value. Reboot the device. Identical value. Log out, then log in as a different user. Identical value. iOS: delete and reinstall the app. Identical value. Android: delete and reinstall the app. New value. Back up, then restore onto a second device. New value on the second device. Install on two devices for the same user. Two distinct values. Web: clear site data. New value. Cold start with 20 concurrent accessor calls. One value. Inspect a sample of production values. All match ^[A-Za-z0-9_-]{16,128}$ , no duplicates beyond genuine shared devices. The restore-to-a-second-device test is the one partners most often fail, and the most damaging. A cloned identifier makes two physical devices indistinguishable, so a handset the user never enrolled looks familiar and never triggers a step-up, the extra authentication challenge raised when an action looks unusual. User agent Browser request through your full edge and proxy chain. Value matches what the browser sent, byte for byte. Native app. Matches the product token format, and contains no user-assigned device name. Hybrid webview. Webview string present with your app token appended. Agent-assisted transaction. Carries channel:agent-assisted , never a browser string. Inspect a sample of production values. No HTTP library signatures, email addresses, or phone numbers. Cross-check against device identifier platform history. No identifier appears as both iOS and Android. The last two catch the most common defects: a backend leaking its own HTTP client string, and a cross-platform build hardcoding one platform token. Actor Every automated job sends system with a distinct id ; every back-office action sends operator with an opaque id , and no context headers. Every end-user call sends end-user and all three context headers. Every program or configuration call sends operator or system . Inspect one day of your outbound requests. X-Auth-Actor never reads end-user for traffic that originated from a job, and never reads system or operator for traffic that originated from your app or website. Common questions Many of our users share one IP, behind corporate NAT or a VPN. Send the IP you observe. Shared ranges, VPNs, and proxies are handled in scoring. We proxy all mobile traffic through one egress gateway and cannot see the device IP. You cannot meet the requirement on that path. Raise it with your technical account manager before enforcement. Our users share devices (family accounts, kiosks, agent-assisted onboarding). Send the same identifier for each. MatchMove models many-to-many relationships between devices and users. Tell your risk contact about kiosk and agent devices so they are classified rather than flagged. The identifier resets when a web user clears cookies. That reduces signal on the web channel, and it is correct. Do not compensate with fingerprinting without discussing it with MatchMove first. We already send a device identifier to our own fraud vendor. Can we reuse it? Yes, if it meets the format rules and is not from a prohibited source. Reusing one value keeps your risk view and MatchMove's aligned. What if a device identifier is spoofed? It is a signal, not an authentication factor. Compromise is contained by revoking the device's binding to the user, so it is no longer treated as known, and by challenging the action with step-up authentication. Rotating the identifier is not the remedy. Can we normalize the user agent before sending? No. Send it verbatim. Parsing happens on MatchMove's side. A normalized string breaks the 3DS browser channel and defeats bot detection, which depends on exact token order and spacing. Rollout These headers roll out in two phases. During the warning phase, missing or degraded values are accepted and the request is processed, and MatchMove will share with you details of your compliance on a periodic basis. Once enforcement begins, a missing or invalid header on an end-user request is rejected. The dates for each phase, per header, are stated in the release notes . • [Build with Gen AI](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation/build-with-gen-ai.md): The Matchmove Developer document is LLM-friendly, allowing you to kickstart your development. As a developer or non-technical partner on the MatchMove Platform, you have a powerful suite of tools at your fingertips. This guide will show you how to leverage AI search and generative AI for code, streamlining your workflow and accelerating your projects with our Banking-as-a-Service (BaaS) and embedded finance solutions. Use Ask AI to solve your queries Forget sifting through endless documentation. Our AI-powered search is designed to give you precise, context-aware results instantly, making it easier than ever to find the information you need on the MatchMove platform. Basic Search The Basic Search capability involves searching through all the indexed articles. Click on the search bar located at the top of the developer portal page 2. Type in your MatchMove question. See the available resulting articles. AI Search The AI Search capability involves the AI models digesting through all available content and generating a contextual-aware response. Click on the Ask AI button at the bottom of the Standard Search pop-up window. 2. The AI will go through the entire developer portal and will try to understand it. Then it will answer to the best of its knowledge, including platform context and relationships of the different MatchMove banking components. For technical stakeholders Are you facing an error when trying to issue a virtual account? Need the correct syntax for creating an account at the endpoint? Just paste your query directly into the AI search. The AI understands your intent and provides relevant code snippets, documentation links, or troubleshooting steps specific to the MatchMove Banking API. Best Practices: Looking for the most efficient way to handle a transaction webhook from our platform? The AI can surface idiomatic patterns and well-regarded solutions from our internal knowledge base. Troubleshooting: Describe the symptoms of a bug, like a transaction status not updating correctly after a POST request. The AI can often point you to common causes or specific lines of code that might be responsible. For Non-Technical Partners: For non-technical stakeholders Finding Functionality: "How do I issue a virtual card to a new user?" or "Where can I find the dashboard for international remittances?" AI search allows you to ask natural language questions to discover platform features, even if you don't know the exact terminology for our services. Self-Service Support: Before contacting our support team, try AI search. Many common questions about account configuration or user roles can be answered quickly by the AI, pulling information directly from our help articles and FAQs. Understanding Jargon: If a developer or a report uses technical terms you're unfamiliar with—such as "Spend, Send, Lend," or "virtual account provisioning"—ask the AI. It will provide clear, concise explanations tailored to your understanding of the MatchMove platform. Build with GenAI Generative AI isn't just a fancy autocomplete; it's a powerful co-pilot that can write, refactor, and explain code, significantly boosting your productivity on the MatchMove platform. Boilerplate Generation: Need a basic function to retrieve a user's balance or a standard component to display transaction history? Describe what you need, and the AI will generate the initial code, saving you time on repetitive tasks. Code Completion: Beyond simple suggestions, Gen AI can propose entire blocks of code based on the context of your existing project, anticipating your next steps and offering efficient solutions. Refactoring & Optimization: Got a piece of code that could be more readable or performant? Ask the AI to refactor it or suggest optimizations for more efficient handling of large data sets from our transaction endpoint. Code Explanation: Need to quickly understand a legacy codebase or generate documentation? The AI can explain complex logic in plain language or create docstrings for you. Unit Test Generation: Describe the functionality you want to test, and the AI will generate basic unit test cases, helping you achieve better code coverage faster. Grounding: Ensuring Accuracy and Relevance While incredibly powerful, generative AI models can sometimes "hallucinate" or provide plausible but incorrect information. This is where grounding becomes crucial. Grounding is the process of anchoring the AI's outputs to specific, verifiable data sources to ensure factual accuracy and contextual relevance. How to Ground the AI Using MatchMove's Resources As a developer, you are the most critical link in the grounding process. The most effective way to ensure accurate code generation is to direct the AI to the specific, trusted resources within the MatchMove ecosystem. Reference the Developer Portal Directly Our AI is trained on our official documentation, so a direct reference is the best way to get a precise response. Title Description Provide Links to Relevant Articles: When asking a question, include a link to the specific page in the MatchMove Developer Portal that contains the relevant API documentation, SDK guide, or tutorial. Based on the guide here: [link to article], generate a Python function to handle the KYC Advisory webhooks. Quote from the Documentation: If you have a specific piece of a sample request or an API endpoint description, copy and paste it into your prompt. This tells the AI exactly what to use. Can you please read [link to article] and prepare to answer questions about it? Using the POST /v1/users/wallets/cards endpoint with the following request body: { 'id': 'string', 'card_type_code': 'mmvcard' }, generate a Node.js function. Iterate and Refine with Feedback Loops Don't expect perfect code on the first try. The AI is a co-pilot, not an autonomous creator. Title Description Refine Your Prompts: If the initial output is close but not quite right, provide a follow-up prompt that points out the error. That's good, but it's missing the Content-Type header from the documentation. Can you add it? Signal to the AI When It's Incorrect: Use the feedback mechanisms within the AI tool to signal when a response is wrong. This helps the model learn and improves the quality of future suggestions for both you and your colleagues. That's not what I need. Can you try to generate a new one? Validate and Test Every Output This is the most crucial step. Treat AI-generated code as a starting point, not a final solution. Perform a Manual Review: Check for security vulnerabilities, adherence to coding standards, and logical errors. Does the code correctly handle edge cases, like an empty API response or a malformed request? Run Automated Tests: Run unit tests and integration tests on the generated code. Ensure it works as expected and doesn't break existing functionality. Consult the Documentation: While the AI is a great shortcut, always cross-reference its suggestions with the official MatchMove API documentation to confirm accuracy. Sample prompts to get started To help you get the most out of these tools, here are some practical examples of effective prompts. AI Search Prompts (for Developers & Non-Technical Partners): "What are the required parameters for the Create Virtual Card endpoint? Include a JSON example." "I'm getting a 401 Unauthorized error when calling the Get KYC Documents endpoint. What are the common causes for this?" "How do I use the webhooks API to listen for successful payments?" "Where can I find my monthly transaction reports, and how do I download them as a CSV?" "Explain the difference between a virtual account and a physical card account." Generative AI Code Prompts (for Developers): Function Generation: "Write a Python function get_balance that takes a user_id and calls the MatchMove Banking API to return the current balance." Class & Module Creation: "Create a C# class named KYCWebhookHandler that has methods to handle incoming KYC approved and rejected webhook payload events from the MatchMove API." Refactoring: "Refactor the following JavaScript function to use a more modern async/await pattern for calling the Get Business User API. Related Links Start your implementation Begin technical integration Implementation checklist Utilize enumerations Leverage webhooks • [Utilize enumerations](https://developer.matchmove.com/matchmove-banking-operating-system/jumpstart-to-implementation/utilizing-enumerations.md): About Enumerations Enumeration endpoints are helper endpoints for respective businesses to serve dynamic values supported on the platform. Why Enumerations Certain values change regularly due to the evolving business environment. While updates are infrequent, partners are encouraged to consume and rely on these dynamic values to provide the best possible experience for their customers. There are a few business use cases that highlight the need for relying on and consuming these enumerations: Regulatory updates on the sanction list that affects platform-enabled regions Regulatory updates on the sanction list that affect onboarding fields like mobile country code Updates on supported ID types accepted for onboarding Knowing the availability of banks during maintenance periods before initiating payout transactions These are just a few reasons why platform enumerations are important. Learn more about individual enumerations in their respective guides. Platform Enumerations API Platform Enumerations Category API Availability Description Identity & Onboarding List Mobile Country Code Enumerations v1, v2 Create a beneficiary bank account (receiver) for domestic payout transfers Identity & Onboarding List Nationality Enumerations v1, v2 Allowed nationality values for onboarding fields Identity & Onboarding List Marital Status Enumerations v1, v2 Allowed marital status values for onboarding fields Identity & Onboarding List Genders Enumerations v1, v2 Allowed genders values for onboarding fields Identity & Onboarding List Countries Enumerations v1, v2 Allowed countries values for onboarding fields Identity & Onboarding List Titles Enumerations v1, v2 Allowed titles values for onboarding fields Identity & Onboarding List ID Types Enumerations v1, v2 Allowed ID types values for onboarding fields Identity & Onboarding List Document Types Enumerations v1, v2 Allowed document types values for onboarding fields Identity & Onboarding List KYC Types Enumerations v1, v2 Allowed KYC types values for onboarding fields Identity & Onboarding List Source of Income Enumerations v2 Allowed source of income values for onboarding fields Identity & Onboarding List File Types Enumerations v2 Allowed source of income values for onboarding fields Identity & Onboarding List Employment Type Enumerations v2 Allowed employment types values for onboarding fields specifically for PH region Identity & Onboarding List Occupations Enumerations v1, v2 Allowed occupations values for onboarding fields specifically for PH region Identity & Onboarding List City Enumerations v2 Allowed city values for onboarding fields specifically for PH region Identity & Onboarding List Barangay Enumerations (line_3) v2 Allowed barangay values for onboarding fields specifically for PH region Identity & Onboarding List State or Province Enumerations v2 Allowed state or province values for onboarding fields specifically for PH region Identity & Onboarding List Region Enumerations (line_4) v2 Allowed region values for onboarding fields specifically for PH region Identity & Onboarding List Postal Code Enumerations v2 Allowed portal code for onboarding fields specifically for PH region Identity & Onboarding List Business ID Types Enumerations v1, v2 Allowed business ID types values for onboarding fields Identity & Onboarding List Business Roles Enumerations v1, v2 Allowed business roles values for onboarding fields Identity & Onboarding List Source of Funds Enumerations v1, v2 Allowed source of funds values for onboarding fields Identity & Onboarding List Purpose of Account Enumerations v1, v2 Allowed purpose of account values for onboarding fields Identity & Onboarding List Business Document Types Enumerations v1, v2 Allowed business document types values for onboarding fields Domestic Payouts List Domestic Payout Transfer Purpose Enumerations v1 Allowed transfer purpose values for domestic payout fields Domestic Payouts List Domestic Payout Agents Enumerations v1 Allowed domestic transfer agents values for payout fields Cross-border Payouts List Cross-border Payout Purpose Enumerations v2 Allowed transfer purpose values for cross-border payout fields Sample Identity Enumeration Requests List Mobile Country Code Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/mobile_country_codes' \ --header 'Authorization: ••••••' List Mobile Country Code Enumerations response JSON { "mobile_country_codes": [ { "code": "ABW", "description": "+297" }, { "code": "AGO", "description": "+244" }, { "code": "AIA", "description": "+1" }, .. List Nationality Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{prodduct_code}}/v2/users/enumerations/nationalities' \ --header 'Authorization: ••••••' List Nationality Enumerations response JSON { "nationalities": [ { "code": "Afghan", "description": "Nationality for Afghanistan" }, { "code": "Landers", "description": "Nationality for Aland Islands" }, { "code": "Albanian", "description": "Nationality for Albania" }, .. List Marital Status Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/marital_status' \ --header 'Authorization: ••••••' List Marital Status Enumerations response JSON { "marital_status": [ { "code": "DIVORCED", "description": "Divorced" }, { "code": "MARRIED", "description": "Married" }, { "code": "NA", "description": "N/A" }, .. List Genders Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/genders' \ --header 'Authorization: ••••••' List Genders Enumerations response JSON { "genders": [ { "code": "female", "description": "Female" }, { "code": "male", "description": "Male" } ] } List Countries Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/countries' \ --header 'Authorization: ••••••' List Countries Enumerations response JSON { "countries": [ { "code": "AFG", "description": "Afghanistan" }, { "code": "ALA", "description": "Aland Islands" }, { "code": "ALB", "description": "Albania" }, .. List Titles Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/titles' \ --header 'Authorization: ••••••' List Titles Enumerations response JSON { "titles": [ { "code": "Dr", "description": "Dr" }, { "code": "Madam", "description": "Madam" }, { "code": "Miss", "description": "Miss" }, .. List ID Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/id_types' \ --header 'Authorization: ••••••' List ID Types Enumerations response JSON { "id_types": { "primary": [ { "code": "ep", "description": { "display_name": "Employee Pass", "regex_validation": "/^[a-zA-Z0-9]*$/" } }, { "code": "epfin", "description": { "display_name": "EP FIN No.", "regex_validation": "/^[a-zA-Z0-9]*$/" } }, .. List Document Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/document_types' \ --header 'Authorization: ••••••' List Document Types Enumerations response JSON { "document_types": [ { "code": "back_of_id_document", "description": "back_of_id_document" }, { "code": "customer_occupation_details", "description": "customer_occupation_details" }, .. List KYC Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/kyc_types' \ --header 'Authorization: ••••••' List KYC Types Enumerations response JSON { "kyc_types": [ { "code": "EKYC_MYINFO", "description": "EKYC_MYINFO" }, { "code": "KYC_SERVICE", "description": "KYC_SERVICE" }, { "code": "MM_DOCUMENT_UPLOAD", "description": "MM_DOCUMENT_UPLOAD" }, .. List Source of Income Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/main_income_source' \ --header 'Authorization: ••••••' List Source of Income Enumerations response JSON { "main_income_source": [ { "code": "BANK", "description": "Bank" }, { "code": "COBRANDING_PARTNER", "description": "Cobranding Partner" }, { "code": "LOAN_PROCEEDS", "description": "Loan Proceeds" }, .. List File Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/file_types' \ --header 'Authorization: ••••••' List File Types Enumerations response JSON { "file_types": [ { "code": "id", "label": "ID" }, { "code": "video", "label": "Video" }, .. List Employment Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/employment_type' \ --header 'Authorization: ••••••' List Employment Types Enumerations response JSON { "employment_type": [ { "code": "COMMISSION_BASED_AGENT", "description": "Commission Based Agent" }, { "code": "DEPENDENT", "description": "Dependent" }, { "code": "EMPLOYED_CONTRACTUAL", "description": "Employed Contractual" }, .. List Occupations Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/occupations' \ --header 'Authorization: ••••••' List Occupations Enumerations response JSON { "occupations": [ { "code": "accountant", "description": "Accountant" }, { "code": "actor", "description": "Actor" }, .. List City Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/city' \ --header 'Authorization: ••••••' List City Enumerations response JSON { "city": [ { "code": "ABORLAN_PALAWAN", "description": "Aborlan, Palawan" }, { "code": "ABRA_DE_ILOG_OCCIDEN", "description": "Abra De Ilog, Occidental Mindoro" }, { "code": "ABUCAY_BATAAN", "description": "Abucay, Bataan" }, .. List Barangay Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/line_3' \ --header 'Authorization: ••••••' List Barangay Enumerations response JSON { "line_3": [ { "code": "50TH_DISTRICT", "description": "50th District" }, { "code": "A_ET", "description": "A-et" }, { "code": "A_BELTRAN", "description": "A. Beltran" }, { "code": "A_BONIFACIO", "description": "A. Bonifacio" }, { "code": "A_BONIFACIO_CAGUIOA_RIMANDO", "description": "A. Bonifacio-Caguioa-Rimando" }, .. List State or Province Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/state_province' \ --header 'Authorization: ••••••' List State or Province Enumerations response JSON { "state_province": [ { "code": "ABRA", "description": "ABRA" }, { "code": "AGUSANDELNORTE", "description": "AGUSAN DEL NORTE" }, { "code": "AGUSANDELSUR", "description": "AGUSAN DEL SUR" }, .. List Region Enumerations request CURL curl --location 'https://{{identityHostname}}/{{program_code}}/v2/users/enumerations/line_4' \ --header 'Authorization: ••••••' List Region Enumerations response JSON { "line_4": [ { "code": "REGION_01", "description": "Region I" }, { "code": "REGION_02", "description": "Region II" }, { "code": "REGION_03", "description": "Region III" }, .. List Postal Code Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/postal_code' \ --header 'Authorization: ••••••' List Postal Code Enumerations response JSON { "postal_code": [ { "code": "400", "description": "400" }, { "code": "401", "description": "401" }, { "code": "410", "description": "410" }, .. List Business Roles Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/business_roles' \ --header 'Authorization: ••••••' List Business Roles Enumerations response JSON { "business_roles": [ { "code": "END_USER", "description": "End User" }, { "code": "PLATFORM_USER", "description": "Platform User" }, .. List Source of Funds Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/business_source_of_funds' \ --header 'Authorization: ••••••' List Source of Funds Enumerations response JSON { "business_source_of_funds": [ { "code": "DEBT", "description": "Debt" }, { "code": "DEBT_CAPITAL", "description": "Debt Capital" }, .. List Purpose of Account Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/business_purpose_of_account' \ --header 'Authorization: ••••••' List Purpose of Account Enumerations response JSON { "business_purpose_of_account": [ { "code": "CASH_DEPOSIT", "description": "Cash Deposit" }, { "code": "CASH_WITHDRAWAL", "description": "Cash Withdrawal" }, .. List Business Document Types Enumerations request CURL curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/enumerations/business_document_types' \ --header 'Authorization: ••••••' List Business Document Types Enumerations response JSON { "business_document_types": [ { "code": "ACCOUNTING_CORPORATE_REGULATORY_AUTHORITY_REPORT", "description": "Accounting Corporate Regulatory Authority Report" }, { "code": "BOARD_RESOLUTION", "description": "Board Resolution" }, .. Sample Payouts Enumeration Requests List Domestic Payout Transfer Agents Enumerations request CURL curl --location 'https:/{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_agents' \ --header 'Authorization: ••••••' List Domestic Payout Transfer Agents Enumerations response JSON { "total_records": 39, "records_per_page": 10, "total_pages": 4, "page": 1, "links": [ { "rel": "self", "href": "https://api-op-application.matchmove-beta.com/{{program_code}}/v2/users/enumerations/domestic_transfer/agents?page=1&records_per_page=10&return_all=false", "method": "GET" }, { "rel": "next", "href": "https://api-op-application.matchmove-beta.com/{{program_code}}/v2/users/enumerations/domestic_transfer/agents?page=2&records_per_page=10&return_all=false", "method": "GET" } ], "data": [ { "agent_code": "ANZBSGS0XXX", "agent_logo": "https://assets.mmvpay.com/sg/domestic_transfer_agents/ANZ_BANK.png", "mode": "bank", "name": "ANZ Bank", "status": "active", "bic_code": "ANZBSGS0XXX", "fees": { "fixed": "0.000000", "percentage": "0.000000", "variable": "", "fee_calculation_type": "" }, "transfer_details": [ { "channel_id": "382dd1f29f9411ec875a02b5044dcedc", "channel": "FAST", "min_transfer_amount": "0.01", "max_transfer_amount": "200000.00", "transfer_fulfillment_time": "Instant" } ], "account_number_regex": "^[0-9]*$", "account_number_min_length": "5", "account_number_max_length": "34" }, .. List Domestic Payout Transfer Purpose Enumerations request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v1/users/wallets/payouts/domestic/enumerations/transfer_purpose' \ --header 'Authorization: ••••••' List Domestic Payout Transfer Purpose Enumerations response JSON { "purpose_of_transfer": [ { "code": "ACCT", "description": "Account Management" }, { "code": "ADVA", "description": "Advance Payment" }, { "code": "AGRT", "description": "Agricultural Transfer" }, { "code": "AIRB", "description": "Air" .. List Cross-border Payout Transfer Purpose Enumerations request CURL curl --location 'https://{{payouts_base_url}}/{{program_code}}/v2/users/enumerations/transfers/purpose' \ --header 'Authorization: ••••••' List Cross-border Payout Transfer Purpose Enumerations response JSON { "purpose_of_transfer": [ { "code": "ACCT", "description": "Account Management" }, { "code": "ADVA", "description": "Advance Payment" }, .. Related Links Start your implementation Begin technical integration Implementation checklist Build with Gen AI Leverage webhooks • [Prepare to go live](https://developer.matchmove.com/matchmove-banking-operating-system/going-live.md): Learn the security and compliance requirements needed to ensure a successful and confident launch into production. Understand the final steps for validation, obtaining live credentials, and deploying your complete integration. • [Demo and go-live checklist](https://developer.matchmove.com/matchmove-banking-operating-system/going-live/go-live-checklist.md): Learn how to verify the mandatory UAT exit criteria and operational benchmarks required for formal stakeholder sign-off. This checklist ensures that all functional, security, and regulatory requirements are fully validated to guarantee the integrity of the program before it moves to production. Partner product demo Before a staging program is promoted and granted access to the production environment. A partner product demo showcasing the various workflows on how a user or customer can gain access to the financial capabilities of the platform will be required. This demo can be a live demonstration through a conference call or a recorded video. The partner product demo will be reviewed by all the stakeholders of the program, which include, but are not limited to, the MatchMove Technical, Implementations, Compliance, Finance, and Card Operations teams. This final review is to ensure that all best practices and required guidelines for a financial product or application have been met. After the demo and review have been concluded, a UAT exit form will be signed by the partner and MatchMove, indicating that the program is now cleared to move to production. This will commence all the activities required to promote the staging environment to production. To aid the demo submission process, listed below are the items included in, but not limited to, the review: Category Review Items Onboarding ☐ As per payment regulatory guidelines, partners and extension partners integrated in the MatchMove (financial licensee) platform must ensure that the: the MatchMove Terms and Conditions , and the MatchMove Privacy Policy are displayed, accessible, and agreed to by the onboarding user on the sign-up page. Accounts ☐ Inform the user that access to the Accounts feature is disabled until his profile is KYC verified. Cards ☐ Inform the user that access to the Cards feature is disabled until his profile is KYC verified. ☐ As per network payment guidelines, all your app screens displaying a digital representation of your card must ensure that: The wave (contactless) logo is not displayed anywhere on the card. The card chip image is not displayed anywhere on the card. Collections ☐ Inform the user that access to the Collections feature is disabled until his profile is KYC verified. ☐ When a virtual account is provisioned to the user, ensure that the virtual account details are hidden or masked from the user until the virtual account status is already active and usable. This is to prevent users from moving funds to an inactive virtual account, which will only result in transaction rejections. Payouts ☐ Inform the user that access to the Payouts feature is disabled until his profile is KYC verified. Workflows ☐ Showcase the user journey of a new onboarding user into the partner application. This shall include the following: User sign-up and login creation User profile definition User KYC submission and evaluation ☐ Showcase the user journey on how a user gains access to financial assets in the platform. This shall include the following: Accounts provisioning Virtual Accounts provisioning (when applicable) Cards provisioning and activation (when applicable) ☐ Showcase the user journey on how a user manages the financial assets provisioned to him. This shall include the following: Accounts reactivation process (when account is suspended) Update his user profile information Card locking, reactivation, and blocking (when applicable) Access to sensitive and non-sensitive card data (when applicable) Access to virtual account details (when applicable) ☐ Showcase the user journey of how a user utilizes the financial capabilities of the platform. This shall include the following: User performing a wallet transfer transaction User receiving transfers on his virtual account (when applicable) User performing a card transaction (when applicable) User performing a domestic payment using his virtual account (when applicable) User performing a cross-border payment (when applicable) User receiving notifications regarding activities in his account • [Technical readiness](https://developer.matchmove.com/matchmove-banking-operating-system/going-live/technical-readiness.md): The recommended steps for a program's successful transition from development to production are as follows: It should be noted that not all are necessary, but they are recommended to ensure a strong, resilient, and maintainable integration. Technical Readiness Checklist Use this checklist to harden your integration before launching. Robust error handling : Handle all non‑2xx responses and timeouts; include structured logging of error context without sensitive data. Edge case coverage : Validate null or missing fields, duplicate notifications, pagination boundaries, and concurrency scenarios. Privacy‑aware logging : Log request_id platform entity IDs like user_id , wallet_id , card_id, and decision outcomes; redact secrets, PAN, and PII where not required for operations. Rollout plan : Use phased enablement or feature flags where applicable; maintain a rollback plan. Access control : Limit production console and credential access to least privilege; rotate credentials on schedule. Security Readiness Checklist Vulnerability Assessment and Penetration Testing (VAPT) Requirement for Systems Interacting with the MatchMove Platform. VAPT must be conducted by an independent, qualified security firm with demonstrable expertise. VAPT deliverable should include Detailed technical report enumerating findings with CVSS scoring, evidence, affected assets, exploitability, and recommended remediation. Executive summary for management, including risk rating, trend analysis, and residual risk. Attestation letter confirming scope, methods, dates, and tester qualifications. Re-test report validating remediation and confirming closure of findings. Gating criteria for production rollout There are no open VAPT critical or high findings affecting systems that interact with MatchMove at the time of go-live. Any deferred Medium/Low findings should be supported by documented compensating controls. Evidence of a successful retest confirming the resolution of remediated issues. Product readiness Ensure product terms and conditions are established with required regulatory attributions Ensure fees and pricing schedules are established and published to be referenced by your end users Ensure required security and regulatory controls are created Establishing webhooks Set up the callbacks on which they have internal business processes Ensure that callbacks are valid and reachable by simulating some beta transactions. Ensure operational readiness Ensure their access to MatchMove Console Set up their team access across operations, customer service, business, compliance, and finance. Ensure the various teams are trained to handle day-to-day operations • [Support & servicing readiness](https://developer.matchmove.com/matchmove-banking-operating-system/going-live/support-and-servicing-readiness.md): Use MatchMove’s internal support portal to report incidents, request production support, or ask integration questions. Supplying complete, sanitized diagnostics accelerates time-to-resolution. Opening an incident ticket Learn how to raise tickets for servicing your queries regarding the MatchMove Platform. 1 Access MatchMove console Access the support portal via the MatchMove console. MatchMove console and status page can only be accessed via the IPs whitelisted for your access to the MatchMove admin console. 2 Create ticket Click Create Ticket, then select the category that best matches your issue. 3 Provide incident information Fill in the required fields, then click submit. You will receive an email with a ticket ID and a link to track its status. For a faster resolution, ensure your systems are geared up to provide the below information for API issues encountered. Request identifier — the request_id header returned by every MatchMove API response. Endpoint, method, and timestamp — for example, POST /v1/cards at 2025-08-24T05:30:00Z . Full HTTP request and response logs — include headers and a redacted body (see security notes below). Impact assessment — number of affected users and any user-visible errors. Secure Ticket Logging & Redaction Guidelines Never include the following in a ticket—paste only redacted values as per the guidance below. Data type Redaction instructions Primary account numbers (PAN) Show the first six and last four digits: 411111******1111 CVV/CVC Remove entirely. Bearer or secret keys Replace all characters except forthe firstt six and last six with a22bcd*******1ds34a Authentication Headers Replace all characters except for the first six and last six with Basic mt2xff*******3Xa/== • [Subscribe to platform health alerts](https://developer.matchmove.com/matchmove-banking-operating-system/going-live/subscribe-to-platform-health-alerts.md): MatchMove provides real-time visibility into the health of its production APIs. You can check current status, view historical incidents, and receive proactive notifications about planned maintenance or unexpected outages. View system availability Learn how to use status page to view current system status and ongoing or scheduled maintenances. 1 Access MatchMove status page Access status page via MatchMove console MatchMove console and status page can only be accessed via the IPs whitelisted for your access to MatchMove console 2 View current platform services status ( status.matchmove.com ) The status page shows the current status of the platform and provides information in case there are any anomalies. This status page is only available and accessible from partner whitelisted IP addresses. 3 Check on incident history and upcoming maintainence The same page also allows you to see any upcoming maintainences on the platform In addition , reach out to your implementation manager to be added to subscription list to be notified for the same via your registered MatchMove Console email. • [AdminNet overview](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview.md): AdminNet is the secure web portal MatchMove provides to its partners for running a program day to day. It brings two capabilities together in one place: administering the entities in your program (users, accounts, and cards) and reporting on the data behind every movement of funds. What AdminNet does Everything in AdminNet supports one of two jobs—running the program or understanding how it performs. The controls available to you depend on your region and the role assigned to your account. Administration Act directly on a user, an account, or a card. Review onboarding and due diligence, approve or reject KYC/KYB, lock or unlock accounts, manage card lifecycles, and top up your program prefund—all from the portal. Reporting Export and download data at the program, user, account, and card levels, from live transaction lists to scheduled end-of-day reports, so your team can analyze customer behavior and reconcile with confidence. Key terms Extension Partner —you: the client operating a program on the MatchMove platform. End User —your customer, the owner of the registered account and/or a card. Accessing AdminNet An authorized administrator on the partner side invites each new user from the Administration module. From there, a new user gets set up in three steps: Verify your email — open the invitation email and confirm your address. Set a password — a follow-up email lets you create a password that meets the security policy. Log in — sign in with your registered email and password. AdminNet modules at a glance Each module groups a set of related areas. Use this as a map for where to find a given task in the portal. Module What you can do Key Areas Home See program balances, recent admin activity, and a high-level overview of every product with links into each module. Program Info · Quick Links · Admin Activities Onboarding Review individual and business customers, run due diligence, and act on KYC/KYB and account status. Customer · Customer Due Diligence · Risk Assessment Accounts View accounts and balances per customer, virtual accounts for collections, and your program prefund and balance. Customer · Customer Virtual · Program Cards Browse issued cards, drill into card and transaction detail, and manage card status. Type of Cards · Card Transactions · Management Actions Collections Track consumer and business collection transactions against virtual and program accounts. Customer Virtual Accounts · Program Accounts Payouts Review domestic and cross-border payments, manage recipients, and view corridors. Transactions · Recipients · Corridors Transactions Inspect fund movements across the platform — credits, debits, reversals, transfers, load/unload and open-loop flows. Closed Loop · Open Loop Reports Generate and download end-of-day reports for the program. Summary · Balance · Transaction Dashboard (Main) The landing page opens on your program's vital signs. Two balances summarize the state of your funds, alongside your program's region and currency, a feed of recent admin activity, and quick links to supporting resources. Program Prefund The amount you load into the program that has not yet been allotted to any user account. Every credit to a user account draws this down. For just-in-time (mJIT™) programs, each card transaction first credits the user account, depleting the prefund in real time. Program Balance The total funds allotted to users for payments. Card payments and domestic or cross-border payouts debit from here. When you initiate a debit on a user, those funds return to the program's prefund. Reports AdminNet generates a set of reports on an end-of-day basis, all available to download from the portal. They fall into three families: Summary reports — an end-of-day overview of overall program performance (Daily MIS). Balance reports — end-of-day positions for cards and account (Card Balance, Account Balance). Transaction reports — the day's card and account activity, including credits, debits, settlements, mismatches, unsettled data, loading, refunds, reversals, authorisations, release and no-auth. Getting help The dashboard's Quick Links connect you to supporting resources without leaving the portal: Knowledge Base — the self-service portal, where you can also raise and track support tickets. Developer Docs — MatchMove's API and SDK documentation across all products. System Health Status — live status and upcoming maintenance for every product line and region. Freshdesk — for access issues, including whitelisted-IP problems, and account-specific questions. • [Onboarding dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/onboarding.md): Onboarding is the core product within AdminNet. It represents the individuals and businesses you empower with financial services — each customer profile is the central hub for receiving and making payments, issuing cards, and spending. Under the Onboarding tab you manage customers, run customer due diligence, and review risk. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Each customer profile can be used for: Receiving payments — customers receive funds from various sources. Making payments —send funds to individuals or businesses. Card issuance — provide customers with debit or prepaid cards. Card spending —let customers manage their finances through card transactions. Sub-tabs The Onboarding tab contains three sub-tabs: Customers Customer Due Diligence Risk Assessment — availability depends on your program's configuration. Customer types The customer list is split into two tabs based on user type. Each customer is assigned a unique User ID used to search for and identify them. Type Definition Individual A natural person seeking to access financial services for a product you offer via the MatchMove platform—typically your end-user or consumer, for whom you issue accounts and cards and provide payouts and collections. Business An individual or entity representing a business, organization, or corporate entity onboarded to avail payment services on behalf of a business. Customers What you can do From the Customers sub-tab you can: View the customer list and open a customer's details Lock or unlock a customer Exempt or flag users Approve or reject KYC/KYB Upload, view and delete KYC/KYB documents Viewing a customer Customers → Individual / Business tab → Filter → select a search field → enter or select a value → Apply → click the User ID. The customer's detail page opens in a new tab. Available filters, include but are not limited to: A Role filter is supported on the Business list, with values End User , Platform User , and Sub Partner User . The STATUS filter has been extended to include the v2 user statuses: Pending , Pending Verification , Verification Completed , Pending Activation , Active , Rejected , Suspended , Terminated , and Blacklisted . KYC / KYB Status and KYC Sub-Status / KYB Sub-Status are first-class filters on both the Customers list and the Customer Due Diligence list. A Risk Assessment Status filter is available with v2 values Pending , Unknown , Cleared , and Rejected . Customer detail page The detail page is organized into sections. Some differ slightly between individuals and business customers. Section Contents Personal / Business Details Biographical or general information, contact details, and address information (billing/residential for individuals; operational/foundational for businesses). Additional Details Purpose of amount, source of funds, and employment type. Associated Parties (Businesses only) A dedicated section listing Associated Parties created against the business. Each AP shows its role, status, KYC outcome, supporting documents and address details. Business Hierarchy (Businesses only) A dedicated section listing other users (e.g. Platform Users / employees) onboarded under the business. Verification Details (Individual) KYC details reflect the v2 workflow status (Not Submitted, Pending, In Progress, Completed) along with the corresponding KYC sub-status. The verification reference is preserved across rejection → resubmit cycles. (Businesses) Reflects the v2 KYB workflow status, with separate states for the parent business and each associated party. Risk Details Details and outcomes from the customer's risk assessment. Account Details Account ID, account number, status, wallet balance, and net balance. Card Details Information on any cards issued to the customer (if applicable). Documents Documents uploaded via the eKYC flow (automated) or the KYC API (manual) will appear here with their provider document IDs, status, and provider-side approval/rejection reasons. Risk Details Surfaces the v2 risk evaluation, including risk evaluation date, risk assessment status, and the underlying rule outcomes. Action Buttons Lock / Unlock is allowed for v2 statuses including Active, Pending, Pending Verification, Verification Completed, Pending Activation, Rejected, Suspended, and Blacklisted (effectively all states except final-terminated and already-locked). Transaction Details The customer's transaction history on the platform. Recipient Details Recipients created by the customer for cross-border and domestic transactions (coming soon) . Lock and unlock The detail page lets you manage an individual account: Lock — temporarily restrict a customer's access. Lock is available for all statuses, including Active , Pending , Pending Verification , Verification Completed , Pending Activation , Rejected , Suspended , and Blacklisted . Unlock — reactivate a locked customer; their status reverts to the previous one. When a user is locked, their account and cards are also locked (inactive). Locked users can initiate a KYC/KYB retry flow. For details on a specific account, contact support. To lock: Customers → Individual/Business tab → click User ID → Customer Details → Lock → confirm in the popup → Lock User . To unlock: the same path, choosing Unlock → Unlock User . KYC / KYB flows Individual user (KYC) New individual created → Pending. Approved KYC → Full KYC + Active. Rejected KYC → Min KYC + Active. If user is Locked and KYC is Rejected → user can retry: upload, delete, view, Approve, Reject. If first Approved and then Rejected → Min KYC + Active. Business user (KYB) New business created → Pending. Approved KYB → Full KYB + Active. Rejected KYB → Min KYB + Pending. If user is Locked and KYB is Rejected → user can retry: upload, delete, view, Approve, Reject. If first Approved and then Rejected → Min KYB + Locked. Customer Due Diligence (CDD) Customer due diligence verifies your customers against the country's compliance requirements through Know Your Customer (KYC) and Know Your Business (KYB) checks. A strong process helps: Combat financial crime — prevent money laundering, terrorist financing, and other illegal activity. Enhance security — safeguard your platform and its users by verifying identities. Ensure regulatory compliance — meet the financial regulations of each issuing region. The following CDD features are available: The CDD list is presented with Individual and Business tabs. Filtering on KYC Status , KYB Status , KYC Sub-Status , KYB Sub-Status , and Risk Assessment Status returns accurate results, including for the Not Submitted state. Filtering Business records by Role (End User / Platform User / Sub Partner User) will returns matching records. Approved KYC documents can be viewed on the CDD detail screen. The Customer Due Diligence list is split into Individual and Business tabs and can be filtered by KYC/KYB status. Status Definition Not Submitted The customer has not yet started verification. Pending The application has been submitted, and the documents are under review. In Progress All required information and documents have been submitted, and the evaluation is ongoing. Completed (Sub-status: Approved) The application has been reviewed and approved by the relevant authorities. (Sub-status: Rejected) The application was rejected due to missing or insufficient information; the customer must resubmit with corrections. Customers are notified on approval or rejection of their KYC/KYB. Lock/unlock and approval actions depend on your region and role access. Customers with full KYC/KYB approval have their wallet limits updated to post-KYC/KYB limits; before approval, pre-KYC/KYB limits apply (subject to partner and region). Risk Assessment The Risk Assessment screens showing field names, structure, and rule outcomes match the risk service results. A Business tab is available alongside the Individual tab. Layout and behavior are mirrored for both — same filters, same export, same columns. Risk Assessment Report and risk details update flows—the report reflects the evaluation date, evaluator, subcriteria, and final outcome. The Risk Assessment list is sorted by Risk Evaluation Date by default. Risk Section default columns and the Risk Assessment Status filter pills (Pending / Unknown / Cleared / Rejected) have been adjusted to reflect the risk service results. • [Accounts dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/accounts.md): An account is a digital ledger that functions as the root payment instrument — the primary source of funds. It is sometimes referred to as a wallet or a digital/virtual account. Each user profile can have at most one account, identified by a unique Wallet ID . Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Sub-tabs The Accounts tab contains three sub-menus: Customer Accounts Customer – Virtual Accounts Program Accounts Customer Accounts Customer Accounts shows the details of a specific wallet, the cards linked to it, and the transactions made using it. The User ID and Wallet ID are hyperlinked — clicking them opens the customer detail page and the wallet detail page, respectively. Field Description Account holder details User ID, email address, mobile country code and number. User Type Individual or Business. Wallet ID Unique reference for the wallet in the MatchMove system, used for tracking wallet details. Wallet Number The number generated when the wallet is created. Status Active · Locked · Blocked · Pending Activation. Date Created The wallet's creation date. Customer – Virtual Accounts A virtual account is a proxy account created against an account issued by the MatchMove platform. It plugs the MatchMove-issued account into banking infrastructure so funds can be collected through banking channels. You can share your virtual account number with a counterparty, who can then initiate payments from their own bank account. The User ID and Wallet ID are hyperlinked to the customer and wallet detail pages: Field Description Wallet ID Unique reference for the wallet, used for tracking wallet details. Account holder Name The account holder's name as registered with the bank. Account Number The wallet number assigned when creating a FAST account. Bank Code The bank code of the virtual account. Banking Provider The associated banking partner. Status Active · Inactive · Terminated · Initialised · Pending · Rejected · Failed. User Type Consumer or Business. Date Added Date and time the virtual account was created. Date Updated Latest update date and time of the virtual account. Program Accounts The Program Accounts page gives a complete overview of prefund transactions and fund movements across both Program Prefunds (Top-up) and Program Account Balances (Debit Prefunds) . Account types are hyperlinked for easy navigation. Program Prefund Account Displays the complete history of top-up prefund transactions — both automated and manually added. The Program Prefund Account link opens four sections: Program Virtual Account Prefund Account Transactions Pending Prefund Approval Notifications Program Virtual Account Shows the corporate virtual account information along with the balance. Title Description Group Fields Account Details Account Number, Account ID, Account holder Name, User Type, Status. Bank Details Bank Code, Bank Name, Banking Provider, Bank Address, Bank Country. Created At / Updated At Date of creation; date of any update. Where there are multiple virtual accounts, all are listed. Add Program Prefund Authorised admin users can add prefund to the program prefund account on behalf of the consumer. Program Prefund Account → Add Program Prefund → complete the fields → Add. Field Description Consumer Non-editable Prefund Amount Mandatory; must be greater than zero Payment Reference Number Mandatory Narration Optional Source Reference ID Optional Account Reference ID Optional Prefund Account Transactions The movement of funds related to the corporate virtual accounts, with date and time. Two tabs: All — the complete transaction history. Prefund Addition — top-up transaction history. Pending Prefund Approval All pending prefund transactions awaiting approval. Available actions (dependent on the roles assigned): Action Description Approve Click Approve , then Confirm in the popup. The transaction is approved and removed from the pending queue. Edit Update Prefund Amount, Payment Reference Number, Narration, Source Reference ID and Account Reference ID. Reject Click Reject and confirm the rejection in the popup. Notifications Lists the prefund notifications set by admin users for the Credit and Debit prefund types. Action Description Add Set a notification for the Top-up (Credit) prefund type. Notification amount is mandatory. Edit Only the notification amount can be edited; it must be greater than zero. Delete Delete an existing notification after confirming in the popup. Program Account Balance Lets admin users view the list of Program Account Balance transactions. Clicking the Program Account Balance link displays the program balance transactions. • [Cards dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/cards.md): A card is a payment device that lets a user transact at merchants. Cards can be physical or virtual, and can be tokenised for use in digital wallets. The platform lets you customise a card's attributes, behaviours and lifecycle — including spending limits, the number of card uses, and the number of active cards. These controls align with KYC: Spending limits — customers set limits based on their financial profile, helping them manage finances responsibly. Number of card uses — some customers prefer a single-use virtual card for specific online transactions. Number of active cards — helps verify the legitimacy of card requests and prevents unauthorised issuance. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Sub-tabs The Cards tab contains two sub-menus: Cards (the card list) Card Transactions Type of Cards The card list is the central place to view every virtual and physical card issued for a chosen period, each showing its current status. The list distinguishes between Virtual and Physical tabs — a virtual card has a different number, design and even limits versus a physical card. Title Description Card type Statuses Virtual — exists in digitised form, presented on screen and active immediately. Active · Locked · Blocked Physical — a tangible instrument for in-store and online purchases. Active · Pending Activation · Locked · Blocked Field Description Card ID A card ID derived from the card number, used for tracking card details. User ID The user's ID, used for tracking user details. Wallet ID The user's wallet ID, returned at wallet creation. Proxy Number A unique number used as an alternative to the card number. Card Transactions Only cards with an Active status can be used to make purchases; attempts on inactive or cancelled cards are automatically declined. Card transactions fall into three types: Authorization Settlement Account Verification Authorization Online messages received as the platform processes transactions for cardholder accounts. There are two kinds: Non-financial — originates from the card network, payment institutions or merchants as part of the processing lifecycle; no impact on customer balances. Includes account verification. Financial — initiated when a cardholder executes and confirms a payment; impacts customer balances. Includes ATM, card-present, mobile wallet, card-not-present and contactless (wearable) transactions. Authorization transactions appear under two sub-menus: Purchase History — authorised and approved open-loop transactions. From the list you can open the transaction, the card used, and the user who transacted. Quick filter pills for Success and Failed are available. Purchase Reversal — open-loop transactions that were reversed. Because they were not settled with the network, the funds are returned to the customer; the report supports reconciliation. Both open a transaction detail page with these sections: Transaction Details, Amount Details, Merchant Details, Card Details, Account Details, User Details. Representative fields: Group Fields Transaction Details Transaction ID, Transaction Type, Response Code, Channel (POS/ECOM/ATM), Network (e.g. VISA, Mastercard, RuPay), Retrieval Reference Number, Trace, Local Transaction Time/Date, Created At, Settlement Date, Transmission Date & Time. Amount Details Card Amount, Card Currency, Transaction Amount & Currency, Fee Amount & Currency, Total Amount & Currency. Merchant Details Merchant Name, Merchant ID, Merchant Category Code, Terminal ID, Acquiring Institution & code. Card Details Card Number, Card ID, Proxy Number, Card Status, Preferred Name, Card Type, Date Expiry/Created/Closed, Closure Reason. Account Details Wallet ID, Wallet Number, Wallet Balance, Net Balance, Date Created, Status. User Details Personal details, biographical information, contact details, address information. Settlement The settlement process reconciles transactions: receiving and validating clearing files ( Clearing ), comparing them with the authorised transactions on record ( Reconciliation ), and posting reconciled values to cardholder and program balances ( Posting ). Settlement transactions are categorised into buckets: Bucket Definition Exact Match Authorisation and settlement amounts match exactly, with no discrepancies. Mismatch The authorised and settled amounts differ — e.g. currency conversion variations, final hotel charges, or unavailable e-commerce goods. No Auth A settlement with no corresponding authorisation (e.g. subscription charges). Auth Release Authorised but not settled within the network's expected timeframe; the transaction is unsuccessful and funds are returned. Credit Voucher Already settled with the network but requires a credit to the customer — merchant-originated credits (e.g. inability to deliver goods or services). Each bucket opens the same detail sections (Transaction Details, Amount, Merchant, Card, Account, User), with settlement-specific fields such as Settlement Date, Reversal Response Code, Reversal Date, Reversal Settlement Date and Response Balance. Account Verification Non-financial transactions that let merchants validate a cardholder's account status before submitting a full authorisation or recurring payment. Categorised by status: Success, Failed, Reversed. Card Detail Information Opening a specific card gives a complete view of that card: Section Definition Card Information Card status (active, suspended, blocked), issuance and expiration dates. User Information User details associated with the card, including biographical information and billing address. Account Details The account linked to the card — account type and number, account holder information, balance. For non-shared-balance programs, Card Balance Details (with card number) appear here. Transaction History A record of all transactions on the card. A Settlement Date Range filter is available to filter by settlement date. Card Management Actions The platform provides controls for security and lifecycle management. These controls depend on region and role access. Action Use Case Lock Temporarily disable a card — when misplaced (not confirmed lost/stolen) or to prevent unauthorised use if suspicious activity is suspected. Locked cards cannot be used for new transactions, though existing pre-authorised transactions may still process. Only Active cards can be locked. Unlock Reactivate a locked card. Block When a card is confirmed lost, stolen or damaged, or to prevent further use in case of suspected fraud. For lost or stolen cards, terminate the card completely and issue a new one with a fresh PAN (Primary Account Number) for enhanced security. • [Collections dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/collections.md): Collections let you receive payments globally with ease. You can collect funds from any entity — corporate or individual — anywhere in the world, consolidating your receivables in one place. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. What Collections gives you: Collect from anyone — from any entity, whether a business or an individual. Global reach — receive funds from entities in any country not on a sanctions list. Flexible payment channels — support a range of payment instruments, including bank transfers. Multicurrency support — accept payments in fiat and cryptocurrencies*, with funds stored securely in your MatchMove account in fiat currency. Customisable frequency — set the collection frequency that suits your receivables process. Benefits: effortless global collections in any supported currency, convenient choice of payment method for your clients, and streamlined receivables management on a single platform. Sub-tabs Under Collection Transactions there are two sub-menus: Customer – Virtual Accounts Program Accounts Customer – Virtual Accounts Displays the list of consumer and business collection transactions. Category Fields Account holder details User ID, Account type, Account number, Name. Originator details Originator Account Number, Name, Bank code, Reference ID. Transaction details Total Amount, Fee, Amount Credited, Channel, Type, Additional details, Recipient name, Purpose of Transaction, status, transaction date, and updated date and time. Program Accounts Lists the transactions made to the program prefund account. Category Description Originator details Originator Account Number, Name, Bank code, Reference ID. Transaction details Total Amount, Fee, Amount Credited, Channel, Type, Additional details, Recipient name, Purpose of Transaction, status, transaction date, and updated date and time. Transaction statuses Customer virtual account and program account collection transactions can carry these statuses: Status Pending Accepted Timeout Cancelled Reversed Failed Failed Rejected Success Reversed Cryptocurrency support is subject to your program's configuration and the applicable region. • [Payouts dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/payouts.md): Payouts give you a 360° view of the domestic and cross-border payments made by your users and their associated entities. You can send money internationally quickly and securely, and track every transaction end to end. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Sub-tabs The Payouts tab contains three sub-menus: Transactions Recipients Corridors Transactions View payout information and filter it for a chosen period. Payout transactions are split into two tabs based on type: Cross-border Domestic (this section will be enabled soon) Cross-border transaction The cross-border capability lets users transfer funds from their MatchMove account to recipients in different geographies. The detail page is organized into sections: Section Fields Transaction Details Transaction ID, User Amount (amount the user sends), Recipient Amount (amount the receiver gets), Converted Amount (in the sender's currency), FX Rate, Transaction Sub Status, Status Remarks, Customer Remarks. Sender and Receiver information Sender's personal info (User ID, Country, Currency, User Type) and recipient's personal info (Recipient ID, Country, Currency, User Type). Receiving Institution Type — the entity or channel the recipient receives funds through (bank account, mobile wallet, cash pickup) — and details (Name, Branch, Branch Code). Transparent Rates & Fees Quote, Total Fee, Platform Fee, Program Fee. Additional details Purpose of Payment, Source of Funds, User Occupation, Relationship with Sender. Transaction Timeline A chronological record of transaction events and status updates, from initiation to final settlement. Recipients AdminNet is your recipient management hub. When you add a new recipient, their information is automatically risk-screened; if a recipient is flagged as risky, you are notified and the payment is held until resolved. From the Recipients sub-tab you can: View a comprehensive list of all individual and business recipients added to the program. Access detailed beneficiary information — user demographics, account details, and past transaction history. Get real-time status updates on each recipient. Opening a recipient gives a full view: Category Fields Recipient details Recipient ID, Biographical Information, Contact Details, Address Information, Account status, Recipient Type (Individual/Business), Receiving Country, Receiving Currency, Additional Details (purpose of amount, relationship with sender), Receiving Institution Information (name, type, branch, account details). User details (recipient created by) User ID, User Type (Individual/Business). Corridors A corridor is a specific combination of source and destination that defines how funds can be sent. MatchMove offers a wide network of corridors so you can send funds exactly how you need. A corridor is defined by: Field Description Source Country Where the money originates. Source Currency The currency used to send the funds. Receiving Country Where the recipient receives the money. Receiving Currency The currency the recipient receives. Payment Type The type of transaction (e.g. Business to Business, Consumer to Consumer). Channel The method used to receive funds (e.g. bank account, mobile wallet, cash pickup). Each corridor also exposes transparent detail to help you decide: Supported payment types — e.g. B2B, C2C. Estimated transfer times — the expected timeframe for completion. Limits and fees — applicable transaction limits and pricing, including platform and program-specific fees. Network of receiving institutions — institutions available to receive funds within the corridor. Receiving institution types — available payout options, including bank accounts, mobile wallets and cash pickup. • [Transactions dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/transactions-dashboard.md): The Transactions tab is the ledger of fund movements across your program. It groups closed-loop activity that stays within the platform alongside open-loop card, collection, and payout flows. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Sub-tabs Closed Loop Card Transactions (see the Cards module) Collection Transactions (see the Collections module) Payout Transactions (see the Payouts module) Program Transactions (coming soon) Closed Loop Closed-loop transactions occur within the MatchMove platform — typically confined to platform-specific wallets and cards, with funds remaining inside the system. Depending on the transaction and program account type, closed-loop activity is split into: Credit Debit Reversals Money Transfer Load (if available) Unload (if available) Each list opens initially on the default date range and can be filtered by status. Every detail page shares the sections Transaction details, Additional details, Account details, and User details (Money Transfer and Load and Unload also include card or receiver details). Credit A list of top-ups—money added to a wallet from the program prefund. Transactions → Closed Loop → Credits Statuses: Pending · Success · Waiting · Refunded · Failed Field Description Transaction ID Unique ID for each credit transaction. API Reference ID Unique ID created during the wallet top-up. Transaction Type / Type Code The type of credit transaction; code T for top-up/credit. Transaction Status Active for successful transactions; pending for unsuccessful. Transaction Amount / Fees Charged / Currency The credited value, fee charged, and currency. Payment Provider / Provider Status Provider and the payment status it reports. Balance Post Transaction Balance after the credit. Date Created When the transaction was carried out. Additional Details → Reason Reason for the top-up/credit. Debit A list of debits from the wallet. Transactions → Closed Loop → Debits Statuses: Pending · Success · Waiting · Refunded · Failed · API Failed · Temporary Fields mirror Credit, with Transaction Type Code D for deduct. For a deduct transaction the additional details include Client Reference ID, Purpose of Transfer, Source Amount, Instruction ID, Narration and Comments, plus Fund Category ID , Refund Type and Reason . Reversals A list of reversed or refunded transactions. Transactions → Closed Loop → Reversals Statuses: Pending · Success Fields mirror Debit, with Transaction Type Code R for refund, plus a Debit/Credit Indicator and Balance Post Transaction . Debit reversals carry the same extra fields as debits (Client Reference ID, Purpose of Transfer, Source Amount, Instruction ID, Narration, Comments). Money Transfer Transactions carried out between two wallets via money transfer. The detail page shows the sender and receiver alongside the transaction. Transactions → Closed Loop → Money Transfer Statuses: Active · Canceled · Expired · Claimed · Inactive · Failed Sections: Transaction details, User details, Receiver details, Account details. Receiver details include Receiver ID, email, mobile number and mobile country code. Load (non-shared-balance / legacy programs) Transactions from wallet to card. Transactions → Closed Loop → Load Sections: Transaction details, Card details, Account details, User details. Key fields include Transaction Ref ID, Transaction Status, Transaction Amount, Transaction Currency, Transaction Type ( Load ) and Date Received. Unload (non-shared-balance / legacy programs) Transactions from card to wallet. Transactions → Closed Loop → Unload Same sections and fields as Load, with Transaction Type Unload and Date Received recording when the amount was unloaded. Open loop Open-loop transactions flow through a network that allows interoperability between different financial institutions, banks, and merchants—they are not confined to a single issuer or closed ecosystem, making them widely accepted. Depending on the transaction and program account type, open-loop activity covers the following: Card Transactions — see the Cards module. Collection Transactions — see the Collections module. Payout Transactions — see the Payouts module. Program Transactions — coming soon . • [Reports dashboard](https://developer.matchmove.com/matchmove-banking-operating-system/reporting-and-dashboard/adminnet-overview/reports-dashboard.md): AdminNet generates a set of reports on an end-of-day basis, all available to consume and download from the portal. There are three types of report. Regional feature availability Not all AdminNet features are available in every region, and what you can see depends on your program's configuration and your AdminNet role provisions. Some items described here may not be enabled for your program — contact MatchMove support via Freshdesk to confirm. Type Purpose Summary Reports An end-of-day overview of overall program performance. Balance Reports A summary of end-of-day data for the program. Transaction Reports A summary of card transactional data for the program. Summary Reports End-of-day reports that give an overview of program performance. Subtype Description Daily MIS A summary of the various pools in the system at the end of the day, giving balance-amount details across cards, accounts, and transactions. Balance Reports A summary of end-of-day data for the program. Subtype Description Card Balance Users, their associated accounts, and the corresponding daily balances, including the customer's basic info and card. Wallet Balance User details with the associated account/wallet and corresponding balance. Transaction Reports A summary of card transactional data for the program. Subtype Description Credits An EOD report listing top-up transactions on end-user accounts. Debits An EOD report listing debit transactions on end-user accounts. Unsettled Data An EOD report listing all card transactions unsettled for the day. Card Mismatch Settlement Card transactions settled with a settlement amount different from the authorization amount for the day. Card Settlements Card transactions settled as an exact match for the day (settlement and authorization amounts match exactly). Card Loading Load card transactions and fund movements from the wallet within the system, tailored to the client's specification. Card Refunds User information alongside the refund transactions processed for the day. Reversals User details with the day's online reversals—transaction details, refund type, reason, category, and account details. Card Release Card transactions released during the day because no settlement was received within the stipulated period. Card No-Auth Card transactions force-settled for the day—a consequence of the match-off process, or transactions with no corresponding authorization that could not be matched. Card Authorisations Card transactions that are authorized for the day. Reports are produced at end of day and downloaded from the portal; completed exports appear under Notifications at the top right of the page. • [API References](https://developer.matchmove.com/matchmove-banking-operating-system/matchmove-banking-api-reference/api-references.md): Welcome to the technical specification section of the MatchMove Banking Operating System . This document serves as the formal technical reference for developers building against the MatchMove platform. While the preceding guides cover high-level business workflows and platform architecture, this section focuses on the specific protocols, conventions, and data structures required to implement a robust, production-ready integration. Scope of This Specification This section outlines the foundational technical standards used across all MatchMove RESTful APIs: Request & Response Models: Detailed JSON schemas for all request payloads, path parameters, query strings, and response objects. Authentication & Authorization: Header requirements, environment-level API keys, and token management protocols. Data Conventions: Strict formatting rules for dates (ISO-8601), currency amounts (minor vs. major units), and standard field types. Transaction Reliability: Implementation guidelines for idempotency keys to ensure financial requests are safely executed without duplicate processing during retries. Error & State Handling: Standardized HTTP response codes, error payloads, and diagnostic codes for rapid debugging. Event Notifications: Webhook event signatures and verification patterns for handling asynchronous status changes (e.g., transaction completion, card auths, and KYC status updates). Next Steps Use the navigation sidebar to explore individual API domain specs (Identity, Accounts, Ledgers, Cards, Collections, and Payouts) or jump directly to specific endpoint definitions to begin building and testing in your UAT/staging environment.